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

Abierto
  • ¿Algo no está bien?
#136 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 5 días

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
35/100
Tipo de issue
Nueva funcionalidad
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
github, javascript, json
Área
backend-api-design, documentation, security

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.

Lenguaje dominante
JavaScript
Estrellas
0
Forks
0
Merge medio
3 d 8 h
PR fusionados (30 d)
5

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de AbsaOSS/knowledge-base

Todos los issues de AbsaOSS/knowledge-base

Issues similares

Más issues de JavaScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.