Arch MCP Tools

@koreai/arch-mcp-tools는 AI 코딩 어시스턴트를 Kore.ai Agent Platform에 연결하는 Model Context Protocol(MCP) 서버입니다. 이 서버는 플랫폼에서 에이전트를 빌드, 평가, 최적화, 디버그, 분석할 수 있는 도구 세트를 어시스턴트에게 제공합니다 — 프로젝트, 에이전트, 도구를 생성·편집하고, 평가를 실행하며, 실시간 세션과 트레이스를 검사하고, 실패를 진단합니다 — 에디터나 터미널에서 직접 할 수 있습니다.

모든 MCP 호환 클라이언트(Claude Code, Cursor, VS Code, Codex CLI 등)와 작동합니다. 서버는 **arch-agent-platform**이라는 이름으로 클라이언트에 노출되며, 도구에는 platform_* 및 debug_* 접두사가 붙습니다.

1.5.0 릴리스

@koreai/arch-mcp-tools@1.5.0은 1.x 호환 라인 내에서 SemVer 마이너 업데이트를 유지하면서도 상당한 기능 릴리스입니다.

이 릴리스는 다음을 추가합니다:

• 13개 기능 그룹에 걸친 전체 45개 공개 도구와 179개 스키마 선언 작업에 대한 코드 기반 커버리지;

• 작업 범위별 신뢰도, 안전, 전제 조건, 제한 사항, 종속성 및 검증 지침;

• 추가 arch://guidance/v1/* 리소스와 계획·검증 프롬프트;

• 소유권 안전 arch-mcp-guidance 명령을 통해서만 설치되는 스키마 게이트형 Codex/Claude 스킬 하나;

• 클린 패키지, 권한 부여/격리, 호환성, 실패 격리 및 4가지 메트릭 커버리지 게이트.

지식 프로토콜은 스키마 버전 1을 유지합니다. 패키지 버전과 지식 스키마 버전은 의도적으로 독립적입니다. 기존 45개 도구 검색, 도구 이름과 스키마, 초기화 지침, 프로젝트 빌더 페이로드/순서, 그리고 기존 Studio 다운그레이드 동작은 변경되지 않습니다. 새 리소스와 프롬프트는 추가되며, 지침 구성은 레거시 MCP 표면을 비활성화하지 않고 소프트하게 실패합니다.

사용자는 릴리스를 명시적으로 고정할 수 있습니다:

npx -y @koreai/arch-mcp-tools@1.5.0

Related MCP server: MCP Architect

요구 사항

• Node.js 18 이상 — 서버는 npx로 실행되며 별도 설치가 필요하지 않습니다.

• Kore.ai Agent Platform 계정 — 첫 연결 시 인증합니다(인증 참조).

설치

@koreai/arch-mcp-tools는 표준 stdio MCP 서버입니다. 모든 클라이언트는 동일한 방식으로 실행합니다:

command:  npx
args:     -y  @koreai/arch-mcp-tools

아래의 클라이언트 설정에서 arch-agent-platform이라는 이름의 서버로 추가하세요. 버전을 고정하지 않은 형식은 npm latest 태그를 따릅니다. 재현 가능한 설치를 위해서는 @koreai/arch-mcp-tools@1.5.0을 사용하세요. (내장된 환경은 없습니다 — 환경 선택 참조.)

Claude Code

claude mcp add arch-agent-platform -- npx -y @koreai/arch-mcp-tools

또는 .mcp.json(프로젝트)이나 ~/.claude.json(전역)에 추가하세요:

{
  "mcpServers": {
    "arch-agent-platform": {
      "command": "npx",
      "args": ["-y", "@koreai/arch-mcp-tools"]
    }
  }
}

Cursor

.cursor/mcp.json(프로젝트) 또는 ~/.cursor/mcp.json(전역)에 추가하세요:

{
  "mcpServers": {
    "arch-agent-platform": {
      "command": "npx",
      "args": ["-y", "@koreai/arch-mcp-tools"]
    }
  }
}

VS Code (GitHub Copilot)

.vscode/mcp.json에 추가하세요 — 최상위 키는 servers입니다(mcpServers가 아님):

{
  "servers": {
    "arch-agent-platform": {
      "command": "npx",
      "args": ["-y", "@koreai/arch-mcp-tools"]
    }
  }
}

Codex CLI

codex mcp add arch-agent-platform -- npx -y @koreai/arch-mcp-tools

또는 ~/.codex/config.toml에 추가하세요 — 이 형식은 TOML이며 JSON이 아닙니다:

