跳至主要内容

DDC MCP — Partner Access Guide

Access to the 法鼓全集 (Master Sheng Yen, 聖嚴法師) retrieval service over the Model Context Protocol (MCP).

The corpus is Master Sheng Yen's work in two editions, served as MCP tools you can call from Claude, an MCP-compatible client, or directly over HTTP:

  • 《法鼓全集》 — his authored books (110 titles); source: "faguquanji".
  • wisbook — the shengyen.org free-books edition; source: "wisbook".

retrieve searches both and merges by score; every result carries a source telling you which edition it came from (attribution is always 聖嚴法師). A faguquanji-only deployment still works if the wisbook index isn't present.

1. Endpoint​

Base URLhttps://ddc.changpt.org
TransportsGET/POST /sse (SSE) · POST /mcp (streamable-HTTP)
ProtocolMCP 2024-11-05
AuthAuthorization: Bearer <YOUR_API_KEY> (or X-API-Key: <YOUR_API_KEY>)

Your API key is issued to you privately. Every request must carry it — a request with no/invalid key returns 401. Do not share or commit the key.

2. Quick connectivity test​

A 30-second check from any terminal — replace <YOUR_API_KEY>:

curl -s -X POST https://ddc.changpt.org/mcp \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","versi
on":"1"}}}'

Expected: an initialize result with "serverInfo":{"name":"ddm-ddc-agent", ...}. If you instead get 401, the key/header is wrong; 200 with that body means you're connected.

3. Connect from a client​

Claude Desktop / Claude Code (mcp config)​

{
  "mcpServers": {
    "ddc": {
      "url": "https://ddc.changpt.org/sse",
      "headers": { "Authorization": "Bearer <YOUR_API_KEY>" }
    }
  }
}

MCP Inspector​

npx @modelcontextprotocol/inspector
# Transport: SSE
# URL:       https://ddc.changpt.org/sse
# Header:    Authorization: Bearer <YOUR_API_KEY>

Any MCP-compatible client works the same way: point it at the /sse (or /mcp) URL and add the Authorization header.

4. Tools​

ToolPurpose
retrieve ⭐ recommendedNatural-language retrieval — returns, in one call, the top-k Passage objects, each with the matched snippet and its section-bounded context (the grounding text) plus section_id, source, attribution, title, citation, source_url, book_id, mid_id, score. Searches both editions and merges by score. Ground answers in context, cite section_id + attribution; link with source_url. Args: query, k (1–20, default 5), min_score (default 0.30), plus book scoping (book_ids / exclude_book_ids).
search_ddc_teachings (legacy)⚠️ Deprecated — use retrieve. Returns raw snippets (no grounding context), which invites over-search and weaker grounding. Kept only for backward compatibility; new integrations should call retrieve. Same book scoping.
list_ddc_booksEnumerate the 110-book catalog (book_code, book_title, category_title) to build book_ids / exclude_book_ids. N
o args.
get_chapterFetch one full chapter by chapter_code (from a hit). Returns the full body_text + pages, a reader source_url, citation, and any audio pointers — audiobook episodes (聖嚴法師的有聲書) that read the chapter aloud (episode_title, audio_url, duration_seconds, coverage).
get_book_outlineList a book's chapters (table of contents) by book_code.

Example: retrieve (recommended — chunk + chapter context in one call)​

// retrieve
{ "query": "默照禪的方法", "k": 5, "book_ids": ["04-03"] }

Returns a list of Passage objects, each:

{
  "section_id": "faguquanji:11-03-002#007",
  "source": "faguquanji",
  "attribution": "聖嚴法師",
  "title": "默照禪的下手方法",
  "snippet": "…the matched span…",
  "context": "…the matched span's section (topic-bounded), sized to a grounding budget — the basis…",
  "citation": "《聖嚴法師教默照禪》，第十一輯，頁 42",
  "source_url": "https://ddc.shengyen.org/?doc=11-03-002&page=42",
  "book_id": "04-03",
  "mid_id": "11-03-002",
  "score": 0.98
}

Ground answers in context and cite section_id + attribution. The context is the matched passage's topic-bounded section, sized server-side to a grounding budget (no argument). source names the edition (faguquanji or wisbook); source_url is a human-readable reader deep link for that passage (link it from your citations). mid_id is the chapter code (use with get_chapter for the whole chapter); title is a section label for navigation, not a citation.

Example: search_ddc_teachings (raw snippets)​

// search_ddc_teachings
{ "query": "默照禪的方法", "k": 5, "book_ids": ["04-03"] }

Returns a list of hits, each:

{
  "title": "聖嚴法師教默照禪",
  "score": 0.98,
  "snippet": "…",
  "citation": "《聖嚴法師教默照禪》，第十一輯，頁 42",
  "book_code": "04-03",
  "chapter_code": "11-03-002",
  "source_url": "https://ddc.shengyen.org/…"
}

Then fetch the full chapter:

// get_chapter
{ "chapter_code": "11-03-002" }

Returns the full chapter (body_text, pages, source_url, citation) plus any audio pointers — audiobook episodes reading it aloud:

{
  "chapter_code": "11-03-002",
  "chapter_title": "默照禪的下手方法",
  "book_code": "04-03",
  "body_text": "…full chapter text…",
  "source_url": "https://ddc.shengyen.org/?doc=11-03-002",
  "citation": "《聖嚴法師教默照禪》，第十一輯",
  "audio": [
    {
      "episode_title": "默照禪 12",
      "audio_url": "https://…/episode.mp3",
      "duration_seconds": 1730,
      "coverage": 0.82
    }
  ]
}

Book scoping recap: omit both book_ids and exclude_book_ids → search all books; book_ids: ["04-03"] → only that book (exhaustive within it); exclude_book_ids: [...] → everything except those. Discover codes with list_ddc_books.

Full argument/return schemas are provided to partners on request.

5. Notes & support​

  • Encoding: all text is Traditional Chinese (繁體中文), UTF-8.
  • Rate / availability: this is a shared service; please keep request volume reasonable. Let us know your expected load if it's high.
  • Key rotation: each partner has an individual key — tell us if you need it rotated or revoked.
  • Questions / issues: reply to your onboarding contact with the failing request (URL, headers minus the key, and the response code).