Engineering Knowledge MCP

Un servidor MCP local muy ligero que proporciona a los agentes de codificación (Claude Code, GitHub Copilot, etc.) una base de conocimiento de ingeniería compartida para buscar y actualizar: convenciones internas, detalles de API, configuración de infraestructura, flujos de autenticación, configuración de desarrollo local, etc.

El conocimiento reside como archivos Markdown simples en este repositorio Git. El servidor MCP es una capa fina y sin estado de lectura/escritura sobre el sistema de archivos: nada más.

1. Qué hace esto

• Los agentes de codificación pueden buscar en la base de conocimiento en lugar de adivinar las convenciones internas o pedir al usuario que se repita.

• Los agentes pueden capturar nuevos hechos con casi ninguna fricción (una llamada de herramienta, sin necesidad de saber dónde pertenece el hecho).

• Los agentes pueden crear y actualizar documentos de conocimiento estructurados de forma determinista.

• Todo es Markdown en Git, por lo que es útil incluso sin el servidor MCP: búscalo con grep, léelo, edítalo, revisa los diffs, haz commit, haz PR, exactamente como código.

Related MCP server: bikky

2. Arquitectura

engineering-knowledge-mcp/
├── knowledge/           # the knowledge base itself (Markdown, organized by topic area)
│   ├── api/
│   ├── cloud/
│   ├── data/
│   ├── frontend/
│   └── general/
├── inbox/
│   └── knowledge-inbox.md   # low-friction capture target; triage manually into knowledge/
├── src/
│   ├── index.ts         # MCP server entrypoint (stdio transport)
│   ├── paths.ts         # path sanitization / traversal protection
│   ├── knowledge.ts     # search, get, create, update, capture logic
│   └── tools/index.ts   # MCP tool registration + input schemas
├── test/                # node:test unit tests
├── CLAUDE.md            # agent instructions auto-loaded by Claude Code when working in this repo
├── package.json
└── tsconfig.json

Decisiones de diseño, deliberadamente:

• MCP solo sobre stdio. Sin servidor HTTP, sin Express: el cliente (Claude Code, Copilot, MCP Inspector) inicia este proceso y habla JSON-RPC sobre stdin/stdout.

• Sin base de datos, sin embeddings, sin almacén vectorial. La búsqueda es coincidencia de tokens sin distinción de mayúsculas/minúsculas sobre secciones de Markdown, calculada bajo demanda. Esto es suficiente a la escala de decenas a cientos de documentos pequeños, y significa que no hay índice que mantener sincronizado con los archivos en disco: los archivos son la fuente de verdad, siempre.

• Sin índice en memoria, sin vigilancia del sistema de archivos. Cada llamada de herramienta lee lo que necesita del disco en el momento de la llamada. Más simple y barato a esta escala.

• Sin commits automáticos de Git. Las llamadas de herramienta solo tocan el árbol de trabajo. La revisión y el commit/push dependen de ti. (El diseño deja espacio para añadir auto-commit o creación de PR más adelante sin cambiar los contratos de las herramientas).

Nota sobre el SDK oficial

El resumen mencionaba @modelcontextprotocol/server; el paquete realmente publicado es @modelcontextprotocol/sdk (v1.30+), que es el que usa este proyecto (McpServer + StdioServerTransport).

3. Cómo se almacena el conocimiento

Cada documento es un archivo Markdown bajo knowledge/<area>/<topic>.md, con frontmatter mínimo opcional:

---
title: APIM
tags:
  - api
  - apim
---

# APIM

## Base paths

Internal modelling APIs use ...

## Authentication

...

## Local development

...

No hay esquema obligatorio más allá de eso: el frontmatter es opcional, los encabezados son solo secciones ## normales de Markdown. search_knowledge y update_knowledge usan encabezados de nivel ## (y más profundos) como unidad de "sección", por lo que estructurar los documentos con encabezados claros hace que tanto los resultados de búsqueda como las actualizaciones sean más precisos.

El conocimiento capturado pero no clasificado va a inbox/knowledge-inbox.md como entradas con marca de tiempo. Periódicamente (a mano, o pidiendo a un agente que ayude) mueve/organiza las entradas de la bandeja de entrada a los documentos adecuados en knowledge/.

4. Ejecutarlo

Requiere Node.js 20+.

npm install
npm run build
npm start

Para iteración local (se ejecuta directamente desde TypeScript mediante tsx, sin paso de compilación):

