Engineering Operations MCP

A small, safe MCP server that gives Codex structured, read-only access to engineering operations evidence. This first working stage exposes search_logs over Streamable HTTP using deterministic local JSON fixtures.

What works in Stage 1

• search_logs filters by service, environment, severity, text, and bounded time range.
• Zod validates strict inputs; the maximum window is 24 hours and the maximum result limit is 100.
• Passwords, tokens, API keys, email addresses, and long identifying numbers are redacted.
• Every accepted or directly rejected tool execution emits a JSON audit event to stderr.
• The server is stateless and read-only, making it safe to replicate later.
• Both Streamable HTTP and local stdio transports use the same tool implementation.
• Docker Compose starts the complete sample as one non-root, read-only container.

The fixture clock uses the newest timestamp in test-data/logs.json, so the demo remains deterministic. Set OPS_CLOCK_MODE=realtime when replacing fixtures with a live adapter.

Run with Docker

docker compose up --build -d
docker compose ps

The MCP endpoint is http://127.0.0.1:3000/mcp; health is available at http://127.0.0.1:3000/health.

Register it with Codex:

codex mcp add engineering-ops --url http://127.0.0.1:3000/mcp
codex mcp list

Use a prompt such as:

Use engineering-ops to search payment-api production error logs from the last 30 minutes for timeout errors. Show the evidence and do not make production changes.

Develop and verify

Node.js 20 or newer is required.

npm install
npm run build
npm test
docker compose up --build -d
npm run smoke -- http://127.0.0.1:3000/mcp

For a local process-spawned integration, build once and run npm run start:stdio. Protocol traffic uses stdout; audit logs use stderr.

Tool contract

Example input:

{
  "service": "payment-api",
  "environment": "production",
  "query": "timeout",
  "severity": "error",
  "sinceMinutes": 30,
  "limit": 10
}

The response contains the effective time window, matching and error counts, redacted top-error groups, and a truncation indicator. Production actions, shell execution, SQL, and write tools are not exposed.

Staged roadmap

1. Stage 1 — working sample (this repository): containerized search_logs, fixtures, limits, redaction, auditing, tests, and MCP smoke test.
2. Stage 2 — complete mock MVP: add get_recent_deployments, Markdown-backed get_runbook, and evidence-based diagnose_service behind the same server factory.
3. Stage 3 — local demo stack: add separate mock provider and demo-console containers; use Compose profiles so the MCP server still runs alone.
4. Stage 4 — real read-only adapters: add OpenSearch, GitHub/CI, and deployment providers behind repository interfaces, plus authentication and durable audit storage.

Suggested GitHub description

A safe, containerized TypeScript MCP server that gives Codex structured, read-only engineering operations evidence with validated queries, secret redaction, audit logging, and deterministic local demos.

The staged roadmap follows the original Engineering Operations MCP design and acceptance criteria.