delivery-mcp-server

PH.02 of the AI-Forward Delivery Leader Build Program. MCP(Model Context Protocol) 서버로서 delivery-copilot의 인덱싱된 프로그램 문서 — SOW, 상태 보고서, QBR 노트, 위험 등록부 — 를 도구, 리소스 및 프롬프트로 노출하며, 모든 MCP 호스트(Claude Desktop, Claude Code)가 직접 사용할 수 있고, 계정별 격리는 PH.01에서 그대로 이어집니다.

MCP는 거의 모든 배송/PM 배경의 후보자가 실제로 구축해 본 적이 없는 부분입니다: 대부분의 사람들은 채팅 클라이언트 내에서 MCP 서버를 사용해 본 적이 있습니다. 이 서버는 처음부터 구축되었으며, 이 README는 각 구성 요소의 용도에 대한 설명을 겸합니다.

상태

구축 및 검증 완료: 3개의 도구, 1개의 리소스, 1개의 프롬프트, 모두 실제 MCP Client와 Claude Code의 claude mcp add를 통해 종단 간 테스트되었습니다.

MCP가 무엇인지, 그리고 왜 이렇게 구축되었는지

MCP는 호스트 애플리케이션(Claude Desktop, Claude Code)이 데이터와 기능을 노출하는 서버와 통신하는 방식을 표준화합니다 — 앱별로 맞춤형 통합 대신 하나의 통합으로. 서버는 세 가지 고유한 기본 유형을 노출하며, 이 빌드는 단순히 설명하는 대신 실제로 구분을 보여주기 위해 세 가지를 모두 의도적으로 사용합니다:

• Tools — 모델이 대화 중에 자신의 인수를 선택하여 호출하기로 결정하는 작업입니다. search_delivery_docs가 이 서버의 주요 도구입니다.

• Resources — 애플리케이션이 URI로 로드하기로 선택하는 읽기 전용 데이터로, 브라우저가 페이지를 가져오는 방식과 유사합니다 — 모델이 자체적으로 호출하는 것이 아닙니다. delivery://{account}/{filename}이 이 서버의 리소스입니다: 이미 원하는 문서를 알고 있을 때 전체 문서를 가져옵니다.

• Prompts — 사용자가 이름으로 호출하는 메시지 템플릿으로, 슬래시 명령어와 같습니다. draft_status_update가 이 서버의 프롬프트입니다: 계정을 선택하면 미리 작성된 지침이 대화에 추가됩니다.

검색/생성 분할이 여기서 실제 아키텍처 결정입니다. delivery-copilot/ask.py는 청크를 검색 하고 Claude를 호출하여 인용된 답변을 생성하는 것을 하나의 스크립트로 수행합니다. 그 파이프라인에 다른 모델이 없기 때문입니다. MCP 서버 내부에는 이미 모델이 루프에 있습니다 — 호스트 대화를 실행하는 모든 것. 따라서 search_delivery_docs는 검색만 수행하고 일치하는 청크를 데이터로 반환합니다. 호스트 자체의 모델이 이를 읽고, 도구의 독스트링에 내장된 인용/거부 지침(서버가 시스템 프롬프트를 소유하지 않기 때문에 접지 지침을 남길 수 있는 유일한 장소)에 따라 접지된 답변을 직접 작성합니다. 한 가지 결과를 언급할 가치가 있습니다: 이 서버는 Claude를 전혀 호출하지 않습니다. ANTHROPIC_API_KEY가 없고, 청구된 요청이 없습니다 — 로컬 임베딩 및 벡터 검색으로, ingest.py가 이미 수행하는 작업과 정확히 동일합니다. 생성 비용은 전적으로 호스트의 몫입니다.

격리는 PH.01에서 변경 없이 그대로 유지됩니다. 모든 도구는 account 인수를 받고 해당 계정의 Chroma 컬렉션(delivery_docs__<account>)만 읽습니다 — 이 레이어에서도 두 번째 테스트 계정으로 다시 확인했습니다: 관련 없는 질문(오직 meridian-health만 답할 수 있는 질문)을 했을 때, Meridian 콘텐츠가 아닌 자체 단일 노트만 반환되었습니다.

저장소 구조 — 왜 이게 delivery-copilot에서 Python import로 사용되지 않는가

이 저장소는 delivery-copilot에 정확히 한 가지에 의존합니다: chroma_db/의 데이터 아티팩트이며, 그 코드는 아닙니다. 저장소 간 pip install -e도, 공유 모듈도 없습니다:

• list_accounts()는 client.list_collections()를 읽고 delivery_docs__ 접두사를 제거합니다 — data/raw/가 전혀 필요하지 않습니다.

• list_documents(account)는 해당 컬렉션의 청크 메타데이터에 이미 저장된 고유한 source 값을 읽습니다.

• delivery:// 리소스는 청크를 원래 순서로 연결하여 문서를 재구성합니다 (ingest.py가 이미 할당하는 source::N 청크 ID에서 파싱됨).

DELIVERY_DB_PATH를 구축된 Chroma 저장소(기본값: ../delivery-copilot/chroma_db, 두 저장소가 형제로 클론되었다고 가정)로 지정하면 이 서버가 작동합니다 — 코드 관점에서 완전히 자체 포함되어 있으며, 독립적으로 클론 가능하며, ai-fundamentals-rig와 delivery-copilot이 서로 독립적인 방식과 일치합니다.

기록할 만한 발견 (환경)

mcp[cli]는 pyjwt[crypto] → cryptography를 가져옵니다. cryptography는 v46.0.4부터 사전 빌드된 x86_64 macOS 휠을 중단했습니다(이후 arm64 전용 릴리스) — 이 (진정한 Intel) 머신에 설치하려고 하면 소스에서 컴파일을 시도했고 Rust/OpenSSL 헤더가 없어 실패했습니다. requirements.txt에서 cryptography==46.0.3으로 고정했습니다. 이는 x86_64 휠이 있는 마지막 릴리스로, pyjwt의 cryptography>=3.4.0을 충족시킵니다. "pip install"은 CPU 아키텍처에 휠이 있다고 조용히 가정한다는 것을 상기시킵니다 — 항상 그런 것은 아닙니다.

또한: MCP Python SDK의 현재 주요 버전(v2)은 **Python 3.10+**가 필요합니다; 이 머신의 시스템 Python은 3.9.6이었습니다. 공식 python.org 설치 프로그램을 통해 시스템 인터프리터와 함께 3.13을 설치했습니다. 특히 이 저장소의 .venv를 위해.

설정

# 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

실행

수동 테스트, 호스트 불필요 — 실제 인메모리 Client를 통해 모든 도구/리소스/프롬프트 호출:

python test_server.py

MCP Inspector (대화형, 로컬 웹 UI 열기):

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

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

그런 다음, Claude Code 채팅에서: "Using the delivery-copilot MCP server, who owns the Okta risk for meridian-health, per the docs?" — Claude가 search_delivery_docs를 직접 호출하고 반환된 내용을 인용합니다.

다음은?

PH.02는 기능이 완료되었습니다: 3개의 도구, 1개의 리소스, 1개의 프롬프트, 로컬 및 Claude Code를 통해 라이브로 테스트되었습니다. 차단되지 않는 자연스러운 확장: 실제 계정이 생기면 두 번째 실제 계정(여기에는 meridian-health 특정 항목이 없음), 그리고 PH.03의 에이전트 상태/위험 에이전트는 처음부터 시작하는 대신 draft_status_update를 기반으로 구축할 수 있습니다.

다음의 일부: AI-Forward Delivery Leader Build Program.