npm run dev

Ambos inician el servidor en stdio y esperan a que un cliente se conecte: no verás tráfico de protocolo en la terminal; solo registros de inicio/diagnóstico (escritos en stderr, nunca en stdout, ya que stdout está reservado para los mensajes del protocolo MCP).

5. Pruebas con MCP Inspector

Interfaz interactiva:

npx @modelcontextprotocol/inspector npm run dev

Esto abre una interfaz de navegador donde puedes llamar a search_knowledge, list_knowledge_topics, get_knowledge, capture_knowledge, create_knowledge y update_knowledge manualmente e inspeccionar sus esquemas JSON y respuestas.

No interactivo / scriptable:

npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list

npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name search_knowledge --tool-arg query="apim authentication"

6. Ejemplo de configuración de cliente MCP

Claude Code / la mayoría de los clientes MCP usan un bloque de configuración como:

{
  "mcpServers": {
    "engineering-knowledge": {
      "command": "node",
      "args": ["/absolute/path/to/engineering-knowledge-mcp/dist/index.js"]
    }
  }
}

Para el soporte MCP de GitHub Copilot, usa la entrada de servidor stdio equivalente command/args en su archivo de configuración MCP. Ejecuta npm run build primero para que exista dist/index.js, o apunta command/args a npx tsx /absolute/path/to/src/index.ts para ejecutar desde el código fuente directamente.

7. Cómo debería un agente usar las herramientas

Este repositorio incluye un CLAUDE.md con la instrucción siguiente, que Claude Code carga automáticamente cuando trabaja dentro de este repositorio. Para otros clientes (Copilot, etc.), añade la instrucción equivalente a su prompt de sistema / archivo de instrucciones:

Antes de preguntar al usuario sobre convenciones de ingeniería internas, infraestructura, APIs, autenticación, configuración de plataforma o patrones de desarrollo establecidos, busca en el MCP de conocimiento de ingeniería. No inventes valores de configuración internos. Si el usuario pide explícitamente recordar, capturar o añadir conocimiento de ingeniería duradero, usa las herramientas de escritura del MCP de conocimiento.

Guía herramienta por herramienta:

• search_knowledge(query) — primera parada para "¿cómo solemos...?", "¿cuál es nuestra convención para...?", "¿cuál es la URL base / flujo de autenticación para...?". Devuelve secciones clasificadas con rutas de archivo, no documentos completos. También busca entradas aún no clasificadas en inbox/knowledge-inbox.md, por lo que una captura reciente es localizable incluso antes de que se haya archivado bajo un tema adecuado. Entre los documentos que ya coinciden en el texto del cuerpo/encabezado, uno cuyo frontmatter tags también coincida con una palabra de la consulta se clasifica más alto: las etiquetas aumentan la clasificación, no crean una coincidencia por sí solas.

• list_knowledge_topics() — sin argumentos; lista la ruta, el título y las etiquetas de cada documento sin el contenido completo. Úsalo para explorar lo que existe cuando aún no tienes un buen término de búsqueda, o para comprobar si un tema ya existe antes de llamar a create_knowledge.

• get_knowledge(topicOrPath) — una vez que sabes (o search_knowledge te dijo) qué documento quieres, tráelo completo. Acepta referencias flexibles: "apim", "api/apim" o "knowledge/api/apim.md".

• capture_knowledge(content, suggestedTopic?) — úsalo cuando el usuario diga "recuerda esto" / "anota eso" / afirme un hecho que vale la pena conservar, y no quieras hacerle averiguar dónde pertenece. Simplemente añade a la bandeja de entrada.

• create_knowledge(topic, title, content) — úsalo al añadir un tema genuinamente nuevo que aún no existe. Falla de forma clara si el tema ya existe (usa update_knowledge en su lugar).

• update_knowledge(topicOrPath, heading, content, mode) — la herramienta de escritura deliberadamente no en lenguaje natural. Consulta la nota de diseño a continuación.

Por qué update_knowledge toma heading + mode en lugar de un change de texto libre

El resumen marcó esto como algo que necesita un diseño cuidadoso: el objetivo es que el agente (que tiene un LLM) decida qué significa un cambio en lenguaje natural, no que este servidor ejecute su propia interpretación de IA de las instrucciones. Así que update_knowledge toma un objetivo estructural y determinista en su lugar:

• topicOrPath — qué documento.

