Skip to main content
Glama
deenesjakoruzh
bdc-assist

bdc-doc-mcp

by bdc-assist
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Hybrid

BDC Doc RAG

bdc-assist의 문서 RAG MCP

bdc_doc_mcp/config.py      env-driven embeddings/LLM/Chroma (replaces utils/__init__.set_emb_llm)
bdc_doc_mcp/ingest.py      .pkl/.md/.mdx/.txt/.pdf → embeddings → Chroma (replaces utils/chroma/utils.py)
bdc_doc_mcp/api.py         FastAPI: /health /search
bdc_doc_mcp/mcp_server.py  search_docs MCP tool for AI agents — self-contained, same search as the API
bdc_doc_mcp/preproc/       source-specific preprocessing pipeline
tests/                     self-checks + API / agent notebooks
data/                      preproc output (*.pkl), ingest input

설정

uv sync
cp .env.example .env    # then fill in keys/URLs

소스 저장소

전처리(--sources all)에만 필요합니다. API/MCP 서버와 기존 .pkl 파일 수집은 이 저장소 없이 작동합니다. 이 저장소 옆에 클론하거나(또는 환경 변수가 이를 가리키도록 설정):

git clone https://github.com/stagecc/interim-bdc-website ../interim-bdc-website   # BDC_WEBSITE_DIR
git clone https://github.com/stagecc/bdc-gitbook ../bdc-gitbook                   # BDC_GITBOOK_DIR

모델

완성(completion)에는 Azure의 OpenAI API(gpt-4o-mini 기본값)를 사용합니다.

임베딩에는 Sterling의 Ollama를 사용합니다(RENCI VPN을 통해 연결).

kubectl -n ner port-forward svc/ollama 11434:11434

또는 groonga/bge-m3-Q4_K_M-GGUF 모델로 로컬 Ollama를 사용합니다.

Related MCP server: okfy

수집

