# fs-scoping-mcp

An [MCP](https://modelcontextprotocol.io) 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:

| Tool | What it does | PM job-to-be-done |
|---|---|---|
| `search_use_cases` | Vector search over a curated bank of 18 FS/banking AI use case patterns | "Has anyone solved something like this before, and what's the typical ROI driver / risk level?" |
| `list_use_case_categories` | Lists the use-case categories | Filter the search above |
| `estimate_roi` | Transparent, first-pass ROI math (payback period, 3-year ROI %, all assumptions echoed back) | "Is this worth building, and what does the client need to believe for that to be true?" |
| `flag_compliance_considerations` | Keyword-driven FS regulatory checklist (KYC/CIP, AML/BSA, Fair Lending, SR 11-7, GLBA, GDPR, EU AI Act, PCI-DSS) | "What will compliance/legal ask about, before they ask it in front of the client?" |
| `draft_problem_statement` | Turns workshop notes into a structured Situation/Complication/Outcome/Metrics brief | "Get everyone to sign off on the same problem before solutioning starts." |

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

```mermaid
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

```bash
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):

```bash
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:

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

## Test it

```bash
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](LICENSE).