delivery-mcp-server

PH.02 del AI-Forward Delivery Leader Build Program. Un servidor MCP (Model Context Protocol) que expone los documentos de programa indexados de delivery-copilot — SOW, informes de estado, notas de QBR, registro de riesgos — como herramientas, un recurso y un prompt que cualquier host MCP (Claude Desktop, Claude Code) puede usar directamente, con aislamiento por cuenta heredado directamente de PH.01.

MCP es la pieza que casi ningún candidato con experiencia en delivery/PM habrá construido realmente: la mayoría de las personas han usado un servidor MCP dentro de un cliente de chat. Este está construido desde cero, y este README sirve también como explicación de para qué sirve cada componente móvil.

Estado

Construido y verificado: 3 herramientas, 1 recurso, 1 prompt, todos probados de extremo a extremo a través de un Client MCP real y mediante claude mcp add en Claude Code.

Qué es MPC y por qué está construido así

MCP estandariza cómo una aplicación host (Claude Desktop, Claude Code) se comunica con un servidor que expone datos y funcionalidad — una integración en lugar de una hecha a medida por aplicación. Un servidor expone tres tipos primitivos distintos, y esta construcción utiliza los tres deliberadamente, para mostrar la distinción de forma práctica en lugar de solo describirla:

• Herramientas — una acción que el modelo decide llamar, en medio de la conversación, eligiendo sus propios argumentos. search_delivery_docs es la herramienta principal de este servidor.

• Recursos — datos de solo lectura que la aplicación elige cargar por URI, de la misma manera que un navegador obtiene una página — no es algo que el modelo invoque por sí mismo. delivery://{account}/{filename} es el recurso de este servidor: obtén un documento completo cuando ya sabes cuál quieres.

• Prompts — una plantilla de mensaje que una persona invoca por nombre, como un comando slash. draft_status_update es el prompt de este servidor: elige una cuenta, obtén una instrucción preescrita insertada en la conversación.

La división recuperación/generación es la decisión arquitectónica real aquí. delivery-copilot/ask.py recupera fragmentos y llama a Claude para generar una respuesta citada en un solo script, porque nada más en ese pipeline es un modelo. Dentro de un servidor MCP, ya hay un modelo en el bucle — el que sea que esté ejecutando la conversación del host. Entonces search_delivery_docs solo hace recuperación y devuelve los fragmentos coincidentes como datos; el propio modelo del host los lee y redacta la respuesta fundamentada por sí mismo, guiado por la instrucción de citación/rechazo codificada en el docstring de la herramienta (el único lugar donde un servidor puede dejar instrucciones de fundamentación, ya que no posee el prompt del sistema). Una consecuencia que vale la pena mencionar: este servidor llama a Claude cero veces. Sin ANTHROPIC_API_KEY, sin solicitud facturada — es incrustación local y búsqueda vectorial, exactamente lo que ingest.py ya hace. El costo de generación es completamente del host.

El aislamiento se mantiene sin cambios desde PH.01. Cada herramienta toma un argumento account y lee solo la colección Chroma de esa cuenta (delivery_docs__<account>) — verificado nuevamente en esta capa con una segunda cuenta de prueba: al hacerle una pregunta no relacionada (algo que solo meridian-health podría responder) no devolvió más que su propia nota única, nunca contenido de Meridian.

Estructura del repositorio — por qué esto no es una importación de Python desde delivery-copilot

Este repositorio depende de delivery-copilot para exactamente una cosa: el artefacto de datos en chroma_db/, no su código. Sin pip install -e entre repositorios, sin módulos compartidos:

• list_accounts() lee client.list_collections() y elimina el prefijo delivery_docs__ — no necesita data/raw/ en absoluto.

• list_documents(account) lee los valores source distintos ya almacenados en los metadatos de los fragmentos de esa colección.

• El recurso delivery:// reconstruye un documento concatenando sus fragmentos en orden original (analizados desde los IDs de fragmento source::N que ingest.py ya asigna).

Apunte DELIVERY_DB_PATH a cualquier almacén Chroma construido (por defecto: ../delivery-copilot/chroma_db, asumiendo que ambos repositorios están clonados como hermanos) y este servidor funciona — genuinamente autónomo en cuanto a código, clonable de forma independiente, coincidiendo con cómo ai-fundamentals-rig y delivery-copilot son cada uno independiente del otro.

Un hallazgo que vale la pena conservar (entorno)

mcp[cli] trae pyjwt[crypto] → cryptography. cryptography eliminó las ruedas precompiladas para macOS x86_64 a partir de v46.0.4 (lanzamientos solo para arm64 desde entonces) — al instalar en esta máquina (genuinamente Intel) intentó compilar desde el código fuente y falló sin encabezados de Rust/OpenSSL. Se fijó cryptography==46.0.3 en requirements.txt, la última versión con una rueda para x86_64, satisfaciendo cómodamente la dependencia cryptography>=3.4.0 de pyjwt. Un recordatorio de que "pip install" asume silenciosamente que tu arquitectura de CPU tiene una rueda — no siempre es así.

También: la versión principal actual del SDK de Python para MCP (v2) requiere Python 3.10+; el Python del sistema de esta máquina era 3.9.6. Se instaló 3.13 mediante el instalador oficial de python.org, junto al intérprete del sistema, específicamente para el .venv de este repositorio.

Configuración

# needs delivery-copilot's index already built: `python ingest.py` in that repo first
python3.13 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Ejecútalo

Pruebas manuales, sin necesidad de host — llama a cada herramienta/recurso/prompt a través de un Client real en memoria:

python test_server.py

MCP Inspector (interactivo, abre una interfaz web local):

uv run mcp dev server.py     # or: pip install uv, then the same command

Regístrate con Claude Code:

claude mcp add delivery-copilot \
  -e DELIVERY_DB_PATH=/absolute/path/to/delivery-copilot/chroma_db \
  -- /absolute/path/to/delivery-mcp-server/.venv/bin/python /absolute/path/to/delivery-mcp-server/server.py

claude mcp list   # confirm it connects

Luego, en un chat de Claude Code: "Usando el servidor MCP de delivery-copilot, ¿quién es el propietario del riesgo de Okta para meridian-health, según los documentos?" — Claude llama a search_delivery_docs por sí mismo y cita lo que devuelve.

Qué sigue

PH.02 está completo en funcionalidad: 3 herramientas, 1 recurso, 1 prompt, probado localmente y en vivo a través de Claude Code. Extensiones naturales, no bloqueantes: una segunda cuenta real una vez que exista (nada aquí es específico de meridian-health), y el agente de estado/riesgo de PH.03 podría basarse razonablemente en draft_status_update en lugar de empezar desde cero.

Parte del AI-Forward Delivery Leader Build Program.