@ploc-mcp/server

Ploc(plocai.com) MCP 서버. AI 코딩 환경(Claude Code, Codex, Claude Desktop, Antigravity CLI/Desktop 등 MCP 호환 클라이언트)에서 Ploc의 학습/회상 기능을 도구로 호출할 수 있게 한다.

사용자용 npm 경로 vs 개발자용 local 경로

• 일반 사용자 기본값은 npm 경로입니다. MCP 설정에는 npx -y @ploc-mcp/server를 사용하세요.
• ploc_status는 @ploc-mcp/[email protected]부터 npm 배포본에 포함되어 있습니다. Claude Desktop / Codex app smoke test도 npm 경로로 확인할 수 있습니다.
• Ploc 팀/contributor dogfood 전용 local 경로는 node /Users/hyun/dev/nemory/ploc-mcp-server/dist/server.js입니다. 로컬 개발본에서도 ploc_status를 사용할 수 있습니다.
• 일반 사용자는 local 경로를 따라하면 안 됩니다. 이 경로는 Ploc 소스가 같은 위치에 있고 npm run build까지 완료된 개발자 환경에서만 동작합니다.

Tools (자연어 호출)

| 도구 | 용도 | 비고 | |---|---|---| | ploc_status | MCP 서버의 로컬 연결/설정/라우팅 상태 진단 | token source(canonical vs alias), route table(Spring/Python agent)까지 표시 (v0.3.0+) | | save_to_ploc | 현재 대화/메모를 Ploc에 저장 | 항상 Python agent /ingest로 저장해 recall 대상 보장. learning_note는 플래시카드 생성을 위해 Spring analyze-raw에도 dual-write (ADR-053). project 인자로 scope override | | recall_topic | 저장된 기억을 자연어로 회상 (evidence 포함) | Python agent /recall. project 미지정이면 secure-by-default 차단, 전체 검색은 project="all" 명시 (ADR-054). v0.3.0+ | | init_project_context | 현재 repo의 Ploc project context 준비 상태 점검 | .ploc을 쓰지 않고 root/project 후보/context 파일/다음 액션만 반환 | | build_context_pack | .ploc, AGENTS/CLAUDE, README, docs, ploc-context 핵심 문서를 bounded Markdown pack으로 미리보기 | read-only. .git, node_modules, 빌드 산출물, 대용량 발표/이미지 파일 제외 | | save_work_log | 프로젝트 작업 로그 또는 검토된 context pack을 work_log로 저장 | Python agent /ingest, source=mcp-project-context, project는 인자 → env → repo .ploc 순서 | | recall_project_context | 프로젝트 범위 작업 로그·결정·진행상황 회상 | recall_topic과 같은 /recall 경로. project 미지정 시 secure-by-default 차단 | | check_context_drift | .ploc, MASTER_PLAN, decisions, pack size 등 context drift 후보 점검 | read-only. git dirty 여부는 사용자가 git status --short로 확인하도록 안내 | | get_flashcards | 복습 카드(grouped) 조회 — 만기/그룹/항목 단위 | limit, dueOnly 지원. tag 필터는 미지원(백엔드 확장 필요) | | get_session | 저장된 분석 결과 단건 조회 | sessionId = analysisResultId |

오류 정규화 (error envelope, v0.3.0+): MCP/Python/Spring 경계 오류는 raw token 없이 { code, message, retryable, authStatus?, route?, tokenPrefix?, correlationId? }로 정규화된다. code 예: missing_token·deprecated_token_alias·invalid_token·auth_unavailable· missing_project·agent_unavailable·spring_unavailable·dual_write_partial_failure.

Prompts (슬래시 명령)

MCP prompts는 Claude Code에서 /mcp__ploc__<name> 형태로 노출될 수 있는 결정적 트리거다. Claude Desktop / Codex app은 slash prompt 노출을 기대하지 말고, 자연어로 tool call이 선택되는지 확인한다. slash 미노출 ≠ MCP 실패다. 서버 연결과 tool call 성공 여부를 기준으로 판단한다.

| 슬래시 | 동작 | 인자 | |---|---|---| | /mcp__ploc__save_current | 현재 대화 전체를 save_to_ploc으로 저장 | title?, tags? (쉼표 구분) | | /mcp__ploc__recall_topic | 저장된 기억을 recall_topic으로 회상 | query, project? (all이면 전체 검색) | | /mcp__ploc__review_due | 만기 카드를 받아 퀴즈 모드 진행 (dueOnly=true) | limit? |

