fs-scoping-mcp

An MCP server that helps an Applied AI Product Manager scope AI engagements in Financial Services / Retail Banking — the first-weeks-of-an-engagement work of grounding a vague ask in proven patterns, sanity-checking a business case, flagging regulatory reality early, and turning a workshop's whiteboard into a brief an engineering team can build from.

Built to learn the Model Context Protocol hands-on, and shaped around a real job to be done rather than a toy example: search → estimate → flag risk → draft the brief is the actual loop a Forward Deployed AI PM runs with a client before anyone writes a line of solution code.

Why this exists

Most MCP demos wrap a single API call. This one instead models a small but real piece of a PM's toolkit, end to end:

It also exposes one resource (usecases://fs-banking/all, the raw knowledge base) and one prompt (discovery_workshop_starter), so the project exercises all three core MCP primitives — tools, resources, and prompts — not tools alone.

Architecture

flowchart LR
    Host["MCP Host<br/>(Claude Desktop / Claude Code / any MCP client)"] -->|JSON-RPC over stdio| Server["fs-scoping-mcp server<br/>(FastMCP)"]
    Server --> Tools["Tools<br/>search_use_cases · estimate_roi<br/>flag_compliance_considerations<br/>draft_problem_statement"]
    Server --> Resource["Resource<br/>usecases://fs-banking/all"]
    Server --> Prompt["Prompt<br/>discovery_workshop_starter"]
    Tools --> RAG["rag.py<br/>TF-IDF + cosine similarity<br/>over use_cases.json"]
    Tools --> ROI["roi.py<br/>pure business-case math"]
    Tools --> Compliance["compliance.py<br/>keyword rule engine"]
    Tools --> PS["problem_statement.py<br/>template generator"]

An engineering trade-off worth calling out

search_use_cases is retrieval-augmented, but it's not backed by a hosted embedding model or a vector database like Chroma/Pinecone/pgvector. It uses scikit-learn's TF-IDF vectorizer plus cosine similarity over an in-memory matrix. For a knowledge base of a few dozen short documents, that's a deliberate choice, not a shortcut:

• Zero network calls, no API key, starts in well under a second — the server works completely offline.

• Deterministic, so the test suite can assert exact top-1 results instead of fuzzy-matching embedding drift.

• The retrieval interface (VectorIndex.search) is identical to what a real dense-embedding + vector-DB implementation would expose. Swapping in sentence-transformers + Chroma later means changing rag.py's internals, not any tool-facing code or test.

This is the kind of trade-off worth saying out loud in an interview: RAG doesn't require a vector database, it requires a retrieval step over your own data — the storage/embedding choice is an implementation detail sized to the corpus.

Project layout

src/fs_scoping_mcp/
  server.py             # FastMCP app: tool/resource/prompt registration
  rag.py                # TF-IDF vector index over the use-case knowledge base
  roi.py                # ROI/business-case calculation
  compliance.py          # keyword-driven regulatory flagging
  problem_statement.py   # structured brief generation
  data/use_cases.json    # 18 curated FS/banking AI use case patterns
tests/                   # unittest-based tests (pytest-compatible), 22 tests

Setup

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

Run it

As a standalone stdio server (for testing with the MCP inspector):

mcp dev src/fs_scoping_mcp/server.py

Or point any MCP-compatible host at it directly. For Claude Desktop or Claude Code, add to your MCP config:

{
  "mcpServers": {
    "fs-scoping": {
      "command": "python3",
      "args": ["-m", "fs_scoping_mcp.server"],
      "cwd": "/absolute/path/to/fs-scoping-mcp/src"
    }
  }
}

Test it

pytest            # or: python -m unittest discover -s tests

22 tests cover the ROI math (including edge cases like a negative-payback scenario and invalid inputs), the RAG search (relevance ranking, category filtering, score ordering), the compliance rule engine (region aliasing, explicit non-determination when nothing matches), and the problem-statement generator (required-field validation).

Example: what a session looks like

> search_use_cases(query="drafting SAR narratives faster", top_k=1)
[{"score": 0.41, "id": "aml-transaction-monitoring-narratives", "title": "AML alert narrative generation", ...}]

> flag_compliance_considerations(use_case_description="Drafts SAR narratives from AML alerts", region="US")
[{"framework": "AML / Bank Secrecy Act (BSA)", "matched_keywords": ["aml", "sar"], "why_it_matters": "..."}]

> estimate_roi(process_name="SAR narrative drafting", volume_per_month=300,
               minutes_per_task_before=40, minutes_per_task_after=15,
               fully_loaded_hourly_cost_usd=55, one_time_implementation_cost_usd=80000,
               annual_run_cost_usd=20000)
{"hours_saved_per_year": 1500.0, "labor_savings_per_year_usd": 82500.0,
 "payback_period_months": 15.4, "three_year_roi_pct": ..., "caveats": [...]}

What this project is / isn't

• Is: a real, runnable MCP server with tests, built to learn the protocol's tool/resource/prompt primitives properly, shaped around genuine Applied AI PM workflows in a regulated industry.

• Isn't: a compliance authority (the flagging tool is explicit that it's a heuristic prompt for expert review) or a finance-grade ROI model (the ROI tool says so in its own output).

License

MIT — see LICENSE.