[mcp_servers.arch-agent-platform]
command = "npx"
args = ["-y", "@koreai/arch-mcp-tools"]

기타 MCP 클라이언트

명령어 npx와 인수 ["-y", "@koreai/arch-mcp-tools"]를 사용하여 stdio 서버를 구성하세요. 선택적으로 AGENTS_URL 환경 변수를 설정하여 환경을 고정할 수 있습니다.

선택적 Codex 또는 Claude 지침 스킬

이 패키지에는 서버의 버전별 작업 카탈로그를 기반으로 하는 표준 arch-platform 스킬 하나가 포함되어 있습니다. 설치는 명시적으로 수행되며 일반 MCP 시작 시 절대 실행되지 않습니다:

# User scope
npx -y -p @koreai/arch-mcp-tools arch-mcp-guidance install --client codex --scope user
npx -y -p @koreai/arch-mcp-tools arch-mcp-guidance install --client claude --scope user

# Project scope (run in the project root)
npx -y -p @koreai/arch-mcp-tools arch-mcp-guidance install --client codex --scope project
npx -y -p @koreai/arch-mcp-tools arch-mcp-guidance install --client claude --scope project

설치 프로그램은 관리되지 않거나 수정된 파일을 거부하고 소유권 매니페스트에 해시를 기록합니다. 이 패키지가 소유한 변경되지 않은 파일만 제거하려면 install을 uninstall로 바꾸세요.

또는 그냥 어시스턴트에게 요청하세요

이 내용을 코딩 도구의 채팅에 붙여넣으면 서버가 자동으로 설정됩니다:

npx -y @koreai/arch-mcp-tools를 실행하는 arch-agent-platform이라는 MCP 서버를 추가하고 이 프로젝트의 MCP 설정에 넣으세요. 도구별 설정 위치 — Claude Code: .mcp.json (mcpServers) · Cursor: .cursor/mcp.json (mcpServers) · VS Code: .vscode/mcp.json (servers) · Codex: ~/.codex/config.toml ([mcp_servers.arch-agent-platform]). 선택적으로 AGENTS_URL을 내 환경으로 설정하세요.

환경 선택

어떤 환경도 하드코딩되어 있지 않습니다. 처음 사용할 때 도구가 연결할 환경을 묻습니다. 또는 서버의 env에서 AGENTS_URL을 설정하여 환경을 고정할 수 있습니다(platform_connect에 serverUrl을 전달해도 됩니다).

환경을 고정한 예시(Claude Code / Cursor 형식):

{
  "mcpServers": {
    "arch-agent-platform": {
      "command": "npx",
      "args": ["-y", "@koreai/arch-mcp-tools"],
      "env": {
        "AGENTS_URL": "https://agents.kore.ai"
      }
    }
  }
}

코드 기반 작업 및 종속성 지식

Arch는 카탈로그 매니페스트, 기능 패밀리, 모든 스키마 기반 작업, 종속성 엣지 및 기능별/도구별 세부 정보를 위한 추가 arch://guidance/v1/* 리소스를 제공합니다. 게시된 모든 도구는 정확히 한 번 나타납니다. 작업은 MCP 클라이언트에 공개되는 것과 동일한 유효 입력 스키마를 사용합니다. 선별된 안전, 범위, 전제 조건, 지원, 제한 사항 및 검증 참조는 실제 도구/작업에 해당하는 경우에만 허용됩니다.

다중 기능 작업 전에는 plan-platform-operation을 사용하고 특정 작업 후에는 verify-platform-operation을 사용하세요. 정적 종속성은 순서를 안내합니다. 인증된 프로젝트 빌더 보고서는 실시간 프로젝트 준비 상태의 권위 있는 근거로 남아 있습니다. 공개 Arch MCP 작업이 없는 기능은 실행 가능한 지원으로 표시되지 않습니다.

도구

Arch Build

플랫폼 프로젝트, 워크플로우, 에이전트, 도구, 인증 프로필, 통합, MCP 서버, 구성, 버전, 배포 및 가져오기를 생성하고 변경합니다.

확장 가능한 프로젝트 빌더 프로토콜

프로젝트 빌더 표면은 의도적으로 기능 중립적입니다. 클라이언트는 platform_project_builder(action: "describe"), MCP 리소스 및 프롬프트를 통해 핵심 온톨로지와 등록된 공급자를 학습합니다. 기본 도구를 호출하고 응답을 로컬에서 결합하여 기능 간 종속성을 재구성하지 않습니다.

