MCP CONNECT
MCP 연결 가이드
확인 중...
masblue-mcp — Claude Code 전용 연결 가이드. 총 165개 도구를 활용하여 masblue-platform 코드베이스를 탐색합니다.
MCP 엔드포인트
https://doc.force-ai.tech/mcp전송 방식
Streamable HTTP (POST)인증
없음 — allowed_hosts 제한도구 수
165개방법 1 — .mcp.json 파일 (팀 공유, 추천)
프로젝트 루트에 .mcp.json을 추가하면 팀 전원이 동일한 설정으로 연결됩니다. Git에 커밋하여 공유하세요.
1
프로젝트 루트에 파일 생성
# 프로젝트 루트에서
cat > .mcp.json << 'EOF'
{
"mcpServers": {
"masblue-mcp": {
"type": "http",
"url": "https://doc.force-ai.tech/mcp"
}
}
}
EOF2
Claude Code 재시작 또는 프로젝트 재로드
# 현재 세션에서 즉시 적용 /mcp # MCP 서버 목록 확인
3
연결 확인
# Claude Code에서 실행 masblue-mcp 서버에 연결된 도구 목록을 보여줘
방법 2 — claude mcp add CLI (개인 설정)
현재 사용자에게만 적용되는 전역 설정. ~/.claude.json에 저장됩니다.
# HTTP 타입으로 전역 등록 claude mcp add masblue-mcp --transport http https://doc.force-ai.tech/mcp # 등록 확인 claude mcp list # 특정 서버 상세 확인 claude mcp get masblue-mcp
※ --scope project 옵션 추가 시 현재 프로젝트의 .claude/settings.json에 저장됩니다.
방법 3 — Settings UI
Claude Code 설정 화면에서 직접 추가합니다.
- /settings 입력 → Settings 열기
- MCP Servers 섹션 → + Add 클릭
- 이름:
masblue-mcp - Type:
http - URL:
https://doc.force-ai.tech/mcp - 저장 후 Claude Code 재시작
연결 확인 방법
Claude Code에서 확인
# MCP 서버 목록
/mcp
# 연결 테스트
get_dashboard 도구로 V2 통계 보여줘
# 도구 직접 호출 예시
search_code("로그인 컴포넌트")헬스체크 (curl)
curl https://doc.force-ai.tech/health
# → {"status":"ok"}
curl https://doc.force-ai.tech/api/version
# → {"version":"...",...}도구 목록 (165개)
검색 (Weaviate)
3개unified_search | 코드/문서/지식 통합 검색 — V1/V2 모든 소스를 한 번에 검색. Weaviate 하이브리드 검색(BM25 + dense vector) → reranking 파이프라인. |
search_knowledge | 스킬/프롬프트/프로젝트 문서 통합 검색. |
search_skills_tool | 스킬 시맨틱 검색 (Weaviate MasbluemcpSkill). category: analysis | migration | domain | llm-guide | engineering | agent-persona | checklist | command source: native | agent-skills tags: 태그 목록 (OR 매칭, PG 후필터) |
V2 명령/이벤트 분석
8개get_dashboard | Neo4j 대시보드 통계 (V2 커맨드/이벤트 수). Returns: 성공 시 TextResult (커맨드/이벤트 수 등 통계 문자열), 캐시 오류 등 실패 시 ErrorResult. |
coverage_stats | V1→V2 커버리지 통계. Returns: 성공 시 TextResult ("전체: N | 커버: M | X%" 형식), 캐시 오류 등 실패 시 ErrorResult. |
list_v2_commands | V2 커맨드 전체 목록. Returns: 성공 시 TextResult (커맨드 이름 목록, 없으면 안내 메시지), 캐시 오류 등 실패 시 ErrorResult. |
get_command | V2 커맨드 상세 스펙. |
event_flow | 이벤트 플로우 조회. |
dependency_graph | MSA 서비스 의존성 그래프 — 4종 raw type 라인 포함. Returns: 성공 시 TextResult ("from → to (type)" 형식 목록, 없으면 안내 메시지), 캐시 오류 등 실패 시 ErrorResult. type 종류: ``PROXIES_TO`` (BFF), ``PRODUCES`` (이벤트 발행), ``CONSUMES`` (이벤트 구독), ``DEPENDS_ON`` (직접 의존성). |
uncovered_features | V2 미커버 V1 피처 목록. Returns: 성공 시 TextResult ("[domain] name" 형식 목록, 없으면 안내 메시지), 캐시 오류 등 실패 시 ErrorResult. |
migration_chain | V1 피처 → V2 마이그레이션 체인. |
분석 & 검증
3개auto_analyze | 변경된 레포만 자동 증분 분석. 로컬 레포를 git pull로 최신화 후 증분 색인. |
force_reanalyze | 모든 레포를 강제로 전체 재분석 (incremental=False). 시간이 오래 걸릴 수 있음. |
validate_v1_v2_consistency | V1→V2 매핑 정합성 검증 — CALLS_API/COVERED_BY 체인 + orphan 노드 점검. Returns: TextResult — 정합성 점수, CALLS_API/커버 통계, 경고/이슈 목록. Neo4j 미연결 시 ErrorResult — ADR-0123 fallback signal 트리거 (stale cache). |
데이터 관리
4개upsert_v1_feature | V1 기능을 Neo4j + Weaviate에 단건 등록/업데이트한다. |
delete_weaviate_collection | Weaviate 컬렉션을 삭제하고 스키마를 재생성한다. collection_name: MasbluemcpV2Code | MasbluemcpV1Feature | MasbluemcpV1BusinessLogic | MasbluemcpV1FrontendCode | MasbluemcpV1BackendCode | MasbluemcpSkill | MasbluemcpPrompt | MasbluemcpInsuranceDoc. |
delete_neo4j_by_label | Neo4j에서 특정 레이블 노드를 모두 삭제한다 (DETACH DELETE). label 예시: V2Command | V2Event | V1Feature | CodeFile | SyncRun. |
reset_all_databases | Neo4j 전체 + Weaviate 전체 컬렉션을 초기화한다. 주의: 모든 데이터 삭제됨. fastmcp 3.x 동의 게이트: confirm=False (기본) 일 때 ctx.elicit 로 사용자 확인을 받는다. confirm=True 전달 시 우회. |
서비스 레지스트리
3개list_service_registry | PostgreSQL service_registry 테이블에서 등록된 서비스 전체 목록을 조회한다. Returns: TextResult — 레포/타입/언어/org 컬럼 정렬 목록 (없으면 안내 문구). |
upsert_service_registry | PostgreSQL service_registry에 서비스를 등록/업데이트한다. |
delete_service_registry_entry | PostgreSQL service_registry에서 서비스를 제거한다. |
Token Savings
3개ts_get_stats | 현재 세션 + 누적 토큰 절감 통계. Returns: TextResult — [세션]/[누적] 호출·절감 토큰·히트율 요약. |
ts_get_patterns | Neo4j 도구 호출 패턴 분석 (top-10). Returns: TextResult — 도구/호출수/히트율 컬럼 테이블. |
ts_invalidate_cache | 캐시 수동 무효화 (전체 삭제 + wiki 캐시 초기화). |
코드 품질
3개record_quality_snapshot | 코드 품질 스냅샷을 DB에 기록한다. 이전 스냅샷 대비 변화도 반환. |
get_quality_trend | 최근 N일간 코드 품질 트렌드를 조회한다. |
get_quality_dashboard | 최근 품질 스냅샷 요약 대시보드. |
스킬 & 배포
6개upsert_skill | SkillRegistry 추가/수정 + Weaviate MasbluemcpSkill 재색인. description이 빈 문자열이면 content[:200] 자동 사용. author가 빈 문자열이면 신규 시 'masblue', 수정 시 기존 값 유지. |
list_service_configs | 등록된 외부 서비스 연결 설정 목록. domain: v2 | internal | general (빈 문자열이면 전체) api_key 필드는 마스킹하여 반환. |
get_service_config | 특정 외부 서비스 연결 설정 상세 조회 (api_key 전체 포함). name: v2-neo4j | v2-weaviate | internal-postgresql 등. |
list_skill_guides | 등록된 스킬/배포 가이드 전체 목록 (name, category). Returns: 성공 시 TextResult (스킬 이름/카테고리/업데이트 일자 목록), 실패 시 ErrorResult. |
get_skill_guide | 스킬/배포 가이드 조회. skill_name: deploy | gitflow | cluster. |
get_deployment_guide | apple/container 빌드 + ECR 푸시 + kubectl 전체 배포 플로우 가이드. Returns: 성공 시 TextResult (deploy 스킬 content 원문), 실패 시 ErrorResult. |
프롬프트 & 훅
6개list_prompts | 프롬프트 목록 + 변수 안내. task_type: analysis | generation | migration | search |
get_prompt | 프롬프트 조회 + {{var}} 자동 치환. 예: get_prompt("analyze-v1-feature", {"feature_description": "보험료 계산 화면"}) |
search_prompts_tool | 프롬프트 시맨틱 검색 (Weaviate MasbluemcpPrompt). |
list_hooks | 트리거별 훅 목록. trigger_event: sync_complete | pre_design | feature_request | coverage_change | scheduled |
get_hook | 훅 조회 + 실행 가이드. |
trigger_hook | 훅 실행 — actions 순서대로 도구 호출 가이드 반환. 실제 MCP 도구를 순서대로 호출하는 가이드를 반환합니다. |
문서 검색
6개generate_wiki | 코드 컨텍스트 기반 Wiki 문서 자동 생성 (RAG + Claude API). |
search_project_docs | 프로젝트 문서(doc_registry) 전문 검색 — 아키텍처, 인프라, MCP, 마이그레이션 등. |
ask_codebase | 코드베이스에 자연어 질문. hybrid search + 리랭킹으로 관련 코드를 찾아 구조화 반환. scope: all(전체) | v1(V1 원본) | v2(V2 MSA) | migration(마이그레이션) | insurance(보험) |
read_wiki_structure | 생성된 Wiki 문서 전체 목록 (slug, 제목, 카테고리, 상태). Returns: 성공 시 TextResult (JSON 배열: slug/title/category/doc_type/ status/version/has_mermaid), 실패 시 ErrorResult. |
read_wiki_contents | 생성된 Wiki 문서 전체 내용 조회 (slug 기반). |
ask_question | 코드베이스 RAG Q&A — Weaviate 검색 + Neo4j 그래프 enrichment + Claude API 답변. Weaviate 시맨틱 검색 결과에 Neo4j 관계 정보를 추가하여 코드 구조를 이해하는 깊이 있는 답변을 생성합니다. |
웹 검색
2개web_search | DuckDuckGo 웹 검색 (API 키 불필요). 결과 압축으로 토큰 절감. 최대 10건. |
web_search_docs | 기술 문서 특화 웹 검색 (safe_search 고정). 라이브러리/프레임워크 레퍼런스 조회용. |
Export Discovery
3개discover_source_db | OnForce/PolicyForce source DB의 전체 테이블 목록과 row count를 반환합니다. DB 직접 접근 불가 시 V1 Management API를 통해 리소스 목록을 반환합니다. |
get_table_schema_tool | 특정 테이블의 컬럼 정의, PK, FK, 인덱스를 반환합니다. DB 직접 접근 불가 시 V1 API 응답에서 필드 구조를 추출합니다. |
preview_table_data_tool | 특정 테이블의 상위 N개 행을 반환합니다 (최대 100). DB 직접 접근 불가 시 V1 API에서 데이터를 가져옵니다. |
보험 문서
4개scan_gdrive_insurance_docs | Google Drive 보험 PDF 스캔 → DB 미등록 건 식별. Returns: TextResult — 미등록 파일 목록 요약. |
ingest_insurance_doc | Google Drive PDF 1건 다운로드→텍스트 추출→Weaviate 색인. |
ingest_all_insurance_docs | DB 미등록/실패 건 전량 일괄 색인. |
search_insurance_docs | 보험 문서 시맨틱 검색 (Weaviate MasbluemcpInsuranceDoc). |
기타
111개unified_search_v2 | SearchType 라우팅 + Retriever dispatch (Wave 4.4 / ADR-0024). cognee BaseRetriever 3-step 패턴 — 8 retriever 중 search_type 에 매칭되는 retriever 가 dispatch. 기존 unified_search 도구 (5-metric reranker) 와 dual-track 공존. container.graph_engine / vector_engine 미배선 (None) 시 retriever 는 stub mode 로 빈 결과 반환. |
get_structure | V1/V2 코드 구조 조회 — 라우트, 서비스, 커맨드 등 통합 조회. Neo4j 그래프에서 구조화된 코드 엔티티를 조회한다. |
get_flow | 코드 플로우 분석 — E2E, 이벤트, 마이그레이션 체인 통합 조회. |
get_coverage | V1→V2 마이그레이션 커버리지 분석. |
sync_all | V1/V2 코드 동기화 + 인덱싱 통합. Git → Neo4j(그래프) + Weaviate(벡터) 파이프라인. |
sync_status | 동기화/인덱싱 상태 전체 현황. |
remember | **[Deprecated v1.0.0+ (ADR-0166 Phase 1)]** AKB-style ``akb_put`` 권장 — Phase 2/3 backend 위임 + hard removal 예정 (사용자 명시 승인 후). **Wiki 작업 진입점 (4-verb policy, ADR-0135)** — 텍스트를 MemoryEntry 로 변환 + Wiki contradiction 보존 게이트 (ADR-0025). contradiction 마커 (`⚠️ 모순 ...`) 검출 시 requires_human_review=True 강제. LLM 자동 reconcile 차단 — 우회 옵션 없음. |
recall | **[Deprecated v1.0.0+ (ADR-0166 Phase 1)]** AKB-style ``akb_query`` 권장 — default 가 ``HYBRID_RRF`` 로 격상됨 (env ``MASBLUE_RECALL_LEGACY_DEFAULT=1`` 로 v0.x 복원). **Wiki 작업 진입점 (4-verb policy, ADR-0135)** — 메모리 조회, search_type 자동 선택 + Retriever dispatch (ADR-0024). cognee V2 `recall()` 시그니처 미러. search_type 미지정 시 query 분석으로 best-fit retriever 자동 선택 (FEELING_LUCKY 패턴): - SQL/Cypher 키워드 → CYPHER - 백틱 / `::` → V2_CODE - wiki/page/doc → WIKI - 그 외 → GRAPH_COMPLETION (default) |
forget | **[Deprecated v1.0.0+ (ADR-0166 Phase 1)]** AKB-style ``akb_delete`` 권장 — Phase 2/3 backend 위임 + hard removal 예정 (사용자 명시 승인 후). **Wiki 작업 진입점 (4-verb policy, ADR-0135)** — 메모리 삭제 (ADR-0025). Wave 5.3 시점은 placeholder — 실 PG DELETE 는 Wave 5+ ORM 추가 시점. everything=True 는 사용자 명시 승인 사항 (forbidden.md §Kill Criteria). |
improve | **[Deprecated v1.0.0+ (ADR-0166 Phase 1)]** AKB-style ``akb_edit`` 또는 후속 feedback API 권장 — Phase 2/3 backend 위임 예정 (사용자 명시 승인 후). **Wiki 작업 진입점 (4-verb policy, ADR-0135)** — 메모리 enrichment, feedback_weight 가중치 조정 + (옵션) memify pipeline (ADR-0027). cognee V2 API 의 4 번째 동사. dataset_name 의 FeedbackEntry 들을 처리해 각 target MemoryEntry 의 feedback_weight 갱신. invoke_memify=True 면 Wave 7.2 의 memify Task chain 호출 (KG 보강 / summary 갱신). ADR-0026 (V1 비대상): dataset_name 이 'v1-' prefix 면 거절. |
cognify_wiki_article | **[Deprecated v1.0.0+ (ADR-0166 Phase 1)]** AKB-style ``akb_put`` + metadata relations 권장 — Phase 2/3 backend 위임 예정 (사용자 명시 승인 후). **Wiki 작업 진입점 (4-verb policy, ADR-0135/0138)** — ECL 관계 추출. article_id (Wiki article slug 또는 UUID) 의 entity/claim/relationship 을 LLM 합성으로 추출. ADR-0030 schema 강제 (entity:{name} / claim:{stem}:{slug} / relationship: source/target/edge_type/evidence prefix). ADR-0088 disk cache 활용 — content_hash 기반, 동일 article 재호출 70% 절감. 본 도구는 `container.article_analyzer` (ADR-0082 process-wide singleton) 를 호출. LLM gateway 부재 시 placeholder (빈 결과) 반환 — 운영 시점에 cost 가드. |
consistency_score | 7 service x 5 pattern 의 AST 분류 -> score 계산. |
contract_compatibility | 서비스 간 이벤트 producer/consumer 매칭을 검증한다. |
generate_mermaid | Neo4j 그래프 데이터로 Mermaid 다이어그램 생성. 실제 코드 관계만 반영하므로 LLM 환각 없는 정확한 다이어그램. |
plan_wiki | 2단계 Wiki 일괄 생성 — 구조 계획 + 페이지별 생성 + 저장. Neo4j 도메인 토폴로지를 분석하여 Wiki 구조를 자동 결정하고, 각 페이지를 순서대로 생성하여 저장합니다. Mermaid 다이어그램이 자동으로 삽입됩니다. |
generate_wiki_from_config | 저장된 Wiki 프리셋으로 문서 일괄 생성. upsert_wiki_config로 저장한 프리셋을 로드하여 정의된 페이지 구조대로 Wiki를 생성합니다. |
file_answer_to_wiki | 질의 답변이나 분석 결과를 위키 페이지로 저장한다 (복리형 축적). ask_question, deep_research 등의 좋은 답변을 위키에 역으로 저장하여 지식이 채팅 히스토리에서 사라지지 않고 위키에 축적되게 한다. |
update_wiki_page | 기존 위키 페이지를 새 정보로 부분 업데이트한다 (전체 재생성 X). 기존 문서의 구조와 내용을 유지하면서 새 컨텍스트를 통합한다. 모순이 있으면 '⚠️ 모순' 마커가 자동 삽입되고, 더 이상 정확하지 않은 내용은 취소선 처리된다. |
ingest_source | 새 소스를 위키에 투입한다 — 요약 페이지 생성 + 기존 페이지 자동 업데이트. Karpathy LLM Wiki 패턴의 핵심 연산. 단일 소스가 여러 기존 페이지에 영향을 미치며, auto_update=True면 관련 페이지가 자동으로 갱신된다. |
upsert_wiki_config | Wiki 구조 프리셋 저장/업데이트. 문서 페이지 구조를 미리 정의하여 generate_wiki_from_config로 일괄 생성할 수 있습니다. |
rebuild_wiki_index | 위키 전체 인덱스를 재구축한다. 모든 GeneratedDocMeta를 조회하여 카테고리별 카탈로그를 생성한다. 각 항목: slug, 제목, 한줄 요약(doc_type), 버전, 최종 갱신일. 결과는 DocRegistry slug='WIKI_INDEX'로 저장되어 다른 도구가 참조할 수 있다. |
append_wiki_log | 위키 로그에 이벤트를 추가한다. 시간순 추가 전용(append-only) 기록으로, ingest/query/lint/update 등 위키에 대한 모든 작업 이력을 추적한다. |
deep_research | Deep Research — 반복 심층 분석으로 깊이 있는 답변 생성. 단순 1회 RAG Q&A가 아닌, 질문 분해 → 다중 소스 검색 → 중간 답변 → 품질 평가 → 후속 질문 루프를 최대 {max_iterations}회 반복합니다. 복잡한 아키텍처 질문, 마이그레이션 분석, 크로스 도메인 분석에 적합합니다. |
export_wiki | Wiki 문서를 Markdown 또는 HTML로 export. |
lint_wiki | 위키 건강 점검 — 모순, 고아 페이지, 누락 엔티티, stale 페이지 검출. Karpathy LLM Wiki 패턴의 lint 연산. 위키가 커지면서 발생하는 품질 저하를 자동 감지한다. 검사 항목: 1. 모순 마커: '⚠️ 모순' 태그가 포함된 페이지 2. 고아 페이지: 다른 페이지에서 참조되지 않는 페이지 3. 누락 엔티티: Neo4j에 있지만 위키 페이지가 없는 V2 도메인 4. Stale 페이지: 최근 동기화 후 갱신되지 않은 페이지 |
wiki_cycle | Karpathy LLM Wiki 패턴의 ingest 워크플로우를 한 번에 실행한다. 새 소스(아티클·노트·트랜스크립트·코드)를 받아서: 1. discuss=True → 요약 + 영향 페이지 후보만 반환 (write 없음) 2. discuss=False → ingest_source 호출 → (auto_lint면) lint_wiki 호출 3. 모든 단계 결과를 단일 보고서로 반환 반드시 docs/WIKI_SCHEMA.md의 Ingest 워크플로우 규약을 따른다. |
wiki_cycle_v2 | wiki_cycle 5-Task chain 백그라운드 dispatch (ADR-0021 / Wave 3.3). cognee 의 cognify pipeline 패턴 — 즉시 pipeline_id 반환 후 백그라운드에서 extract_chunks → extract_graph → summarize → embed → store 5단계 직렬 실행. 진행/에러는 wiki_cycle_status() 도구로 폴링. 기존 wiki_cycle 도구 (동기, 즉시 응답) 와 dual-track 공존. |
wiki_cycle_status | wiki_cycle_v2 의 활성 백그라운드 task + 에러 ring buffer 노출 (ADR-0021). Returns: TextResult — 활성 task 목록 + key 별 에러 ring buffer 스냅샷. |
get_wiki_cache_status | ArticleAnalyzer in-memory cache 누적 메트릭 조회. ADR-0080 (cache layer) + ADR-0081 (metric) 의 process-wide singleton 통계. cache 활성 여부 + hits/misses/evictions/expirations + hit_ratio + 현재 size + max_size + ttl_seconds. Returns: WikiCacheStatusResult — singleton 미초기화 시 enabled=False + 0 값. |
get_skill | 스킬 상세 조회 + 사용 가이드. detail: meta | body | full - meta: 메타데이터만 (name, category, description, tags, version, author, source) - body: 기존 동작 (content 전체) + 메타 헤더 - full: content + 모든 skill_attachment 포함 |
add_skill_file | 스킬 첨부 파일 추가/수정. attachment_type: reference | script | example | framework 동일 skill_name + filename 존재 시 내용 갱신 (ON CONFLICT UPDATE). |
get_skill_file | 스킬 첨부 파일 조회. |
list_skill_files | 스킬의 모든 첨부 파일 목록. |
explain_code_unit | 파일/함수/클래스를 Neo4j 컨텍스트 + LLM 요약으로 설명. UA `/understand-explain` 동등 + V1↔V2 도메인 컨텍스트 자동 주입. ADR-0045 spec 참조. |
generate_codebase_onboarding | Audience 별 신규 멤버 코드베이스 가이드 생성. UA `/understand-onboard` 동등 + V1↔V2 glossary 자동 주입 + v1-migrator audience 추가. ADR-0046 spec 참조. |
analyze_full | 5 specialist orchestration 으로 코드베이스 종합 분석. UA `/understand` 동등 + V1↔V2 + 4 audience 차별화. 흐름: 1. project-scanner → inventory (Phase 1+2) 2. file-analyzer → graph (5 concurrent batch) 3. architecture-analyzer → layers (8 layer) 4. tour-builder → tour (audience-aware) 5. graph-reviewer (include_review=True 시) → approve/partial/reject 6. LLM 종합 요약 |
get_graph_overview | Neo4j 전체 그래프 통계. 반환: - labels: [{ label, count }] — 노드 라벨별 수 - total_nodes, total_relationships |
get_dependency_graph_json | 전체 또는 도메인별 의존성 그래프를 JSON 단일 형식으로 반환. 기존 dependency_graph 도구는 텍스트("from → to") 반환이라 프론트엔드 그래프 시각화 호환을 위해 별도 도구를 제공한다. |
search_migration_patterns | Weaviate MasbluemcpMigrationPattern 컬렉션 시맨틱 검색 + 패싯 필터. 반환: - items: 패턴 카드 목록 (pattern_type, source/target_framework, complexity, domain, description, score) - count: 결과 수 |
analyze_diff_impact | Git diff 변경 파일을 Neo4j 그래프에 매핑해 영향받는 노드·레이어·위험도를 분석. UA `/understand-diff` 동등 + V2Command/Event/Route/Service 영향까지 확장 (V1↔V2 도메인 가치). ADR-0044 spec 참조. |
event_flow_v2 | 비즈니스 도메인 + flow + step 의 3-level hierarchy 추출. UA `/understand-domain` 동등 + V1↔V2 매핑 자동 주입. ADR-0048 spec 참조. 기존 event_flow (단순 텍스트) 와 의미 다름 — generic 도메인 추출 도구. |
validate_7_repo_consistency | 7 repo cross-repo 일관성 score (0-100%) 측정. 로컬 filesystem 우선 (`/Users/phil/masblue/dev/<repo>/`), 미접근 시 GitHub API fallback (DOC_GITHUB_TOKEN 환경변수). 6 체크: adr_layout / claude_md_lines / parent_authority / god_file_count / invariants / archive_tier. force-project-management 는 spec-only — ADR / CLAUDE-200 / invariants 체크 N/A. remote mode 에서 god_file_count / archive_tier 는 N/A. Returns: dict {score_overall, per_check, per_repo, details, mode}. mode = "local" | "remote". Sub-100% 는 측정 결과일 뿐 fail 아님. |
get_tool_call_stats | tool_calls 테이블 기반 도구 호출 통계. 반환: - summary: 총 호출/고유도구/캐시히트율/토큰/기간 - top_tools: 상위 20개 도구 - recent: 최근 limit건 |
get_realtime_events | realtime_events 테이블 최근 이벤트. |
get_quality_trend_json | quality_snapshots 일별 집계 (JSON 응답). get_quality_trend가 마크다운 텍스트를 반환하는 데 비해 이 도구는 프론트엔드 차트용 JSON을 반환한다. |
get_cache_status | cache_entries + sync_events 조회. |
get_llm_usage | llm_usage 테이블 모델/공급자별 사용량 집계. |
get_v1_source_resources | v1_source_data 테이블 — 145 리소스 타입 + 항목 조회. params 없으면 resource_type별 카운트 집계만 반환. params.resource_type 지정 시 해당 타입의 항목 limit건 반환. |
list_hooks_json | hook_registry 조회 (JSON 응답). list_hooks가 텍스트를 반환하는 데 비해 이 도구는 프론트엔드용 구조화 데이터를 반환한다. |
gcx_metrics_query | Grafana metrics (PromQL) 쿼리 — gcx CLI wrap. |
gcx_logs_query | Grafana logs (LogQL, Loki) 쿼리 — gcx CLI wrap. |
gcx_dashboards_list | Grafana dashboard 목록 — folder/search 필터. |
gcx_dashboards_get | Grafana dashboard 단일 조회 — UID 기반. |
gcx_alerts_list | Grafana 알람 목록 — state/folder 필터. |
gcx_slo_list | Grafana SLO 목록 — service 필터. |
gcx_slo_get | Grafana SLO 단일 조회. |
gcx_synthetic_list | Grafana Synthetic Monitoring check 목록. |
gcx_synthetic_get | Grafana Synthetic Monitoring check 단일 조회. |
gcx_irm_list | Grafana IRM (Incident Response Management) 사고 목록. |
gcx_irm_get | Grafana IRM 사고 단일 조회. |
gcx_alerts_silence | Grafana 알람 silence 생성 (write, scope alerting.silences:write). |
deploy | masblue-mcp/masblue-web 전체 배포 파이프라인 (1-click). 버전 범프 → 린트+테스트 → git commit+push → docker buildx+ECR 푸시 → force-tenant-house 태그 업데이트+push → ArgoCD 롤아웃 대기 → 헬스체크 검증. 로컬 개발 환경에서만 동작합니다 (docker, kubectl, aws CLI 필요). |
infra_status | Force MSA 개발 인프라 전체 상태를 확인합니다. VPN 연결, K8s 라우팅, DNS resolver, 서비스 헬스체크를 한 번에 점검합니다. 로컬 개발 환경에서만 동작합니다 (connect.sh --status 실행). Returns: 성공 시 TextResult (connect.sh --status 출력), 실패 시 ErrorResult. |
infra_connect | Force MSA 개발 환경에 연결합니다. VPN → AWS SSO → EKS kubeconfig → DNS resolver 순서로 전체 연결 플로우를 실행합니다. 로컬 개발 환경에서만 동작합니다 (connect.sh 기본 실행, watch 루프 제외). Returns: 성공 시 TextResult (connect.sh 출력), 실패 시 ErrorResult. |
ecr_cache_create | ECR cache repo 11개 일괄 생성 + lifecycle policy 적용 (idempotent). force-to-msa T3 A3.2 cache-from/to args 활성화 prerequisite. ADR-0081 결정에 따라 masblue-mcp 가 11 repo 의 truth 보유. 본 함수가 단일 entry point. |
ecr_cache_delete | ECR cache repo 11개 일괄 삭제 (idempotent — 이미 삭제된 repo skip). T3 종료 시 또는 cache 무효화 정책 변경 시 사용. force=True 로 image 보유한 repo 도 삭제 (untagged 7d lifecycle 가 자동 정리하지만 수동 force 옵션). |
ecr_cache_list | ECR cache repo 11개 의 현재 상태 조회 (실시간 boto3 describe). ADR-0081 §부정 R13 (외부 변경 drift) 감지: 본 함수가 cache truth 의 *유일한* 조회 경로. 결과가 11개 미만 = 외부 수동 변경 → incident-kb 등록 의무. |
argocd_app_status | ArgoCD 전체 앱의 sync/health 상태를 조회한다. Returns: TextResult: 앱별 sync status + health 요약. |
argocd_app_diff | 특정 ArgoCD 앱의 live state vs desired state diff 를 조회한다. |
argocd_sync_history | 특정 ArgoCD 앱의 최근 sync 이력을 조회한다. |
dependency_matrix | 서비스 간 주요 패키지 버전을 비교한다. |
scan_local_insurance_dir | 로컬 디렉토리 보험 문서 스캔 → DB 미등록 건 식별. |
ingest_local_insurance_doc | 로컬 파일 1건 텍스트 추출→Weaviate 색인. |
ingest_local_insurance_dir | 로컬 디렉토리 미색인 문서 전량 일괄 색인. |
extract_v1_source_data | India V1 test.4ceai.com API에서 전체 원본 데이터를 추출하여 masblue-mcp PostgreSQL에 저장한다. 145개 테이블의 원본 데이터를 resource_type별로 JSONB 저장. **W6-PR2 Security**: 하드코딩 비밀번호 제거. password 가 빈 문자열일 때 `MASBLUE_MCP_V1_TEST_PASSWORD` 환경변수에서 로드 — `.env` 또는 K8s ExternalSecret 경유. |
clear_wiki_cache | ArticleAnalyzer in-memory cache 강제 클리어 (cycle 79, ADR-0083). ADR-0080/0081/0082 의 process-wide cache 항목 전체 삭제. reset_stats=True 면 hit/miss 카운터도 0 으로 리셋. confirm=False 시 ctx.elicit 동의 게이트. |
save_wiki_cache | ArticleAnalyzer cache 를 disk 에 JSON 저장 (cycle 83, ADR-0087). ADR-0086 의 save_to_disk 를 MCP 도구로 노출. 운영자가 명시 trigger 로 cache 영구화 (LLM cost 절감 효과 process restart 후에도 보존). |
load_wiki_cache | ArticleAnalyzer cache 를 disk 에서 JSON 로드 (cycle 83, ADR-0087). ADR-0086 의 load_from_disk 를 MCP 도구로 노출. 기존 in-memory cache 에 병합 — 동일 key 는 disk 값으로 덮어씀. confirm=False 시 elicit 동의 게이트. |
run_akb_benchmark | LongMemEval-Ko 합성 dataset 으로 retrieval 품질 측정. |
upload_document | Base64 인코딩된 데이터를 스토리지에 업로드한다. SHA-256 체크섬으로 중복 제거. 동일 파일이면 기존 키 반환. |
list_documents | 스토리지의 문서 목록을 조회한다. |
get_document_url | 문서 다운로드용 presigned URL을 생성한다. |
list_capabilities | 등록된 capability 목록 조회 (type/owner 필터 + status='active'). |
register_capability | Capability 등록 — cypher/sql/weaviate/python. |
execute_capability | 등록된 capability 를 실행하고 결과 반환. |
onboarding_status | 현재 환경의 온보딩 진행 상태를 진단해서 어떤 step 이 완료/누락됐는지 보고한다. Returns: :class:`StepResult` — connect.py --status 출력 + 성공 여부. |
onboarding_prereqs | 필수 CLI (mise/uv/gh/kubectl/helm/devspace/netbird/python3) 설치 상태 확인. Returns: :class:`StepResult` — installed/missing 목록 + 누락 시 설치 안내. |
onboarding_aws_sso | AWS SSO 디바이스 인증 흐름을 boto3 로 직접 실행하고 ~/.aws/sso/cache/ 에 토큰을 저장한다. Returns: :class:`StepResult` — connect.py 실행 결과. |
onboarding_netbird | NetBird 클라이언트 설치 + setup-key 등록 + Force MSA 라우트 enrollment 를 자동화한다. Returns: :class:`StepResult` — connect.py 실행 결과. |
onboarding_eks_access | EKS DescribeCluster 권한 진단 + 미충족 시 force-infra-modules access entry PR 안내. Returns: :class:`StepResult` — cluster 상태 (권한 OK) 또는 access entry PR 안내. |
onboarding_kubeconfig | kubernetes-asyncio 로 ~/.kube/config 에 force-msa-dev context 를 안전하게 주입하고 동작을 검증한다. Returns: :class:`StepResult` — connect.py 실행 결과. |
onboarding_clone_repos | ~/masblue/dev/force-to-msa 클론 상태 + submodule 동기화 검증. Returns: :class:`StepResult` — 클론 / submodule 상태 + 누락 시 명령 안내. |
onboarding_ide_setup | .mcp.json 검증 — masblue-mcp entry + endpoint 일치 확인. Returns: :class:`StepResult` — 발견된 .mcp.json 위치 + 등록 상태. |
onboarding_smoke_test | Kubectl get nodes + devspace dev api-gateway --dry-run 으로 환경 검증 (5 service 헬스 포함). Returns: :class:`StepResult` — connect.py 실행 결과. |
onboarding_bootstrap | masblue-platform 개발 환경을 8 step 으로 부트스트랩한다. |
list_guidelines | 지침/규약/프로젝트 컨텐츠 목록 조회. |
get_guideline | Slug 으로 지침 단건 조회 (content 포함). |
upsert_guideline | 지침 추가/수정. slug 충돌 시 update + revision 자동 기록. |
archive_guideline | 지침을 status='archived' 로 soft delete. idempotent. |
list_guideline_revisions | 지침 변경 이력 조회 (최신 우선, 최대 200). |
get_guideline_hashes | Light endpoint: sha256 hashes of all active guidelines + constitution_head. Used by UserPromptSubmit hook for per-prompt validation (~5ms target). Returns manifest_version, hashes dict (slug->sha256), constitution_head, and unresolved consistency_violations. |
get_active_guidelines | Full active guideline set, optionally filtered by layer. Called when hash mismatch detected by hook (~200ms target). |
get_constitution_layer | Spec tree mirror entries by layer name. Wraps force-project-management 9-layer spec tree. |
akb_put | AKB-style vault 에 신규 entry 삽입. |
akb_query | AKB-style vault 안에서 Hybrid RRF 검색. |
akb_edit | AKB-style entry 부분 업데이트 (PR-12 실 구현). |
akb_delete | AKB-style entry 삭제 (PR-12 실 구현). |
ci_status | GitHub Actions workflow run 상태를 조회한다. |
ci_run_detail | 특정 workflow run 의 job 상세를 조회한다. |
alembic_status | 서비스별 alembic current revision 을 조회한다. |
alembic_history | 특정 서비스의 alembic migration history 를 조회한다. |
사용 예시
V1 기능 검색
# 자연어 검색 (통합 도구) unified_search(query="보험료 계산 컴포넌트", source="code", version="v1", portal="agent") # 특정 포털 라우트 조회 (통합 도구) get_structure(version="v1", entity_type="routes", portal="management")
V2 커맨드 파악
# 전체 통계 get_dashboard() # 도메인별 커맨드 get_structure(version="v2", entity_type="commands", domain="claim") # 특정 커맨드 상세 get_command(command_id="CreateClaim")
마이그레이션 현황 확인
# 전체 커버리지 % coverage_stats() # 미전환 기능 목록 uncovered_features(portal="agent") # V1→V2 마이그레이션 체인 추적 migration_chain(v1_feature="보험료 조회")
지식 레지스트리 활용
# 스킬 목록 확인
list_skill_guides()
# 배포 가이드 조회
get_deployment_guide()
# 프롬프트 변수 치환 적용
get_prompt(name="v2_command_spec", variables={"domain": "claim"})트러블슈팅
| 증상 | 원인 | 해결 |
|---|---|---|
| MCP 서버가 목록에 없음 | .mcp.json 위치 또는 JSON 문법 오류 | 프로젝트 루트 위치 확인, JSON 검증 후 Claude Code 재시작 |
| 도구 호출 시 연결 오류 | VPN 미연결 또는 네트워크 차단 | VPN 연결 확인, curl https://doc.force-ai.tech/health 테스트 |
| 검색 결과가 비어 있음 | 색인 데이터 없음 (초기 상태) | sync_v1_repos() 또는 sync_v2_repos()로 색인 실행 |
| 토큰 낭비 발생 | 캐시 미적용 또는 TTL 만료 | ts_get_stats()로 히트율 확인, ts_invalidate_cache()로 재설정 |
| type: http 인식 안 됨 | Claude Code 버전 구버전 | claude --version 확인 후 최신 버전으로 업그레이드 |