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

Ouverte
  • Quelque chose ne va pas ?
#136 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 5 jours

Personne n'a encore pris cette issue.

Évaluation

Difficulté
5/5
Temps estimé
Plus d'une semaine
Accessibilité débutants
35/100
Type d'issue
Fonctionnalité
Clarté
Clairement spécifiée
Activité
Active
Stack technique
github, javascript, json
Domaine
backend-api-design, documentation, security

Piste de recherche

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.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

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.

Langage dominant
JavaScript
Étoiles
0
Forks
0
Merge moyen
3 j 8 h
PR mergées (30 j)
5

Préparer son environnement

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de AbsaOSS/knowledge-base

Toutes les issues de AbsaOSS/knowledge-base

Issues similaires

Plus d'issues JavaScript

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.