Jiphyeonjeon Agent

jiphyeonjeon-agent

Bring 집현전 to Claude — 논문 검색 · 딥리뷰 · 북마크 · 커리큘럼까지 Claude 대화창에서

[](https://github.com/KimJiSeong1994/jiphyeonjeon-agent/actions/workflows/ci.yml) [](./LICENSE) [](https://python.org) [](https://claude.ai) [](https://github.com/KimJiSeong1994/jiphyeonjeon-agent/releases)

---

Jiphyeonjeon (집현전) is an agent-native research workspace for academic papers. It exposes 집현전 (PaperReviewAgent) as native MCP tools, so Claude — and any MCP client — can search papers across 6 sources, run deep multi-agent paper reviews, explore citation graphs, generate learning curricula, and draft figures, all from one conversation. Unlike search-only research MCP servers, it covers the full workflow: discover → deeply review → learn → visualize → publish.

한 번의 Claude 대화로 집현전의 모든 기능 접근. 자신의 계정 권한 그대로, 검색·리뷰·북마크·커리큘럼을 자동 실행합니다.

---

Why jiphyeonjeon-agent?

• Claude 대화 한 번으로 집현전 6개 소스 검색 (arXiv, Google Scholar, OpenAlex, DBLP, Connected Papers, OpenAlex Korean) 부터 딥리뷰·북마크·커리큘럼까지 — 자연어로 "GraphRAG 논문 5개 찾아서 리뷰해줘" 하면 자동 실행
• 내 집현전 계정 권한 그대로 — 북마크·리뷰 기록은 내 것만 보이고 수정됨
• 11개 도구 + 6개 스킬 — Claude가 자연어 요청을 자동으로 매핑하는 에이전트 인터페이스
• 집현전 버전에 맞춰 노출 도구 집합 자동 조정 — capability negotiation으로 호환성 보장
• 로컬 머신 stdio — 외부 서버·OAuth 셋업 없이 즉시 동작

> Named after the Jiphyeonjeon (집현전), the Hall of Worthies from the Joseon Dynasty — this bridge brings that collection of scholars into your Claude conversation.

---

Quick Start

Option 1: Claude 한 줄 설치 (추천)

Claude Code에서 다음 중 하나를 말하면 자동 설치됩니다:

"집현전 agent 설치해줘"
"jiphyeonjeon setup"
"집현전 연결해줘"

/jh:setup 스킬이 자동 트리거되어 설치 과정을 안내합니다.

단계:

1. Claude Code에 위 텍스트 입력
2. 집현전 username/password 물어봄 → 사용자가 터미널에서 setup.sh 실행
3. 설치 완료 — 이후 /jh:* 스킬 즉시 사용 가능

Option 2: 터미널 원샷

# 1) clone — 경로는 자유 (아래는 예시)
git clone https://github.com/KimJiSeong1994/jiphyeonjeon-agent.git ~/jiphyeonjeon-agent
cd ~/jiphyeonjeon-agent

# 2) 한 번에 설치 (uv sync + JWT 발급 프롬프트 + claude mcp add + 스킬 복사)
bash scripts/setup.sh

집현전 username/password 프롬프트 → Claude MCP 등록 → 완료.

Option 3: 수동 (고급)

JWT를 이미 가진 경우:

JIPHYEONJEON_TOKEN= bash scripts/setup.sh

또는 ~/.claude/claude.json에 수동 등록:

{
  "mcpServers": {
    "jiphyeonjeon": {
      "command": "uv",
      "args": ["--directory", "path/to/jiphyeonjeon-agent", "run", "jiphyeonjeon-mcp"],
      "env": {
        "JIPHYEONJEON_TOKEN": "",
        "JIPHYEONJEON_BASE_URL": "https://jiphyeonjeon.kr"
      }
    }
  }
}

참고: .venv/bin/python -m jiphyeonjeon_mcp 직접 호출도 가능하며, uv 오버헤드 없이 더 빠르게 기동됩니다.

---

Features

Tools (11)

| Tool | What it does | 집현전 엔드포인트 | |------|------------|-------------------| | search_papers | 키워드로 논문 검색 (6개 소스) | POST /api/search | | get_paper | 단일 논문 메타데이터 조회 | GET /api/papers/{id} | | start_review | 논문 딥리뷰 시작 (비동기 → session_id) | POST /api/deep-review | | get_review_status | 리뷰 진행 상태 폴링 | GET /api/deep-review/status/{id} | | list_bookmarks | 내 북마크 목록 | GET /api/bookmarks | | add_bookmark | 논문을 북마크 (metadata 직접 지정 가능) | POST /api/bookmarks/from-paper | | remove_bookmark | 북마크 삭제 | DELETE /api/bookmarks/{id} | | create_curriculum | 주제별 학습 커리큘럼 생성 | POST /api/curricula/generate | | explore_related | 인용 그래프 탐색 (cite/cited-by) | POST /api/bookmarks/{id}/citation-tree | | generate_figure | 방법론 텍스트 → SVG 다이어그램 | POST /api/autofigure/method-to-svg | | create_blog_draft | 블로그 초안 작성 (admin 권한) | POST /api/blog/posts |

Skills (6)

스킬은 여러 도구를 조합해 복잡한 워크플로우를 자동 실행합니다. make install-skills로 설치하면 트리거 키워드가 자동 인식됩니다.

| 스킬 | 트리거 | 흐름 | |------|-------|------| | /jh:setup | "집현전 agent 설치", "jiphyeonjeon setup" | 집현전 로그인 → JWT 발급 → Claude MCP 등록 → 스킬 복사 | | /jh:review-paper | "딥리뷰", "deep review", "review this paper" | search → start_review → 폴링 → 리뷰 표시 | | /jh:build-curriculum | "커리큘럼", "study plan", "학습 경로" | 주제·난이도 입력 → 커리큘럼 생성 | | /jh:daily-digest | "오늘 논문", "digest", "브리핑", "daily update" | 북마크 기반 일일 브리핑 생성 | | /jh:explore | "관련 논문", "citation tree", "more like this" | 특정 논문 주변 인용 그래프 탐색 | | /jh:draft-blog | "블로그 초안", "blog draft", "post draft" | 여러 논문 기반 블로그 포스트 작성 |

스킬 설치:

make install-skills   # ~/.claude/skills/ 로 복사

Safety & Protocol

• Capability Negotiation — GET /api/version 프로브로 집현전 버전 확인 후 지원 도구만 등록. 구형 서버도 9개 도구로 fallback 호환.
• Path Traversal Defense — 모든 URL 내 id는 정규식 검증 ([a-zA-Z0-9\-_.:] 범위, 최대 256자).
• Prompt-Injection Framing — 백엔드 에러 메시지는 [backend said: ...] 프레임으로 감싸고 제어문자 제거.
• JWT Security — 토큰은 SecretStr로 관리, 로그/repr에 노출 안 함. 24시간 만료, revocation 지원.
• Stdio JSON-RPC — 모든 로그는 stderr로, stdout은 JSON-RPC만 → Claude Code 통신 간섭 없음.

---

Architecture

Claude Code (stdio)
        │
        ↓ (JSON-RPC)
  jiphyeonjeon-agent server
  (FastMCP 1.0, async)
        │
        ↓ (httpx + Bearer JWT)
  집현전 FastAPI
  (https://jiphyeonjeon.kr — default;
   localhost:8000 for self-hosting)

부트스트랩 순서:

1. Config Load — JIPHYEONJEON_TOKEN + JIPHYEONJEON_BASE_URL env 읽기
2. Capability Probe — GET /api/version 호출로 지원 도구 확인
3. Tool Registration — 동적으로 지원 도구만 등록
4. Server Run — mcp.run() (stdio 선택) → Claude Code 연결 대기

---

Tech Stack

| Layer | Technologies | |-------|-------------| | Agent Runtime | mcp>=1.2.0 with FastMCP 1.0 | | HTTP Client | httpx>=0.27.0 (async) | | Config & Secrets | pydantic-settings>=2.3.0 with SecretStr | | Validation | pydantic>=2.7.0 (v2 strict) | | Transport | stdio (SSE/HTTP roadmap) | | Dev Tooling | uv (package manager), ruff (lint/format), mypy (strict type check) | | Testing | pytest>=8.0.0, pytest-asyncio>=0.23.0, respx>=0.21.0 (mock httpx) | | Distribution | uv build, uvx compatible |

---

Environment Variables

| 변수 | 필수 | 설명 | |------|------|------| | JIPHYEONJEON_TOKEN | Yes | JWT Bearer token (from POST /api/auth/login) | | JIPHYEONJEON_BASE_URL | No | 집현전 FastAPI 주소 (기본: https://jiphyeonjeon.kr, 자체 호스팅 개발자만 http://localhost:8000) | | JIPHYEONJEON_TIMEOUT | No | 요청 타임아웃 초 (기본: 30.0, 검색은 90 권장) | | JIPHYEONJEON_VERIFY_SSL | No | TLS 인증서 검증 (기본: true, 로컬 자체 서명만 false) | | JIPHYEONJEON_AUTO_UPDATE_CHECK | No | 시작 시 GitHub Releases 에서 새 버전 확인 (기본: true, 0 으로 비활성화). 알림만 — 자동 업데이트 아님 | | JIPHYEONJEON_SCOPE | No | Claude Code MCP 등록 스코프 (기본: user) |

---

Tool Catalog (상세)

각 도구의 파라미터 및 반환값:

search_papers

• params: query (필수, min 1자), max_results (1-50, 기본 10), sources (arxiv/googlescholar/openalex/dblp/connectedpapers/openalex_korean, 선택), year_start (int, 선택), year_end (int, 선택), fast_mode (bool, 기본 true)
• returns: {papers: [{title, authors, abstract, arxiv_id, ...}], total: int, query_analysis: str}

get_paper

• params: paper_id (arxiv id/DOI/doc_id)
• returns: {paper: {title, authors, abstract, venue, year, pdf_url, ...}}

start_review

• params: paper_ids (list, min 1), num_researchers (1-6, 기본 3), fast_mode (bool, 기본 true)
• returns: {session_id: str, status: str}

getreviewstatus

• params: session_id (from start_review)
• returns: {session_id, status: "processing"|"completed"|"failed", progress: int, report_available: bool}

list_bookmarks

• params: none
• returns: {bookmarks: [{id, title, topic, tags, created_at, ...}]}

add_bookmark

• params: paper_id (선택, auto-resolve metadata) 또는 title + authors + year + venue + arxiv_id + doi (direct metadata), topic (기본 "Claude Agent"), tags, context (선택)
• returns: {bookmark: {id, title, ...}}

remove_bookmark

• params: bookmark_id
• returns: {deleted: true, bookmark_id, raw}

create_curriculum

• params: topic (필수), difficulty (beginner/intermediate/advanced, 기본 intermediate), num_modules (2-15, 기본 5)
• returns: {curriculum: {modules: [{week, title, papers, goals, ...}]}}

explore_related

• params: bookmark_id, depth (1-3, 기본 2), max_per_direction (1-30, 기본 10)
• returns: {graph: {nodes: [...], edges: [...]}}

generate_figure

• params: method_text (min 10자), paper_title (선택), optimize_iterations (1-10, 기본 1)
• returns: {success: bool, svg_content: str, figure_png_b64: str (optional), error: str (optional)}

createblogdraft

• params: title (1-300자), content (markdown, min 10자), excerpt (optional), tags (optional), thumbnail_url (optional)
• returns: {post: {id, slug, title, published: false, ...}}

---

Project Layout

src/jiphyeonjeon_mcp/
  __init__.py          Package marker
  server.py            FastMCP instance + main() entry point
  client.py            JiphyeonjeonClient (httpx + JWT auth + error translation)
  auth.py              401/404/429/403 → McpError translation layer
  config.py            pydantic-settings env loader (SecretStr JWT)
  capability.py        GET /api/version → dynamic tool set negotiation
  validators.py        Path traversal defense, id validation
  tools/               One module per domain
    __init__.py          register_all() orchestrator
    search.py            search_papers
    papers.py            get_paper
    review.py            start_review, get_review_status
    bookmarks.py         list_bookmarks, add_bookmark, remove_bookmark
    curriculum.py        create_curriculum
    explore.py           explore_related
    figure.py            generate_figure
    blog.py              create_blog_draft
  resources/           (planned) jh:// URI resource handlers

skills/                Claude Code skill files (trigger patterns + flows)
  jh-setup.md          Auto-install orchestrator
  jh-review-paper.md   Deep review workflow
  jh-build-curriculum.md
  jh-daily-digest.md   Bookmark-based briefing
  jh-explore.md        Citation graph explorer
  jh-draft-blog.md     Blog post generator

scripts/               CLI helpers
  setup.sh             One-shot install (credentials → JWT → MCP register → skills copy)
  smoke_stdio.py       Smoke test (stdio transport)
  e2e_live.py          End-to-end test vs live 집현전 backend

tests/unit/            Unit tests (6 files, 37 functions, 47 cases with parametrize)
  test_auth.py         JWT + error translation
  test_client.py       httpx wrapper behavior
  test_capability.py    Capability probe + fallback
  test_tools.py         Tool contract verification
  test_tools_contract.py  Backend response shape checking
  test_validators.py    Path traversal + id validation

pyproject.toml         Project metadata, dependencies, tool config
Makefile              Common targets (test, lint, typecheck, dev, install-skills)
CHANGELOG.md          Release notes
CLAUDE.md             Developer guidelines (stdio constraints, auth, local dev loop)

참고: Python 패키지 폴더명이 jiphyeonjeon_mcp로 남아있는 것은 PyPI 패키지명/CLI 엔트리포인트(jiphyeonjeon-mcp) 및 import 경로와의 일관성 유지를 위함입니다.

---

Testing

Unit Tests

uv run pytest tests/unit/ -v

37개 test 함수 (47개 테스트 케이스 with parametrize)가 6개 파일에서 실행:

• auth, client, capability, validators, tool contracts 커버

Smoke Test (stdio transport)

python scripts/smoke_stdio.py

stdin/stdout JSON-RPC가 제대로 작동하는지 확인.

End-to-End (live backend)

python scripts/e2e_live.py

실제 집현전 인스턴스를 대상으로 도구 호출 테스트.

---

Security Notes

• JWT는 환경변수로만 — 명령어 인자·설정 파일에 노출 금지
• SecretStr — 토큰은 로그/traceback에서 자동 마스킹
• 24시간 만료 — 집현전에서 JWT 발급 시 default 만료 시간, 필요 시 연장 가능
• Path traversal defense — 모든 {id} URL 파라미터는 정규식 검증
• Prompt-injection framing — 백엔드 에러는 사용자 메시지 컨테이닝으로 격리
• stdout 보호 — 모든 로그는 stderr로, stdout은 JSON-RPC만 → Claude와의 통신 안전 보장

---

Roadmap

v0.1.0 (현재)

• 11 tools + 5 skills (setup 포함 6 skills)
• JWT 패스스루 인증
• stdio transport
• Capability negotiation + fallback

v0.2.0 (예정)

• PAT (Personal Access Token) 지원 — 장기 만료 토큰 옵션
• HTTP transport 추가
• Resource handlers (jh:// URIs)

v1.0.0 (장기)

• OAuth 2.1 + refresh token
• claude.ai remote connector (웹 기반 MCP)
• 커리큘럼 share link 통합

---

Contributing

Issues, PRs 환영합니다. [CLAUDE.md](./CLAUDE.md) 참조 — 코딩 컨벤션, 테스트 규칙, 커밋 메시지 형식 포함.

코딩 컨벤션:

• Python 3.12, type hints required (mypy strict)
• async def for all tool handlers
• 한국어 커밋 메시지 허용
• ruff format + lint (line-length 100)

---

References

• Model Context Protocol Spec (v0.1)
• Anthropic Python SDK
• Jiphyeonjeon (PaperReviewAgent)
• FastMCP

---

License

[Apache License 2.0](./LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: KimJiSeong1994
• Source: KimJiSeong1994/jiphyeonjeon-agent
• License: Apache-2.0
• Homepage: https://jiphyeonjeon.kr

Install and usage instructions live in the source repository linked above.