@toktokhan/ai-native-mcp

AI Native Manager MCP Server — Claude Code에서 프로젝트 에이전트·스킬·태스크·메모리를 바로 사용할 수 있는 MCP 서버입니다.

설치 및 연결

전역 연결 (개인 PC)

claude mcp add ai-native -e PROJECT_ID=<project-id> -- npx -y @toktokhan/ai-native-mcp

프로젝트 범위 연결 (팀 공유 가능)

claude mcp add ai-native -s project -e PROJECT_ID=<project-id> -- npx -y @toktokhan/ai-native-mcp

PROJECT_ID를 설정하면 모든 도구에서 프로젝트 ID를 생략할 수 있습니다.

도구 목록 (15개)

1. init — 프로젝트 초기 세팅

작업 시작 시 가장 먼저 호출합니다. 프로젝트의 에이전트·스킬·워크플로우·태스크·최근 히스토리를 한 번에 로드합니다.

init()
init({ projectId: "project-modapl" })

파라미터: | 이름 | 타입 | 설명 | |------|------|------| | writeConfig | boolean (선택) | true 설정 시 CLAUDE.md + .claude/commands/ 자동 생성 | | projectRoot | string (선택) | 파일을 쓸 경로 (기본: 현재 작업 디렉토리) |

반환: 프로젝트 정보, 에이전트 목록 (스킬 포함), 워크플로우 목록, 태스크 목록, 최근 히스토리 5개

writeConfig: true 동작

init({ writeConfig: true })

Claude Code 프로젝트에 다음 파일을 자동 생성/업데이트합니다:

CLAUDE.md — 프로젝트 컨텍스트 섹션 추가

## AI Native Manager — 프로젝트명
- 에이전트 목록
- 현재 단계
- 사용 가능한 MCP 도구 목록

