mcp-metro: Instructions file for Codex

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

An MCP (Model Context Protocol) server built on the fa-mcp-sdk framework. It exposes tools, prompts, and resources to AI agents via STDIO or HTTP/SSE transports.

Commands

# Build & run
yarn build                 # tsc
yarn cb                    # clean dist/ + build
yarn start                 # node dist/src/start.js (HTTP mode)
node dist/src/start.js stdio   # STDIO mode (Claude Desktop)

# Lint & typecheck
yarn lint                  # oxlint
yarn lint:fix              # oxlint --fix
yarn format                # oxfmt --check
yarn format:fix            # oxfmt
yarn typecheck             # tsc --noEmit

# Tests
yarn test                  # jest (all tests)
yarn test:mcp              # STDIO transport tests
yarn test:mcp-http         # HTTP transport tests
yarn test:mcp-sse          # SSE transport tests
npx jest tests/path/to/file.test.ts   # single test file

# Utilities
yarn check-llm             # Validate OpenAI API key for Agent Tester
yarn generate-token        # JWT token generator UI

# JWT token generation (CLI)
node scripts/generate-jwt.js -u <username> -ttl <duration> [-s <service>] [-p <params>]
# duration: <N>s | <N>m | <N>d | <N>y
# example: node scripts/generate-jwt.js -u admin -ttl 30d -s my-mcp -p "role=admin;team=ops"

# JWT generation API (HTTP endpoint, requires webServer.genJwtApiEnable: true)
# POST /gen-jwt  {"username":"user","ttl":"30d","service":"svc","params":"key=val"}

yarn consul:unreg          # deregister from Consul

JWT Token Generation (Skill /gen-jwt)

Generate JWT tokens for MCP server authentication using the /gen-jwt skill. Triggers: user asks to generate/create a JWT token, mentions "jwt", "token for user", "generate a token for".

Start/stop the server: yarn build && yarn start. Stop with Ctrl+C. Port is in config/default.yaml → webServer.port. Force stop: node scripts/kill-port.js <port>.