모든 소스에서 전체 재구축(두 소스 저장소의 클론 필요 — 설정 참조; data/*.pkl을 작성한 뒤 로드):

uv run python -m bdc_doc_mcp.preproc.pipeline --sources all --ingest --reset

개별 파일 또는 디렉터리:

uv run python -m bdc_doc_mcp.ingest ./data/docs.pkl --doc-type docs   # BDC_Chatbot preproc .pkl
uv run python -m bdc_doc_mcp.ingest ../interim-bdc-website/src/pages --doc-type page --reset

임베딩 모델은 컬렉션 내에서 교환할 수 없습니다 — bge-m3는 1024차원, text-embedding-3-small은 1536차원입니다. 모델을 전환하려면 --reset과 전체 재수집이 필요합니다.

API

uv run uvicorn bdc_doc_mcp.api:app --port 8000     # docs at /docs

엔드포인트

본문

응답

GET /health

—

{status, documents}

POST /search

{query, k, mode?, doc_type?, date_from?, date_to?}

순위가 매겨진 청크 + 메타데이터 + 점수

mode는 embedding(기본값; 의미적 유사성, 점수 = 거리, 낮을수록 좋음) 또는 keyword(퍼지 리터럴 단어 일치 — 대소문자/구두점을 무시하고 작은 오타를 허용하므로 picsure는 "PIC-SURE"를 찾음; 점수 = 발생 횟수, 높을수록 좋음 — 정확한 이름/약어에 사용)입니다. doc_type는 검색할 유형의 CSV입니다(예: page,faq). 생략하면 docs, page, faq, video만 검색됩니다 — fellow, update, event를 명시적으로 지정하여 검색하세요. date_from/date_to(YYYY-MM-DD, 포함)는 날짜로 필터링합니다. 이벤트 및 업데이트 문서만 날짜를 가지므로 날짜 필터는 암시적으로 해당 유형으로 좁혀집니다.

이 서비스는 설계상 검색 전용입니다. 수집은 CLI를 통해 오프라인으로 이루어지며(수집 참조), 답변은 호출자의 몫입니다 — 에이전트가 자체 LLM을 가져옵니다.

MCP

uv run python -m bdc_doc_mcp.mcp_server           # stdio
uv run python -m bdc_doc_mcp.mcp_server --http    # streamable HTTP, port MCP_PORT (default 8001)

search_docs라는 하나의 도구를 노출합니다 — API와 동일한 검색이지만 Chroma를 직접 쿼리하므로 API 서비스가 실행될 필요가 없습니다. 수집된 .chroma_db + 임베딩이 필요합니다.

Stdio 클라이언트(Claude Desktop/Code, Cursor)는 서버를 직접 시작합니다 — 등록하세요:

{"mcpServers": {"bdc-doc-mcp": {
  "command": "uv",
  "args": ["--directory", "/path/to/bdc-doc-mcp", "run", "python", "-m", "bdc_doc_mcp.mcp_server"]
}}}

네트워크 클라이언트: --http를 실행하고 대신 http://host:8001/mcp를 가리키게 하세요.

스모크 테스트: uv run python tests/test_mcp.py

전처리

bdc_doc_mcp/preproc/는 BDC_Chatbot 파이프라인을 포팅한 것입니다:

모듈

소스

포팅된 위치 (BDC_Chatbot)

참고 사항

bdc_repo.py

interim-bdc-website MDX

utils/preproc/proc_BDC_repo.py (거의 그대로)

fellows, events, latest-updates, pages

bdc_docs.py

bdc-gitbook markdown

utils/preproc/proc_BDC_docs.py (모듈 수준 LLM 초기화 제거)

헤더 계층별로 청크됨; 저장소 클론 필요

freshdesk.py

bdcatalyst.freshdesk.com

utils/preproc/proc_freshdesk.py

실시간 스크레이핑

vids.py

Google Sheet + Drive SRT

utils/preproc/proc_BDC_vids.py (GoogleSheetsReader 클래스 평면화)

타임스탬프 URL이 있는 비디오 트랜스크립트

utils.py

—

—

LLM 청크 컨텍스트화 + 요약기

pipeline.py

—

utils/preproc_doc.py

오케스트레이터

--no-contextualize는 청크별 LLM 호출을 건너뜁니다(훨씬 빠르지만 검색이 약해짐). 소스 경로는 BDC_WEBSITE_DIR / BDC_GITBOOK_DIR에서 가져옵니다.

테스트

uv run python tests/test_ingest.py                             # batching + chunk-id logic, no network
uv run python tests/test_keyword.py                            # keyword ranking, pure function, no DB or API
uv run python tests/test_mcp.py                                # starts the server over stdio and exercises its tools; needs .chroma_db + embeddings

노트북(각각 무료 포트에서 API를 시작하고 끝에 종료합니다; 둘 다 수집된 .chroma_db가 필요합니다):

  • tests/api_test.ipynb — 일반 API 연습: /health, /search, doc_type 필터. 로컬 임베딩만 필요합니다.

  • tests/agent_test.ipynb — 도구 호출 에이전트(deepagents): 구성된 LLM이 search_docs를 LangChain 도구로 받아 호출 시점을 결정합니다. 완성 공급자에 연결할 수 있어야 합니다.

Available Tools

1 tool
search_docsA

Search the BDC (NHLBI BioData Catalyst) documentation database.

Returns the top-k matching chunks with content, metadata (source, doc_type, datetime when available), and a score.

query is the search text. In embedding mode phrase it as a question or topic (e.g. "how do I bring my own data"); in keyword mode give the literal terms to match.

k is the number of chunks to return (default 5). Raise it (10-20) for broad or multi-part questions; each chunk is a small section of a document.

mode toggles the search engine:

  • "embedding" (default): semantic similarity — best for questions, topics, and paraphrased wording. score is a distance (lower = more similar).

  • "keyword": fuzzy literal word matching — ignores case and punctuation ("picsure" finds "PIC-SURE") and tolerates small typos — best for exact names, acronyms, tool names, or error messages the embedding may blur. Chunks matching more of the query terms rank first; score is the total number of occurrences (higher = better).

doc_type is a CSV string of types to search (e.g. "page,faq" or "video"). Available types:

  • docs: BDC GitBook platform documentation — user guides, how-tos, and technical reference (bdcatalyst.gitbook.io)

  • page: key pages of the BDC website — about/overview, joining BDC, analyzing & sharing data, usage costs and terms

  • faq: Freshdesk help-desk FAQ articles (support questions & answers)

  • video: transcripts of BDC YouTube tutorials/webinars, with timestamped links into the video

  • fellow: BDC Fellows profiles — fellowship recipients and their research projects

  • update: dated news posts ("latest updates") from the BDC website

  • event: dated BDC events — webinars, workshops, deadlines When doc_type is omitted, only docs, page, faq, and video are searched — name fellow, update, or event explicitly to search them.

date_from / date_to ("YYYY-MM-DD", inclusive) filter by date. Only event and update docs carry a date, so a date filter implicitly narrows to those types. Results are ranked by relevance, NOT date — for "recent"/"latest" questions, always set date_from to bound the range, then compare the dates returned.

ParametersJSON Schema
NameRequiredDescriptionDefault
kNo
modeNoembedding
queryYes
date_toNo
doc_typeNo
date_fromNo

TDQS

A5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses behavioral traits: default doc types when omitted, score interpretation (distance vs occurrences), the effect of date filters, and ranking by relevance not date. It also notes that only event and update docs carry dates, further clarifying behavior. No annotation contradiction exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with bullet points for modes and types, and clear paragraphs for date and ranking behavior. It is lengthy but every sentence carries essential information, and it is front-loaded with the purpose and return content. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (6 parameters, no output schema, no annotations), the description is complete. It explains return format, scoring meaning, type-specific behavior, and parameter interactions. It fully equips an agent to invoke the tool correctly for a variety of use cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, and it does thoroughly. It explains query phrasing for each mode, k's range and purpose, mode options with detailed semantics, doc_type as a CSV list with each type's meaning, and date_from/date_to format and inclusive behavior. This adds far more meaning than the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it searches the BDC (NHLBI BioData Catalyst) documentation database and returns top-k matching chunks with content, metadata, and a score. It names the specific resource and what is returned, making the tool's purpose unambiguous even without sibling tools for differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance on when to use embedding vs keyword mode, how to adjust k for broad questions, when to explicitly name doc_type values, and how to use date filters for recency queries. It also warns that date filters implicitly narrow to types with dates and explains ranking behavior, giving clear when-to-use and when-not-to-use instruction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev0.1.0
    • First observedsearch_docs
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.6/5.0

Scored across 1 tool

Disambiguation5/5

With only a single tool, there is no possibility of ambiguity. The tool has a clearly defined purpose for searching documentation.

Naming Consistency5/5

The tool name 'search_docs' follows a consistent verb_noun pattern and is descriptive. Since it is the only tool, naming is inherently consistent.

Tool Count1/5

The server exposes only one tool, which is extremely thin. Even though the tool is multi-functional, a single tool does not constitute a well-scoped set; most servers with this purpose would benefit from at least a couple of complementary tools (e.g., retrieving a document by ID or listing available types).

Completeness3/5

The search tool covers multiple documentation sources and provides filtering and multiple modes, which addresses the core purpose. However, it lacks any other operation such as fetching a specific document, listing available doc types, or managing content, leaving notable gaps for a documentation server.

Maintenance

ActivityMaintained
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers

  • Markdown RAG MCP

    mohllal
    A
    license
    Not graded
    quality
    D
    maintenance
    Provides semantic search over markdown documentation using RAG, allowing natural language queries and integration with MCP clients.
    1
    MIT

  • okfy

    0dust
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI agents to search, read, and traverse documentation bundles in Open Knowledge Format via MCP tools.
    506 npm
    73
    MIT

  • docrag

    ryan-m-bishop
    A
    license
    Not graded
    quality
    D
    maintenance
    Provides RAG (Retrieval Augmented Generation) access to technical documentation through MCP, enabling LLMs to search and retrieve relevant documentation on-demand.
    4
    MIT

  • webdocs-mcp

    saianthireddy
    A
    license
    Not graded
    quality
    A
    maintenance
    Crawl documentation sites, index them with hybrid search, and expose them as MCP tools so LLM agents can search and retrieve current docs.
    MIT