PolyHedra / docs /prd.md
yf176
Deploy Polyhedra to HF Spaces
891fe52
|
Raw History Blame Contribute Delete
52 kB
# Polyhedra - Product Requirements Document ## Document Control | Field | Value | |-------|-------| | **Project Name** | Polyhedra | | **Version** | 2.0.0 | | **Type** | MCP Tool Server | | **Status** | Ready for Development | | **Created** | November 26, 2024 | | **Last Updated** | November 29, 2025 | | **Author** | Product Team | | **Stakeholders** | Engineering, Research Community | ### Revision History | Version | Date | Author | Changes | |---------|------|--------|----------| | 2.0.0 | 2024-11-26 | Product Team | BREAKING: Removed internal LLM calls, simplified to pure MCP tool server | | 1.x | - | Product Team | Legacy versions with built-in LLM agents | --- ## Executive Summary ### Purpose Polyhedra is a pure Model Context Protocol (MCP) tool server designed to augment IDE-based AI assistants (Cursor, GitHub Copilot, Windsurf, VS Code) with academic research capabilities. Unlike traditional research tools, Polyhedra does not call LLMs directlyβ€”all content generation is handled by the IDE's native AI, while Polyhedra provides specialized research tools and data access. ### Key Capabilities - **Paper Discovery**: Search and retrieve academic papers via Semantic Scholar API - **Citation Management**: Automated BibTeX generation and reference management - **RAG Retrieval**: Semantic search across indexed papers for relevant citations - **Context Management**: Read/write project files for research workflow - **Project Scaffolding**: Initialize standardized research project structures ### Target Audience - ML/AI researchers using modern IDEs with AI assistants - PhD students requiring streamlined research workflows - Academic professionals seeking IDE-integrated paper management ### Success Criteria - Sub-2-second paper search response time - 100% valid BibTeX generation - Support for 4+ major IDEs (Cursor, Copilot, Windsurf, VS Code) - Setup time under 5 minutes --- ## 1. Product Overview ### 1.1 Vision Polyhedra is a **pure MCP tool server** that extends IDE AI assistants (Cursor, GitHub Copilot, Windsurf, VS Code) with academic research capabilities. **Polyhedra does NOT call LLMs** β€” all generation capabilities come from the IDE's AI. ### 1.2 Architecture Philosophy ``` β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ IDE (Cursor / Copilot) β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚ IDE's LLM (Claude/GPT) β”‚ β”‚ β”‚ β”‚ β€’ Intent understanding β”‚ β”‚ β”‚ β”‚ β€’ Literature review generation β”‚ β”‚ β”‚ β”‚ β€’ Paper writing β”‚ β”‚ β”‚ β”‚ β€’ Hypothesis generation β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β”‚ MCP Protocol β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚ Polyhedra MCP Server β”‚ β”‚ β”‚ β”‚ β€’ Paper search (Semantic Scholar API) β”‚ β”‚ β”‚ β”‚ β€’ Context management (project files) β”‚ β”‚ β”‚ β”‚ β€’ RAG retrieval (relevant papers) β”‚ β”‚ β”‚ β”‚ β€’ Citation management (BibTeX) β”‚ β”‚ β”‚ β”‚ β€’ File read/write β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` ### 1.3 What Polyhedra Does vs What IDE Does | Capability | Polyhedra (MCP) | IDE (LLM) | |------------|-----------------|-----------| | Search academic papers | βœ“ | | | Fetch paper metadata & BibTeX | βœ“ | | | Read project files | βœ“ | | | Write/save files | βœ“ | | | RAG retrieval | βœ“ | | | Manage citations | βœ“ | | | Understand user intent | | βœ“ | | Generate literature review | | βœ“ | | Generate hypotheses | | βœ“ | | Write paper sections | | βœ“ | | Decide workflow | | βœ“ | ### 1.4 Target Users - ML/AI researchers using Cursor, Copilot, or Windsurf - PhD students who want AI-assisted research workflow - Anyone who wants academic paper tools in their IDE ### 1.5 Tech Stack ```yaml language: Python 3.11+ mcp_framework: mcp (official SDK) http_client: httpx data_validation: Pydantic bibtex_parser: bibtexparser embeddings: sentence-transformers vector_store: numpy (simple cosine similarity) package_manager: uv supported_ides: - Cursor - GitHub Copilot - Windsurf - VS Code (with MCP extension) ``` --- ## 2. System Architecture ### 2.1 High-Level Architecture ``` β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ MCP Server β”‚ β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚ Tool Layer β”‚ β”‚ β”‚ β”‚ search_papers | get_paper | get_context β”‚ β”‚ β”‚ β”‚ query_similar | save_file | manage_citations β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚ Service Layer β”‚ β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚ β”‚ β”‚ Papers β”‚ β”‚ Context β”‚ β”‚ Citationsβ”‚ β”‚ β”‚ β”‚ β”‚ β”‚ Service β”‚ β”‚ Service β”‚ β”‚ Service β”‚ β”‚ β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚ β”‚ β”‚ RAG β”‚ β”‚ File β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ Service β”‚ β”‚ Service β”‚ β”‚ β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` ### 2.2 Directory Structure ``` polyhedra/ β”œβ”€β”€ pyproject.toml β”œβ”€β”€ README.md β”œβ”€β”€ src/ β”‚ └── polyhedra/ β”‚ β”œβ”€β”€ __init__.py β”‚ β”œβ”€β”€ server.py # MCP server entry point β”‚ β”œβ”€β”€ tools/ β”‚ β”‚ β”œβ”€β”€ __init__.py β”‚ β”‚ β”œβ”€β”€ papers.py # search_papers, get_paper β”‚ β”‚ β”œβ”€β”€ context.py # get_context, get_project_status β”‚ β”‚ β”œβ”€β”€ retrieval.py # query_similar_papers β”‚ β”‚ β”œβ”€β”€ citations.py # add_citation, get_citations β”‚ β”‚ └── files.py # save_file, read_file β”‚ β”œβ”€β”€ services/ β”‚ β”‚ β”œβ”€β”€ __init__.py β”‚ β”‚ β”œβ”€β”€ semantic_scholar.py β”‚ β”‚ β”œβ”€β”€ context_manager.py β”‚ β”‚ β”œβ”€β”€ citation_manager.py β”‚ β”‚ β”œβ”€β”€ rag_service.py β”‚ β”‚ └── file_service.py β”‚ └── schemas/ β”‚ β”œβ”€β”€ __init__.py β”‚ β”œβ”€β”€ paper.py β”‚ └── project.py └── tests/ β”œβ”€β”€ test_tools/ └── test_services/ ``` ### 2.3 Project Output Structure When used in a research project: ``` my-research/ β”œβ”€β”€ .poly/ β”‚ β”œβ”€β”€ config.yaml # Project configuration β”‚ └── embeddings/ # Cached paper embeddings β”‚ └── papers.pkl β”œβ”€β”€ literature/ β”‚ β”œβ”€β”€ papers.json # Paper metadata (structured) β”‚ β”œβ”€β”€ review.md # Generated by IDE's LLM β”‚ └── gaps.md # Generated by IDE's LLM β”œβ”€β”€ ideas/ β”‚ └── hypotheses.md # Generated by IDE's LLM β”œβ”€β”€ method/ β”‚ └── design.md # Generated by IDE's LLM β”œβ”€β”€ paper/ β”‚ β”œβ”€β”€ abstract.md β”‚ β”œβ”€β”€ introduction.md β”‚ └── ... # All generated by IDE's LLM β”œβ”€β”€ references.bib # Managed by Polyhedra └── .cursorrules # IDE prompts for research workflow ``` --- ## 3. MCP Tools Specification ### 3.1 Tool: `search_papers` Search academic papers via Semantic Scholar. ```yaml name: search_papers description: | Search for academic papers on Semantic Scholar. Returns paper metadata including title, authors, abstract, citations, and BibTeX entry. input_schema: type: object properties: query: type: string description: Search query (topic, keywords, or paper title) limit: type: integer default: 20 description: Maximum number of papers to return (max 100) year_start: type: integer description: Filter papers from this year onwards year_end: type: integer description: Filter papers until this year fields_of_study: type: array items: type: string description: Filter by fields (e.g., "Computer Science", "Medicine") required: [query] output_schema: type: object properties: papers: type: array items: $ref: "#/schemas/Paper" total_results: type: integer query_used: type: string ``` ### 3.2 Tool: `get_paper` Get detailed information for a specific paper. ```yaml name: get_paper description: | Get detailed information about a specific paper by its ID. Returns full metadata, abstract, BibTeX, and citation context. input_schema: type: object properties: paper_id: type: string description: Semantic Scholar paper ID or DOI or ArXiv ID required: [paper_id] output_schema: type: object properties: paper: $ref: "#/schemas/Paper" references: type: array description: Papers this paper cites citations: type: array description: Papers that cite this paper ``` ### 3.3 Tool: `get_context` Read project files for context. ```yaml name: get_context description: | Read one or more project files to provide context for generation. Use this before writing paper sections to get relevant background. input_schema: type: object properties: files: type: array items: type: string description: | File paths relative to project root. Common paths: literature/papers.json, literature/review.md, ideas/hypotheses.md, method/design.md include_papers: type: boolean default: false description: If true, include full paper metadata from papers.json required: [files] output_schema: type: object properties: contents: type: object description: Map of filename to file content missing_files: type: array description: Files that were requested but don't exist ``` ### 3.4 Tool: `query_similar_papers` RAG retrieval for relevant papers. ```yaml name: query_similar_papers description: | Find papers most relevant to a query using semantic similarity. Useful when writing sections that need specific citations. Papers must first be indexed via index_papers. input_schema: type: object properties: query: type: string description: Natural language query describing what you need k: type: integer default: 5 description: Number of papers to return required: [query] output_schema: type: object properties: papers: type: array items: type: object properties: paper_id: type: string title: type: string abstract: type: string relevance_score: type: number bibtex_key: type: string ``` ### 3.5 Tool: `index_papers` Index papers for RAG retrieval. ```yaml name: index_papers description: | Index papers from papers.json for semantic search. Call this after search_papers to enable query_similar_papers. input_schema: type: object properties: papers_file: type: string default: "literature/papers.json" description: Path to papers JSON file required: [] output_schema: type: object properties: indexed_count: type: integer status: type: string ``` ### 3.6 Tool: `save_file` Save generated content to project. ```yaml name: save_file description: | Save content to a file in the project. Creates parent directories if they don't exist. input_schema: type: object properties: path: type: string description: File path relative to project root content: type: string description: Content to write append: type: boolean default: false description: If true, append instead of overwrite required: [path, content] output_schema: type: object properties: success: type: boolean path: type: string bytes_written: type: integer ``` ### 3.7 Tool: `add_citation` Add a citation to references.bib. ```yaml name: add_citation description: | Add a BibTeX entry to the project's references.bib file. Handles duplicates automatically (skips if key exists). input_schema: type: object properties: bibtex: type: string description: BibTeX entry string paper_id: type: string description: | Alternative: Semantic Scholar paper ID. Will fetch BibTeX automatically. required: [] # One of bibtex or paper_id required output_schema: type: object properties: key: type: string description: The BibTeX citation key added: type: boolean description: True if newly added, false if already existed ``` ### 3.8 Tool: `get_citations` List all citations in references.bib. ```yaml name: get_citations description: | Get all citation keys and entries from references.bib. Useful for checking what papers are already cited. input_schema: type: object properties: keys_only: type: boolean default: true description: If true, return only keys. If false, return full entries. required: [] output_schema: type: object properties: citations: type: array items: type: object properties: key: type: string title: type: string authors: type: string year: type: integer count: type: integer ``` ### 3.9 Tool: `get_project_status` Get current project state. ```yaml name: get_project_status description: | Get overview of current research project state. Shows which files exist and project progress. input_schema: type: object properties: {} required: [] output_schema: type: object properties: project_root: type: string existing_files: type: array items: type: string paper_count: type: integer citation_count: type: integer indexed_for_rag: type: boolean ``` ### 3.10 Tool: `init_project` Initialize a new research project. ```yaml name: init_project description: | Initialize a new research project with standard directory structure. input_schema: type: object properties: path: type: string default: "." description: Project root path name: type: string description: Project name (used in config) required: [] output_schema: type: object properties: created_dirs: type: array created_files: type: array project_root: type: string ``` --- ## 4. Data Schemas ### 4.1 Paper Schema ```python # schemas/paper.py from pydantic import BaseModel from typing import Optional class Paper(BaseModel): id: str # Semantic Scholar ID title: str authors: list[str] year: int venue: Optional[str] abstract: str citation_count: int bibtex_key: str # e.g., "vaswani2017attention" bibtex_entry: str # Full BibTeX string url: Optional[str] pdf_url: Optional[str] fields_of_study: list[str] ``` ### 4.2 Project Config Schema ```python # schemas/project.py from pydantic import BaseModel from typing import Optional class ProjectConfig(BaseModel): name: str created_at: str paper_count: int = 0 indexed: bool = False ``` --- ## 5. Service Implementations ### 5.1 Semantic Scholar Service ```python # services/semantic_scholar.py import httpx from typing import Optional class SemanticScholarService: BASE_URL = "https://api.semanticscholar.org/graph/v1" def __init__(self, api_key: Optional[str] = None): self.api_key = api_key self.client = httpx.AsyncClient( headers={"x-api-key": api_key} if api_key else {} ) async def search( self, query: str, limit: int = 20, year_start: Optional[int] = None, year_end: Optional[int] = None, fields_of_study: Optional[list[str]] = None ) -> list[dict]: """Search papers by query""" params = { "query": query, "limit": min(limit, 100), "fields": "paperId,title,authors,year,venue,abstract," "citationCount,fieldsOfStudy,url,openAccessPdf" } if year_start or year_end: year_filter = f"{year_start or ''}-{year_end or ''}" params["year"] = year_filter if fields_of_study: params["fieldsOfStudy"] = ",".join(fields_of_study) resp = await self.client.get( f"{self.BASE_URL}/paper/search", params=params ) resp.raise_for_status() return resp.json().get("data", []) async def get_paper(self, paper_id: str) -> dict: """Get paper by ID""" resp = await self.client.get( f"{self.BASE_URL}/paper/{paper_id}", params={ "fields": "paperId,title,authors,year,venue,abstract," "citationCount,citations,references,fieldsOfStudy," "url,openAccessPdf" } ) resp.raise_for_status() return resp.json() def generate_bibtex(self, paper: dict) -> tuple[str, str]: """Generate BibTeX key and entry for a paper""" # Generate key: firstauthorYear first_author = paper["authors"][0]["name"].split()[-1].lower() year = paper.get("year", "unknown") key = f"{first_author}{year}" # Generate entry authors = " and ".join(a["name"] for a in paper["authors"]) entry = f"""@article{{{key}, title={{{paper['title']}}}, author={{{authors}}}, year={{{year}}}, venue={{{paper.get('venue', '')}}}, }}""" return key, entry ``` ### 5.2 Citation Manager Service ```python # services/citation_manager.py import bibtexparser from pathlib import Path from typing import Optional class CitationManager: def __init__(self, project_root: Path): self.bib_path = project_root / "references.bib" def load(self) -> bibtexparser.Library: if self.bib_path.exists(): return bibtexparser.parse_file(str(self.bib_path)) return bibtexparser.Library() def save(self, library: bibtexparser.Library): bibtexparser.write_file(str(self.bib_path), library) def add_entry(self, bibtex_str: str) -> tuple[str, bool]: """Add entry, returns (key, was_added)""" library = self.load() new_entry = bibtexparser.parse_string(bibtex_str).entries[0] key = new_entry.key existing_keys = {e.key for e in library.entries} if key in existing_keys: return key, False library.add(new_entry) self.save(library) return key, True def get_all_keys(self) -> list[str]: library = self.load() return [e.key for e in library.entries] def get_all_entries(self) -> list[dict]: library = self.load() return [ { "key": e.key, "title": e.get("title", ""), "authors": e.get("author", ""), "year": int(e.get("year", 0)) if e.get("year") else None } for e in library.entries ] ``` ### 5.3 RAG Service ```python # services/rag_service.py import json import pickle import numpy as np from pathlib import Path from sentence_transformers import SentenceTransformer class RAGService: def __init__( self, project_root: Path, model_name: str = "all-MiniLM-L6-v2" ): self.project_root = project_root self.embeddings_path = project_root / ".poly" / "embeddings" / "papers.pkl" self.model = None # Lazy load self.model_name = model_name self._index = None def _load_model(self): if self.model is None: self.model = SentenceTransformer(self.model_name) def index_papers(self, papers_file: Path) -> int: """Index papers for retrieval""" self._load_model() papers = json.loads(papers_file.read_text()) texts = [] metadata = [] for paper in papers: text = f"{paper['title']}. {paper['abstract']}" texts.append(text) metadata.append({ "id": paper["id"], "title": paper["title"], "abstract": paper["abstract"], "bibtex_key": paper.get("bibtex_key", "") }) embeddings = self.model.encode(texts, show_progress_bar=False) self._index = { "embeddings": embeddings, "metadata": metadata } self.embeddings_path.parent.mkdir(parents=True, exist_ok=True) with open(self.embeddings_path, "wb") as f: pickle.dump(self._index, f) return len(papers) def query(self, query: str, k: int = 5) -> list[dict]: """Find top-k similar papers""" if self._index is None: self._load_index() if self._index is None: return [] self._load_model() query_emb = self.model.encode([query])[0] embeddings = self._index["embeddings"] similarities = np.dot(embeddings, query_emb) / ( np.linalg.norm(embeddings, axis=1) * np.linalg.norm(query_emb) ) top_indices = np.argsort(similarities)[-k:][::-1] results = [] for idx in top_indices: meta = self._index["metadata"][idx] results.append({ "paper_id": meta["id"], "title": meta["title"], "abstract": meta["abstract"], "bibtex_key": meta["bibtex_key"], "relevance_score": float(similarities[idx]) }) return results def _load_index(self): if self.embeddings_path.exists(): with open(self.embeddings_path, "rb") as f: self._index = pickle.load(f) def is_indexed(self) -> bool: return self.embeddings_path.exists() ``` ### 5.4 Context Manager Service ```python # services/context_manager.py import json from pathlib import Path from typing import Optional class ContextManager: def __init__(self, project_root: Path): self.root = project_root def read_files(self, paths: list[str]) -> tuple[dict, list[str]]: """Read multiple files, return contents and missing files""" contents = {} missing = [] for path in paths: full_path = self.root / path if full_path.exists(): contents[path] = full_path.read_text() else: missing.append(path) return contents, missing def write_file(self, path: str, content: str, append: bool = False) -> int: """Write content to file, return bytes written""" full_path = self.root / path full_path.parent.mkdir(parents=True, exist_ok=True) mode = "a" if append else "w" with open(full_path, mode) as f: return f.write(content) def get_status(self) -> dict: """Get project status""" existing = [] check_paths = [ "literature/papers.json", "literature/review.md", "literature/gaps.md", "ideas/hypotheses.md", "method/design.md", "paper/abstract.md", "paper/introduction.md", "paper/related_work.md", "paper/method.md", "paper/experiments.md", "paper/conclusion.md", "references.bib" ] for path in check_paths: if (self.root / path).exists(): existing.append(path) paper_count = 0 papers_file = self.root / "literature" / "papers.json" if papers_file.exists(): papers = json.loads(papers_file.read_text()) paper_count = len(papers) citation_count = 0 bib_file = self.root / "references.bib" if bib_file.exists(): import bibtexparser lib = bibtexparser.parse_file(str(bib_file)) citation_count = len(lib.entries) indexed = (self.root / ".poly" / "embeddings" / "papers.pkl").exists() return { "project_root": str(self.root), "existing_files": existing, "paper_count": paper_count, "citation_count": citation_count, "indexed_for_rag": indexed } def init_project(self, name: Optional[str] = None) -> dict: """Initialize project structure""" dirs = [ "literature", "ideas", "method", "paper", ".poly/embeddings" ] created_dirs = [] for d in dirs: path = self.root / d if not path.exists(): path.mkdir(parents=True) created_dirs.append(d) created_files = [] # Create empty references.bib bib_path = self.root / "references.bib" if not bib_path.exists(): bib_path.write_text("") created_files.append("references.bib") # Create config config_path = self.root / ".poly" / "config.yaml" if not config_path.exists(): import yaml from datetime import datetime config = { "name": name or self.root.name, "created_at": datetime.now().isoformat(), "paper_count": 0, "indexed": False } config_path.write_text(yaml.dump(config)) created_files.append(".poly/config.yaml") return { "created_dirs": created_dirs, "created_files": created_files, "project_root": str(self.root) } ``` --- ## 6. MCP Server Implementation ### 6.1 Server Entry Point ```python # server.py from mcp.server import Server from mcp.server.stdio import stdio_server from mcp.types import Tool, TextContent from pathlib import Path import json from polyhedra.services.semantic_scholar import SemanticScholarService from polyhedra.services.citation_manager import CitationManager from polyhedra.services.rag_service import RAGService from polyhedra.services.context_manager import ContextManager # Initialize server server = Server("polyhedra") # Services (initialized per project root) _project_root: Path = Path.cwd() _papers_service = SemanticScholarService() _citation_manager: CitationManager = None _rag_service: RAGService = None _context_manager: ContextManager = None def _init_services(project_root: Path = None): global _project_root, _citation_manager, _rag_service, _context_manager _project_root = project_root or Path.cwd() _citation_manager = CitationManager(_project_root) _rag_service = RAGService(_project_root) _context_manager = ContextManager(_project_root) _init_services() @server.list_tools() async def list_tools() -> list[Tool]: return [ Tool( name="search_papers", description="Search academic papers on Semantic Scholar", inputSchema={ "type": "object", "properties": { "query": {"type": "string", "description": "Search query"}, "limit": {"type": "integer", "default": 20}, "year_start": {"type": "integer"}, "year_end": {"type": "integer"} }, "required": ["query"] } ), Tool( name="get_paper", description="Get detailed paper information by ID", inputSchema={ "type": "object", "properties": { "paper_id": {"type": "string"} }, "required": ["paper_id"] } ), Tool( name="get_context", description="Read project files for context", inputSchema={ "type": "object", "properties": { "files": { "type": "array", "items": {"type": "string"} } }, "required": ["files"] } ), Tool( name="query_similar_papers", description="Find similar papers using semantic search", inputSchema={ "type": "object", "properties": { "query": {"type": "string"}, "k": {"type": "integer", "default": 5} }, "required": ["query"] } ), Tool( name="index_papers", description="Index papers for semantic search", inputSchema={ "type": "object", "properties": { "papers_file": {"type": "string", "default": "literature/papers.json"} } } ), Tool( name="save_file", description="Save content to project file", inputSchema={ "type": "object", "properties": { "path": {"type": "string"}, "content": {"type": "string"}, "append": {"type": "boolean", "default": False} }, "required": ["path", "content"] } ), Tool( name="add_citation", description="Add BibTeX citation to references.bib", inputSchema={ "type": "object", "properties": { "bibtex": {"type": "string"}, "paper_id": {"type": "string"} } } ), Tool( name="get_citations", description="List all citations in references.bib", inputSchema={ "type": "object", "properties": { "keys_only": {"type": "boolean", "default": True} } } ), Tool( name="get_project_status", description="Get current project status", inputSchema={"type": "object", "properties": {}} ), Tool( name="init_project", description="Initialize research project structure", inputSchema={ "type": "object", "properties": { "name": {"type": "string"} } } ) ] @server.call_tool() async def call_tool(name: str, arguments: dict) -> list[TextContent]: if name == "search_papers": papers = await _papers_service.search( query=arguments["query"], limit=arguments.get("limit", 20), year_start=arguments.get("year_start"), year_end=arguments.get("year_end") ) # Add BibTeX to each paper results = [] for p in papers: key, entry = _papers_service.generate_bibtex(p) results.append({ "id": p["paperId"], "title": p["title"], "authors": [a["name"] for a in p.get("authors", [])], "year": p.get("year"), "venue": p.get("venue"), "abstract": p.get("abstract", ""), "citation_count": p.get("citationCount", 0), "bibtex_key": key, "bibtex_entry": entry }) # Auto-save to papers.json papers_path = _project_root / "literature" / "papers.json" papers_path.parent.mkdir(parents=True, exist_ok=True) papers_path.write_text(json.dumps(results, indent=2)) return [TextContent( type="text", text=json.dumps({ "papers": results, "total_results": len(results), "saved_to": "literature/papers.json" }, indent=2) )] elif name == "get_paper": paper = await _papers_service.get_paper(arguments["paper_id"]) key, entry = _papers_service.generate_bibtex(paper) result = { "paper": { "id": paper["paperId"], "title": paper["title"], "authors": [a["name"] for a in paper.get("authors", [])], "year": paper.get("year"), "abstract": paper.get("abstract", ""), "bibtex_key": key, "bibtex_entry": entry }, "references": len(paper.get("references", [])), "citations": len(paper.get("citations", [])) } return [TextContent(type="text", text=json.dumps(result, indent=2))] elif name == "get_context": contents, missing = _context_manager.read_files(arguments["files"]) return [TextContent( type="text", text=json.dumps({ "contents": contents, "missing_files": missing }, indent=2) )] elif name == "query_similar_papers": results = _rag_service.query( arguments["query"], k=arguments.get("k", 5) ) return [TextContent(type="text", text=json.dumps({"papers": results}, indent=2))] elif name == "index_papers": papers_file = _project_root / arguments.get("papers_file", "literature/papers.json") count = _rag_service.index_papers(papers_file) return [TextContent( type="text", text=json.dumps({"indexed_count": count, "status": "success"}) )] elif name == "save_file": bytes_written = _context_manager.write_file( arguments["path"], arguments["content"], append=arguments.get("append", False) ) return [TextContent( type="text", text=json.dumps({ "success": True, "path": arguments["path"], "bytes_written": bytes_written }) )] elif name == "add_citation": if arguments.get("bibtex"): key, added = _citation_manager.add_entry(arguments["bibtex"]) elif arguments.get("paper_id"): paper = await _papers_service.get_paper(arguments["paper_id"]) _, entry = _papers_service.generate_bibtex(paper) key, added = _citation_manager.add_entry(entry) else: return [TextContent(type="text", text='{"error": "Provide bibtex or paper_id"}')] return [TextContent( type="text", text=json.dumps({"key": key, "added": added}) )] elif name == "get_citations": if arguments.get("keys_only", True): keys = _citation_manager.get_all_keys() return [TextContent( type="text", text=json.dumps({"citations": keys, "count": len(keys)}) )] else: entries = _citation_manager.get_all_entries() return [TextContent( type="text", text=json.dumps({"citations": entries, "count": len(entries)}) )] elif name == "get_project_status": status = _context_manager.get_status() return [TextContent(type="text", text=json.dumps(status, indent=2))] elif name == "init_project": result = _context_manager.init_project(arguments.get("name")) return [TextContent(type="text", text=json.dumps(result, indent=2))] return [TextContent(type="text", text=f"Unknown tool: {name}")] async def main(): async with stdio_server() as (read_stream, write_stream): await server.run(read_stream, write_stream) if __name__ == "__main__": import asyncio asyncio.run(main()) ``` --- ## 7. IDE Integration ### 7.1 Configuration Files **Cursor** (`.cursor/mcp.json`): ```json { "mcpServers": { "polyhedra": { "command": "python", "args": ["-m", "polyhedra.server"], "env": {} } } } ``` **VS Code / GitHub Copilot** (`settings.json`): ```json { "mcp": { "servers": { "polyhedra": { "command": "python", "args": ["-m", "polyhedra.server"] } } } } ``` **Windsurf** (`.windsurf/mcp.json`): ```json { "mcpServers": { "polyhedra": { "command": "python", "args": ["-m", "polyhedra.server"] } } } ``` ### 7.2 IDE Prompt Instructions Create `.cursorrules` or `.github/copilot-instructions.md`: ```markdown # Research Project Instructions This is an academic research project. Use Polyhedra MCP tools for research tasks. ## Workflow ### 1. Literature Search When asked to find papers or do a literature review: 1. Use `search_papers` to find relevant papers 2. Use `index_papers` to enable semantic search 3. Use `get_context` to read papers.json 4. Generate a literature review and save with `save_file` to literature/review.md 5. For each cited paper, use `add_citation` to update references.bib ### 2. Writing Paper Sections When writing paper sections: 1. Use `get_context` to load relevant files (review.md, hypotheses.md, etc.) 2. Use `query_similar_papers` to find papers to cite 3. Generate content with proper citations (\cite{key} format) 4. Use `save_file` to save the section 5. Use `add_citation` for any new citations ### 3. Citation Format - Always use \cite{bibtex_key} or [@bibtex_key] format - Check existing citations with `get_citations` before adding - Only cite papers from papers.json ### 4. Project Status Use `get_project_status` to see what files exist and progress. ## File Locations - Literature review: literature/review.md - Paper metadata: literature/papers.json - Research gaps: literature/gaps.md - Hypotheses: ideas/hypotheses.md - Method design: method/design.md - Paper sections: paper/{section}.md - Citations: references.bib ``` --- ## 8. Functional Requirements ### Requirements Summary Table | ID | Requirement | Priority | Status | |----|-------------|----------|--------| | FR-001 | Paper Search | P0 | Not Started | | FR-002 | RAG Retrieval | P0 | Not Started | | FR-003 | Citation Management | P0 | Not Started | | FR-004 | Context Management | P0 | Not Started | | FR-005 | Project Initialization | P1 | Not Started | | NFR-001 | Performance | P0 | Not Started | | NFR-002 | Reliability | P0 | Not Started | | NFR-003 | Compatibility | P0 | Not Started | ### FR-001: Paper Search **Priority**: P0 (Critical) **Status**: Not Started **Description** Search Semantic Scholar API and return structured paper data with automatically generated BibTeX entries. **Acceptance Criteria** - Returns papers with all required fields (title, authors, abstract, year, venue, citation count) - Auto-generates BibTeX key using format: `firstauthor+year` - Auto-generates valid BibTeX entry - Saves results to `literature/papers.json` - Handles API rate limiting gracefully with retry logic - Returns up to 100 results per query **Dependencies**: Semantic Scholar API access --- ### FR-002: RAG Retrieval **Priority**: P0 (Critical) **Status**: Not Started **Description** Index papers locally and enable semantic similarity search for finding relevant citations during writing. **Acceptance Criteria** - Indexes paper titles and abstracts using sentence transformers - Returns top-k most similar papers to a natural language query - Includes relevance scores (cosine similarity) - Cached embeddings persist across sessions in `.poly/embeddings/` - Supports re-indexing when papers.json is updated **Dependencies**: sentence-transformers, numpy --- ### FR-003: Citation Management **Priority**: P0 (Critical) **Status**: Not Started **Description** Manage project's `references.bib` file with automatic deduplication and BibTeX validation. **Acceptance Criteria** - Add new citations without duplicates (check by key) - Fetch BibTeX by Semantic Scholar paper ID - List all citation keys - List all citation entries with metadata - Generate 100% valid BibTeX format - Support manual BibTeX entry addition **Dependencies**: bibtexparser --- ### FR-004: Context Management **Priority**: P0 (Critical) **Status**: Not Started **Description** Read and write project files to provide context to IDE's LLM for content generation. **Acceptance Criteria** - Read multiple files in one call - Report missing files (don't fail silently) - Create parent directories automatically on write - Support append mode for incremental updates - Return file contents as structured JSON - Handle encoding issues gracefully **Dependencies**: None (standard library) --- ### FR-005: Project Initialization **Priority**: P1 (High) **Status**: Not Started **Description** Initialize a new research project with standardized directory structure and configuration files. **Acceptance Criteria** - Creates standard directories: `literature/`, `ideas/`, `method/`, `paper/`, `.poly/embeddings/` - Creates empty `references.bib` - Creates `.poly/config.yaml` with project metadata - Idempotent (safe to run multiple times) - Returns list of created directories and files **Dependencies**: None (standard library) --- ### NFR-001: Performance **Priority**: P0 (Critical) **Status**: Not Started **Description** Ensure responsive tool execution to maintain IDE assistant responsiveness. **Acceptance Criteria** - Paper search: < 2 seconds (including API call) - Local file operations: < 100ms - RAG indexing: < 5 seconds for 100 papers - RAG query: < 500ms - Citation operations: < 50ms --- ### NFR-002: Reliability **Priority**: P0 (Critical) **Status**: Not Started **Description** Handle errors gracefully without crashing or losing data. **Acceptance Criteria** - API failures return informative error messages - Network timeouts handled with retry logic - File I/O errors reported clearly - Invalid BibTeX rejected with validation errors - No data corruption on concurrent access --- ### NFR-003: IDE Compatibility **Priority**: P0 (Critical) **Status**: Not Started **Description** Support major IDEs with MCP protocol compatibility. **Acceptance Criteria** - Works with Cursor IDE - Works with GitHub Copilot (VS Code) - Works with Windsurf - Works with VS Code + MCP extension - Provides configuration templates for each IDE --- ## 9. Development Tasks ### Phase 1: Core Services (Week 1) ```yaml tasks: - id: T-001 name: Project setup description: | - pyproject.toml with dependencies - src layout - Basic tests structure estimate: 2h - id: T-002 name: Semantic Scholar service description: | - Search endpoint - Get paper endpoint - BibTeX generation - Rate limiting estimate: 4h depends_on: [T-001] - id: T-003 name: Citation manager service description: | - BibTeX parsing with bibtexparser - Add/get/list operations - Deduplication estimate: 3h depends_on: [T-001] - id: T-004 name: RAG service description: | - Paper indexing - Embedding with sentence-transformers - Similarity search - Caching estimate: 4h depends_on: [T-001] - id: T-005 name: Context manager service description: | - File read/write - Project status - Project init estimate: 3h depends_on: [T-001] ``` ### Phase 2: MCP Server (Week 2) ```yaml tasks: - id: T-006 name: MCP server implementation description: | - Server setup with mcp SDK - All 10 tools implemented - Tool schemas estimate: 6h depends_on: [T-002, T-003, T-004, T-005] - id: T-007 name: IDE configuration files description: | - .cursor/mcp.json template - .vscode settings template - .cursorrules template estimate: 2h depends_on: [T-006] - id: T-008 name: Integration testing description: | - Test with Cursor - Test with Copilot - End-to-end workflow estimate: 4h depends_on: [T-006, T-007] ``` ### Phase 3: Polish (Week 3) ```yaml tasks: - id: T-009 name: Error handling description: | - API errors - File not found - Invalid inputs estimate: 3h depends_on: [T-006] - id: T-010 name: Documentation description: | - README with setup instructions - Tool documentation - Example workflows estimate: 3h depends_on: [T-008] - id: T-011 name: Package and publish description: | - PyPI setup - Installation instructions estimate: 2h depends_on: [T-010] ``` **Total: ~3 weeks** (down from 8 weeks in v1.x) --- ## 10. Testing Strategy ### Unit Tests ```python # tests/test_services/test_citation_manager.py def test_add_citation(): mgr = CitationManager(tmp_path) bibtex = "@article{test2023, title={Test Paper}}" key, added = mgr.add_entry(bibtex) assert key == "test2023" assert added == True def test_no_duplicate_citations(): mgr = CitationManager(tmp_path) bibtex = "@article{test2023, title={Test}}" mgr.add_entry(bibtex) key, added = mgr.add_entry(bibtex) assert added == False assert len(mgr.get_all_keys()) == 1 ``` ### Integration Tests ```python # tests/test_integration.py async def test_search_and_index_workflow(): # 1. Search papers result = await call_tool("search_papers", {"query": "transformers", "limit": 5}) papers = json.loads(result[0].text)["papers"] assert len(papers) == 5 # 2. Index papers result = await call_tool("index_papers", {}) assert json.loads(result[0].text)["status"] == "success" # 3. Query similar result = await call_tool("query_similar_papers", {"query": "attention mechanism", "k": 3}) similar = json.loads(result[0].text)["papers"] assert len(similar) == 3 ``` --- ## 11. Success Metrics ### Performance Metrics | Metric | Target | Measurement Method | |--------|--------|--------------------| | Paper Search Response Time | < 2 seconds | Average response time over 100 queries | | Local Operations | < 100ms | File read/write, citation operations | | RAG Indexing | < 5 seconds per 100 papers | Benchmark with standard paper set | | RAG Query | < 500ms | Average query time | ### Quality Metrics | Metric | Target | Measurement Method | |--------|--------|--------------------| | Search Result Relevance | Relevant papers in top 10 | Manual evaluation by researchers | | Citation Accuracy | 100% valid BibTeX | Automated validation with LaTeX | | BibTeX Deduplication | 0 duplicate keys | Automated testing | ### Compatibility Metrics | Metric | Target | Measurement Method | |--------|--------|--------------------| | IDE Support | 4+ IDEs supported | Integration testing | | Setup Time | < 5 minutes | Timed user testing from install to first search | | Documentation Completeness | 100% API coverage | Documentation review | ### Adoption Metrics (Post-Launch) | Metric | Target (3 months) | Measurement Method | |--------|-------------------|--------------------| | Active Users | 100+ | Telemetry (opt-in) | | Papers Searched | 10,000+ | Usage statistics | | Projects Initialized | 50+ | Project creation count | --- ## Appendix A: Example IDE Conversation ``` User: Search for papers about efficient vision transformers Copilot: I'll search for papers on efficient vision transformers. [Calls search_papers with query="efficient vision transformers"] Found 20 papers. Here are the top results: 1. **EfficientViT: Memory Efficient Vision Transformer** (liu2023) - Citations: 245 - Year: 2023 2. **MobileViT: Light-weight Vision Transformer** (mehta2022) - Citations: 890 - Year: 2022 ... Papers saved to literature/papers.json. Would you like me to: 1. Generate a literature review 2. Index papers for semantic search 3. Look at a specific paper User: Generate a literature review and save it Copilot: I'll read the papers and generate a review. [Calls get_context with files=["literature/papers.json"]] [Calls index_papers] # Literature Review: Efficient Vision Transformers ## Overview Vision Transformers (ViTs) have achieved remarkable success... ## Taxonomy of Approaches ### 1. Architecture Modifications ... [Calls save_file with path="literature/review.md"] [Calls add_citation for each cited paper] βœ“ Saved literature review to literature/review.md βœ“ Added 12 citations to references.bib ``` --- ## Appendix B: Comparison with v1.x | Aspect | v1.x (Agent-based) | v2.0 (Pure MCP) | |--------|-------------------|-----------------| | LLM calls | Internal | IDE handles | | Complexity | High | Low | | Dependencies | Many (LLM SDKs) | Few | | Development time | 8 weeks | 3 weeks | | Cost | User pays API | IDE subscription | | Flexibility | Fixed prompts | IDE customizable | | Maintenance | Prompt updates | Minimal |
# Polyhedra - Product Requirements Document
## Document Control
| Field | Value |
|-------|-------|
| **Project Name** | Polyhedra |
| **Version** | 2.0.0 |
| **Type** | MCP Tool Server |
| **Status** | Ready for Development |
| **Created** | November 26, 2024 |
| **Last Updated** | November 29, 2025 |
| **Author** | Product Team |
| **Stakeholders** | Engineering, Research Community |
### Revision History
| Version | Date | Author | Changes |
|---------|------|--------|----------|
| 2.0.0 | 2024-11-26 | Product Team | BREAKING: Removed internal LLM calls, simplified to pure MCP tool server |
| 1.x | - | Product Team | Legacy versions with built-in LLM agents |
---
## Executive Summary
### Purpose
Polyhedra is a pure Model Context Protocol (MCP) tool server designed to augment IDE-based AI assistants (Cursor, GitHub Copilot, Windsurf, VS Code) with academic research capabilities. Unlike traditional research tools, Polyhedra does not call LLMs directlyβ€”all content generation is handled by the IDE's native AI, while Polyhedra provides specialized research tools and data access.
### Key Capabilities
- **Paper Discovery**: Search and retrieve academic papers via Semantic Scholar API
- **Citation Management**: Automated BibTeX generation and reference management
- **RAG Retrieval**: Semantic search across indexed papers for relevant citations
- **Context Management**: Read/write project files for research workflow
- **Project Scaffolding**: Initialize standardized research project structures
### Target Audience
- ML/AI researchers using modern IDEs with AI assistants
- PhD students requiring streamlined research workflows
- Academic professionals seeking IDE-integrated paper management
### Success Criteria
- Sub-2-second paper search response time
- 100% valid BibTeX generation
- Support for 4+ major IDEs (Cursor, Copilot, Windsurf, VS Code)
- Setup time under 5 minutes
---
## 1. Product Overview
### 1.1 Vision
Polyhedra is a **pure MCP tool server** that extends IDE AI assistants (Cursor, GitHub Copilot, Windsurf, VS Code) with academic research capabilities.
**Polyhedra does NOT call LLMs** β€” all generation capabilities come from the IDE's AI.
### 1.2 Architecture Philosophy
```
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ IDE (Cursor / Copilot) β”‚
β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚
β”‚ β”‚ IDE's LLM (Claude/GPT) β”‚ β”‚
β”‚ β”‚ β€’ Intent understanding β”‚ β”‚
β”‚ β”‚ β€’ Literature review generation β”‚ β”‚
β”‚ β”‚ β€’ Paper writing β”‚ β”‚
β”‚ β”‚ β€’ Hypothesis generation β”‚ β”‚
β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚
β”‚ β”‚ MCP Protocol β”‚
β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚
β”‚ β”‚ Polyhedra MCP Server β”‚ β”‚
β”‚ β”‚ β€’ Paper search (Semantic Scholar API) β”‚ β”‚
β”‚ β”‚ β€’ Context management (project files) β”‚ β”‚
β”‚ β”‚ β€’ RAG retrieval (relevant papers) β”‚ β”‚
β”‚ β”‚ β€’ Citation management (BibTeX) β”‚ β”‚
β”‚ β”‚ β€’ File read/write β”‚ β”‚
β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
```
### 1.3 What Polyhedra Does vs What IDE Does
| Capability | Polyhedra (MCP) | IDE (LLM) |
|------------|-----------------|-----------|
| Search academic papers | βœ“ | |
| Fetch paper metadata & BibTeX | βœ“ | |
| Read project files | βœ“ | |
| Write/save files | βœ“ | |
| RAG retrieval | βœ“ | |
| Manage citations | βœ“ | |
| Understand user intent | | βœ“ |
| Generate literature review | | βœ“ |
| Generate hypotheses | | βœ“ |
| Write paper sections | | βœ“ |
| Decide workflow | | βœ“ |