MCP (Model Context Protocol) — sysmon + mcp-client

A lightweight MCP server (sysmon) and a TypeScript MCP client (mcp-client) that demonstrate integrating local LLMs (via an OpenAI-compatible client) with a set of system and weather tools. The server exposes tools over the MCP protocol and the client connects to a running MCP server over stdio, forwards LLM requests to a local LLM endpoint, and executes tool calls via the MCP SDK.

Status: Example / demo code. Use for experimentation and extension.

Contents

• sysmon/: An MCP server that registers system- and weather-related tools.
• mcp-client/: A TypeScript MCP client that connects to a server, talks to a local LLM (OpenAI-compatible API), and orchestrates tool calls.

Key dependencies: @modelcontextprotocol/sdk, openai (client configured for local LLM), systeminformation, zod, dotenv.

Quick overview

• The sysmon server registers the following tools (see sysmon/src/tools):
  • get-system-info — CPU, RAM, and network stats using systeminformation.
  • list-processes — list running processes.
  • kill-process — terminate a process by PID.
  • get-alerts — fetch active weather alerts for a US state (NWS API).
  • get-forecast — fetch forecast for latitude/longitude (NWS API).
• The mcp-client connects to a running MCP server (stdio transport), calls an LLM via an OpenAI-compatible client configured to a local LLM endpoint, and maps model function/tool calls to MCP tool invocations.

Requirements

• Node.js (v18+ recommended)
• npm or yarn
• A local LLM endpoint compatible with the openai client (an HTTP endpoint that accepts the OpenAI-like chat completion surface). Set LLM_BASE_URL to point at it.

Environment variables

Create a .env file at the repository root or in mcp-client when running the client. Important env vars used by the client:

LLM_BASE_URL=http://localhost:11434/   # required — local LLM endpoint
API_KEY=sk-local-llm                     # optional — API key for local LLM
LLM_MODEL=llama3.1                       # optional — model name passed to the LLM
SYSTEM_PROMPT=                            # optional — additional system prompt content
LOG_FILE=mcp-client.log                  # optional — client log file

The server (sysmon) writes tool usage logs to logs/tool-usage.log in the repository working directory.

Build & Run

1. Install dependencies at the repo root or per-package

# from repo root
cd sysmon
npm install
npm run build

cd ../mcp-client
npm install
npm run build

2. Run the server (stdio transport) — this starts the MCP server which communicates over STDIO:

# from repo root
node sysmon/build/index.js
# or if installed globally via the package's bin: ./sysmon/build/index.js

3. Run the client and point it to the server script you want to spawn/connect to (the client expects a server script path):

cd mcp-client
node build/index.js ../sysmon/build/index.js
# Then use the interactive chat loop in the client terminal

Notes:

• The client build/index.js expects a path to an MCP server script; it will spawn that script with python3 (for .py) or node (for .js). The example above runs the built sysmon JS server.
• The client uses an OpenAI-compatible client configured to LLM_BASE_URL. This allows connecting to local LLM servers that present an OpenAI-like HTTP API.

How tools are invoked

• The LLM can request a function/tool call. The client converts those function calls into MCP tool invocations via the @modelcontextprotocol/sdk client. Tool results are returned to the LLM in the next cycle of messages.
• Tools are registered inside sysmon/src/tools/registerSystemTools.ts and each handler lives in SystemInfoTool.ts and WeatherTools.ts.

Development notes

• Add a new tool:
  • Implement a handler that returns { content: [{ type: 'text', text: '...' }] } (see existing tools).
  • Register it in registerSystemTools.ts with a zod input schema.
• Tool invocations are wrapped with wrapToolHandler which logs invocations to logs/tool-usage.log.
• Client logging: mcp-client appends runtime logs to mcp-client.log (configurable via LOG_FILE).

Security & permissions

• The kill-process tool will attempt to kill processes and requires the running user to have appropriate permissions. Use with care.
• The NWS API calls are unauthenticated, but respect the NWS API usage policies and User-Agent requirements.

Contributing

• Issues and PRs welcome. Keep changes focused and add small examples or tests for new tools.

License

This repository uses the ISC license as indicated in the packages’ package.json files.

---