Download docs/prd.md from polyHedra/PolyHedra: direct link, hf CLI and curl.
- Browser
- Download file 52 kB
-
https://huggingface.co/spaces/polyHedra/PolyHedra/resolve/main/docs/prd.md
- Command line
-
hf download hf://spaces/polyHedra/PolyHedra/docs/prd.md
-
curl -L -o prd.md https://huggingface.co/spaces/polyHedra/PolyHedra/resolve/main/docs/prd.md
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
# 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
# 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
# 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
# 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
# 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
# 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
# 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):
{
"mcpServers": {
"polyhedra": {
"command": "python",
"args": ["-m", "polyhedra.server"],
"env": {}
}
}
}
VS Code / GitHub Copilot (settings.json):
{
"mcp": {
"servers": {
"polyhedra": {
"command": "python",
"args": ["-m", "polyhedra.server"]
}
}
}
}
Windsurf (.windsurf/mcp.json):
{
"mcpServers": {
"polyhedra": {
"command": "python",
"args": ["-m", "polyhedra.server"]
}
}
}
7.2 IDE Prompt Instructions
Create .cursorrules or .github/copilot-instructions.md:
# 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.yamlwith 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)
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)
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)
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
# 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
# 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 |