MCP server (TypeScript)

# AGENTS.md: MCP server (TypeScript)

This repository is a Model Context Protocol server built with the official TypeScript SDK (`@modelcontextprotocol/sdk`).
Check the installed SDK version in `package.json` before writing imports — APIs and import paths have changed between majors.

## Layout
```
src/index.ts         creates the server, registers tools/resources/prompts, connects the transport
src/tools/<name>.ts  one tool per file: exports a register(server) function
src/lib/             API clients and shared helpers
```

## Transport
- **stdio** for local servers launched by the agent. **stdout belongs to the protocol.** Never `console.log` —
  log with `console.error` (stderr) or a logger pointed at stderr. A stray print corrupts the JSON-RPC stream.
- **Streamable HTTP** for remote servers. Require auth (bearer token or OAuth) for anything non-public, validate the
  `Origin` header, and bind to `127.0.0.1` when running locally.

## Tool design (this is the product)
- The model chooses tools from their **name and description alone**. Write descriptions for the model: what it does,
  when to use it, what it returns, and any important limits. One to three sentences.
- Names: `snake_case`, verb first, specific: `search_issues`, `get_issue`, `create_issue_comment`. Not `issues` or `do_action`.
- Few, focused tools beat many overlapping ones. If two tools are often confused, merge them or sharpen the descriptions.
- Inputs: small, typed zod schemas with `.describe()` on every field. Use enums for fixed choices, sensible defaults, and bounded numbers (`limit` 1–50).
- Outputs: concise text the model can use. Return the fields that matter, not the whole raw API response.
  Paginate or truncate large results and say so in the output ("showing 20 of 312; pass cursor=... for more").
- Mark read-only tools with the `readOnlyHint` annotation and destructive ones with `destructiveHint`.

## Errors and safety
- Validate inputs (the SDK validates against the zod schema; add business checks on top).
- Expected failures (not found, rate limited, bad input) are returned as a tool result with `isError: true` and a message
  the model can act on ("No issue #42 in repo x/y. Use search_issues to find valid numbers."). Do not throw for them.
- Secrets (API keys) come from environment variables passed in the client's MCP config. Never return them in output.
- Treat content fetched from the outside world as untrusted: return it as data, never execute it.
- Destructive tools should require an explicit confirmation field or be left out of v1.

## Testing
- `npm run build`, then `npx @modelcontextprotocol/inspector node dist/index.js` to list and call tools by hand.
- Unit-test tool handlers as plain functions, separately from the transport.

## Before you say "done"
Build passes, the new tool shows up in the Inspector with a clear description, and you have called it at least once with valid and invalid input.

# CLAUDE.md

@AGENTS.md

## Claude Code notes
- Skills from this loadout live in `.claude/skills/`: `add-mcp-tool`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "MCP server (TypeScript)" v1.0.0 — https://loadout.jnw-it.com/loadouts/mcp-server-typescript/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes
- Skills from this loadout live in `.agents/skills/`: `add-mcp-tool`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "MCP server (TypeScript)" v1.0.0 — https://loadout.jnw-it.com/loadouts/mcp-server-typescript/ -->

---
description: MCP tool definition conventions
globs: src/tools/**/*.ts
alwaysApply: false
---

- Tool names are `snake_case`, verb first, unique across the server.
- Descriptions are written for the model: what, when to use, what it returns, limits. 1–3 sentences.
- Every input field has a zod type and `.describe(...)`. Bound numbers, use enums for fixed options, give defaults.
- Return concise `content: [{ type: "text", text }]`; summarise large API responses and paginate.
- Expected failures return `{ isError: true, content: [...] }` with an actionable message. Do not throw.
- Never write to stdout (`console.log`) — use `console.error`.
- Annotate read-only tools with `readOnlyHint: true`; destructive ones with `destructiveHint: true`.
- Secrets come from `process.env`, never from tool arguments or source code.

---
name: add-mcp-tool
description: Design, implement and test a new tool on a TypeScript MCP server. Use when the user asks to add a capability, endpoint or action to their MCP server.
---

# Add an MCP tool

## 1. Design first (write this down in your reply)
- **Name:** verb-first `snake_case`, not clashing with existing tools (check `src/tools/`).
- **Description:** 1–3 sentences for the model — what it does, when to use it instead of the other tools, what it returns.
- **Inputs:** each field with type, constraints and description. Keep it to what the model can reasonably know.
- **Output:** the few fields the model needs, formatted as short text or compact JSON.
- **Failure cases:** list them and the message each returns.
- **Side effects:** read-only, or does it change something? Destructive tools need a confirmation input or a human decision first.

If an existing tool almost does this, propose extending it instead of adding a near-duplicate.

## 2. Implement
Create `src/tools/<name>.ts` with a `register(server)` function, following the patterns already in the repo and the SDK version installed.
The shape (adjust to the installed SDK's API):

```ts
import { z } from "zod";
import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

export function register(server: McpServer) {
  server.registerTool(
    "get_weather",
    {
      title: "Get weather",
      description: "Current weather for a city. Use for present conditions only; there is no forecast. Returns temperature (°C), conditions and wind.",
      inputSchema: { city: z.string().min(1).max(100).describe("City name, e.g. 'Leeds' or 'Leeds, UK'") },
      annotations: { readOnlyHint: true },
    },
    async ({ city }) => {
      const result = await lookupWeather(city);
      if (!result) {
        return { isError: true, content: [{ type: "text", text: `No city called "${city}" found. Try adding the country.` }] };
      }
      return { content: [{ type: "text", text: `${result.name}: ${result.tempC}°C, ${result.summary}, wind ${result.windKph} km/h` }] };
    },
  );
}
```

Register it in `src/index.ts`. Put API calls in `src/lib/` with timeouts.

## 3. Test
1. `npm run build` (and `npm test` if there are tests; add one for the handler logic).
2. `npx @modelcontextprotocol/inspector node dist/index.js` → Tools → list → call with valid input, then invalid input.
3. Confirm nothing is written to stdout except protocol messages.

## 4. Report
The tool signature, its description, sample output, and how to reload it in the human's client
(most clients need the MCP server restarted to see new tools).