# MCP Agent Toolkit

An MCP (Model Context Protocol) server that exposes production agent-kernel tools — blackboard shared state, SCAR failure memory, and LLM response cache — as standard MCP tools any Claude or GPT agent can call.

> For project walkthroughs, architecture flowcharts, and system context, visit the live landing page: [my-portfolio-github-io-beta-five.vercel.app/projects/mcp-agent-toolkit.html](https://my-portfolio-github-io-beta-five.vercel.app/projects/mcp-agent-toolkit.html)

## What it does

Connects the three core reliability patterns from 18 months of building production multi-agent systems into a single MCP server:

| Tool Group | Tools | What it solves |
|------------|-------|---------------|
| **Blackboard** | `blackboard_write`, `blackboard_read`, `blackboard_list` | Shared agent state without direct coupling |
| **SCAR Memory** | `scar_lookup`, `scar_record` | Repeated failure prevention — find the known fix before retrying |
| **Response Cache** | `cache_get`, `cache_set` | Stop paying twice for identical LLM requests |

## Part of The Machine OS

This repo is a **spoke** of [The Machine OS](https://github.com/shubham0086/the-machine-os): it
backs the `~~scar-memory` and `~~blackboard` connectors that supercharge the `/debug`,
`/incident-response`, and `/agent-design` skills.

**Prerequisite:** Node.js **22.5+** (`node:sqlite` is built in from 22.5; on recent versions it
runs without a flag and just prints an experimental warning to stderr, which does not affect the
stdio protocol).

### Option A — install via the Machine OS plugin (recommended for Claude Code)

```bash
/plugin marketplace add shubham0086/the-machine-os
/plugin install ai-engineering-tools@machine-os
/reload-plugins
```

This launches the server for you (as the `agent-memory` MCP server) — no manual config.

### Option B — point any MCP client at it directly

Works in Claude Desktop, Cursor, Windsurf, Cline, Zed, or any `mcp.json` client. No clone needed;
`npx` fetches and runs it:

```json
{
  "mcpServers": {
    "agent-memory": {
      "command": "npx",
      "args": ["-y", "github:shubham0086/mcp-agent-toolkit"],
      "env": { "MCP_AGENT_TOOLKIT_DATA_DIR": "/abs/path/to/persist" }
    }
  }
}
```

`MCP_AGENT_TOOLKIT_DATA_DIR` is optional but recommended under `npx`: it points the SQLite store
at a stable path so blackboard state and SCAR memory survive across runs (the npx package dir is
ephemeral). Omit it and storage falls back to the package's own `data/` dir.

### Local dev

```bash
npm install
npm start    # runs the stdio server from this checkout
```

## Tool reference

### Blackboard

```
blackboard_write(run_id, agent, key, value)  — persist an artifact
blackboard_read(run_id, agent, key)          — read latest artifact
blackboard_list(run_id, agent)               — list all keys for an agent
```

Agents communicate through the blackboard, never directly. The Coder writes `code`. The Auditor reads `code`. If either fails and retries, the other's work is still in SQLite.

### SCAR Memory

```
scar_lookup(agent, error_type, context?)  — retrieve known resolution
scar_record(agent, error_type, resolution, context?)  — store a new resolution
```

When an agent hits `JSONDecodeError` and you fixed it with `json_repair()`, record it. Next time any agent hits the same error in the same context, `scar_lookup` returns the fix before the retry loop starts.

### Response Cache

```
cache_get(messages, model)                    — check cache before calling LLM
cache_set(messages, model, response, provider)  — store response after call
```

SHA-256 hashes the messages + model into a cache key. Identical requests never hit the API twice.

## Tests

```bash
npm test
```

13 tests covering blackboard isolation, SCAR round-trips, and cache hit/miss behavior.

## Stack

- **MCP SDK** (`@modelcontextprotocol/sdk`) — the official Anthropic MCP server library
- **node:sqlite** — Node.js 22 built-in synchronous SQLite, zero native compilation
- **stdio transport** — standard MCP pattern, works with any client

## Related repos

- [agent-scars](https://github.com/shubham0086/agent-scars) — standalone SCAR pattern
- [agent-recall](https://github.com/shubham0086/agent-recall) — solution memory
- [equilibrium](https://github.com/shubham0086/equilibrium) — the AgentKernel these patterns came from