Artifact Hub

Artifact Hub is a team-oriented Agent knowledge base and MCP Server. It uses Git to store reusable knowledge artifacts, exposes MCP tools to IDEs and Agents, and provides a Dashboard for viewing knowledge, reviewing tasks, and usage.

It can continue to serve as a legacy skill registry, or act as a centralized AI knowledge base that accumulates the skill, spec, plan, review, and adr artifacts produced in every Agent session.

Quick Start

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

After the service starts, it prints an access Token and exposes:

• Dashboard: http://localhost:3721

• REST API: /api/*

• MCP HTTP endpoint: /mcp

Enter the Token printed at startup in the Dashboard to connect.

Related MCP server: jt-mcp-server

Global Installation

Run this in the repository root:

npm link

After that, you can use the artifact-hub command directly on this machine, or invoke it from other projects via npx artifact-hub.

Centralized Agent Knowledge Base

Teams can deploy Artifact Hub as a centralized MCP Server. The knowledge/** directory in Git is the source of truth:

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

Supported knowledge artifact types:

• skill: Reusable operational skills, engineering standards, and tool usage.

• spec: Specifications for products, interfaces, processes, data models, etc.

• plan: Reusable execution plans, migration plans, and implementation steps.

• review: Code review, design review, and risk review outcomes.

• adr: Architecture Decision Records, including decision status and superseded decisions.

Recommended Agent workflow:

1. On first connection, call get_agent_instructions to retrieve the team knowledge base usage rules.

2. Before starting a larger task, call session_start to record the session.

3. Before producing reusable content, call search_artifacts to avoid duplicating knowledge.

4. When relevant knowledge is found, call get_artifact to load the full content.

5. After producing new reusable skill, spec, plan, review, or adr artifacts, call create_artifact or update_artifact to save them.

6. Before finishing a task, call session_end so the system records which artifacts were produced in this session.

How to Get Agents to Actively Use It

artifact-hub install writes MCP configuration and Agent instructions into the IDE/Agent config locations supported by the project, for example:

• Claude Code: CLAUDE.md

• Codex / generic Agents: AGENTS.md

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

These instructions require Agents to search the knowledge base before starting reusable work and to save knowledge artifacts after producing reusable content. The MCP Server also provides the get_agent_instructions tool, so Agents that support dynamic tool calls can pull the rules again at runtime.

Usage is recorded in .artifact-hub/usage.json. The "Usage" page in the Dashboard shows Agent session, search, and write statistics, so you can observe whether the team is actually reusing the knowledge base.

Installing to an IDE

Write MCP configuration and Agent instructions with one command:

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

You can also generate MCP configuration for a single IDE:

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 writes to .cursor/mcp.json, and Claude Code writes to .mcp.json. The configuration points to the MCP HTTP endpoint:

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

If the IDE only supports a stdio bridge, you can generate a proxy configuration:

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

Knowledge Artifact Format

Each knowledge artifact is a Markdown file with 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.

Common fields include:

• 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 additionally supports triggers and eval_cases; adr additionally supports decision_status and supersedes.

MCP Tools

General knowledge base tools:

• get_agent_instructions: Retrieve the knowledge base usage rules Agents must follow.

• session_start: Record the start of an Agent session.

• session_end: Record the end of an Agent session and what was produced.

• search_artifacts: Search knowledge artifacts by type, project, tag, alias, status, and keyword.

• get_artifact: Read a full knowledge artifact.

• get_related_artifacts: Get recommendations for related knowledge artifacts.

• create_artifact: Create a new knowledge artifact.

• update_artifact: Update a knowledge artifact.

• archive_artifact: Archive a knowledge artifact.

• delete_artifact: Delete a knowledge artifact.

• get_artifact_history: View Git history.

• get_artifact_diff: View version differences.

• rollback_artifact: Roll back to a specified Git ref.

• validate_artifact: Run rule-based Reviewer checks.

• propose_artifact_change: Submit a knowledge artifact change for review.

• list_review_tasks: View review tasks.

• review_artifact: Record approval, rejection, or escalation.

• evaluate_artifact: Run eval cases for skill type artifacts.

• get_git_status: View the Git status of the knowledge base.

Tools compatible with the legacy skill API are still retained:

• search_skills

• get_skill

• create_skill

• update_skill

• propose_skill_update

• evaluate_skill

• save_artifact

Dashboard

The Dashboard now uses the knowledge base as its main entry point:

• "Knowledge Base" page: Search and view skill/spec/plan/review/adr.

• "Review" page: View pending review tasks and approve or reject them.

• "Usage" page: View Agent session, search, and write statistics.

• "Settings" page: View MCP configuration, toggle strict approval or open writing.

Migration

Legacy skills/*.md files can be migrated to the new knowledge base directory:

artifact-hub migrate --root .

The command writes legacy skills to knowledge/skill/*.md, preserving the original content and marking migration information in the frontmatter.

Governance

The service defaults to strict mode:

• Writes of high-risk artifacts or artifacts requiring review go to .artifact-hub/reviews/.

• Maintainers can approve or reject them on the "Review" page in the Dashboard.

• Settings are stored in <root>/.artifact-hub/settings.json.

After switching to open mode, additions and modifications are written directly to the Git-backed knowledge store.

Development

Start the API Server and Vite Dev Server separately:

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

Vite runs at http://localhost:5173 and proxies /api to the backend.

Architecture

• packages/core: artifact frontmatter, indexing, Git service, store, review, session usage, eval.

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

• packages/server: REST API, SSE, static Dashboard, CLI.

• packages/web: React + Vite Dashboard.

Testing

npm test
npm run build

License

This project is licensed under the MIT License. See LICENSE for details.

Common Commands

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>