arXiv Research-Concept Companion

AI/ML 학습 보조 에이전트(KSE Agentic Lab 과제)입니다. Obsidian 보관소에서 개념 요약 노트를 읽고, 관련 arXiv 논문을 찾고, 각각을 주제 관련성과 연령 보정 인용 영향도로 채점한 다음, 통과한 후보가 기반으로 삼는 정립된 논문들을 찾아 그 결과를 다시 보관소에 써 넣습니다.

• 기존 MCP 서버(Part A): Obsidian Local REST API MCP.

• 커스텀 MCP 서버(Part B): custom_server/ — FastMCP 앱으로, 공개 arXiv 및 OpenAlex API(인증 불필요)를 대상으로 하는 도구 3개를 제공합니다.

• 에이전트: agent/ — OpenRouter 기반 PydanticAI Agent이며, 두 MCP 연결을 도구 세트로 보유하고 LangGraph 상태 머신이 오케스트레이션합니다.

사전 요구 사항

• Python 3.12+, uv.

• OpenRouter API 키.

• Obsidian에 Local REST API 커뮤니티 플러그인이 설치·실행 중이어야 하며, Obsidian과 통신하는 MCP 서버(어느 Obsidian Local REST API MCP 구현이든 무방 — 실행 명령은 아래에서 설정 가능)가 있어야 합니다.

Related MCP server: arxiv-mcp

설치

uv sync
cp .env.example .env

.env 작성:

실행

하나의 uv 프로젝트를 공유하는 두 개의 독립 프로세스:

# process 1 — the custom MCP server (arXiv + OpenAlex)
uv run python -m custom_server.server

# process 2 — the agent (connects to both MCP servers), driven by a free-text prompt
uv run python -m agent.graph "Find papers related to my 'Transformers Concept Note'"

agent/graph.py는 custom_server/server.py 자체를 stdio 서브프로세스로 직접 실행하므로, 프로세스 2는 프로세스 1이 이미 실행 중일 필요가 없습니다 — 위의 두 명령은 각각 독립적으로 시작할 수 있음을 보여줄 뿐입니다.

프롬프트는 노트 제목을 그대로 쓴 것이 아닙니다 — 에이전트의 첫 단계(parse_prompt)는 LLM 호출을 이용해 프롬프트가 어느 Obsidian 노트를 가리키는지 식별합니다. 만약 노트를 찾지 못하면 Obsidian을 건드리지 않고 즉시 실행을 중단하고 프롬프트에 Obsidian 노트나 페이지가 지정되지 않았습니다."라는 메시지를 출력합니다. 노트를 찾았는데 그 안에서 충분한 개념 키워드(min_keywords 미만, 기본값 2)가 나오지 않으면, 그 노트를 읽은 뒤 실행을 멈추고 arXiv 검색 대신 "정보 부족" 메시지를 출력합니다.

오프라인 / 재생 모드

커스텀 서버는 원래 세 개의 실시간 네트워크 API(arXiv, OpenAlex, OpenRouter)를 호출합니다. 그러나 CUSTOM_SERVER_OFFLINE=1로 설정하면 대신 custom_server/fixtures/에 기록된 픽스처에서 도구 제공 — 네트워크 접근이나 OPENROUTER_API_KEY가 필요 없습니다. 네트워크가 불안정한 상태에서 데모/발표할 때나 빠른 반복 작업에 유용합니다.

CUSTOM_SERVER_OFFLINE=1 uv run python -m custom_server.server

포함되는 범위: search_arxiv_papers(어떤 검색어에도 동일하게 제공되는 기록된 검색 피드 1개 — 아래 제한 사항 참조)와 GPT-3(2005.14165), ResNet(1512.03385) 두편에 대한 score_paper_relevance / find_foundational_citations입니다.

알려진 제한 사항:

• search_arxiv_papers는 오프라인 모드에서 쿼리 무관(이하는)입니다 — 쿼리 텍스트와 관계없이 항상 동일한 기록된 피드를 반환합니다.

• score_paper_relevance와 find_foundational_citations는 위 두 기록된 논문만 인식합니다. 기록에 없는 arxiv_id는 PaperNotFoundError를 발생합니다(실제 OpenAlex 조회에서도 OpenAlex 논문이 누락될 때와 동일한 오류입니다). score_paper_relevance에 전달된 기록 외 논문 제목은 FixtureNotFoundError를 발생 — 조용히 틀린 답을 주는 대신 구별 가능한 오류를 돌려줍니다.

픽스처를 다시 만들거나 확장하려면: uv run custom_server.fixtures.record로 이용하면 기록된 arXiv/OpenAlex 응답(모두 공개 auth API)을 다시 가져오고 custom_server/fixtures/ 안의 그대로 JSON/XML 파일을 덮어씁니다. 새 논문을 추가하려면 해당 논문의 두 httpx.get 호출을 record.py에 추가하고, relevance_scores.json에도 그에 대응하는 항목을 직접 입력하세요(코드로 생성되지는 않은 자료 — 실제 OpenRouter 출력이 아닙니다. 원시 채팅 완료 응답을 그대로 저장하기엔 wire 형식의 손상 위험에 비해 이득이 없기 때문입니다. 대신 구조화된 {relevance, novelty, rationale} 필드가 PydanticAI FunctionModel을 통해 직접 재생됩니다).

테스트

uv run pytest custom_server/tests agent/tests

모든 네트워크 호출(arXiv, OpenAlex, OpenRouter)은 모킹됩니다. 테스트 중 실 시간 트래픽이 발생하지 않습니다.

