# 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

```bash
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:

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

Use a prompt such as:

```text
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.

```bash
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:

```json
{
  "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.