# MCP Tool Server for Ticketing Automation

A local, fully free demonstration of the **Model Context Protocol (MCP)** — a Python-based MCP server exposing IT helpdesk ticketing operations as tools, connected to Claude Code as a real agentic client.

## What this demonstrates

- Building an MCP server from scratch using Anthropic's official Python SDK
- Wrapping domain logic (a ticketing system) as MCP tools with clean schemas
- Connecting a real AI agent (Claude Code) as an MCP client and observing genuine tool-selection reasoning, not scripted calls
- Instrumenting tool calls with success/failure and latency metrics
- Debugging a real Python decorator/introspection bug end-to-end

## Architecture

```
Natural language request
        │
        ▼
   Claude Code (MCP client)
        │  stdio / JSON-RPC
        ▼
   server.py (MCP server, FastMCP)
        │
        ▼
   database.py (SQLite: tickets.db)
        │
        ├── tickets table        (ticket data)
        └── tool_calls_log table (success/failure + latency per call)
```

## Tools exposed

| Tool | Description |
|---|---|
| `create_ticket_tool(title, description)` | Creates a new ticket, status defaults to `open` |
| `search_tickets_tool(keyword, status)` | Searches tickets by keyword and/or status |
| `update_status_tool(ticket_id, new_status)` | Updates a ticket's status |

## Tech stack (100% free, no API costs)

- **Python 3.10** — implementation language
- **Anthropic MCP Python SDK** (`mcp[cli]`, pinned to `<2.0.0`) — open-source protocol implementation
- **SQLite** (Python standard library) — local, file-based data store
- **MCP Inspector** — official browser-based tool for manual testing/debugging of the server in isolation from any AI client
- **Claude Code** — free agentic client (uses existing claude.ai login, not the metered API) that reasons over the exposed tools and decides when to call them

No cloud hosting, no Docker, no paid API keys. Runs entirely on a local machine.

## Metrics

Every tool call is wrapped in a `track_metrics` decorator that records success/failure and latency (ms) into a `tool_calls_log` table. A separate script, `check_metrics.py`, aggregates this into a summary report:

```
Total tool calls: 7
Successful: 7
Success rate: 100.0%
Average latency: 9.68 ms

Per-tool breakdown:
  create_ticket_tool: 3 calls, 100.0% success, 13.03 ms avg latency
  search_tickets_tool: 3 calls, 100.0% success, 3.16 ms avg latency
  update_status_tool: 1 calls, 100.0% success, 19.21 ms avg latency
```

Note: this measures **tool execution latency** (time inside the Python function), not full end-to-end request latency through the MCP protocol and model reasoning.

## Design decisions worth explaining

- **Business logic separated from protocol layer**: `database.py` (pure functions, tested standalone first) is independent of `server.py` (the MCP wrapper). Bugs in one layer can't be confused with bugs in the other.
- **SQLite over Postgres/MySQL**: zero setup, file-based, appropriate for a single-user demo. A real multi-user production system would need Postgres for concurrent write support.
- **Parameterized SQL queries** (`?` placeholders) used throughout to prevent SQL injection.
- **Operational data (`tool_calls_log`) kept separate from domain data (`tickets`)** — a real pattern for separating observability data from business data.
- **Explicit, detailed tool docstrings** — these are what the AI client actually reads to decide when/how to use each tool; vague docstrings measurably degrade tool-selection accuracy.

## A real bug I hit and fixed

Wrapping tools in a metrics-tracking decorator broke the MCP SDK's ability to read each tool's real parameter list — the Inspector started showing generic `args`/`kwargs` fields instead of `title`/`description`. Cause: a hand-written decorator hides the original function's signature from introspection tools (like the `inspect` module the MCP SDK uses to build tool schemas), even if you manually copy over `__name__` and `__doc__`. Fixed using Python's standard `functools.wraps`, which preserves the full signature, not just the name and docstring.

## How to run it

```bash
# 1. Activate the virtual environment
.\venv\Scripts\Activate.ps1

# 2. (Optional) Test the server in isolation
mcp dev server.py

# 3. Register with Claude Code (one-time)
claude mcp add ticketing-server -- python server.py

# 4. Launch Claude Code from the project folder and just talk to it
claude
> Create a ticket for a broken projector in the main conference room, then search for tickets related to the projector to confirm it was created.

# 5. Check aggregated metrics
python check_metrics.py
```

## What I'd add with more time

- Deduplication logic for near-identical tickets
- A fourth tool (e.g. `delete_ticket` or `assign_ticket`) to test more complex multi-step agent chains
- Postgres backend for concurrent access
- Containerizing the server (Docker) for a more "enterprise deployment" story
- HTTP/SSE transport instead of stdio, to demonstrate a remote (not just local) MCP server