도구 계약(Part C)

search_arxiv_papers (custom)

score_paper_relevance(custom)

find_foundational_citations (커스텀)

설계 근거

• 왜 Obsidian인가: 과제에서 에이전트가 읽고 동시에 쓸 수 있는 기존 MCP 서버가 필요하다. 학생 지식의 개념 노트는 "내가 이미 아는 것은?"라는 입력으로 자연스럽고, 통과한 후보를 다시 기록해 볼트 안에서 이 연결고리가 명확하게 보이게 닫힌다.

• 왜 로그인 장벽이 있는 사이트 대신 arXiv + OpenAlex인가: 처음 고려했던 KSE 스케줄/Moodle 자료는 모두 개인 로그인이 필요한 반면, 과제의 공개 API 규칙이 이러들을 배제한다. arXiv와 OpenAlex는 공개적이고 인증이 필요 없으며, "관령성 + 바력"(relevance + impact) 영역을 직접 지원한다.

• 왜 관련성을 임베딩이 아닌 LLM으로 판정하는가: 서버공개 상에서 OpenRouter는 임베딩 엔드포인트가 없다(라이브 모델 카탈로그와 대조로 확인). 그래서 score_paper_relevance는 벡터 유사도 대신 PydanticAI 구조화 출력 호출을 써서, 프로젝트가 어차피 사용하는 단일 모델 자격 증명을 그대로 재사용한다.

• 왜 find_foundational_citations가 "OpenAlex로 다시 검색"이 아닌가: 이건 특정 논문의 참고 리스트 하나를 받아 그것을 인용충격으로 정렬한다 — 과제 자체의 예시들이 활용하는 와 대안, 통제된 지표 비교와 같은 종류다. 키워드 중심의 search_arxiv_papers와는 목적도 처리 단계도 다르다.

• 필터링은 4번째 툴이 아니라 단순 파이썬이다: agent/graph.py의 filter_candidates_node 안에서 이루어지는 "관련성 임계값 + impact_pass" is filtering은 이미 점수가 부과된 데이터에 대해 결정적인 후처리일 뿐 새 도메인 로직이 아니다 — 그것을 툴로 만들면 단지 if 문을 하나 덧본 셈이 된다.

• 절충과 제한: 커스텀 서버의 오프라인/리플레이 모드(위의 "오프라인 / 재생 모드" 참조)는 레코딩되어 있는 논문 2편과 어떤 질의에든 무관한 arXiv 검색을 커버한다 — 임의의 질의를 일반적으로 기록하거나 재생하는 기능은 아니다. agent/의 자체 Obsidian 및 OpenRouter 호출은 그 모드의 지원을 받지 않으며 실제 온라인 연결이 그대로 필요하다. 영향력/관련성 임계값은 .env 파일의 값이라, 요청 때마다 런타임으로 조정할 수는 없다.

연기된 사항(flagged, 不是 포기)

• 하드코딩된 임계값을 .env를 넘어선 더 풍부한 런타임 유연성으로 노출시키는 것.

데모 / 방어 체크리스트

• uv run python -m custom_server.server가 단독 실행되고, 원시 MCP 클라이언트의 list_tools 3개 도구가 모두 표시됩니다.

• uv run pytest custom_server/tests agent/tests — 전체 통과, AI액세스는 모두 mock 처리되어 있습니다.

• CUSTOM_SERVER_OFFLINE=1 uv run python -m custom_server.server — 실 네트에 연결할 wait, API 키 없이 3개 도구 호출을 모두 처리 가능한 것을 볼 수 있습니다(위 "오프라인/재생 모드" 참고).

• 데모 볼트 노트에 개념 요약(예: "attention mechanisms")을 채워넣고 'Transformers Concept Note'로 명명한다.

• uv run python -m agent.graph "Find papers 관련 to my 'Transformers Concept Note'" — 라이브 실행 전체: 노트 참조를 맞는지, 노트를 읽고, arXiv를 검색하고, 후보를 점수화하며, 필터링하고, 기반 인용을 찾고, "<note> — Related Papers"라고 하는 write-back을 금고다.

• 최종 결과를 만드는 데 두 MCP 연결이 모두 기여하는 것을 보여줍니다: write-back된 노트가 arXiv/OpenAlex 데이터(커스텀 서버)와 사용자의 원본 개념 노트 내용(Obsidian)을 모두 인용합니다.

• 정보 부족 데모: 노트 제목을 명명하지 않는 프롬프트(예: "What's a transformer?")로 시연 — Obsidian 호출 없이 에이전트가 멈추며 "Not enough information..."을 출력함을 보여준다. 이어서 내용이 거의 비어 있는 노트로 실행 — 노트를 읽고 arXiv를 호출하기 전에 멈추는 것을 보여준다.

• Obsidian 실패 데모: Local REST API 플러그인을 중지시키거나(또는 잘못된 OBSIDIAN_API_KEY/존재하지 않는 노트 제목을 사용) — 에이전트가 빈 결과를 만악한 조용한 실패 대신 뚜렷이 구분되는 하나의 오류를 내는지 보여준다.

• 커스텀 서버 실패 데모: 유효하지 않은 카테고리로 search_arxiv_papers를 호출하거나, OpenAlex에 없는 arXiv ID로 find_foundational_citations를 호출 — 정상 빈 결과와 구분되어 각각 ValueError/PaperNotFoundError가 나는 것을 보여준다.