tossinvest-openapi-mcp: Instructions file for Claude Code

CLAUDE.md

Guidance for AI agents (Claude Code and others) working in this repository.

What this is

An MCP (Model Context Protocol) server, distributed via npm and run over stdio, that exposes the Toss Securities (토스증권) Open API specification as agent-friendly tools.

It is read-only: it explains the API, it never calls it. There is no authentication, no network access at runtime, and no account/credential handling. All data comes from the bundled openapi.json.

Architecture

• openapi.json — the bundled Toss Securities OpenAPI 3.1 document. Source of truth.
• src/spec/store.ts — loads openapi.json once, flattens operations, indexes tags & schemas, and resolves local $refs (with cycle protection via deref).
• src/format.ts — renders operations and schemas as compact, agent-readable markdown.
• src/codegen.ts — generates curl / TypeScript / Python request samples.
• src/guides.ts — curated, use-case-oriented integration guides; each step references a real operationId that is validated against the spec at request time.
• src/server.ts — registers all MCP tools (McpServer.registerTool) with zod input schemas.
• src/index.ts — stdio entry point (#!/usr/bin/env node).

Conventions

• Tool descriptions are written for agents, in English — imperative, action-oriented, and they cross-reference related tools (e.g. "use get_endpoint for full detail").
• Tool output is markdown text, optimized for token efficiency: lists/overviews first, full detail via a drill-down tool. Never dump raw JSON when a field tree is clearer.
• Never invent spec content. If something is not in openapi.json, say so.
• stdio servers must not write to stdout; all logging goes to stderr.

Build & verify

npm install
npm run build          # tsc → dist/
node dist/index.js     # starts the stdio server (logs to stderr)

To smoke-test tools, drive the server with MCP JSON-RPC over stdio (initialize → notifications/initialized → tools/list → tools/call).