# MCP Tool Server

A Model Context Protocol style tool server. It advertises a set of tools with JSON
schemas so an AI agent can discover them, and executes tool calls safely. This is
the pattern that lets agents act on real systems rather than only chatting.

## Why it is useful for companies
Agents are only useful when they can do things: run a calculation, query a service,
look something up. MCP standardizes how tools are exposed and called, so the same
tools work across different agents and models. This server shows that pattern with
a safe registry you extend with your own company tools.

## What it does
- Advertises tools with JSON-schema input definitions at `/tools`
- Executes tool calls at `/call`, with input validation and safe evaluation
- Ships with three example tools: calculator, stats, knowledge_lookup

## Quickstart
```bash
make install
make run     # http://localhost:8080
curl -s localhost:8080/tools | python3 -m json.tool
curl -s -X POST localhost:8080/call -H "content-type: application/json" \
  -d '{"name":"calculator","arguments":{"expression":"2*(3+4)"}}'
```

## Adding your own tool
Decorate a function in app/tools.py with `@tool(name, description, schema)`. It is
then discoverable and callable immediately, no other wiring needed.

## Stack
Python, FastAPI, JSON-schema tool registry, Docker, GitHub Actions CI, Pytest.

## License
MIT

## Workflow diagram

```mermaid
flowchart LR
  A[AI agent] -->|GET /tools| S[MCP Tool Server]
  S -->|tool schemas| A
  A -->|POST /call name+args| S
  S --> V[Validate + execute]
  V --> R[Result back to agent]
```

A runnable list-and-call sample is in [examples/sample_output.json](examples/sample_output.json).