calc-mcp: Instructions file for Claude Code

Project Rules

Overview

MCP (Model Context Protocol) server providing 21 tools for calculations and operations that LLMs struggle with. Published as @coo-quack/calc-mcp on npm.

Tech Stack

• Runtime: Bun
• Language: TypeScript (strict mode)
• Linter/Formatter: Biome (2-space indentation)
• Docs: VitePress (docs/)
• Dependencies: @modelcontextprotocol/sdk, zod, mathjs, date-fns

Commands

• bun test — Run all tests
• bun run build — Build for production (minify + sourcemap + shebang)
• bun run lint — Biome check
• bun run format — Biome format
• bun run dev — Start dev server
• bun run docs:dev — VitePress dev server

Project Structure

src/index.ts          # MCP server entry, tool registration
src/tools/*.ts        # 21 tool modules (one file per tool)
tests/tools/*.test.ts # Unit tests (one file per tool)
tests/e2e/            # E2E tests (Node.js test runner via MCP protocol)
docs/                 # VitePress documentation site

Tool Architecture

Every tool follows the same pattern:

import { z } from "zod";
import type { ToolDefinition } from "../index.js";

const schema = {
  param: z.string().describe("Description"),
};

const inputSchema = z.object(schema);
type Input = z.infer<typeof inputSchema>;

export function execute(input: Input): string {
  // Pure business logic, returns string (JSON or plain text)
}

export const tool: ToolDefinition = {
  name: "tool_name",        // snake_case
  description: "LLM-facing description",
  schema,                   // NOT inputSchema
  handler: async (args: Record<string, unknown>) => {
    const input = inputSchema.parse(args);
    return execute(input);
  },
};

Registration: import in src/index.ts → add to tools array.

Adding a New Tool

1. Create src/tools/<name>.ts — export execute() and tool
2. Create tests/tools/<name>.test.ts — test execute() directly
3. Register in src/index.ts — import and add to tools array
4. Update docs: README.md, docs/tools.md, docs/examples.md