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.

Related MCP server: MCP API Tool Demo

Run it

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):

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