Project Structure and Package Layout

The AI Trading MCP repository is an npm workspaces monorepo. The root package ("pro") is the CLI entry point — it delegates execution to @backtest-kit/cli, which bootstraps the trading engine by reading the config files at the project root. Two workspace packages (@pro/agent, @pro/main) compile to CJS bundles and are injected into the CLI runtime via a path alias map. Everything below describes what lives where and why.

Directory Tree

config/
  loader.config.ts        # imports @pro/agent + @pro/main into the CLI runtime
  alias.config.ts         # maps @pro/* → packages/*/build/index.cjs
  setup.config.ts         # persistence modes + serve() — the MCP HTTP bridge
modules/
  paper.module.ts         # ccxt Binance: market data only — fills stay simulated in the engine
  live.module.ts          # + Broker adapter: real Binance spot execution
content/
  manual.strategy/
    manual.strategy.ts    # the deliberately empty strategy
    modules/              # per-strategy copy of the exchange modules
    session.txt           # GramJS session — the strategy folder is the process cwd
    dump/                 # data/ (persist) · mcp/ + images/ (audit) · report/ (jsonl)
packages/
  agent/                  # @pro/agent — scraper + manual_mcp (DI: Scraper / StatusController / StatusMarkdown)
  main/                   # @pro/main — entrypoints: --session, --entry --paper, --entry --live
mcp.servers.json          # Claude Code MCP config: npx @backtest-kit/mcp (stdio)

`config/` — CLI Runtime Configuration

The three files in config/ are read directly by @backtest-kit/cli at startup. They are not bundled — they run in the CLI’s Node.js process and configure the runtime before any strategy or package code executes.

loader.config.ts

Side-effect imports that pull @pro/agent and @pro/main into the CLI runtime. Without this, the workspace packages are never loaded and their registrations (MCP schema, entrypoints) never run.

alias.config.ts

Exports a map of bare specifiers to their resolved CJS bundles. The CLI uses this to rewrite require("@pro/agent") → packages/agent/build/index.cjs at runtime.

setup.config.ts

Wires persistence backends for every live/backtest subsystem (Storage, Recent, Notifications, Memory, State, Session), configures JSONL event logging, and calls serve() to start the MCP HTTP bridge on 127.0.0.1:60051.

`alias.config.ts`

export default {
    "@pro/agent": require("../packages/agent/build/index.cjs"),
    "@pro/main": require("../packages/main/build/index.cjs"),
}

The default export is the alias map. The CLI uses this to rewrite bare specifiers at runtime — require("@pro/agent") resolves to packages/agent/build/index.cjs and require("@pro/main") resolves to packages/main/build/index.cjs.

`loader.config.ts`

import "@pro/agent";
import "@pro/main";

These two side-effect imports are what executes the workspace packages inside the CLI runtime — they trigger the package entry points so that addMCPSchema and the --paper / --live / --session entrypoints are registered before the engine starts.

Before running npm start, you must run npm run build (or npm run build:win on Windows). This compiles both workspace packages with Rollup and emits packages/agent/build/index.cjs and packages/main/build/index.cjs. The alias map’s require() calls target these built artifacts — importing the raw TypeScript sources directly is not supported.

`modules/` — Exchange Adapters

paper.module.ts

Instantiates a ccxt Binance public client (no API keys). Provides real market data — live candles, order book, ticker — while all fills remain simulated inside the engine. Safe to run without Binance credentials.

live.module.ts

Instantiates a ccxt Binance authenticated client and registers a full spot broker adapter with three commit methods: commit_buy (guaranteed limit + market top-up entry), commit_trade (atomic OCO bracket placement), and commit_cancel (verified close with cancel-sweep). Requires BINANCE_API_KEY and BINANCE_API_SECRET.

`content/manual.strategy/` — The Strategy Folder

The strategy folder is the process working directory when the trading process starts. All relative paths — session.txt, dump/, and any strategy-local asset — resolve from here.

manual.strategy.ts

The deliberately empty strategy. Registers main_strategy with only logging callbacks (onOpen, onClose, onActivePing) and no signal logic. Entries happen exclusively when the agent calls open_position.

modules/

A per-strategy copy of the exchange modules (paper.module.ts, live.module.ts). The strategy loads its own modules so that swapping strategies does not affect or require changes to the global modules/ directory at the project root.

session.txt

The GramJS user session string written by --session auth. Read at startup to authorize the Telegram scraper. Treat it like a private key — it grants full access to the Telegram account that scanned the QR code.

dump/

Runtime output tree. data/ holds persisted state (signals, storage, memory, etc.), mcp/ and images/ are the MCP audit trail (one markdown file + referenced PNGs per get_status call), and report/ contains the JSONL event streams.

