# mcp-server-example

A minimal [Model Context Protocol](https://modelcontextprotocol.io) server in TypeScript. It exposes a small device catalog and SDK method reference to AI agents through three read-scoped tools, so an integrator can ask an agent questions like *"which readers support BLE?"* or *"how do I subscribe to access events?"* instead of reading documentation.

This is a sanitized, self-contained echo of a pattern I've used in production: put an MCP server in front of an SDK so third-party integrators can build against it through an agent.

## The design point

**The tool schemas are the governance layer.** There is deliberately no `unlock_door` tool in this server. An agent connected to it can list devices, get device details, and search SDK methods, and nothing else. "What can the AI do?" becomes a precise, auditable question answered by the schema, not by trusting the model to behave.

## Tools

| Tool | Scope |
|---|---|
| `list_devices` | Read. Optional filters by category and capability |
| `get_device` | Read. Single device by id |
| `search_sdk` | Read. Keyword search over SDK method reference |

## Run it

```bash
npm install
npm run inspect      # opens the MCP Inspector against this server
```

Or wire it into Claude Desktop / Cursor as a stdio server:

```json
{
  "mcpServers": {
    "example": { "command": "npx", "args": ["tsx", "/path/to/mcp-server-example/src/index.ts"] }
  }
}
```

Then ask: *"Which readers support BLE and what SDK call subscribes to events?"* and watch the agent chain `list_devices` and `search_sdk`.

## What I'd add for a real deployment

- An HTTP transport (SSE or streamable HTTP) for remote clients, with auth on the transport
- Per-client scoping: which tools a given integrator's token can see
- Audit logging of every tool invocation (who, what, when, arguments)
- Write-scoped tools only behind explicit approval workflows