API: https://api.plocai.com (기본). 인증: Ploc 설정 화면에서 발급한 ploc_… API Token (X-Ploc-Token 헤더, ADR-015).

1. 토큰 발급

1. https://plocai.com 로그인
2. 설정 → 개발자 연동 탭에서 API Token 발급 (ploc_ prefix)
3. 노출되면 즉시 revoke 후 재발급. 만료 정책은 현재 수동 revoke만 있음

1.5 토큰 로그인 (rc 파일 편집 없이, ADR-057)

~/.zshrc/.mcp.json를 직접 고치지 않고 한 명령으로 토큰을 저장/갱신한다:

npx @ploc-mcp/server login            # 토큰 입력 프롬프트 → ~/.ploc/config(0600) 저장
npx @ploc-mcp/server login --token ploc_xxx --no-verify   # 비대화형(CI)
npx @ploc-mcp/server logout           # 저장된 credential 삭제
npx @ploc-mcp/server status           # 현재 토큰 소스/경로/충돌 진단(서버 미기동)

• 토큰 우선순위: PLOC_TOKEN(env) > PLOC_API_TOKEN(deprecated alias) > ~/.ploc/config > 없음.
• 권장: .mcp.json/~/.zshrc에서 PLOC_TOKEN을 지우고 login만 쓰면 갱신이 한 명령으로 끝난다. env가 남아 있으면 login 토큰을 덮어쓰며 ploc_status가 충돌을 경고한다.
• @ploc/cli·Python agent도 동일한 ~/.ploc/config를 읽으므로 소스가 하나로 통일된다.
• login은 PLOC_AGENT_BASE가 설정돼 있으면 토큰을 라이브 검증한다(미배포/네트워크 오류 시 저장은 하되 "미검증" 안내).

2. 환경 변수

| 변수 | 필수 | 기본값 | |---|---|---| | PLOC_TOKEN | ✅ | — (canonical 토큰 env. 서버는 기동되지만 모든 호출이 안내 에러로 응답함) | | PLOC_API_TOKEN | ❌ | — (deprecated alias. PLOC_TOKEN이 없을 때만 사용되고 ploc_status가 경고함. 둘 다 있으면 PLOC_TOKEN 우선) | | PLOC_API_BASE | ❌ | https://api.plocai.com (Spring product API — 플래시카드/세션/learning_note dual-write) | | PLOC_AGENT_BASE | ❌ | https://agent.plocai.com (Ploc hosted Python agent — 일반 사용자는 설정 불필요. self-host/staging/local 개발 override용) | | PLOC_PROJECT_KEY | ❌ | — (.ploc 파일의 project = ... 값으로도 추론 가능. recall_topic은 project가 없으면 차단) |

v0.2.0부터 토큰 검증은 lazy로 동작한다. 토큰이 없거나 형식이 잘못돼도 서버는 기동되고, 각 도구 호출 시 사람이 읽을 수 있는 안내 메시지로 응답한다. (이전: top-level throw로 서버 자체 기동 실패)

3. 설치

A. npm public (일반 사용자 기본값)

npx -y @ploc-mcp/server   # 직접 실행 테스트

이 경로는 Claude Desktop / Codex app / Antigravity 등 일반 사용자 smoke test의 기본값이다. @ploc-mcp/[email protected]부터 ploc_status도 npm 경로에서 확인할 수 있다.

B. 로컬 빌드 (Ploc 팀/contributor dogfood 전용)

git clone https://github.com/nemory/ploc.git   # 또는 기존 클론 사용
cd ploc/ploc-mcp-server
npm install
npm run build
# dist/server.js 생성됨 → 아래 설정의 args에 절대경로 지정

현재 로컬 개발본 dogfood 경로:

node /Users/hyun/dev/nemory/ploc-mcp-server/dist/server.js

일반 사용자는 이 경로를 따라하지 않는다. 로컬 경로는 Ploc 저장소를 같은 위치에 가진 개발자만 사용할 수 있다.

4. 클라이언트별 설정 snippet

각 snippet은 두 가지 모드를 함께 제공한다.

• npm (권장): @ploc-mcp/server 공개 배포본 사용. 일반 사용자는 이 경로
• local: 로컬 빌드 결과를 직접 가리킴. 소스 개발/디버깅용

Ploc 개발 운영 원칙:

