backlog_mcp AGENTS.md

AGENTS.md — Agent Instructions for backlog-mcp

This file is the canonical instruction set for any AI agent working on this project. Read this file in full before starting any task.

---

What Is This Project?

backlog-mcp is a TypeScript MCP (Model Context Protocol) server that provides AI agents with read access to a Backlog (Nulab) space. Authentication uses a static API Key stored in .env — no browser or Playwright session required.

Architecture Rules

1. Server uses factory pattern. Each incoming MCP request gets a new McpServer + StreamableHTTPServerTransport pair. Never reuse a server instance across requests.

2. Auth is a config concern, not a tool concern. The BacklogHttpClient receives apiKey from config at construction time. Tool handlers never touch auth directly.

3. HTTP-first for Backlog access. All Backlog REST API calls go through src/backlog/http-client.ts using Axios. The API Key is injected automatically via axios.create({ params: { apiKey } }).

4. Zod validates everything. Environment variables (src/config.ts) and tool inputs (each tool's schema) are all validated with Zod before use.

5. Two-layer type system. Raw Backlog API response types live in src/types/backlog-api.ts. Normalized domain types used by handlers live in src/types.ts. Mappers in src/backlog/mappers.ts bridge the two. Never use raw types outside of http-client.ts and mappers.ts.

Coding Standards

• TypeScript strict mode. No any. No implicit types.
• ESM with .js extensions. All imports must end in .js (NodeNext module resolution).
• Errors use McpError. Every business error must use the McpError class with a typed code. Use factory helpers from src/errors.ts.
• Tool errors set isError: true. MCP clients rely on this flag. Never return an error as normal content.
• 401/403 from Backlog = invalid API key. assertOk() in the HTTP client handles this — tool handlers just catch McpError.
• Utility functions in src/utils.ts. Shared helpers (e.g. date formatting, string manipulation) must live in src/utils.ts, not inline in tool or handler files.
• Prefer libraries over hand-rolled code. For common tasks (date formatting, etc.), use well-known npm packages instead of writing custom implementations.
• Raw API response types in src/types/backlog-api.ts. Types that mirror the exact shape of Backlog REST API responses must live there, separate from the normalized application interfaces in src/types.ts.