Distrify Network Server

A 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

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:

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.