🤖 @backtest-kit/mcp

import { setConfig } from '@backtest-kit/mcp';
setConfig({
  CC_MCP_HOST: '127.0.0.1',
  CC_MCP_PORT: 60051,
  CC_MCP_NAME: 'my-mcp',
});
Copy

Values passed to setConfig() always take precedence over env vars.

When the package runs as the stdio MCP server (npx @backtest-kit/mcp, the backtest-kit-mcp command, or node build/index.mjs), the bridge address can be passed as CLI arguments instead of env vars:

npx -y @backtest-kit/mcp@latest --host 127.0.0.1 --port 60051
Copy

{
  "mcpServers": {
    "trading-signals": {
      "command": "npx",
      "args": ["@backtest-kit/mcp@latest", "--host", "127.0.0.1", "--port", "60051"]
    }
  }
}
Copy

or

npx -y @backtest-kit/mcp@latest --sse 8081
Copy

claude mcp add --transport sse trading-signals http://localhost:8081/sse
Copy

Resolution order for host and port: CLI arguments → setConfig() → env vars → defaults (127.0.0.1:60051).

CLI arguments apply only in binary mode — an entrypoint guard (helpers/getEntry.ts) makes sure that when the package is imported as a library, the host process's argv never leaks into the configuration.

By default the stdio server registers all five tools. --tools takes a comma-separated list of tool names and registers only those — the rest never appear in the agent's tool list at all, so no prompt engineering is needed to keep the agent away from them:

# Read-only agent: it can watch the portfolio but not touch it
npx @backtest-kit/mcp --tools get_status

# Observe and exit, but never open or average
npx @backtest-kit/mcp --tools get_status,close_position,notify_user
Copy

{
  "mcpServers": {
    "trading-signals": {
      "command": "npx",
      "args": ["@backtest-kit/mcp", "--tools", "get_status,close_position"]
    }
  }
}
Copy

Valid names are exactly the tool names the agent sees: get_status, open_position, close_position, average_position, notify_user. An unknown name fails the startup with the list of unknown and available names — a typo silently dropping a tool would only surface later as odd agent behaviour.

This is transport-level narrowing, independent of the engine's permissions field in the MCP schema. The two compose: --tools decides what the agent is offered, permissions decides what the engine accepts. Restricting a tool here is convenient for running several agents against one trading process with different mandates; enforcing the boundary for real belongs in the schema, which the agent cannot bypass.

By default the server speaks stdio: the agent spawns the process and talks to it over stdin/stdout. --sse swaps that for SSE over HTTP, so a client can attach across the network instead of owning the process:

# Default port 8080
npx @backtest-kit/mcp --sse

# Explicit port
npx @backtest-kit/mcp --sse 9000
Copy

Two endpoints are exposed:

SSE is a two-channel transport: the GET stream stays open for the whole session and carries every server→client message, while the client POSTs its own messages to the second endpoint. The sessionId handed out on connect correlates the two, so several clients can attach at once — each gets its own session and closing one does not disturb the others.

Point a connector that bridges an external MCP endpoint to a local HTTP one at http://localhost:8080/sse. The startup line is written to stderr, never stdout, so the same binary can be piped either way without corrupting a JSON-RPC stream.

--sse composes with everything else — --tools still narrows the surface, --host / --port still point at the trading bridge (those describe where the engine lives, which is unrelated to how the agent connects):

npx @backtest-kit/mcp --tools get_status --sse 9000
Copy

The optional value is positional, so a path immediately after the flag is read as the port:

npx @backtest-kit/mcp --sse ./strategy.ts   # ✗ fails: "./strategy.ts" is not a port
npx @backtest-kit/mcp ./strategy.ts --sse   # ✓ path first, then the flag
Copy

A non-port value fails the startup rather than being ignored — silently treating it as "no port given" would swallow the strategy path and start with nothing loaded.

agent (Claude / any MCP client)
  └─ stdio JSON-RPC ─ backtest-kit-mcp          (this package, binary)
       tools/*.tool.ts
       └─ MCPCommandService ── HTTP POST ──► serve()   (this package, imported)
                                              routes/mcp.ts
                                              └─ MCPPublicService ─► MCP.* (backtest-kit)
                                                                      └─ Live.commitCreateSignal / commitClosePending
Copy

The stdio process never touches trading state — it only speaks HTTP. The trading process registers schemas, runs Live, and answers on /api/v1/mcp/*. Both roles ship in one package: importing it gives you serve(), executing it starts the stdio server (an entrypoint guard makes the side-effect import a no-op in library mode).

HTTP handlers never signal operation failure through status codes. Every response is 200 with:

{ "data": …, "status": "ok",    "error": "",                          "requestId": "…", "serviceName": "…" }
{            "status": "error", "error": "MCP Error: no active position for BTCUSDT" }
Copy

MCPCommandService throws when error is non-empty; the tool catches and returns the message to the agent as isError. Transport-level failures (engine down, wrong port) surface the same way via fetchApi's exception.

Request envelope: { clientId, serviceName, userId, requestId, data }. The mcpName is resolved server-side: CC_MCP_NAME if set, otherwise the first registered schema — the agent never needs to know it.

Public surface — functions/serve.function.ts (serve/getRouter), functions/setup.function.ts (setLogger), config/params.ts (setConfig/getConfig), index.ts re-exports + lib container.

Stdio server — main/entry.ts (McpServer + StdioServerTransport, entrypoint-guarded via helpers/getEntry.ts, --tools selection via helpers/getArgs.ts), tools/get_status.tool.ts, tools/open_position.tool.ts, tools/close_position.tool.ts, tools/average_position.tool.ts, tools/notify_user.tool.ts (zod-validated arguments, isError mapping).

HTTP bridge — config/router.ts (micro + router + CORS, /api/v1/mcp/* mount), routes/mcp.ts (five POST handlers, always-200 envelope), routes/health.ts.

Service layer (lib/services/):

• command/MCPCommandService.ts — HTTP client used by the tools (fetchApi against CC_MCP_HOST:CC_MCP_PORT).
• public/MCPPublicService.ts — server-side entry: resolves mcpName (CC_MCP_NAME or first schema), validates arguments, delegates down.
• private/MCPPrivateService.ts — thin logging proxy over the backtest-kit MCP singleton.
• base/LoggerService.ts — no-op by default (keeps stdio stdout clean); swap via setLogger.

DI & config — lib/core/{di,provide,types}.ts, lib/index.ts (container bootstrap), utils/omit.ts (log payload trimming).