MCP 服务器

Grant Workflow MCP Server

A Python MCP server for querying grant applications and previewing or committing scoped reviewer reassignments.

README

Grant Workflow MCP Server

A small Python MCP server for safely querying grant applications and previewing or committing scoped reviewer reassignments. It was built for the WizeHive take-home exercise.

Stack

Python, FastMCP, Pydantic, and PyMongo
MongoDB in Docker for local data
Anthropic tool-use loop for the optional natural-language agent
A JSON golden set and runnable evaluation script

Setup

Create an environment and install dependencies:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env

Start MongoDB and seed the supplied JSON-lines files:
```
docker compose up -d
.\scripts\seed.ps1
```
The seed script requires the MongoDB Database Tools mongoimport executable. Source data remains in candidate_packet/data/; this avoids maintaining a duplicate copy.
Start the MCP server over stdio:
```
python -m server.mcp_server
```

Agent and evaluations

Set ANTHROPIC_API_KEY in .env, then run:

python -m evals.run_evals

The runner prints pass/fail per golden question, aggregate accuracy, per-question latency, and total input/output tokens. It intentionally exits rather than pretending to evaluate if no API key is configured.

Run the lightweight validation tests with pytest.

Tools

The four required tools are search_applications, get_application, cycle_summary, and reassign_reviewer. A very narrow read-only reviewer_workload_summary helper is included because the required agent question ("Which reviewer has the most active assignments?") cannot be answered from the four specified data paths. It prevents the agent from guessing or receiving raw reviewer documents.

reassign_reviewer is preview-first: dry_run=True by default, a cycle or status scope is mandatory, commit requires the exact preview count, and commits over 50 records are rejected. The MCP server never prompts on standard input; confirmation is supplied through the structured expectedCount field so an agent session cannot hang. See DESIGN.md for residual risks.

MCP Server:

Running the MCP server once through MCP Inspector, confirming the five exposed tool names and schemas. <img width="711" height="378" alt="image" src="https://github.com/user-attachments/assets/e6794552-952f-48df-a383-31009ed15f09" /> <img width="705" height="375" alt="image" src="https://github.com/user-attachments/assets/bf9cd3eb-474f-4de1-a985-ebdb77087a39" />

Running safe verification calls to confirm tools:

search_application

get_application <img width="601" height="318" alt="image" src="https://github.com/user-attachments/assets/467f7119-2cfe-4142-b13c-777ccb056f2c" /> <img width="559" height="566" alt="image" src="https://github.com/user-attachments/assets/2b26edb0-39fb-441f-9f62-66c906961232" /> <img width="525" height="557" alt="image" src="https://github.com/user-attachments/assets/49bffcdf-e9d2-408f-a662-4e5dd8a23b97" />
cycle_summary <img width="585" height="330" alt="image" src="https://github.com/user-attachments/assets/924ff834-8cdd-47b3-858e-7f219d2a1398" /> <img width="535" height="412" alt="image" src="https://github.com/user-attachments/assets/63eea109-efb7-46f0-a727-6235c2c58262" />
reviewer_workload_summary <img width="508" height="524" alt="image" src="https://github.com/user-attachments/assets/d01a8df9-178b-4971-b8f2-6fdf38d09e84" />
reassign_reviewer <img width="575" height="426" alt="image" src="https://github.com/user-attachments/assets/4a1c46ef-9475-4c78-a519-c32ee17e03ed" /> <img width="581" height="286" alt="image" src="https://github.com/user-attachments/assets/d0027b80-0f30-4833-a023-6a64cf6603ff" /> <img width="568" height="493" alt="image" src="https://github.com/user-attachments/assets/13d3f031-4b31-414c-bbbe-6249808d9acb" /> <img width="524" height="269" alt="image" src="https://github.com/user-attachments/assets/555c7adc-c9d9-4bc1-9f62-7b5a628727d1" />