• Claude Code는 기능 개발 중 루트 .mcp.json에서 로컬 /Users/hyun/dev/nemory/ploc-mcp-server/dist/server.js를 바라본다.
• Claude Desktop / Codex app은 npm 배포본(npx -y @ploc-mcp/server) 기준으로 일반 사용자 smoke test를 수행한다.
• 기능 수정 후에는 npm test && npm run build를 통과시킨 뒤 Claude Code 로컬 dist로 확인한다.
• npm 배포 후에는 Claude Code도 npm 경로로 잠시 되돌려 최종 smoke test를 수행한다.
• ploc_status는 로컬 개발본과 npm 배포본(@ploc-mcp/[email protected] 이상) 모두에서 smoke test한다.

Claude Code (.mcp.json 또는 claude mcp add)

일반 사용자 또는 배포 후 최종 smoke용 npm 경로:

{
  "mcpServers": {
    "ploc": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@ploc-mcp/server"],
      "env": { "PLOC_TOKEN": "${PLOC_TOKEN}" }
    }
  }
}

Ploc 개발자 dogfood용 로컬 경로:

{
  "mcpServers": {
    "ploc": {
      "type": "stdio",
      "command": "node",
      "args": ["/Users/hyun/dev/nemory/ploc-mcp-server/dist/server.js"],
      "env": { "PLOC_TOKEN": "${PLOC_TOKEN}" }
    }
  }
}

CLI 등록도 가능: claude mcp add ploc -- node /Users/hyun/dev/nemory/ploc-mcp-server/dist/server.js

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "ploc": {
      "command": "npx",
      "args": ["-y", "@ploc-mcp/server"],
      "env": { "PLOC_TOKEN": "ploc_xxx" }
    }
  }
}

로컬 빌드는 command를 node로, args에 dist/server.js 절대경로. 변경 후 Claude Desktop 재시작 필요. 일반 사용자 검증은 npm 경로를 기준으로 한다.

Codex CLI (~/.codex/config.toml)

[mcp_servers.ploc]
command = "npx"
args = ["-y", "@ploc-mcp/server"]
env = { PLOC_TOKEN = "ploc_xxx" }

로컬 빌드:

[mcp_servers.ploc]
command = "node"
args = ["/abs/path/to/ploc/ploc-mcp-server/dist/server.js"]
env = { PLOC_TOKEN = "ploc_xxx" }

일반 사용자 검증은 npm 경로를 기준으로 한다.

Antigravity CLI / Desktop

• Global: ~/.gemini/antigravity-cli/mcp_config.json
• Workspace: .agents/mcp_config.json

{
  "mcpServers": {
    "ploc": {
      "command": "npx",
      "args": ["-y", "@ploc-mcp/server"],
      "env": { "PLOC_TOKEN": "ploc_xxx" }
    }
  }
}

Antigravity는 hook/plugin도 지원하므로 세션 종료 시 자동 저장 등 자동화는 plugin template으로 추가 예정 (backlog).

Gemini CLI 사용자: Google이 2026-05-19 Gemini CLI를 Antigravity CLI로 전환한다고 공지했고, 일반 사용자용 Gemini CLI는 2026-06-18 이후 중단 예정. 신규 설정은 Antigravity 경로를 사용하세요 (ADR-023).

5. 연결 검증

각 클라이언트에서 MCP 서버가 등록되면:

1. npm 경로: 도구 목록에 ploc_status, save_to_ploc, recall_topic, init_project_context, build_context_pack, save_work_log, recall_project_context, check_context_drift, get_flashcards, get_session 등이 보이는지 확인 (@ploc-mcp/[email protected] 이상은 ploc_status 포함)
2. local 경로: 위 도구 목록이 보이는지 확인
3. npm/local 경로에서 "플록 연결 상태 확인해줘"라고 말해 ploc_status 호출 → tokenConfigured, tokenPrefixValid, apiBase 확인
4. npm/local 공통으로 get_flashcards를 dueOnly=false, limit=3으로 호출 → JSON 응답 + 그룹 목록 확인
5. 401/403이면 토큰 문제, 404/500이면 PLOC_API_BASE 확인

문제 해결:

• tokenConfigured: false 또는 PLOC_TOKEN 환경변수가 설정되지 않았습니다 → env 설정 누락
• tokenPrefixValid: false 또는 PLOC_TOKEN 형식이 올바르지 않습니다 → 잘못된 토큰
• agentBase가 https://agent.plocai.com이면 hosted agent 기본값을 정상 사용 중이다. staging/local/self-host agent를 붙일 때만 PLOC_AGENT_BASE로 override한다.
• HTTP 401 → 만료/revoke된 토큰, 재발급
• node 18+ 필요 (engines)