Both modules/ at the project root and content/manual.strategy/modules/ exist simultaneously. The root copy is the authoritative source; the strategy copy is what actually gets loaded at runtime. This separation means you can add or modify strategies without touching the shared module files — and you can experiment with a custom exchange adapter in one strategy without affecting others.

`packages/agent/` — `@pro/agent`

The agent package is the sensory layer: it scrapes the Telegram channel, composes what Claude sees on every get_status call, and dumps a full audit trail to disk.

Services

Three DI-registered services: ScraperService (GramJS client, fetches last 15 posts with images), StatusControllerService (composes the full get_status payload with queue guard and 90 s timeout), and StatusMarkdownService (dumps every response to dump/mcp/<stamp>.md and dump/images/).

DI Container

Dependency injection wiring in di.ts, provide.ts, and types.ts. The IoC container is the single import surface used by config/setup.ts when registering the MCP schema.

Config: params.ts

Reads CC_TELEGRAM_API_ID, CC_TELEGRAM_API_HASH, and CC_TELEGRAM_CHANNEL from the environment. Supplies a development fallback for the API pair but these should always be replaced with your own credentials from my.telegram.org.

Config: setup.ts

The single call that wires the Telegram feed into the MCP surface. Calls addMCPSchema with mcpName: "manual_mcp" and delegates getMessages to StatusControllerService.getStatus.

The MCP schema registration from packages/agent/src/config/setup.ts:

import { addMCPSchema } from "backtest-kit";
import ioc from "../lib";

addMCPSchema({
  mcpName: "manual_mcp",
  async getMessages(context, when, mcpName) {
    return await ioc.statusControllerService.getStatus(context, when, mcpName);
  },
});

`packages/main/` — `@pro/main`

The main package registers the three CLI entrypoints that the @backtest-kit/cli process dispatches based on command-line flags.

paper.ts (--paper)

Spawns Live.background() for every symbol in CC_SYMBOL_LIST, loads paper.module.ts from the strategy folder, and starts the engine in paper mode. Real market data, simulated fills.

live.ts (--live)

Same as paper but loads live.module.ts and connects the Binance spot broker adapter. Requires BINANCE_API_KEY and BINANCE_API_SECRET in the environment.

session.ts (--session)

Runs the one-shot GramJS QR authorization flow. Writes the resulting session string to session.txt in the current working directory. Run once from content/manual.strategy/ before the first paper or live start.

packages/main/src/config/params.ts parses CC_SYMBOL_LIST (defaults to 13 pairs: BTCUSDT, ETHUSDT, and eleven others) and provides the command-line argument parsing shared by all three entrypoints.

`mcp.servers.json` — Claude Code Integration

{
  "mcpServers": {
    "backtest-kit-mcp": {
      "command": "npx",
      "args": ["-y", "@backtest-kit/mcp@latest"]
    }
  }
}

Wires npx @backtest-kit/mcp@latest as a stdio MCP server into Claude Code. The stdio server holds no trading state — it forwards every tool call over HTTP to the trading process running on 127.0.0.1:60051. Start the full stack with:

npm run start:claude   # launches: claude --dangerously-skip-permissions --mcp-config ./mcp.servers.json

MCP Tools

Project Layout

Project Structure and Package Layout

Directory Tree

`config/` — CLI Runtime Configuration

loader.config.ts

alias.config.ts

setup.config.ts

`alias.config.ts`

`loader.config.ts`

`modules/` — Exchange Adapters

paper.module.ts

live.module.ts

`content/manual.strategy/` — The Strategy Folder

manual.strategy.ts

modules/

session.txt

dump/

`packages/agent/` — `@pro/agent`

Services

DI Container

Config: params.ts

Config: setup.ts

`packages/main/` — `@pro/main`

paper.ts (--paper)

live.ts (--live)

session.ts (--session)

`mcp.servers.json` — Claude Code Integration

Build docs developers (and LLMs) love

MCP Tools

Project Layout

Documentation Index

​Directory Tree

​config/ — CLI Runtime Configuration

loader.config.ts

alias.config.ts

setup.config.ts

​alias.config.ts

​loader.config.ts

​modules/ — Exchange Adapters

paper.module.ts

live.module.ts

​content/manual.strategy/ — The Strategy Folder

manual.strategy.ts

modules/

session.txt

dump/

​packages/agent/ — @pro/agent

Services

DI Container

Config: params.ts

Config: setup.ts

​packages/main/ — @pro/main

paper.ts (--paper)

live.ts (--live)

session.ts (--session)

​mcp.servers.json — Claude Code Integration

Build docs developers (and LLMs) love

Directory Tree

`config/` — CLI Runtime Configuration

`alias.config.ts`

`loader.config.ts`

`modules/` — Exchange Adapters

`content/manual.strategy/` — The Strategy Folder

`packages/agent/` — `@pro/agent`

`packages/main/` — `@pro/main`

`mcp.servers.json` — Claude Code Integration