ops-toolbox

A small Model Context Protocol server that gives an assistant four things a support engineer actually reaches for: tail a log, check whether an endpoint is answering, search a runbook of past fixes, and write a new fix back into it.

No dependencies. It is plain Node, node server.js and it runs.

What MCP is, briefly

Model Context Protocol is a standard way to hand an AI client a set of tools it can call. The client starts your server as a subprocess and they speak JSON-RPC 2.0 over stdin and stdout, one message per line. The client asks tools/list to find out what exists, then tools/call to run one and get the result back as text.

That is the whole idea. There is no framework requirement, which is why this server has no dependencies: the protocol is small enough to implement directly, and doing it directly makes it obvious what is going on.

Two things matter when you write one:

• stdout belongs to the protocol. A stray console.log puts a non-JSON line in the stream and the client drops the connection. Every diagnostic in this server goes to stderr, which the client is free to capture or ignore.

• A tool failing is not a protocol failure. A missing file comes back as a normal result flagged isError, so the model can read the message and correct itself. Protocol errors are reserved for things like an unknown tool name or a missing required argument.

Related MCP server: holmesgpt-runbook-mcp

The tools

Two details worth pointing out because they are the kind of thing that bites you in production:

• tail_log resolves the requested path and rejects anything that lands outside the configured root. A model will happily pass ../../../etc/shadow if you let it.

• tail_log reads only the last 256 KB of a file rather than the whole thing. A tail of a rotated 4 GB log should not be an out-of-memory error.

• runbook_add writes to a temp file and renames it over the original. A rename on the same filesystem is atomic, so a crash halfway through cannot leave a truncated runbook behind.

Requirements

Node 20 or newer. Nothing else.

Install

git clone https://github.com/coreyhiggins/mcp-server-example.git
cd mcp-server-example
node selftest.js     # confirm it works before wiring it up

There is no npm install step because there is nothing to install.

Configuration

Both paths come from the environment so the same server can point at sample data during development and at real paths on a server.

Wiring it into a client

Claude Desktop

Edit the config file, then restart the app.

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ops-toolbox": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-example/server.js"],
      "env": {
        "OPS_LOG_ROOT": "/var/log",
        "OPS_RUNBOOK": "/absolute/path/to/mcp-server-example/data/runbook.json"
      }
    }
  }
}

Use absolute paths. The client does not start the server in your shell's working directory, so a relative path will not resolve the way you expect.

Claude Code

claude mcp add ops-toolbox \
  --env OPS_LOG_ROOT=/var/log \
  --env OPS_RUNBOOK=/absolute/path/to/mcp-server-example/data/runbook.json \
  -- node /absolute/path/to/mcp-server-example/server.js

Then claude mcp list should show it connected.

Driving it by hand

The server is just a program reading lines on stdin, so you can talk to it without any client at all. This is the fastest way to debug one:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25"}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"runbook_search","arguments":{"query":"nginx 502"}}}' \
  | node server.js

Self-test

node selftest.js

20 assertions covering the tools, the JSON-RPC layer, and one real end-to-end handshake against a spawned server over stdio. The HTTP checks hit a throwaway server this script starts on 127.0.0.1, so the test needs no network access. Exits non-zero if anything fails.

Layout

server.js       JSON-RPC plumbing, stdio loop, protocol version negotiation
tools.js        the four tools and their schemas
selftest.js     the one runnable check
data/           seed runbook
sample-logs/    a log file to point tail_log at while you try it

How this is used in production

I run Ubuntu servers where the first ten minutes of any incident are the same three questions: what does the log say, is the service actually answering, and have we seen this before. Those questions are what these four tools are. Putting them behind MCP means I can ask in plain language and get the answer without switching to a terminal, and the runbook grows every time something breaks instead of living in my head.

The security choices in here are not decoration. A tool that takes a file path from a model is an untrusted input path, so it gets a root confinement check, a read cap, and an atomic write. Same review I would give any script that runs on a box with real users on it.

License

MIT