.claude/agents/*.md — 6개 에이전트를 Claude Code 서브에이전트로 설치

.claude/agents/
├── planner.md    → PlannerBot  (PRD, 요구사항 분석, 태스크 분해)
├── architect.md  → ArchitectBot (UI/UX, 아키텍처 설계)
├── builder.md    → BuilderBot   (코드 구현, Git 관리)
├── tester.md     → TestBot      (테스트 시나리오, 자동화 테스트)
├── reviewer.md   → ReviewerBot  (코드 리뷰, 보안 리뷰, 갭 분석)
└── operator.md   → OperatorBot  (배포, 문서 생성, 회고)

각 에이전트 파일에는 역할·스킬 지침·행동 원칙·프로젝트 메모리가 포함됩니다. Claude Code에서 "PlannerBot에게 PRD를 작성해달라고 해" → 서브에이전트가 자동 실행됩니다.

.claude/commands/skill-*.md — 28개 스킬을 슬래시 커맨드로 설치

/skill-1-PRD-작성       → PRD 작성 지침 즉시 실행
/skill-11-코드-구현     → 코드 구현 지침 즉시 실행
...

다음 대화부터 Claude Code가 에이전트·스킬 컨텍스트를 자동으로 인식합니다.

2. task_list — 태스크 조회

task_list()
task_list({ status: "in_progress" })
task_list({ assignedTo: "builder" })

파라미터: | 이름 | 타입 | 설명 | |------|------|------| | projectId | string (선택) | PROJECT_ID 바인딩 시 생략 가능 | | status | enum (선택) | backlog | in_progress | pr_created | in_review | done | | assignedTo | string (선택) | 담당 에이전트 역할로 필터 |

3. task_run — 태스크 실행

태스크 ID를 기반으로 작업을 시작합니다. 담당 에이전트의 스킬 지침과 메모리를 반환하고, 태스크 상태를 in_progress로 변경합니다.

task_run({ taskId: "task-m2" })
task_run({ taskId: "task-m2", context: "기존 MQTT 연동 코드 위에 추가 작업" })

파라미터: | 이름 | 타입 | 설명 | |------|------|------| | taskId | string | 실행할 태스크 ID | | context | string (선택) | 추가 컨텍스트 |

4. task_update — 태스크 업데이트

task_update({ taskId: "task-m2", status: "done" })
task_update({ taskId: "task-m2", status: "pr_created", description: "PR #42 생성 완료" })

파라미터: | 이름 | 타입 | 설명 | |------|------|------| | taskId | string | 태스크 ID | | status | enum (선택) | backlog | in_progress | pr_created | in_review | done | | title | string (선택) | 제목 변경 | | description | string (선택) | 설명 변경 | | priority | enum (선택) | critical | high | medium | low |

5. memory_save — 메모리 저장

의사결정, 이슈, 마일스톤, 에이전트 학습 내용 등을 프로젝트 히스토리에 저장합니다.

memory_save({
  type: "decision",
  title: "MQTT QoS 레벨 결정",
  content: "유실 방지를 위해 QoS 1 채택",
  tags: ["mqtt", "architecture"]
})

파라미터: | 이름 | 타입 | 설명 | |------|------|------| | type | enum | decision | milestone | issue | lesson_learned | best_practice | client_communication | agent_memory | | title | string | 제목 | | content | string | 내용 | | tags | string[] (선택) | 태그 |

6. memory_list — 메모리 조회

memory_list()
memory_list({ type: "decision", limit: 10 })

파라미터: | 이름 | 타입 | 설명 | |------|------|------| | type | string (선택) | 유형 필터 | | limit | number (선택) | 최대 반환 개수 (기본: 20) |

7. memory_search — 메모리 검색

키워드로 히스토리를 검색합니다. 과거 의사결정이나 관련 맥락을 찾을 때 사용합니다.

memory_search({ query: "MQTT" })
memory_search({ query: "보안", type: "decision" })

8. client_log — 클라이언트 소통 로깅

Slack 봇 에이전트 전용

6개의 에이전트가 Slack 봇으로 클라이언트와 소통한 내용을 프로젝트 메모리에 저장합니다. 다음 대화에서 맥락으로 활용됩니다.

client_log({
  agentRole: "planner",
  channel: "#project-alpha",
  clientMessage: "요구사항 중 결제 기능 우선순위를 높여주세요",
  agentResponse: "알겠습니다. 결제 태스크를 critical로 변경하겠습니다.",
  summary: "결제 기능 우선순위 상향 요청",
  tags: ["priority", "payment"]
})

파라미터: | 이름 | 타입 | 설명 | |------|------|------| | agentRole | enum | planner | architect | builder | tester | reviewer | operator | | channel | string (선택) | Slack 채널 또는 DM | | clientMessage | string | 클라이언트 메시지 | | agentResponse | string | 에이전트 응답 | | summary | string (선택) | 소통 내용 요약 | | tags | string[] (선택) | 태그 |

9. agent_context — 에이전트 컨텍스트 조회

특정 에이전트의 스킬 목록과 학습된 메모리를 조회합니다.

agent_context({ agentRole: "builder" })

에이전트 역할: planner · architect · builder · tester · reviewer · operator

10. skill_list — 스킬 목록 조회

skill_list()
skill_list({ role: "builder" })

11. skill_run — 스킬 실행

스킬의 상세 지침을 반환하고 실행 내역을 기록합니다.

skill_run({ skillId: "skill-11" })
skill_run({ skillId: "skill-1", context: "커머스 프로젝트 PRD 작성" })

주요 스킬 ID: | ID | 이름 | 역할 | |----|------|------| | skill-1 | PRD 작성 | planner | | skill-2 | 요구사항 분석 | planner | | skill-7 | UI/UX 설계 | architect | | skill-10 | 아키텍처 설계 | architect | | skill-11 | 코드 구현 | builder | | skill-18 | 코드 리뷰 | reviewer | | skill-23 | 배포 | operator |

전체 목록: skill_list() 호출

12. skill_update — 스킬 내용 수정

로컬 작업 중 스킬 지침을 수정합니다. 현재는 인메모리 저장(서버 재시작 시 초기화), DB 연동 후 영구 반영됩니다.

skill_update({
  skillId: "skill-11",
  content: "# 코드 구현\n\n## Instructions\n1. 설계 문서 확인\n2. ..."
})

13. workflow_run — 워크플로우 실행

워크플로우의 모든 단계를 순서대로 실행합니다.

workflow_run({ workflowId: "wf-4" })
workflow_run({ workflowId: "wf-1", context: "IoT 프로젝트 요구사항 분석" })

워크플로우 목록: | ID | 이름 | |----|------| | wf-1 | 요구사항 분석 워크플로우 | | wf-2 | 아키텍처 설계 워크플로우 | | wf-3 | Task 생성 워크플로우 | | wf-4 | Task 실행 루프 워크플로우 | | wf-5 | 문서 생성 워크플로우 | | wf-6 | 배포 관리 워크플로우 | | wf-7 | 품질 검증 워크플로우 | | wf-8 | 스프린트 회고 워크플로우 |

14. workflow_update — 워크플로우 수정

워크플로우 단계나 연결된 스킬을 수정합니다. 현재는 인메모리 저장.

workflow_update({
  workflowId: "wf-4",
  steps: [
    { order: 1, skillId: "skill-11", skillName: "코드 구현", agentRole: "builder" },
    { order: 2, skillId: "skill-20", skillName: "갭 분석", agentRole: "reviewer" },
    { order: 3, skillId: "skill-13", skillName: "Git 관리", agentRole: "builder" }
  ]
})

15. report — 프로젝트 현황 리포트

report()
report({ format: "slack" })   // Slack 전송용 텍스트
report({ format: "summary" }) // JSON 요약
report({ format: "full" })    // 전체 마크다운 (기본값)

아키텍처

Claude Code
    │
    │ MCP (stdio)
    ▼
@toktokhan/ai-native-mcp
    │
    ├── init          → 프로젝트 전체 컨텍스트 로드
    ├── task_*        → 태스크 관리
    ├── memory_*      → 히스토리/메모리 관리
    ├── client_log    → Slack 봇 대화 저장
    ├── agent_context → 에이전트 컨텍스트
    ├── skill_*       → 스킬 조회/실행/수정
    ├── workflow_*    → 워크플로우 실행/수정
    └── report        → 현황 리포트

에이전트 구조

| 역할 | 이름 | 담당 | |------|------|------| | planner | PlannerBot | PRD, 요구사항 분석, 태스크 분해 | | architect | ArchitectBot | UI/UX, 디자인 시스템, 아키텍처 | | builder | BuilderBot | 코드 구현, Git 관리 | | tester | TestBot | 테스트 시나리오, 자동화 테스트 | | reviewer | ReviewerBot | 코드 리뷰, 보안 리뷰, 갭 분석 | | operator | OperatorBot | 배포, 문서 생성, 회고 |

개발

# 빌드
npm run build

# 개발 모드 (tsx)
PROJECT_ID=project-modapl npm run dev

# 로컬 MCP 연결 (빌드 후)
claude mcp add ai-native-local -e PROJECT_ID=project-modapl -- node /path/to/mcp-server/build/index.js

로드맵

• [ ] Supabase API 연동 (실제 DB 영구 저장)
• [ ] Slack API 직접 연동 (client_log 자동 수집)
• [ ] 에이전트별 메모리 영구 저장
• [ ] 프로젝트 생성/수정 도구 추가