Code Review

Code Review — FMP MCP Server

You are reviewing changes to this repository. This server exposes 253+ read-only financial-data tools over MCP (HTTP/SSE) using toolception + Fastify. Most of the load-bearing rules here are non-obvious and live in the intent layer (the AGENTS.md hierarchy), not in the code. A generic review misses them. Your job is to catch real bugs and any violation of this repo's documented invariants.

Work through the steps in order. Do not skip step 1 or step 3 — nor step 4 when the diff touches the toolception integration surface.

1. Load behavioral guidelines

Invoke the karpathy-guidelines skill first (via the Skill tool) and review through its four lenses:

• Surgical changes — every changed line should trace to the PR's stated purpose. Flag drive-by refactors, reformatting, or "improvements" to untouched code.
• Simplicity — flag speculative abstraction, unused config/flexibility, and error handling for impossible states.
• Surfaced assumptions — flag silent decisions where multiple interpretations existed.
• Verifiable success — flag behavior changes that arrive without a test proving them.

2. Scope the diff

Determine what changed.

• Given a PR reference — CI passes it as owner/repo/pull/N. Extract the number N and run gh pr diff N (the repo is inferred from the checkout); a full PR URL also works.
• Otherwise (local working branch) — diff against main:

git diff --merge-base main --stat
git diff --merge-base main

List the changed files and collapse them to the source directories touched — that set drives step 3.

3. Load the intent layer (live read — do not rely on memory)

Always read the root AGENTS.md (it defines the intent layer and its maintenance rules). Then, for each touched directory, read its matching doc. Read the area's FLOW.md too when one exists. Loading is hierarchical and T-shaped: root + the specific node.

Directories without their own doc (src/constants, src/prompts, src/schemas, src/types, src/utils) inherit the root AGENTS.md plus the nearest parent that does have one — review them on general dimensions (step 5) and the invariants in scope.

The rules you cite in findings come from the docs you just read — quote the actual Key Rule / Anti-pattern / Pitfall, do not paraphrase from this skill.

4. Toolception deep-check (only when the diff touches the integration surface)

toolception is the core MCP layer, but node_modules/toolception ships compiled dist/ only — the readable source and the real API contracts live upstream at the public repo code-rabi/toolception. When the diff touches the integration surface, verify it against the actual upstream source, not memory.

Trigger when the diff touches any of: src/toolception-adapters/**, src/index.ts (the createMcpServer config), src/endpoints/*.ts (defineEndpoint), src/prompts/** (the McpServer.prompt() extension), or bumps toolception in package.json / package-lock.json.

Fetch the source with gh, pinned to the installed version:

1. Read the installed version from node_modules/toolception/package.json (the version field) with the Read tool. The matching tag is v<version> (e.g. v0.6.3).
2. Pull the relevant source — raw, no base64 decode. Substitute that version into ref:

gh api -H "Accept: application/vnd.github.raw" "/repos/code-rabi/toolception/contents/src/index.ts?ref=v<version>"
gh api "/repos/code-rabi/toolception/contents/src/<area>?ref=v<version>" --jq '.[].name'   # list a dir
gh search code --repo code-rabi/toolception "<symbol>"                                      # locate a symbol

Offline fallback for the type contracts: node_modules/toolception/dist/index.d.ts.

Fetch the area that matches the change:

Verify the diff against the fetched contracts:

• The config this repo passes to createMcpServer (catalog, moduleLoaders, startup{mode, toolsets}, context, sessionContext{queryParam}, exposurePolicy{namespaceToolsWithSetKey, maxActiveToolsets?, allowlist?}, createServer, http) still matches the upstream CreateMcpServerOptions type — flag renamed/removed/ retyped keys.
• ModuleLoader is still (context?) => McpToolDefinition[] | Promise<McpToolDefinition[]> and the McpToolDefinition shape the adapters / ToolCollector emit still matches upstream.
• McpServer.prompt() still exists upstream — a runtime extension reached via type cast that silently no-ops if dropped (list_mcp_assets then vanishes with no error).
• On a toolception version bump: fetch the new tag's source and re-verify every contract above. Flag any breaking rename/removal/retype (precedent: initialToolsets → toolsets in 0.5.1).

Don't restate the intent layer — docs/src/toolception-adapters/AGENTS.md and docs/src/AGENTS.md / FLOW.md already hold this repo's toolception pitfalls; cite them. Upstream toolception ships its own AGENTS.md files too (e.g. src/session/AGENTS.md) — fetch them for its documented intent when a change is subtle.