# Research Thread Agent > Local-first AI/ML research curation: Quick Search, Learning Path, Research Lineage, Trending Feed, My Feed, Venues. Data from Semantic Scholar, HuggingFace, GitHub. MCP server included. - **Type:** MCP server - **Install:** `agentstack add mcp-hyeongus2-research-thread-agent` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [hyeongus2](https://agentstack.voostack.com/s/hyeongus2) - **Installs:** 0 - **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [hyeongus2](https://github.com/hyeongus2) - **Source:** https://github.com/hyeongus2/research-thread-agent - **Website:** http://localhost:3000 ## Install ```sh agentstack add mcp-hyeongus2-research-thread-agent ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Research Thread Agent A local-first, open-source research curation tool for AI/ML researchers and developers. Automatically collects papers, models, and repositories from **Semantic Scholar**, **Hugging Face Hub**, and **GitHub**, then presents them in seven views: - **Quick Search** — Papers, models, and repos for a keyword, sorted by quality signal (citations / downloads / stars) - **Learning Path** — Historical development of a topic, organized chronologically by era - **Research Lineage** — Citation-based graph showing relationships between papers - **Researcher Network** — Coauthorship network around a chosen PI/author - **Trending Feed** — Community-upvoted papers from Hugging Face (daily / weekly / monthly) - **My Feed** — Personalized paper alerts based on your subscribed categories and keywords - **Venues** — Browse papers from major ML/AI conferences by year All data is stored on your local machine (SQLite). No external server, no account required, no telemetry. --- ## Two Ways to Use | | Desktop App | MCP Server | |---|---|---| | **Interface** | Native app — double-click to open, no terminal needed | Claude.ai chat extension | | **AI cost** | Your own Anthropic API credits | Covered by Claude Pro subscription | | **Best for** | Visual feed (Instagram-style) | Chat-style queries in Claude | Both interfaces run on the same backend. The desktop app bundles FastAPI + Next.js and launches them automatically. The MCP server exposes the same logic as tools Claude can call during chat. > **Current status**: Next.js + FastAPI interface and MCP server are available now. Electron desktop packaging is on the roadmap. --- ## Features ### Reels A full-screen, vertically swipeable feed of recent trending papers — one paper per screen, scroll for the next: - Papers from Hugging Face Daily Papers (past 30 days), sorted by upvotes; shares the Trending Feed DB cache - Each card shows the paper's preview image (HF thumbnail); papers without one fall back to a text-centric card - **✦ AI** button toggles between the abstract and an on-demand AI summary (requires Anthropic API key) - Like / save buttons (session-local UI), and a direct link to the arXiv page - Scroll-snap with progress pill; next cards' images are preloaded for instant display - Kept mounted across tab switches, so returning to Reels preserves your position ### Quick Search Search across three sources simultaneously with a single keyword: - **Papers** tab — Semantic Scholar: up to 1,000 papers sorted by citation count - **Models** tab — Hugging Face Hub: up to 50 models sorted by downloads - **Repos** tab — GitHub: up to 50 repositories sorted by stars - Filter by date range (past week / month / 3 months / all time) - Page number navigation with 10 / 25 / 50 results per page - Inline abstract expand / collapse on paper cards - **✦ AI Overview** button — generates a 2-sentence topic overview on demand (requires Anthropic API key) - **✦ AI Summary** button per paper — one-sentence summary on demand (requires Anthropic API key) - Every result includes a clickable link to the original source ### Learning Path Enter any research topic (e.g., *Retrieval-Augmented Generation*) and get: - Key papers grouped into chronological eras (Before 2018 / 2018–2020 / 2021–2022 / 2023–2024 / 2025–2026 / …) - Papers sourced from Semantic Scholar (citation-sorted), same as Quick Search - Claude-generated summary of what changed in each era - Hugging Face models and GitHub repos relevant to the topic - Results cached for 7 days so repeat lookups are instant ### Research Lineage Enter a research topic and explore citation-based connections between papers: - Top 100 papers fetched in a **single API call** (reference data embedded — no per-paper expansion calls) - Top-5 by citation count become **Influential** (red) nodes; the rest become **Related** (blue) nodes - Edges drawn where two papers in the result set have a citation relationship - Red arrows indicate influence radiating **out from** influential papers - Node click shows a paper detail card with AI Summary button - Previous graphs saved and shown as a history list — click to reload instantly from cache **Differs from Learning Path**: Learning Path groups papers into chronological eras with AI-generated summaries. Research Lineage shows citation-based relationships between individual papers. > **Limitation**: Citation relationships are metadata-based approximations. A paper citing another may use it as background, comparison, method, dataset, or critique. Citation edges do not guarantee direct intellectual inheritance. --- ### Researcher Network Enter a PI or author name to build a dynamic **coauthorship network** around that researcher, from **Semantic Scholar** author/paper metadata: - Node = researcher; the root author sits at the center, collaborators around it - Edge = coauthorship; **edge thickness reflects the number of shared papers** - Filter by minimum shared papers, max collaborators, and an optional year range - Click a collaborator to see shared years, top shared papers, and the author-position pattern - **Relationship hints** (e.g. *possible mentor-trainee pattern*) are **heuristic only** — surfaced when several metadata signals coincide, never as verified facts - No web crawling or lab-page scraping; results are cached for 30 days > **Important**: This is a coauthorship network, **not** verified academic genealogy. **Coauthorship does not imply an advisor-student relationship.** --- ## Tech Stack | Layer | Technology | |---|---| | Frontend | Next.js 15, React 18 (mobile-first PWA) | | Backend | FastAPI + uvicorn (Python, port 8000) | | AI | Claude API (`claude-sonnet-4-6`) — on-demand only | | Data sources | Semantic Scholar API (+ OpenAlex fallback), Hugging Face Hub API, GitHub REST API | | Storage | SQLite via SQLAlchemy | | Scheduler | APScheduler | --- ## Getting Started ### Prerequisites - Python 3.9+ - Node.js 18+ - A [GitHub personal access token](https://github.com/settings/tokens) (free, no special scopes needed) - An [Anthropic API key](https://console.anthropic.com) (optional — only needed for AI Overview / AI Summary buttons and Learning Path era summaries) > **Note on Anthropic API billing**: The API is billed separately from a Claude.ai Pro subscription. All data collection (Semantic Scholar, Hugging Face, GitHub) works without an API key — the key is only needed when you click the AI summary buttons. ### Installation **Windows:** ```bat git clone https://github.com/hyeongus2/research-thread-agent.git cd research-thread-agent setup.bat ``` **Mac / Linux:** ```bash git clone https://github.com/hyeongus2/research-thread-agent.git cd research-thread-agent chmod +x setup.sh && ./setup.sh ``` `setup` automatically creates a `.venv` virtual environment, installs all Python and Node dependencies, and copies `.env.example` → `.env` on first run. ### Configuration Open the generated `.env` file and fill in your keys: ``` ANTHROPIC_API_KEY= # optional — enables AI Overview, AI Summary, and era analysis GITHUB_TOKEN= # required — unauthenticated requests limited to 60/hour HF_API_TOKEN= # optional — increases HF model search rate limits SEMANTIC_SCHOLAR_API_KEY= # optional — raises rate limit from 100 req/5 min to 1 req/sec RESEND_API_KEY= # optional — only needed for email digest feature USER_EMAIL= # optional — recipient address for email digest CLAUDE_MODEL= # optional — defaults to claude-sonnet-4-6 ``` ### Run **Windows:** ```bat run.bat ``` **Mac / Linux:** ```bash ./run.sh ``` - Frontend (app): [http://localhost:3000](http://localhost:3000) - Backend API docs: [http://localhost:8000/docs](http://localhost:8000/docs) > The app runs entirely on your local machine. There is no cost for keeping it running. --- ## Data & Storage All data is stored in `data/research_thread.db` (SQLite, auto-created on first run, excluded from git). - **Search history** accumulates over time — this is intentional. - **Learning Path** results are cached for 90 days, then regenerated on next request. - To start fresh: go to **Settings → Reset Database**, or run `python scripts/reset_db.py`. --- ## Project Structure ``` research-thread-agent/ ├── setup.bat / setup.sh # One-command setup (venv + npm install) ├── run.bat / run.sh # Start both servers ├── frontend/ # Next.js 15 app (port 3000) │ └── app/ │ ├── page.jsx # Root state machine (welcome → onboarding → feed) │ ├── components/ # Feed, LearningPath, CitationGraph, Onboarding, Settings, … │ ├── context/ # LanguageContext (EN / KO toggle) │ └── i18n/ # en.js, ko.js translation files ├── api/ # FastAPI backend (port 8000) │ ├── main.py # App entry point, CORS, lifespan │ ├── schemas.py # Pydantic request/response models │ └── routes/ # auth, search, learning, feed, notifications, subscriptions, venues, citation_graph, config ├── config/ │ └── settings.py # Centralised env-var settings (Pydantic BaseSettings) ├── services/ # Pure Python business logic │ ├── semantic_scholar_service.py # Semantic Scholar paper search (citation-sorted); OpenAlex fallback │ ├── hf_service.py # HF Hub model search (download-sorted) │ ├── hf_daily_service.py # HF Daily Papers for Trending Feed │ ├── github_service.py # GitHub repo search (star-sorted) │ ├── claude_service.py # On-demand AI summaries (overview + per-paper) │ ├── thread_service.py # Quick Search orchestration │ ├── historical_thread_service.py # Learning Path orchestration │ ├── citation_graph_service.py # Research Lineage graph build (bulk search + batch refs) │ ├── openalex_venue_service.py # OpenAlex venue search fallback │ ├── database_service.py # SQLAlchemy CRUD helpers │ ├── notification_service.py # My Feed: check subscriptions, create notification records │ ├── scheduler_service.py # APScheduler daily background check │ └── email_service.py # Resend email digest (optional) ├── models/ # SQLAlchemy ORM models │ ├── user.py │ ├── notification.py │ ├── subscription.py │ ├── thread.py │ ├── settings.py │ └── paper_code.py # PaperCodeLink — PWC archive code links (arxiv_id → repo_url) ├── mcp_server/ │ └── server.py # MCP server — 4 tools for Claude.ai chat ├── scripts/ # Utility scripts │ ├── reset_db.py # Wipe and reinitialize the database │ ├── import_pwc_links.py # One-time import of Papers with Code archive into SQLite │ └── warm_cache.py # Pre-warm trending cache (daily/weekly/monthly) before opening the app └── utils/ # DB connection, logging, validators ├── database.py ├── logger.py └── validators.py ``` --- ## API Rate Limits | Source | Limit | Handling | |---|---|---| | Semantic Scholar | 100 req/5 min (no key) · 1 req/sec (with key) | Bulk endpoint returns up to 1,000 papers per request | | GitHub | 5,000 req/hour (authenticated) | Requires `GITHUB_TOKEN` | | Hugging Face | Higher with token | `HF_API_TOKEN` recommended | | OpenAlex | 10 req/sec | Automatic fallback when Semantic Scholar is rate-limited | | Claude API | Per-token billing | On-demand only — never called automatically | --- ## MCP Server The MCP server exposes Research Thread Agent tools directly in Claude.ai chat (requires Claude Pro). ### Setup 1. Install dependencies and run setup as above. 2. Open Claude Desktop → Settings → Developer → Edit Config, then add: ```json { "mcpServers": { "research-thread-agent": { "command": "/path/to/research-thread-agent/.venv/bin/python", "args": ["/path/to/research-thread-agent/mcp_server/server.py"] } } } ``` On Windows, use the `.venv\Scripts\python.exe` path: ```json { "mcpServers": { "research-thread-agent": { "command": "C:\\path\\to\\research-thread-agent\\.venv\\Scripts\\python.exe", "args": ["C:\\path\\to\\research-thread-agent\\mcp_server\\server.py"] } } } ``` 3. Restart Claude Desktop. A green "running" indicator appears in the Developer tab. ### Available Tools | Tool | Description | Example prompt | |---|---|---| | `quick_search` | Papers, models, and repos for a keyword | "Search for recent papers on RAG evaluation from the past month" | | `learning_path` | Chronological era-based history of a topic | "Build a learning path for diffusion models" | | `trending_papers` | Top HF Daily Papers by upvotes | "What are the trending AI papers this week?" | | `venue_papers` | Papers from a major ML conference + year | "Show me NeurIPS 2024 papers on transformers" | | `research_lineage` | Citation-based graph of influential papers | "Show the research lineage for attention mechanism transformer" | | `my_feed` | Personalized paper alerts from your local DB | "Show my unread paper alerts" | > **Note on `my_feed`**: Returns papers already saved to your local database. The database is updated when you open the app and visit the My Feed tab (or when the daily background scheduler runs). Requires completing onboarding at least once. --- ## Roadmap ### v1.2.0 (current) - [x] **Reels** — full-screen, vertically swipeable feed of HF Daily Papers (past 30 days, sorted by upvotes); thumbnail-dominant card layout when HF preview image is available, text-centric fallback otherwise; ✦ AI Summary button per card (on-demand); like / save buttons (session-local); scroll-snap with progress pill; next cards' thumbnails preloaded for instant display; tab stays mounted so scroll position is preserved across tab switches - [x] **Quick Search: topic label** — TOPIC / 주제 header with Fraunces italic keyword shown at the top of results, matching Learning Path and Research Lineage layout - [x] **Fix: Settings z-index** — Settings overlay now renders above all in-content UI elements (raised from z-index 10 → 100) ### v1.1.0 - [x] **⚡ cached result indicator across all 7 features** — right-aligned label shown whenever a result is served from cache (DB-backed or in-memory); consistent position and style across Quick Search, Learning Path, Research Lineage, Researcher Network, Trending Feed, My Feed, and Venues - [x] **Quick Search topic mode in-memory cache** — same keyword + period combination renders instantly on re-search without re-fetching; cache lives for the duration of the browser session - [x] **Researcher Network: year filter → dropdowns** — year start/end inputs replaced with `` elements (1950–current year, descending); clearing selection shows `—` naturally - [x] **Researcher Network: author name shown during loading** — Fraunces italic author header appears immediately when search starts, not only after the graph is built - [x] **Researcher Network: shared papers tab count badge** — tab label shows `(N)` matching collaborators tab; count updates dynamically when a collaborator is selected - [x] **Researcher Network: history delete clears in-memory cache** — deleting a history entry now evicts the matching `cacheRef` entry so re-search correctly hits the API instead of stale data - [x] **Researcher Network: topSharedPapers limit 5 → 20** — up to 20 shared papers shown per collaborator edge instead of 5 - [x] **Researcher Network: shared papers filtered by selected collaborator** — clicking a node or list row filters the shared papers tab to that pair; deselect restores full list - [x] **Researcher Network: warning text i18n fix** — "Coauthorship does not imply an advisor-student relation … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [hyeongus2](https://github.com/hyeongus2) - **Source:** [hyeongus2/research-thread-agent](https://github.com/hyeongus2/research-thread-agent) - **License:** MIT - **Homepage:** http://localhost:3000 Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-hyeongus2-research-thread-agent - Seller: https://agentstack.voostack.com/s/hyeongus2 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.