6. 사용 가이드

저장 (save_to_ploc)

사용자는 보통 아래처럼만 말하면 된다.

"플록에 저장해줘"
"이 대화 기억해줘"
"save this to Ploc"

LLM은 저장 전에 title/type/tags/language/source를 되묻지 않고 자동 구성한다.
- 코딩 작업·의사결정·진행상황·다음 액션: `work_log`
- 개념 설명·공부·복습·헷갈린 점: `learning_note`
- 강의/문서/자료 요약: `lecture_summary`

`content`는 원문 전체 복사가 아니라 Markdown 정리본으로 구성한다.
`work_log`는 업무일지 형식으로 작성한다 — 아래 섹션을 순서대로 쓰고, 내용이 없는 섹션은 생략한다:

1. `## 업무 개요`
2. `## 진행 상태`
3. `## 오늘 수행 업무`
4. `## 산출물 및 변경사항`
5. `## 검증 결과`
6. `## 이슈 및 병목`
7. `## 주요 의사결정`
8. `## 다음 작업`
9. `## 공유 및 요청사항`

개념 설명·헷갈린 점·복습 후보 같은 학습 신호는 `work_log` 본문에 섞지 않는다.
요약한 내용에 학습 신호가 강하면 저장 완료 후 `learning_note` 추가 저장을 제안한다.
단, 사용자 확인 없이 같은 내용을 두 타입으로 자동 저장하지 않는다.
`learning_note`는 핵심 개념, 쉬운 설명, 실무 예시, 자주 헷갈리는 점, 확인 질문 중심으로 작성한다.
`source`를 추론하기 어려우면 특정 클라이언트로 고정하지 말고 `mcp`로 저장한다.
긴 세션은 누락을 줄이기 위해 핵심 요약 중심으로 저장하고, 원문 보존이 필요하면 `@ploc/cli` 또는 Webhook 사용.

매개변수: content(필수), title, tags[], source, type(learning_note | work_log | lecture_summary), language.

Project Context Mode

ctx-kit 별도 설치 없이 MCP 서버만으로 repo context를 초기화·미리보기·저장·회상한다.

일반 흐름:

1. "이 repo Ploc project context 상태 확인해줘" → `init_project_context`
2. "저장할 context pack 만들어줘" → `build_context_pack`
3. pack을 검토한 뒤 "이 프로젝트 작업 로그로 저장해줘" → `save_work_log`
4. 이후 "이 프로젝트에서 전에 왜 X로 결정했지?" → `recall_project_context`
5. "컨텍스트 드리프트 확인해줘" → `check_context_drift`

• init_project_context와 build_context_pack, check_context_drift는 read-only다. .ploc 또는 문서를 자동 생성하지 않는다.
• build_context_pack 기본 include: .ploc, AGENTS.md, CLAUDE.md, README*, docs/*.md, docs/**/*.md, ploc-context/MASTER_PLAN.md, decisions.md, backlog.md, PROJECT_OVERVIEW.md, working/*.md.
• save_work_log는 저장 project를 project 인자 → PLOC_PROJECT_KEY → repo .ploc 순서로 찾는다. 그래도 없으면 저장하지 않는다.
• 이 기능은 기존 Python /ingest·/recall을 재사용한다. Graph RAG/LightRAG/Graphiti 도입은 별도 ADR 결정 전까지 포함하지 않는다.

복습 카드 조회 (get_flashcards)

매개변수: limit(1~50), dueOnly(기본 true). 응답에 groups(주제별 카드 묶음), frequentlyWrongConcepts(자주 틀린 개념) 포함.

세션 단건 조회 (get_session)

매개변수: sessionId (UUID = analysisResultId). 저장 시 반환된 sessionId를 그대로 사용.

7. 한계 / 알려진 이슈

• tag 필터 미지원: 백엔드 API 확장 후 추가 예정
• Remote MCP (Claude.ai connector) 미지원: stdio 기반만 동작. public HTTPS + OAuth는 후속
• ploc_status는 @ploc-mcp/[email protected] 이상에서 사용 권장. 0.2.4는 serverVersion 표시가 0.2.3으로 잘못 노출되는 미결이 있었고 0.2.5에서 수정됐다.
• save_to_ploc 응답의 sessionId는 비동기 분석 완료 전이라도 반환됨. 분석 완료 확인은 get_session 폴링 필요 (ploc status CLI 후속 예정, backlog)

8. 라이선스 / 운영주체

운영주체: nemory (ADR-013). 공개 주소는 베타 이후 결정.