# systeminternals-mcp (scaffold)
Minimal FastMCP-compatible scaffold that demonstrates dynamic registration and safe subprocess wrapping for exposing Sysinternals and NirSoft binaries.
Quick demo:
```bash
python server.py --demo procexp64
```
Start the MCP stdio server:
```bash
python server_mcp.py
```
Edit `config.ini` to adjust server settings (log level, timeout, allow_destructive).
The server no longer requires explicit binary paths — it scans the `binaries/` directory recursively.
Security notes: This scaffold sanitizes arguments and uses `asyncio.create_subprocess_exec` without a shell. Extend with explicit safety filters before using in production.
Safety filter: destructive tools (for example `sdelete`, `psexec`, `pskill`) are blocked by default. To run them you must either:
- Add `--confirm` to the tool arguments, or
- Set `allow_destructive = true` in the `[server]` section of `config.ini`.
The server also scans a `binaries` directory recursively if present; place your tool folders (e.g., `systeminternals`, `nirsoft`) under `binaries`.
## Setup
Prerequisites:
- Python 3.11+ (recommended) and `venv`.
Quick setup:
```powershell
python -m venv .venv
.\.venv\Scripts\activate
pip install --upgrade pip
pip install -r requirements.txt
```
## Running
- Run a single-tool demo (CLI):
```powershell
python server.py --demo pslist64
```
- Start the long-running MCP stdio server (for agent integration):
```powershell
python server_mcp.py
```
The `--demo` mode is useful for simple CLI usage and for coding agents that can execute shell commands and parse JSON output. `server_mcp.py` exposes the full MCP stdio endpoint for clients that implement the MCP protocol.
## Using from a CLI or a coding agent
1) Simple CLI / scripting approach (recommended for automation and agents that can run subprocesses): the `--demo` command prints JSON to stdout which is easy to parse from any language.
Example Python snippet (agent or script):
```python
import subprocess, json
proc = subprocess.run([
'python', 'server.py', '--demo', 'pslist64', '--',
# additional tool args go here as separate items
], capture_output=True, text=True)
if proc.returncode == 0 and proc.stdout:
result = json.loads(proc.stdout)
print(result)
else:
print('error', proc.stderr)
```
Note: place any tool arguments after `--demo <toolname>`; the demo command will join remaining argv pieces for the tool.
2) Long-running MCP server (for advanced agents):
- Start the server with `python server_mcp.py` (it will register tools from `binaries.json` or the `binaries/` directory).
- Use an MCP-capable client to connect over stdio (spawn the server as a child process and implement the MCP framing). Many agent frameworks support providing a long-lived process that the agent can call into; in that case the MCP stdio server gives a stable RPC surface.
If your agent framework doesn't implement MCP natively, use the simple subprocess approach above to execute `server.py --demo` per-request.
## Security and best practices
- Never allow untrusted agents or users to run destructive tools. Destructive tools are blocked by default; confirmations are required (interactive prompt, `--confirm` or `allow_destructive=true` in `config.ini`).
- When generating per-tool schemas or probing help text, run the probe in an isolated environment (VM or disposable container) to avoid accidental execution of unsafe binaries.
- For production use, add authentication around the MCP stdio process and run under restricted privileges.
## CI
A GitHub Actions workflow is included at `.github/workflows/ci.yml` that runs the test suite on push and pull requests.
## `mcpServers` (IDE / agent integration)
If your editor/agent supports a `mcpServers` config (for example the Gemini client settings), add entries that either start the stdio MCP server or point to a running HTTP MCP endpoint.
Example — start the long-lived stdio MCP server from this repo (preferred for full MCP integration):
```json
"systeminternals-mcp": {
"command": "python",
"args": [
"C:\\path\\to\\the\\server_mcp.py"
]
}
```
Example — demo/one-shot entry that runs `--demo` and prints JSON (useful for simple agents that call subprocesses):
```json
"systeminternals-mcp-demo": {
"command": "python",
"args": [
"C:\\path\\to\\the\\server.py",
"--demo"
]
}
```
Example — point to an existing HTTP MCP endpoint:
```json
"systeminternals-mcp-http": {
"url": "http://127.0.0.1:12345/mcp"
}
```
Notes:
- Use absolute Windows paths (escape backslashes in JSON) or a plain `python` command if the environment activates the virtualenv automatically.
- If your client supports `cwd` and `env`, set them so the server runs in the repo root and uses the `.venv` Python.
- Prefer the stdio MCP server (`server_mcp.py`) for integrated agents; use `--demo` for simple per-request subprocess calls that return JSON.