Workflow는 첫 번째 v1.1 공급자입니다. 향후 기능은 자체 한정 종류, 작업, 스키마, 가져오기/내보내기, 준비 상태 소유자 및 허용 목록 Studio 경로 어댑터를 가진 공급자 등록 하나를 추가합니다. 최상위 오케스트레이션 규칙을 또 추가하지는 않습니다. 실시간 요청은 매번 Studio 계약 지원을 협상한 후 하나의 권위 있는 프로젝트/공급자 요청을 수행합니다. 기능 응답이 없거나 모호하면 STUDIO_CAPABILITY_UNKNOWN으로 보고됩니다. 명시적으로 더 낮게 공개된 계약인 경우에만 STUDIO_UPGRADE_REQUIRED입니다.

지속 목록/읽기/보고/재개/취소/승인/실행 흐름에는 platform_project_builder_operations를 사용하세요. 부작용에는 Studio가 반환한 정확한 작업 버전과 시도 기반 승인이 필요합니다. 결과를 알 수 없는 소진된 시도를 재시도하지 말고 원시 비밀 값을 절대 보내지 마세요 — 보안 Studio 흐름을 통해 인증 프로필을 생성하거나 승인하고 불투명 참조만 전달하세요.

platform_auth_profiles(create)는 authType: "none" 프로필만 생성합니다. 자격 증명을 포함하는 프로필은 의도적으로 secureSetupRequired 핸드오프를 반환합니다. API 키, 클라이언트 시크릿, 인증서 및 토큰은 절대 MCP/모델 컨텍스트에 들어가면 안 되기 때문입니다. 보안 Studio 설정 후 MCP는 목록 표시, 검사, 메타데이터 업데이트, 검증, 철회, OAuth 시작(비밀이 아닌 connectionConfig 템플릿 값 포함) 및 불투명 프로필 ID를 통합 또는 MCP 서버에 바인딩할 수 있습니다.

Arch Evaluate

평가 자산 생성, 평가 워크플로우 실행 및 CI 증거 읽기.

Arch Optimize

패키지 검증, 컴파일러에 표시되는 모델 검사 및 복구 루프 구동.

Arch Debug

실시간 세션 연결, 실패 추적 및 실행 상태 검사.

기록 세션 분석

debug_session_history는 보존된 세션을 라이브 MCP 버퍼를 사용할 수 없게 된 후에 분석해야 할 때 명시적인 읽기 전용 대안입니다. Codex, Claude 및 표준 호환 MCP 클라이언트에서 동일하게 작동합니다. 먼저 platform_connect로 의도한 Runtime에 연결하여 기존 bearer ID, 작업 공간 및 환경이 권위를 유지하도록 하십시오.

첫 번째 페이지를 나열합니다(기본값은 limit: 50, offset: 0, sortBy: lastActivityAt, sortDir: desc):

{ "action": "list", "projectId": "project-id", "status": ["completed"], "range": "7d" }

offset을 진행시켜 중간 또는 마지막 추적 페이지를 읽습니다. 마지막 페이지를 넘어서는 페이지는 오류가 아닌 빈 성공 페이지입니다:

{
  "action": "get",
  "projectId": "project-id",
  "sessionId": "session-id",
  "limit": 200,
  "offset": 200,
  "types": ["llm_call", "tool_call"]
}

Runtime은 보존, 권한 부여, 정렬 및 반환된 _meta.source, source_chain, is_truncated, warnings 및 errors를 제어합니다. 이 도구는 한 번의 제한된 요청(2 MiB, 10초)을 수행하며, 다른 경로를 탐색하거나, 재시도하거나, 숨겨진 404를 빈 페이지로 조용히 변환하거나, 라이브 저장소를 채우거나, 기록 데이터에서 MCP 라이브 버퍼로 대체하지 않습니다. 오류는 제한된 MCP 오류로 반환됩니다. 필터 값에 자격 증명이나 비밀을 넣지 마십시오.

Arch Analyze

문서, 진단 및 시스템 상태 신호를 설명합니다.

인증

platform_connect를 호출하면 인증이 자동으로 수행됩니다. 순서대로 시도합니다:

1. 명시적 토큰 — authToken 매개변수를 전달합니다.

2. 저장된 자격 증명 — artemis-platform-cli login에서 사용하는 것과 동일한 암호화된 자격 증명 저장소를 읽습니다.

3. 기기 권한 부여 — 브라우저를 열고 동일한 platform_connect 호출에서 승인이 완료될 때까지 폴링합니다.

자격 증명은 향후 세션에서 재사용할 수 있도록 저장됩니다.

라이선스

MIT — LICENSE 참조.