• heading — el texto exacto del encabezado ##/###/etc. que identifica una sección. Si no existe, se añade una nueva sección ## con ese encabezado al final del documento (para que las actualizaciones nunca fallen silenciosamente contra documentos ligeramente desactualizados).

• content — el Markdown literal a escribir.

• mode: "append" (por defecto) añade content al final de la sección, "replace" sobrescribe todo el cuerpo de la sección.

Esto significa que se espera que el agente que llama ya haya convertido "actualiza la sección de desarrollo local para mencionar el nuevo puerto" en contenido Markdown concreto y haya elegido append/replace — exactamente el tipo de juicio que un cliente basado en LLM está posicionado para hacer, y exactamente el tipo de juicio que este servidor ligero no debería hacer a partir de una cadena cruda.

8. Importar una base de conocimiento existente

Si ya tienes notas en algún lugar (una wiki personal, una carpeta de archivos .md, una exportación de Notion, un gran documento de "conocimiento tribal", hilos de Slack que has guardado, etc.), no hay herramienta de importación ni formato especial al que convertir: esto es deliberadamente solo una carpeta de archivos Markdown. Dos formas de empezar, aproximadamente en orden de cuánto de tu estructura existente vale la pena preservar:

A. Coloca los archivos directamente (mejor cuando tus notas ya están razonablemente organizadas)

1. Copia tus archivos .md existentes a knowledge/, clasificándolos en las carpetas que mejor encajen de api/ cloud/ data/ frontend/ general/ (o añade nuevas carpetas de temas: nada impone las cinco iniciales).

2. Añade frontmatter mínimo (title, opcionalmente tags) a cada uno si no lo tiene: no es obligatorio, pero es barato y get_knowledge/los resultados de búsqueda se leen mejor con un título.

3. Divide documentos muy largos en secciones ## con encabezados si aún no lo están: search_knowledge y update_knowledge operan a nivel de encabezado, por lo que un muro de texto de 10,000 palabras en una sola sección se buscará/actualizará peor que el mismo contenido dividido bajo unos pocos encabezados claros.

4. Ejecuta npm test (verificación de que nada se rompió) y prueba algunas llamadas de search_knowledge / get_knowledge mediante el Inspector (§5) con tu contenido real.

5. Revisa el diff y haz commit tú mismo, igual que cualquier otro cambio en este repositorio.

B. Deja que un agente haga la migración por ti (mejor para material fuente desordenado/sin estructurar)

Apunta Claude Code (u otro agente de codificación, una vez que este MCP esté configurado para él) a tus notas existentes y pídele que las migre usando las herramientas de escritura. Por ejemplo:

Tengo notas de ingeniería en ~/notes/engineering/. Léelas y usa create_knowledge para convertirlas en documentos adecuados bajo knowledge/, agrupados por tema. Cuando algo no encaje limpiamente en un tema existente, usa capture_knowledge en su lugar para que caiga en la bandeja de entrada para que yo lo revise.

Esto funciona bien porque convertir prosa desordenada en "un título, algunas etiquetas, unas pocas secciones ## claras" es exactamente el tipo de juicio en el que un agente basado en LLM es bueno: el mismo razonamiento detrás de por qué update_knowledge empuja ese juicio al llamador en lugar del servidor (ver §7). El agente aún no puede escribir fuera de knowledge//inbox/, y cada archivo resultante aparece como un archivo normal sin seguimiento/modificado para que lo revises antes de hacer commit: nada se auto-commitea.

De cualquier manera, trata el primer pase como un borrador: está bien (incluso se espera) que capture_knowledge produzca una bandeja de entrada larga que clasifiques en varias sesiones en lugar de intentar obtener una taxonomía perfecta desde el principio.

9. Notas de seguridad

• Todas las lecturas/escrituras están restringidas a knowledge/ e inbox/ bajo la raíz del repositorio. Cada ruta proporcionada por el llamador pasa por safeResolve (src/paths.ts), que rechaza rutas absolutas, traversal .., bytes nulos y cualquier cosa que resuelva fuera del directorio permitido.

• create_knowledge sanitiza el topic en un segmento de nombre de archivo seguro antes de usarlo.

• Ningún contenido de documento se ejecuta, evalúa o se pasa a un shell.

• Ninguna herramienta ejecuta un comando de shell basado en entrada MCP.

• Los errores son explícitos (por ejemplo, "no se encontró ningún documento de conocimiento que coincida con X") en lugar de recurrir a suposiciones.