# mcp-records-demo

A small, **generic** Model Context Protocol (MCP) server that shows the patterns a real
"build me an MCP integration for my business tool" job asks for — with no client IP in it.
It's a portfolio/demo artifact: swap the in-memory `RecordStore` for a real API client and
it becomes a production integration.

## What it demonstrates
- **Typed tools, read + write** — `list_records`, `get_record`, `create_record`, `update_record`, `review_record`, each with a JSON-Schema input.
- **Write safeguards** — write tools are disabled unless `MCP_ALLOW_WRITES=true` (least-privilege by default).
- **Structured error handling** — validation and not-found errors are returned as structured tool errors; the server never crashes or leaks internals.
- **Deterministic review** — `review_record` runs repeatable, code-driven checks and returns structured findings (not free-form prose).
- **Clean separation** — all domain logic lives in `src/store.js` (dependency-free, fully unit-tested), so it's testable without the transport.

## Run it
```bash
npm install
npm test                          # 8 zero-dependency unit tests on the core logic
npm run example                   # end-to-end: spawns the server and exercises the tools over stdio
MCP_ALLOW_WRITES=true npm start   # run the server on stdio
```

## Use it from Claude Desktop / Claude Code
Add to your MCP client config (e.g. Claude Desktop `claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "records-demo": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-demo/src/server.js"],
      "env": { "MCP_ALLOW_WRITES": "true" }
    }
  }
}
```
Then ask Claude to "list records", "create a record named Widget for 42", or "review record rec_1".

## Turning this into a real integration
Replace `RecordStore` with a client for the target API (REST/GraphQL), map each business action
to a tool, keep the env-gated write safeguard, and add auth via environment secrets (never in code).
The tool surface, validation, error mapping, and tests stay exactly as they are here.

*Author: Shane · built with Claude Code · MIT.*