# agentic-mcp-server

A production-grade **Model Context Protocol server** template in TypeScript, with the [agentic-kit](https://github.com/kalpesh122/agentic-kit) built in: one `AGENTS.md` every AI coding agent reads, skills that encode how to add tools, resources, and prompts, hooks that block destructive commands and force `just check` to pass before an agent can say "done", and a multi-model (Claude + Codex + Gemini) code-review council in CI.

It ships a small but complete example, a markdown knowledge base, exposed three ways: **tools** (`kb.search`, `kb.get`, `kb.add`, `sys.time`), **resources** (`kb://index`, `kb://doc/{slug}` with listing and completion), and **prompts** (`summarise-doc`, `answer-with-sources`). It runs over **stdio** for local hosts (Claude Code, Claude Desktop, Cursor) and over **Streamable HTTP** (stateless, bearer-token protected) for shared deployments. Tool handlers are SDK-free definitions; only `src/server.ts` and the transports touch `@modelcontextprotocol/sdk`, so upgrading to the v2 SDK line is a two-file change. Tests drive the server in-process through the official client, over real HTTP, and with the MCP Inspector CLI.

## 60-second quickstart

```bash
git clone https://github.com/kalpesh122/agentic-mcp-server my-mcp && cd my-mcp
just setup && just build
just test-inspector                # tools/list + a tools/call through the Inspector CLI
```

Register it in Claude Code (project scope) with the included `.mcp.json`, or:

```bash
claude mcp add --scope project kb -- node dist/index.js
```

Requirements: Node 24 (`.node-version`), [just](https://github.com/casey/just). Docker only for the image.

## Commands

| Command | What it does |
|---------|--------------|
| `just setup` | Install dependencies (pnpm 12 via corepack) |
| `just dev` / `just dev-http` | Run over stdio / Streamable HTTP with watch |
| `just test [pattern]` | Vitest (in-process client, HTTP transport, store, env) |
| `just test-inspector` | Build and drive `dist/index.js` with the Inspector CLI |
| `just inspect` | Open the Inspector UI against the built server |
| `just lint` / `just fmt` | Biome check / fix |
| `just typecheck` | `tsc --noEmit` |
| `just build` | Compile to `dist/` |
| `just check` | **Quality gate**: lint + typecheck + test + build |
| `just docker-build` / `just docker-up` | Image and compose (HTTP mode on 3333) |
| `just council` | Local multi-model code review of your branch |

## Capabilities

### Tools

| Tool | Description | Annotations |
|------|-------------|-------------|
| `kb.search` | Full-text search over the knowledge base; nested `filter` object (tag, sort); returns hits + `structuredContent` | read-only, idempotent |
| `kb.get` | Full markdown of one document by slug | read-only, idempotent |
| `kb.add` | Create a document; refused unless `MCP_ALLOW_WRITES=true` | write, non-destructive |
| `sys.time` | Current time, optional IANA zone | read-only |

### Resources

| URI | Content |
|-----|---------|
| `kb://index` | JSON list of `{slug, title, tags}` |
| `kb://doc/{slug}` | One document as `text/markdown`; template lists all docs and completes slugs |

### Prompts

| Prompt | Arguments | Purpose |
|--------|-----------|---------|
| `summarise-doc` | `slug` | Five-bullet summary of one document |
| `answer-with-sources` | `question` | Answer using only the knowledge base, citing slugs |

## Register the server

**Claude Code** (`.mcp.json`, committed in this repo):

```json
{ "mcpServers": { "kb": { "type": "stdio", "command": "node", "args": ["dist/index.js"] } } }
```

HTTP mode: `{ "type": "http", "url": "http://localhost:3333/mcp", "headers": { "Authorization": "Bearer ${MCP_AUTH_TOKEN}" } }` or
`claude mcp add --transport http --scope project kb http://localhost:3333/mcp --header "Authorization: Bearer $MCP_AUTH_TOKEN"`.

**Cursor** (`.cursor/mcp.json`): same `mcpServers` shape as above.

**Claude Desktop** (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`): same `mcpServers` shape; use an absolute path to `dist/index.js` and fully quit the app after editing.

## Configuration

See `.env.example`. `MCP_TRANSPORT` (`stdio` | `http`), `MCP_HTTP_PORT`/`MCP_HTTP_HOST`, `MCP_AUTH_TOKEN` (required, 16+ chars, in HTTP mode), `KB_DIR` (markdown directory), `MCP_ALLOW_WRITES`, `LOG_LEVEL`. The `--transport` CLI flag overrides the env.

## Folder map

```
src/index.ts             CLI entry (--transport), env, knowledge base, start
src/env.ts  src/log.ts   zod env · pino to stderr
src/server.ts            createServer(deps): registers tools, resources, prompts (only SDK touchpoint besides transports)
src/tools/               types.ts (defineTool, text, failure) + one file per tool + index.ts
src/resources/           kb://index, kb://doc/{slug}
src/prompts/             summarise-doc, answer-with-sources
src/kb/store.ts          KnowledgeBase (load, search, get, add)
src/transports/          stdio.ts · http.ts (express: /health, bearer-protected stateless /mcp)
test/                    helpers (in-memory client), server.test.ts, http.test.ts
data/*.md                knowledge base documents (frontmatter title/tags)
.claude/ .agents/ AGENTS.md   the agentic kit
```

## How AI agents work in this repo

- `AGENTS.md` (≤150 lines) is the map: commands, layout, hard rules, definition of done. `CLAUDE.md` imports it; Gemini, Copilot, and Cursor point at it.
- Skills in `.claude/skills/` (mirrored in `.agents/skills/`): `add-tool`, `add-resource`, `add-prompt`, plus the kit's `brainstorm-spec`, `tdd`, `debug`, `code-review`, `council-review`, `verify-before-done`, `adr`, `git-hygiene`.
- Hooks in `.claude/settings.json`: block `rm -rf`, force pushes, reading `.env`; protect lockfiles; format every edited file with Biome; run `just check` when the agent tries to stop and block if it fails.
- CI: `ci.yml` runs `just check` and the Inspector smoke, then builds the image; `ai-council-review.yml` has three models review every PR and post one consolidated comment.
- `specs/001-knowledge-base/` shows the spec → plan → tasks flow; `docs/adr/` records why the stack looks like this.

## Swap-outs

- **Domain**: replace `src/kb/` and the tools in `src/tools/` with your own; keep `defineTool` and the tests' shape.
- **Auth**: replace `bearerAuth` in `src/transports/http.ts` with OAuth 2.1 resource-server checks; keep `/health` public.
- **SDK v2** (`@modelcontextprotocol/server` 2.x, spec 2026-07-28): change the imports in `src/server.ts` and `src/transports/*`; tool definitions do not change.
- **Hosting**: the image runs HTTP on 3333 behind any TLS-terminating proxy.

## License

MIT © Kalpesh Mali