feat(mcp): declare GitHub repositories in the docs manifest to serve technical docs and code references

未關閉
  • 哪裡不對？
#136 0 則留言 0 個 reaction 已指派 0 人 在 GitHub 檢視

維護者通常 5 天內回覆

還沒有人認領這個 Issue。

評估

難度
5/5
預估耗時
一週以上
新手友好度
35/100
Issue 類型
功能
描述清晰度
描述清楚
活躍度
活躍
技術堆疊
github, javascript, json
領域
backend-api-design, documentation, security

研究方向

Start by reading contract/kb-docs.schema.json and contract/ARTIFACT.md, then trace how the manifest is validated and carried into the generated search index and MCP responses. Check the existing MCP work in #119, #128, and #129 for integration points. Done means the optional repository declarations are validated, included in MCP output, documented, and covered by hermetic schema, build, and MCP tests.

由索引模型根據 Issue 內容生成。

描述

enhancement
Feature Description

Let a docs app declare one or more GitHub repositories in the kb-docs.json manifest (contract/kb-docs.schema.json) as its source code references. When the knowledge base is consumed through the MCP server (#119, #128, #129), the server can use that declaration to serve technical documentation and point to the code, not only the user-facing docs.

Problem / Opportunity

The knowledge base is built from user documentation. Agents and developers using it through MCP also need technical detail: how a service is implemented, where a behaviour lives, which module owns a config key. Today the MCP server has no way to know which repositories back a doc app, so it cannot link answers to code or serve the technical docs that exist (README, docs/, ADRs, API specs). Consumers must guess repository names.

Acceptance Criteria
  1. kb-docs.json accepts an optional repositories list per app. Each entry has at least url (GitHub owner/repo), and optionally ref, role/description, and paths (the technical-doc and source locations to expose).
  2. contract/kb-docs.schema.json validates it. Invalid values fail the build with a clear message. Existing manifests without the field stay valid (non-breaking, optional).
  3. Repository values are validated strictly: allow-listed host (github.com), no shell interpolation, no path traversal in paths.
  4. The build carries the declaration into the generated MCP data (search index / app metadata).
  5. MCP responses for an app include the repository references (repo, ref, deep links to files or paths) so clients can fetch code on their own.
  6. Behaviour with MCP disabled is unchanged: nothing is rendered in the HTML output.
  7. contract/ARTIFACT.md documents the field. Tests cover schema, build and MCP output, and stay hermetic (committed fixtures, no network).
Proposed Solution

Add to the app definition in the manifest:

"repositories": [
  {
    "url": "https://github.com/AbsaOSS/example-service",
    "ref": "master",
    "role": "source",
    "description": "Service implementation",
    "paths": ["docs/", "src/", "openapi.yaml"]
  }
]

Start with references only: the MCP server returns links and metadata and does not clone or index code at build time (keeps the build hermetic). Fetching or indexing technical docs from the repos could follow as a separate opt-in step, with a documented trust model since content comes from other repositories.

Alternatives considered:

  • Convention: infer the repo from the release artifact's origin. Implicit, breaks for monorepos and packaged or iframe apps.
  • A separate registry file in this repo. Moves ownership away from the doc app's own repo and drifts.
Dependencies / Related

#119, #128, #129 (MCP server, search index, runtime). Touches contract/, so it must be called out as a contract change in the PR (additive, optional field).

Additional Context

Sub-app artifacts are untrusted input (see AGENTS.md), so the repository references need the same validation as the rest of the manifest.

主要語言
JavaScript
星號
0
分支
0
平均合併
3 天 8 小時
30 天內合併 PR
5

環境準備

  • 提供 Dockerfile 或 Docker Compose 檔案
  • 沒有 Pull Request 範本
  • 閱讀貢獻指南

從這裡開始

  1. 先讀完整個 Issue，再讀專案的貢獻指南。
  2. 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
  3. Fork 儲存庫，在一個分支上完成修改。
  4. 送出 Pull Request，並在描述裡引用這個 Issue 編號。

AbsaOSS/knowledge-base 的其他 Issue

查看 AbsaOSS/knowledge-base 的全部 Issue

相似的 Issue

更多 JavaScript Issue

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。