# MCP Server Demo — Company Records

A working [Model Context Protocol](https://modelcontextprotocol.io) server in
Python that exposes a small company CRM database to AI agents as callable tools,
plus a command-line chat agent that answers natural-language questions by
calling those tools.

Built on the official MCP Python SDK (`mcp`) and the official Anthropic SDK.

## What is MCP?

The Model Context Protocol is an open standard for connecting AI models to
external tools and data. Instead of hard-coding a model's integrations, you run
an **MCP server** that advertises a set of tools (each with a name, description,
and JSON input schema). Any **MCP client** — Claude Desktop, an IDE, or your own
agent — can connect, discover those tools, and let the model call them. The
server and client talk over a simple transport (here, stdio). The result: one
server works with any MCP-compatible client, and the model gets live, structured
access to your data instead of guessing from its training set.

## What this server does

It serves a fictional B2B CRM dataset (12 companies, 16 contacts, 19 deals,
stored in SQLite) through **five tools**:

| Tool | What it does |
|------|--------------|
| `search_companies` | Filter companies by industry, country, and/or minimum headcount |
| `get_company` | Full profile for one company, with its contacts and deals |
| `find_contacts` | Free-text search over contact name, title, or email |
| `deal_summary` | Pipeline totals — counts and dollar value, overall or by stage |
| `top_companies` | Rank companies by revenue, employees, or total deal value |

The dataset is generated by `company_data.py` into a local `company.db`. It's
entirely invented and safe to share; swapping in a real database means pointing
the tools at different SQL.

## How it works

```
                 stdio (MCP)                     tool calls
   chat.py  ─────────────────►  server.py  ─────────────────►  company.db
  (client)  ◄─────────────────  (server)   ◄─────────────────   (SQLite)
            tool results                       rows

   chat.py also calls the Claude API to decide *which* tools to call.
```

- `server.py` defines each tool with the `@mcp.tool()` decorator. FastMCP turns
  the function signature and docstring into the tool's input schema and
  description automatically, and handles the MCP wire protocol.
- `chat.py` launches the server as a subprocess over stdio, discovers its tools,
  and runs an agentic loop: it sends your question to Claude along with the tool
  list, Claude responds with tool calls, `chat.py` executes them against the
  server, feeds the results back, and repeats until Claude has a final answer.

## Setup

```bash
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt
```

The database is built automatically on first use. To build (or rebuild) it
explicitly:

```bash
python company_data.py
# Built .../company.db with {'companies': 12, 'contacts': 16, 'deals': 19}
```

## Running the server

The server speaks MCP over stdio, so you normally run it *through* a client
rather than directly. Two easy ways to poke at it:

**MCP Inspector** (a browser UI for trying tools by hand — no API key needed):

```bash
mcp dev server.py
```

**Claude Desktop** — add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "company-records": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-server-demo/server.py"]
    }
  }
}
```

Restart Claude Desktop and the five tools appear; ask it about the data.

## The chat agent (bonus)

`chat.py` is a self-contained client + agent so you can run the whole thing from
one terminal. It needs an Anthropic API key:

```bash
export ANTHROPIC_API_KEY=sk-ant-...     # or copy .env.example to .env
python chat.py                           # interactive
python chat.py "Who are the CEOs in the database and what are their companies?"  # one-shot
```

### Example session

```
$ python chat.py "What's our total closed-won pipeline, and which company has the most deal value?"
Connected to MCP server with 5 tools: search_companies, get_company, find_contacts, deal_summary, top_companies

  · calling deal_summary()
  · calling top_companies(by='deals', limit=1)

Closed-won deals total $13,075,000 across 7 deals. The company with the most
total deal value is Cobalt Mining Group at $7,700,000.
```

Those figures come straight from the seeded data — `deal_summary` reports
`closed_won` at `$13,075,000`, and `top_companies(by="deals")` ranks Cobalt
Mining Group first. The `· calling …` lines show the actual tool calls Claude
chose to make.

Other questions that work well:

- "Which software companies are in the database and how big are they?"
- "Show me the full record for Pinecrest Health."
- "Find every procurement contact."
- "Rank the top 5 companies by revenue."

## Project layout

```
mcp-server-demo/
├── server.py         # MCP server — five tools over the SQLite DB
├── chat.py           # CLI agent: Claude + MCP tool-calling loop
├── company_data.py   # fictional dataset + SQLite builder
├── requirements.txt
└── .env.example
```

## Tech

Python · Model Context Protocol (`mcp` SDK, FastMCP) · Anthropic API · SQLite