Sumi Docs

Inglés | 简体中文

Sumi Docs publica un corpus de documentación revisado para dos consumidores:

• personas que navegan por un sitio web de Astro y Starlight;

• agentes que consultan el mismo corpus a través de un servidor MCP de solo lectura.

El árbol docs/ raíz revisado y el catálogo de contenido son la fuente semántica de verdad. El sitio web y el servidor MCP son proyecciones direccionables de forma independiente; un host de agente es el cliente MCP.

El repositorio fuente y el sitio de documentación son públicos y están en desarrollo activo. No se ha publicado ningún paquete npm, release de GitHub etiquetado ni binario compatible.

Requisitos previos

• Node.js 25.5.0 o superior

• pnpm 10.26.0 a través de Corepack o la versión declarada en packageManager

• un checkout de confianza al cargar la configuración del host de agente proporcionada por el repositorio

Related MCP server: mcp-docs

Primera ejecución

pnpm install --frozen-lockfile
pnpm run build
node packages/mcp/dist/index.js doctor --json

Doctor informa rutas relativas al proyecto o marcadores de posición de fuentes externas de forma predeterminada. Añade --show-paths solo para diagnóstico local; no adjuntes esa salida a problemas públicos ni a artefactos de compilación.

El sumi-docs.config.json incluido selecciona la raíz docs/ y el documento OpenAPI de ejemplo. Inicia el sitio humano con:

pnpm --filter @sumi-os/docs-web dev

Abre http://127.0.0.1:4321. Los adaptadores de proyecto para Codex, Claude Code y VS Code se describen en Integración con hosts de agentes. Exponen las cuatro herramientas MCP sin requerir la Skill de mantenimiento opcional.

Para exponer el mismo corpus en un endpoint HTTP Streamable de bucle local:

node packages/mcp/dist/index.js serve --transport streamable-http

Conecta un cliente MCP compatible a http://127.0.0.1:3000/mcp. El sitio web estático y la proyección del corpus _mcp no ejecutan ese endpoint por sí mismos.

Para un contenedor local endurecido que use el mismo corpus raíz revisado:

docker compose up --build

El servicio expone MCP en http://localhost:3000/mcp, liveness en /healthz y readiness del corpus en /readyz. Docker es opcional para el desarrollo de fuentes; el despliegue público aún requiere terminación HTTPS y una política de Host explícita.

El repositorio también proporciona tres flujos de trabajo de proyecto opcionales en .agents/skills/: $sumi-docs-use para configuración y operación, $sumi-docs-pr para preparación de propuestas y pull requests, y $sumi-docs-audit para auditorías de repositorio y releases de solo lectura y basadas en evidencia. Enrutan el trabajo pero no reemplazan a MCP ni publican cambios remotos.

Espacio de trabajo

apps/web/                   Astro/Starlight site and corpus publisher
packages/mcp/               stdio and Streamable HTTP MCP server and CLI
packages/corpus-contract/   manifest schemas and conformance fixtures
docs/                       product handbook and default corpus
.agents/skills/             optional project usage and contribution workflows

La operación local y la publicación predeterminada solo con Pages no requieren secretos en tiempo de ejecución. SITE_URL solo es necesario para un candidato de sitio de release. Habilitar el servicio HTTP Streamable de producción opcional requiere variables de endpoint revisadas y material SSH en el entorno protegido production-mcp. El contenedor acepta variables de despliegue documentadas SUMI_DOCS_*; la salida generada, el estado local, los registros, las cachés y los archivos .env permanecen ignorados.

Las instrucciones específicas de cada paquete permanecen en cada espacio de trabajo. Las decisiones de arquitectura activas viven en el directorio docs/decisions/ del espacio de trabajo propietario; el manual raíz presenta sus consecuencias orientadas al usuario sin duplicar los registros de decisiones.

La visibilidad de fuentes y sitio no publica una etiqueta, paquete ni binario. Esos artefactos siguen sujetos a las puertas de release documentadas.