Artifact Hub

Artifact Hub는 팀을 위한 Agent 지식 베이스이자 MCP Server입니다. Git을 사용하여 재사용 가능한 지식 산출물을 저장하고, IDE와 Agent에 MCP 도구를 노출하며, 지식, 리뷰 작업, 사용도를 확인할 수 있는 Dashboard를 제공합니다.

기존 버전의 skill registry로 계속 사용할 수도 있고, Agent의 각 세션에서 생성된 skill, spec, plan, review, adr을 축적하는 중앙 집중식 AI 지식 베이스로 사용할 수도 있습니다.

빠른 시작

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

서비스가 시작되면 액세스 Token을 출력하고 다음을 노출합니다:

• Dashboard: http://localhost:3721

• REST API: /api/*

• MCP HTTP endpoint: /mcp

Dashboard에 시작 시 출력된 Token을 입력하면 연결할 수 있습니다.

Related MCP server: jt-mcp-server

전역 설치

저장소 루트 디렉터리에서 다음을 실행합니다:

npm link

이후 로컬에서 artifact-hub 명령을 직접 사용할 수 있으며, 다른 프로젝트에서 npx artifact-hub로 호출할 수도 있습니다.

중앙 집중식 Agent 지식 베이스

팀은 Artifact Hub를 중앙 집중식 MCP Server로 배포할 수 있습니다. Git의 knowledge/**가 사실의 원천(source of truth)입니다:

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

지원되는 지식 산출물 유형:

• skill: 재사용 가능한 운영 스킬, 엔지니어링 규범, 도구 사용 방법.

• spec: 제품, 인터페이스, 프로세스, 데이터 모델 등의 사양 설명.

• plan: 재사용 가능한 실행 계획, 마이그레이션 계획, 구현 단계.

• review: 코드 리뷰, 솔루션 리뷰, 리스크 리뷰의 축적.

• adr: 아키텍처 결정 기록. 결정 상태와 대체된 결정을 포함합니다.

Agent 권장 워크플로:

1. 최초 연결 시 get_agent_instructions를 호출하여 팀 지식 베이스 사용 규칙을 가져옵니다.

2. 규모가 큰 작업을 시작할 때 session_start를 호출하여 세션을 기록합니다.

3. 재사용 가능한 콘텐츠를 생성하기 전에 search_artifacts를 호출하여 지식을 중복 생성하지 않도록 합니다.

4. 관련 지식이 발견되면 get_artifact를 호출하여 전체 내용을 로드합니다.

5. 새로운 재사용 가능한 skill, spec, plan, review 또는 adr을 생성한 후 create_artifact 또는 update_artifact를 호출하여 저장합니다.

6. 작업을 끝내기 전에 session_end를 호출하여 시스템이 이번 세션에서 어떤 산출물이 축적되었는지 기록하도록 합니다.

Agent가 능동적으로 사용하도록 하는 방법

artifact-hub install은 MCP 구성과 Agent 지침을 프로젝트가 지원하는 IDE/Agent 구성 위치에 작성합니다. 예:

• Claude Code: CLAUDE.md

• Codex / 범용 Agent: AGENTS.md

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

이 지침은 Agent가 재사용 가능한 작업을 시작하기 전에 지식 베이스를 먼저 검색하고, 재사용 가능한 콘텐츠를 생성한 후 지식 산출물을 저장하도록 요구합니다. MCP Server는 또한 동적 도구 호출을 지원하는 Agent가 런타임에 규칙을 다시 가져올 수 있도록 get_agent_instructions 도구를 제공합니다.

사용도는 .artifact-hub/usage.json에 기록되며, Dashboard의 "사용도" 페이지에서 Agent의 session, search, write 통계를 확인할 수 있습니다. 이를 통해 팀이 실제로 지식 베이스를 재사용하고 있는지 관찰할 수 있습니다.

IDE에 설치

원클릭으로 MCP 구성과 Agent 지침을 작성합니다:

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

특정 IDE의 MCP 구성만 생성할 수도 있습니다:

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는 .cursor/mcp.json에 작성하고, Claude Code는 .mcp.json에 작성합니다. 구성은 MCP HTTP endpoint를 가리킵니다:

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

IDE가 stdio bridge만 지원하는 경우 프록시 구성을 생성할 수 있습니다:

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

지식 산출물 형식

각 지식 산출물은 frontmatter가 있는 Markdown 파일입니다:

---
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.

공통 필드는 다음과 같습니다:

• 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은 추가로 triggers와 eval_cases를 지원하고, adr은 추가로 decision_status와 supersedes를 지원합니다.

MCP 도구

공통 지식 베이스 도구:

• get_agent_instructions: Agent가 반드시 준수해야 하는 지식 베이스 사용 규칙을 가져옵니다.

• session_start: Agent 세션 시작을 기록합니다.

• session_end: Agent 세션 종료와 이번 축적 내용을 기록합니다.

• search_artifacts: 유형, 프로젝트, 태그, 별칭, 상태, 키워드로 지식 산출물을 검색합니다.

• get_artifact: 전체 지식 산출물을 읽습니다.

• get_related_artifacts: 관련 지식 산출물 추천을 가져옵니다.

• create_artifact: 새 지식 산출물을 생성합니다.

• update_artifact: 지식 산출물을 업데이트합니다.

• archive_artifact: 지식 산출물을 아카이브합니다.

• delete_artifact: 지식 산출물을 삭제합니다.

• get_artifact_history: Git 기록을 확인합니다.

• get_artifact_diff: 버전 차이를 확인합니다.

• rollback_artifact: 지정된 Git ref로 롤백합니다.

• validate_artifact: 규칙 기반 Reviewer 검사를 실행합니다.

• propose_artifact_change: 지식 산출물 변경 리뷰를 제출합니다.

• list_review_tasks: 리뷰 작업을 확인합니다.

• review_artifact: 승인, 거부 또는 에스컬레이션을 기록합니다.

• evaluate_artifact: skill 유형에 대해 eval cases를 실행합니다.

• get_git_status: 지식 베이스의 Git 상태를 확인합니다.

기존 skill API와 호환되는 도구는 계속 유지됩니다:

• search_skills

• get_skill

• create_skill

• update_skill

• propose_skill_update

• evaluate_skill

• save_artifact

Dashboard

Dashboard는 이제 지식 베이스를 주요 진입점으로 사용합니다:

• "지식 베이스" 페이지: skill/spec/plan/review/adr을 검색하고 확인합니다.

• "리뷰" 페이지: 대기 중인 리뷰 작업을 확인하고 승인 또는 거부를 실행합니다.

• "사용도" 페이지: Agent의 세션, 검색, 쓰기 통계를 확인합니다.

• "설정" 페이지: MCP 구성을 확인하고 엄격한 승인 또는 개방형 쓰기 모드를 전환합니다.

마이그레이션

기존 버전의 skills/*.md를 새 지식 베이스 디렉터리로 마이그레이션할 수 있습니다:

artifact-hub migrate --root .

이 명령은 기존 스킬을 knowledge/skill/*.md에 작성하고, 원본 내용을 보존하며, frontmatter에 마이그레이션 정보를 표시합니다.

거버넌스

서비스는 기본적으로 엄격 모드입니다:

• 고위험 또는 리뷰가 필요한 artifact 쓰기는 .artifact-hub/reviews/로 이동합니다.

• Maintainer는 Dashboard의 "리뷰" 페이지에서 승인하거나 거부할 수 있습니다.

• 설정은 <root>/.artifact-hub/settings.json에 저장됩니다.

개방 모드로 전환하면 추가 및 수정 사항이 Git 기반 knowledge store에 직접 기록됩니다.

개발

API Server와 Vite Dev Server를 각각 시작합니다:

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

Vite는 http://localhost:5173에서 실행되며 /api를 백엔드로 프록시합니다.

아키텍처

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

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

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

• packages/web: React + Vite Dashboard.

테스트

npm test
npm run build

라이선스

이 프로젝트는 MIT License를 사용합니다. 자세한 내용은 LICENSE를 참조하세요.

자주 사용하는 명령

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>