Kioku
Un servidor MCP local-first en .NET que convierte el conocimiento de proyecto de agentes de IA — decisiones, planes, bugs y sesiones — en registros Markdown durables dentro de un vault de Obsidian, con un contrato de herramientas generado, evaluación de retrieval y evidencia de traspaso multi-agente.
- CICLO DE VIDA
- Activo — release estable más desarrollo activo
- ACCESO AL CÓDIGO
- Repositorio público; código fuente, releases y tests son directamente inspeccionables.
- ACCESO A DEMO
- Sin demo en vivo alojada; una demo reproducible de traspaso multi-agente está documentada en el repositorio.
- La arquitectura, el contrato de tools y la evidencia de demo no publicados viven en la rama de desarrollo activo, no en la release 2.3.0.
- No se afirma adopción externa ni escala de producción para este proyecto.
ESTADO ACTUAL
Release 2.3.0 estable — desarrollo activo sobre un contrato más reducido
Las capacidades estables y las de desarrollo activo se presentan por separado más abajo. Las funcionalidades que solo existen en la rama de desarrollo activo están explícitamente etiquetadas como no publicadas.
EL JEFE // PROBLEMA
Los agentes de codificación con IA pierden contexto cuando termina una sesión o proceso: decisiones, planes, bugs y conocimiento de proyecto suelen quedar atrapados en una sola conversación en lugar de convertirse en registros durables y reutilizables. Necesitaba una forma de que un agente traspasara un proyecto a otro agente — o a una futura sesión de sí mismo — sin depender del historial de conversación compartido.
LA ESTRATEGIA // ENFOQUE
Diseñé Kioku como un servidor Model Context Protocol local-first que lee y escribe conocimiento de proyecto estructurado — sesiones, planes, ADRs, bugs y consultas — como Markdown y frontmatter YAML dentro de un vault de Obsidian. El servidor expone este conocimiento mediante tools, prompts y resources MCP tipados detrás de una arquitectura .NET en capas: un adaptador MCP traduce las llamadas del protocolo a contratos de aplicación, los contratos de aplicación dirigen servicios de workflow, y los servicios de workflow dependen de puertos de dominio e infraestructura implementados contra el sistema de archivos, retrieval híbrido y un pipeline opcional de embeddings basado en Ollama. Tests de guarda de arquitectura hacen cumplir la dirección de dependencias y mantienen el servidor como un único ensamblado desplegable en lugar de dividirlo prematuramente.
EL SACRIFICIO // COMPENSACIONES
Mantuve el proyecto como un único ensamblado Kioku.Mcp.Server y usé tests de guarda de arquitectura para sostener los límites en lugar de dividirlo en varios servicios desplegables antes de tener una razón concreta. La rama estable main todavía expone una superficie más antigua de 128 tools en 19 clases de tools; el desarrollo activo reduce esto a un contrato generado y con capacidades configurables — 43 tools por defecto y 59 con todas las capacidades habilitadas — para mantener el esquema del protocolo más pequeño en clientes con presupuestos de contexto limitados. Ese rediseño no está publicado, así que este case study reporta la evidencia estable y la de desarrollo activo por separado en lugar de combinarlas en un solo número.
VICTORIA // RESULTADO
La release estable, versión 2.3.0, se publica como herramienta NuGet llamada kioku-mcp-server, con tests automatizados del servidor, CI en tres sistemas operativos, una suite de evaluación de retrieval documentada e historial de releases. En la rama de desarrollo activo, una demo reproducible multi-proceso muestra a un agente creando una sesión, un plan, un ADR y un bug, cerrando su conexión, y a un segundo agente — mediante una conexión y proceso MCP independientes — recuperando ese contexto de proyecto y continuando el trabajo, que es el comportamiento de persistencia y traspaso que el proyecto buscaba demostrar. Pull requests recientes reportan todos los tests del servidor pasando localmente; eso es validación reportada en el PR, no un resultado re-ejecutado de forma independiente para este case study.
IMPLEMENTADO // VERIFICADO EN LA DOCUMENTACIÓN DEL REPOSITORIO
- Servidor MCP público en .NET 10 publicado como herramienta NuGet kioku-mcp-server, release 2.3.0.
- Transporte local stdio y HTTP, con embeddings y generación opcionales mediante una instancia local de Ollama.
- 128 tools MCP en 19 clases de tools, 10 prompts y 2 resources en la rama estable main auditada.
- Tests automatizados del servidor, CI multi-SO en Ubuntu, Windows y macOS, checks de formato y vulnerabilidades, e historial de releases y changelog documentado.
- Una suite de evaluación de retrieval con Precision@k, Recall@k, MRR y NDCG@k sobre un vault de fixtures bilingüe de 27 notas con 22 consultas puntuadas y 2 pruebas sin respuesta.
PLANIFICADO // NO PRESENTADO COMO ENTREGADO
- Promover la arquitectura en capas de desarrollo activo — adaptador MCP, contratos de aplicación, servicios de workflow, puertos de dominio e infraestructura — a una release estable.
- Publicar el contrato de tools generado más reducido, 43 tools por defecto y 59 con todas las capacidades, como la nueva superficie pública estable, reemplazando el diseño anterior de 128 tools.
- Promover la demo reproducible de traspaso multi-agente de evidencia de desarrollo a comportamiento documentado en una release.
- Reconciliar los resultados de benchmark de desarrollo activo con un entorno y dataset de release estable antes de citarlos fuera de un contexto de desarrollo.
ARQUITECTURA // DESARROLLO ACTIVO
Cliente MCP (Agente de IA)
stdio · Streamable HTTP
Adaptador MCP
Tools · prompts · resources
Contratos de Aplicación
Límites de caso de uso
Servicios de Workflow
Sesiones · documentos · consultas
Puertos de Dominio e Infraestructura
Abstracciones de repositorio
Implementación de Infraestructura
Vault de Obsidian (Markdown/YAML) · embeddings opcionales con Ollama
DECISIONES DE SEGURIDAD
- Kioku es local-first: el vault de Obsidian es la fuente de verdad y permanece completamente legible y editable sin que el servidor esté en ejecución.
- CI ejecuta escaneo de vulnerabilidades de dependencias junto con los gates de build, formato y tests en cada cambio.
- Los embeddings y la generación opcionales se ejecutan mediante una instancia local de Ollama en lugar de un servicio externo obligatorio, por lo que el contenido del vault permanece en la máquina del usuario por defecto.
DECISIONES DE PRUEBAS
- Los tests nativos del servidor corren en Ubuntu, Windows y macOS con un gate de cobertura de línea del 40% aplicado en CI.
- Tests de sandbox de sistema de archivos, smoke tests stdio de la herramienta instalada y smoke tests nativos de Streamable HTTP de archivo único validan la herramienta empaquetada, no solo el árbol de código fuente.
- Los tests de guarda de arquitectura hacen cumplir la forma de constructores, la dirección de dependencias, el registro de DI y la propagación de cancelación en lugar de depender solo de revisión manual.
- Pull requests recientes reportan 708 de 708 tests del servidor pasando localmente; eso es validación reportada en el PR y no se reverifica de forma independiente para este case study.
DECISIONES DE DESPLIEGUE
- El servidor se distribuye como herramienta global de NuGet, kioku-mcp-server, por lo que se instala y ejecuta localmente sin un backend alojado.
- La release 2.3.0 y su changelog se publican desde la rama estable main; el desarrollo activo en develop lleva trabajo sustancial sin publicar.
- El plugin puente de Obsidian se extrajo a su propio repositorio, sandovaldavid/kioku-obsidian, con versionado independiente, manteniendo el ritmo de releases del servidor separado del plugin.
Estable 2.3.0 · desarrollo activo
Ingeniero backend y mantenedor
XP GANADA // APRENDIZAJES
- Los registros Markdown durables y legibles por humanos sobreviven los límites de sesión y proceso mejor que el historial de conversación específico de un proveedor.
- Los tests de guarda de arquitectura mantienen honesto a un servidor de un solo ensamblado sobre su propia dirección de dependencias a medida que la superficie de tools crece y cambia.
- Publicar la metodología de evaluación de retrieval y benchmarks junto con los resultados importa tanto como los números mismos — una métrica sin su entorno y dataset no es evidencia reutilizable.
LIMITACIONES DE ACCESO Y EVIDENCIA
- La arquitectura en capas, el contrato de tools reducido y la demo de traspaso multi-agente descritos arriba viven en la rama de desarrollo activo y no forman parte de la release 2.3.0 hasta que se promuevan.
- Los números de benchmark y retrieval provienen de una única máquina, dataset y configuración de modelo Ollama documentados; no son un SLA entre distintos hardwares.
- Los conteos recientes de tests pasados son reportados en el PR y no se re-ejecutan de forma independiente para este case study; el estado de GitHub Actions no estaba disponible al momento de la revisión.
- No se afirma adopción externa, carga de producción ni impacto comercial para este proyecto.
FUENTE Y EVIDENCIA
- Kioku — servidor MCP para Obsidian
Repositorio público; código fuente, releases, tests y documentación generada son directamente inspeccionables.