# Distrify Network MCP server

A [FastMCP](https://github.com/jlowin/fastmcp) runtime that lets AI tools (Claude, ChatGPT)
search electronic components, prices and availability **across the Distrify distributor
network** through one connection — discovering distributors, requesting access, and
**federating a single query across every distributor the user can access**.

This is the **protocol + routing** plane. It is deliberately separate from:

- the per-distributor **public REST API** (the unchanged data plane it calls), and
- the existing **Distrify Hub** (the `automates` ERP instance for usage/event telemetry) —
  unrelated and untouched.

Identity, the distributor directory and access grants live in a separate Frappe
**"MCP management"** instance (`distrify_mcp_mgmt`), reached over a service-token API.

## Architecture

```
Claude / ChatGPT
   │  Streamable HTTP /mcp  +  OAuth 2.1 (DCR via FastMCP OAuth Proxy)
   ▼
distrify-mcp-server  (this repo — Python/FastMCP, dedicated vserver)
   - tools: list_distributors, request_distributor_access, search/fetch,
     search_components, get_price, get_availability, get_datasheet
   - federated router (parallel fan-out, merge, partial-on-rate-limit)
   │  reads directory + grants (service token)        │ outbound X-DISTRIFY-* headers
   ▼                                                   ▼
Frappe "MCP management" instance              distributor PUBLIC API /api/v1/...
   (directory, network users, grants, OAuth AS)   (search_keyword, get_product_detail,
                                                   get_component_pricing — list + custom)
```

## Layout

| Path | Purpose |
|------|---------|
| `src/distrify_mcp/server.py` | FastMCP app + tool definitions + entrypoint |
| `src/distrify_mcp/router.py` | Distributor public-API client + federated fan-out |
| `src/distrify_mcp/mgmt_client.py` | Client for the Frappe management service API (+ dev fallback) |
| `src/distrify_mcp/normalize.py` | Tolerant extractors for public-API payloads |
| `src/distrify_mcp/config.py` | Env-sourced settings (`DISTRIFY_MCP_*`) |
| `Dockerfile`, `.github/workflows/build.yml` | Containerization + GHCR publish for Watchtower |
| `deploy/docker-compose.yml` | vserver stack (service + Watchtower auto-update) |

## Local development

```bash
pip install -e ".[dev]"
cp .env.example .env          # set DEV_CLIENT_ID / DEV_API_KEY from an API Key Management doc
distrify-mcp                  # serves Streamable HTTP at http://localhost:8000/mcp
```

Inspect the tools without an AI client:

```bash
npx @modelcontextprotocol/inspector
# connect to http://localhost:8000/mcp (Streamable HTTP)
```

## Status

Read-only MVP, built in stages (see the plan). `dev_mode` runs against a single hardcoded
distributor until the management service API and OAuth are wired in. OAuth (FastMCP OAuth
Proxy → Frappe management IdP) and the management API are tracked as follow-up work.