typescript-mcp-server

MCP servers for the Portfolio API, served over HTTP by one Express app.

Endpoint	Server	Tools
/users/mcp	users-mcp	get_user_by_email, get_user_by_name
/accounts/mcp	accounts-mcp	get_accounts_by_user_id
/transactions/mcp	transactions-mcp	get_transactions_by_account_id

The tools chain: an email resolves to a user id, which resolves to accounts, whose ids resolve to transactions.

Default port: 4000. VS Code is wired to both in .vscode/mcp.json.

Scripts

Command	Purpose
npm run dev	Run from source with tsx
npm run build	Compile to dist/
npm start	Run the compiled build
npm run typecheck	Type-check without emitting

Configuration

Copy .env.example to .env. All variables are declared and validated in src/config.ts; startup fails with a readable message if any are invalid.

Variable	Default	Purpose
NODE_ENV	development	development enables pretty logs
LOG_LEVEL	info	debug/info/warn/error/silent
PORTFOLIO_API_BASE	http://localhost:3000	Base URL of the Portfolio API

Layout

src/
  index.ts               Mounts every MCP server on the Express app
  config.ts              Env vars, loaded and validated once
  logger.ts              pino logger (pretty in development)
  api.ts                 Shared axios client for the Portfolio API
  tool-result.ts         Builds the CallToolResult shape
  servers/
    users/
      index.ts           createUsersServer(): registers the tools
      users.api.ts       API calls that return data
      users.schema.ts    zod schemas for input and output
    accounts/
      index.ts           createAccountsServer()
      accounts.api.ts
      accounts.schema.ts
    transactions/
      index.ts           createTransactionsServer()
      transactions.api.ts
      transactions.schema.ts

Logging

Use the logger from src/logger.ts, which writes to stderr. Avoid console.log: it writes to stdout, which is the JSON-RPC wire if this project is ever switched back to the stdio transport.

Errors

Tool handlers do not need try/catch. The MCP SDK catches anything thrown and returns it as a tool result flagged isError, so an API call can simply throw when there is no match.

Schemas

outputSchema is enforced: the SDK validates structuredContent against it and fails the call on a mismatch — but it discards the parsed value, so any normalising has to happen in the .api.ts file before the data is returned.

json-server returns each primary key as a string ("id": "1") while leaving foreign keys numeric ("userId": 1). The schemas use z.coerce.number() on ids to smooth that over; they still advertise a plain integer. Check a new endpoint with curl rather than trusting db.json — json-server rewrites the ids it loads from there.

Adding a tool

Add the API call to <server>.api.ts, its schemas to <server>.schema.ts, and a server.registerTool(...) block in that server's index.ts.

Adding another MCP server

Create src/servers/<name>/ with the same three files, exporting a create<Name>Server(): McpServer, then add one line to the MCP_SERVERS array in src/index.ts.