arxiv-agent-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repo is

A course assignment (ai_agentic_lab_assignment.md): an AI/ML study-companion agent that reads the student's concept-summary notes from Obsidian, discovers related arXiv papers, evaluates each on topical relevance and age-adjusted citation impact, surfaces the well-established papers a given paper builds on, and writes findings back into the vault.

• Existing MCP server (Part A): Obsidian Local REST API MCP.
• Custom MCP server (Part B): custom_server/ — a standalone FastMCP app exposing 3 domain tools over the arXiv API and the OpenAlex API (both public, no auth required).
• Agent: agent/ — a PydanticAI Agent (OpenRouter-backed) holding both MCP connections as native toolsets, orchestrated by a LangGraph state machine.

Build process, task breakdown, and the test-first two-agent loop used to implement each task: see AGENTS.md and TASKS.md.

Commands

uv sync                              # install all dependencies (single shared project)
uv run python -m custom_server.server  # start the custom MCP server — its own process
uv run python -m agent.graph            # start the LangGraph agent (connects to both MCP servers)
uv run pytest custom_server/tests       # run the custom server's unit tests (network calls mocked)
uv run pytest custom_server/tests/test_score_relevance.py -k threshold   # run a single test

The custom server and the agent are two separate uv run invocations (two OS processes) sharing one pyproject.toml/uv.lock — not two separate uv projects. Always start the custom server first; the agent connects out to it as an MCP client subprocess/connection.

Architecture

• custom_server/server.py — FastMCP app; registers the 3 tools from custom_server/tools/. Must stay startable and functional with zero knowledge of agent/.
• custom_server/tools/search_arxiv.py — search_arxiv_papers: the one retrieval-shaped tool (primary data source, arXiv API).
• custom_server/tools/score_relevance.py — score_paper_relevance: combines a PydanticAI/OpenRouter relevance-scoring call with an OpenAlex-derived, age-adjusted citation-impact rule. This is where "similarity" lives — OpenRouter has no embeddings endpoint (verified), so relevance is LLM-judged with a structured output schema, not vector cosine similarity.
• custom_server/tools/foundational_citations.py — find_foundational_citations: OpenAlex citation-graph analysis (given one paper, rank its references by citation count) — distinct from the keyword-search tool even though both touch OpenAlex/arXiv metadata.
• agent/pydantic_agent.py — the PydanticAI Agent and its two MCP toolsets (Obsidian + custom_server).
• agent/graph.py — the LangGraph state machine sequencing the flow; the relevance/impact-threshold filter is plain Python here, not a 4th tool.