krff-shell — Natural Language Finance Shell

Overview

An MCP (Model Context Protocol) server and CLI that wraps the forensic-accounting-toolkit's analytics as 11 tools callable from Claude Desktop or any MCP-compatible client. Tools span the full analytical stack: company registry lookups, trading calendar computations, Beneish M-Score screening, CB/BW dilution assessment, anomaly score retrieval, and JFIA literature search. All tools execute parameterized SQL through a shared DuckDB connection layer (`krff/db.py`) — no string interpolation in query construction. Per-company HTML reports embed interactive Plotly charts as self-contained files with no external CDN dependency. FastAPI REST endpoints mirror all 11 MCP tools for non-MCP integrations.

Problem

The forensic-accounting-toolkit's 12 component libraries each have their own Python API. Using them together requires knowing which library to call, which parquet files to load, how to join results across data sources, and how to format output for human review. A practitioner answering 'which KOSDAQ companies had both a high M-Score and a CB repricing event in the same fiscal year?' must orchestrate at least three libraries, two parquet schemas, and undocumented join logic. krff-shell collapses this into a single natural-language query: the MCP layer handles routing, data loading, and result formatting, while the practitioner describes what they want.

Constraints

• Local-only deployment — krff-shell runs against local parquet files produced by the toolkit's data pipeline; no hosted service, no shared database; each user runs their own instance
• MCP protocol requires all tool inputs and outputs to be JSON-serializable — Plotly figure objects must be serialized and returned as HTML strings, not as native objects
• SQL injection risk in DuckDB: parameterized queries using `?` placeholders work in WHERE clauses but not for table names or column identifiers — dynamic table selection required a different injection mitigation strategy
• FastAPI REST endpoints must maintain schema parity with MCP tool signatures — drift between the two interfaces is not caught by the type checker and required dedicated parity tests
• Claude narrative synthesis is optional and gated behind an API key check — the shell must be fully functional without an active Anthropic API key

Approach

Built `krff/db.py` as a singleton DuckDB connection manager with typed parameterized query helpers. 11 tools implemented as standard Python functions; MCP registration and FastAPI route definition both reference the same function — no code duplication between interfaces. Per-company HTML reports use Plotly with `include_plotlyjs=True` (not CDN) so reports are viewable offline and do not depend on external asset availability. JFIA search (Tool 11) loads `jfia_catalog.json` at startup and runs keyword + abstract full-text matching, returning structured citation records. The test suite (317 tests) covers all 11 tool response schemas, all REST endpoint input/output contracts, SQL injection attempts on every parameterized field, and report HTML structure validation.

Key Decisions

Tech Stack

• Python ≥3.11, uv
• MCP SDK (Anthropic)
• FastAPI + uvicorn
• DuckDB
• Plotly
• pandas, PyArrow
• Anthropic SDK (claude-sonnet-4-6) — optional narrative synthesis
• jfia_catalog.json (Tool 11 data source)
• pytest (317 tests)

Result & Impact

• 11
  MCP tools
• 317
  Tests
• 11 (mirrors MCP tools)
  REST endpoints
• Self-contained HTML (Plotly)
  Report format

The conversational interface for the forensic-accounting-toolkit. Questions that previously required orchestrating multiple libraries and parquet schemas are answered as a single Claude Desktop query. The parameterized SQL layer and 317-test coverage make it the most hardened component in the toolkit from a code-quality standpoint. The self-contained HTML report format has been used in practitioner outreach — a single file attachment that opens in any browser with no dependencies.

Learnings

• SQL injection testing should be part of the initial test suite, not a later hardening pass. The DuckDB injection surface was only discovered when building tests for the demo — if tests had been written first, the f-string interpolation pattern would have been caught before it appeared in the main implementation.
• MCP tool design is an API design problem. The first iteration of several tools returned raw DataFrames serialized to JSON — useful for machine consumption, not for the Claude narrative layer or for human review. The second iteration returns structured objects with a summary string, a findings list, and a data block — a format that the LLM can narrate and a human can skim.
• Parity between MCP tools and REST endpoints is a maintenance constraint, not a one-time setup. The dedicated parity test suite (checking identical inputs produce identical outputs across both interfaces) is what catches drift when one interface's response schema is updated without updating the other.
• Optional Claude narrative synthesis is the right default. Practitioners using the tool for rapid screening do not need narrative for every result — they need the data fast. Narrative is valuable for the final output (the per-company HTML report) and for explaining anomalies to a non-technical stakeholder. Gating it behind an API key check makes the dependency explicit.