Artifact Hub

Artifact Hub es una base de conocimientos de Agent y un MCP Server orientado a equipos. Utiliza Git para guardar artefactos de conocimiento reutilizables, expone herramientas MCP a IDE y Agent, y ofrece un Dashboard para consultar el conocimiento, revisar tareas y medir el uso.

Puede seguir utilizándose como el antiguo skill registry, o como una base de conocimientos de IA centralizada que acumula los skill, spec, plan, review y adr generados en cada sesión de Agent.

Inicio rápido

npm install
npm run build
node packages/server/src/cli.js start --port 3721 --root .

Tras el arranque, el servicio imprime el Token de acceso y expone:

• Dashboard: http://localhost:3721

• REST API: /api/*

• MCP HTTP endpoint: /mcp

Introduce el Token impreso al arrancar en el Dashboard para conectarte.

Related MCP server: jt-mcp-server

Instalación global

Ejecuta en la raíz del repositorio:

npm link

Después, en esta máquina puedes usar directamente el comando artifact-hub, o invocarlo desde otros proyectos mediante npx artifact-hub.

Base de conocimientos centralizada de Agent

El equipo puede desplegar Artifact Hub como un MCP Server centralizado. En Git, knowledge/** es la fuente de verdad:

knowledge/
  skill/<id>.md
  spec/<id>.md
  plan/<id>.md
  review/<id>.md
  adr/<id>.md

Tipos de artefactos de conocimiento admitidos:

• skill: habilidades operativas reutilizables, estándares de ingeniería, métodos de uso de herramientas.

• spec: especificaciones de producto, interfaces, flujos, modelos de datos, etc.

• plan: planes de ejecución reutilizables, planes de migración, pasos de implementación.

• review: revisiones de código, de propuestas y de riesgos consolidadas.

• adr: registros de decisiones de arquitectura, incluido el estado de la decisión y las decisiones sustituidas.

Flujo de trabajo recomendado para Agent:

1. En la primera conexión, llama a get_agent_instructions para obtener las reglas de uso de la base de conocimientos del equipo.

2. Antes de comenzar tareas grandes, llama a session_start para registrar la sesión.

3. Antes de producir contenido reutilizable, llama a search_artifacts para evitar duplicar conocimiento.

4. Cuando encuentres conocimiento relevante, llama a get_artifact para cargar el contenido completo.

5. Tras generar un nuevo skill, spec, plan, review o adr reutilizable, llama a create_artifact o update_artifact para guardarlo.

6. Antes de finalizar la tarea, llama a session_end para que el sistema registre qué artefactos se consolidaron en esta sesión.

Cómo hacer que Agent lo use de forma proactiva

artifact-hub install escribe la configuración de MCP y las instrucciones de Agent en las ubicaciones de configuración de IDE/Agent que admite el proyecto, por ejemplo:

• Claude Code: CLAUDE.md

• Codex / Agent genérico: AGENTS.md

• Cursor: .cursor/rules/knowledge-hub.mdc

Estas instrucciones exigen que Agent consulte la base de conocimientos antes de comenzar trabajo reutilizable y que guarde artefactos de conocimiento tras producir contenido reutilizable. El MCP Server también ofrece la herramienta get_agent_instructions para que los Agent que admiten invocación dinámica de herramientas puedan volver a obtener las reglas en tiempo de ejecución.

El uso se registra en .artifact-hub/usage.json; la página "Uso" del Dashboard muestra las estadísticas de session, search y write de Agent, para observar si el equipo está reutilizando realmente la base de conocimientos.

Instalación en IDE

Escritura con un clic de la configuración de MCP y las instrucciones de Agent:

artifact-hub install --server http://localhost:3721 --token <token>

También puedes generar solo la configuración de MCP de un IDE concreto:

node packages/server/src/cli.js init-ide --ide cursor --server http://localhost:3721 --token <token>
node packages/server/src/cli.js init-ide --ide claude --server http://localhost:3721 --token <token>

Cursor escribe en .cursor/mcp.json; Claude Code escribe en .mcp.json. La configuración apunta al MCP HTTP endpoint:

{
  "mcpServers": {
    "team-artifact-hub": {
      "url": "http://localhost:3721/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Si el IDE solo admite stdio bridge, puedes generar una configuración de proxy:

node packages/server/src/cli.js init-ide --transport stdio --ide cursor --server http://localhost:3721 --token <token>

Formato de los artefactos de conocimiento

Cada artefacto de conocimiento es un archivo Markdown con frontmatter:

---
id: api-contract
type: spec
title: API Contract
status: active
version: 1.0.0
author: agent
owner: platform
description: REST API contract rules.
tags:
  - api
  - backend
aliases:
  - rest contract
related_artifacts:
  - adr/http-style
applicable_projects:
  - billing-service
source_conversation_id: session-1
review_policy: reviewer
risk: medium
created_at: 2026-08-20T00:00:00.000Z
updated_at: 2026-08-20T00:00:00.000Z
---

# API Contract

Use resource-oriented URLs and stable response envelopes.

Los campos comunes incluyen:

• id, type, title, status, version

• author, owner, description

• tags, aliases, related_artifacts

• applicable_projects, source_conversation_id

• review_policy, risk, created_at, updated_at

skill admite además triggers y eval_cases; adr admite además decision_status y supersedes.

Herramientas MCP

Herramientas generales de la base de conocimientos:

• get_agent_instructions: obtiene las reglas de uso de la base de conocimientos que Agent debe cumplir.

• session_start: registra el inicio de la sesión de Agent.

• session_end: registra el fin de la sesión de Agent y lo consolidado en ella.

• search_artifacts: busca artefactos de conocimiento por tipo, proyecto, etiqueta, alias, estado y palabra clave.

• get_artifact: lee el artefacto de conocimiento completo.

• get_related_artifacts: obtiene recomendaciones de artefactos de conocimiento relacionados.

• create_artifact: crea un nuevo artefacto de conocimiento.

• update_artifact: actualiza un artefacto de conocimiento.

• archive_artifact: archiva un artefacto de conocimiento.

• delete_artifact: elimina un artefacto de conocimiento.

• get_artifact_history: consulta el historial de Git.

• get_artifact_diff: consulta las diferencias entre versiones.

• rollback_artifact: revierte a un ref de Git especificado.

• validate_artifact: ejecuta comprobaciones del Reviewer basado en reglas.

• propose_artifact_change: envía una revisión de cambio de artefacto de conocimiento.

• list_review_tasks: consulta las tareas de revisión.

• review_artifact: registra aprobación, rechazo o escalado.

• evaluate_artifact: ejecuta eval cases para artefactos de tipo skill.

• get_git_status: consulta el estado de Git de la base de conocimientos.

Las herramientas compatibles con la antigua skill API se conservan:

• search_skills

• get_skill

• create_skill

• update_skill

• propose_skill_update

• evaluate_skill

• save_artifact

Dashboard

El Dashboard ahora tiene la base de conocimientos como entrada principal:

• Página "Base de conocimientos": busca y consulta skill/spec/plan/review/adr.

• Página "Revisión": consulta las tareas de revisión pendientes y ejecuta aprobación o rechazo.

• Página "Uso": consulta las estadísticas de sesión, búsqueda y escritura de Agent.

• Página "Configuración": consulta la configuración de MCP y alterna entre aprobación estricta o escritura abierta.

Migración

Los antiguos skills/*.md se pueden migrar al nuevo directorio de la base de conocimientos:

artifact-hub migrate --root .

El comando escribe las antiguas skills en knowledge/skill/*.md, conservando el contenido original y marcando la información de migración en el frontmatter.

Gobernanza

El servicio usa por defecto el modo estricto:

• Las escrituras de artefactos de alto riesgo o que requieren revisión entran en .artifact-hub/reviews/.

• El Maintainer puede aprobar o rechazar en la página "Revisión" del Dashboard.

• La configuración se guarda en <root>/.artifact-hub/settings.json.

Al cambiar al modo abierto, las altas y modificaciones se escriben directamente en el knowledge store respaldado por Git.

Desarrollo

Inicia por separado el API Server y el Vite Dev Server:

node packages/server/src/cli.js start --port 3721 --root .
npm run dev

Vite se ejecuta en http://localhost:5173 y proxifica /api al backend.

Arquitectura

• packages/core: frontmatter de artefactos, índice, servicio de Git, store, revisión, uso de sesión, eval.

• packages/mcp-server: enrutador MCP JSON-RPC, gateway HTTP, proxy stdio.

• packages/server: REST API, SSE, Dashboard estático, CLI.

• packages/web: Dashboard React + Vite.

Pruebas

npm test
npm run build

Licencia

Este proyecto utiliza la licencia MIT; consulta LICENSE para más detalles.

Comandos habituales

node packages/server/src/cli.js start --port 3721 --root .
artifact-hub install --server http://localhost:3721 --token <token>
artifact-hub migrate --root .
node packages/server/src/cli.js mcp-proxy --server http://localhost:3721 --token <token>