Download docs/ARCHITECTURE.md from polyHedra/PolyHedra: direct link, hf CLI and curl.
- Browser
- Download file 28.4 kB
-
https://huggingface.co/spaces/polyHedra/PolyHedra/resolve/main/docs/ARCHITECTURE.md
- Command line
-
hf download hf://spaces/polyHedra/PolyHedra/docs/ARCHITECTURE.md
-
curl -L -o ARCHITECTURE.md https://huggingface.co/spaces/polyHedra/PolyHedra/resolve/main/docs/ARCHITECTURE.md
Architecture Documentation
System design and implementation details for Polyhedra MCP Server.
Table of Contents
- Overview
- System Architecture
- Component Design
- Data Flow
- Technology Stack
- Integration Points
- Performance Considerations
- Security & Privacy
Overview
Polyhedra is an MCP (Model Context Protocol) server that extends IDE AI assistants with academic research capabilities. It follows a service-oriented architecture with clean separation of concerns.
Design Principles
- Simplicity: Pure tool server, no UI components
- Composability: Services can be used independently or combined
- Reliability: Comprehensive error handling and graceful degradation
- Performance: Caching, batching, and async operations
- Testability: 100% test coverage, dependency injection
Architecture Patterns
- Service Layer Pattern: Business logic in dedicated services
- Repository Pattern: Data access abstracted behind interfaces
- Strategy Pattern: Pluggable search/retrieval strategies
- Facade Pattern: MCP server provides unified interface
System Architecture
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β IDE (Cursor, VS Code, etc.) β
β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β AI Assistant (Claude, GPT-4, etc.) β β
β ββββββββββββββββββββββ¬ββββββββββββββββββββββββββββββββββ β
ββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββββββββββ
β
β MCP Protocol (JSON-RPC over stdio)
β
ββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββββββββββ
β Polyhedra MCP Server β
β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β Server (server.py) β β
β β β’ Tool registration β β
β β β’ Request routing β β
β β β’ Error handling β β
β ββββββββββββββββββββ¬ββββββββββββββββββββββββββββββββββββ β
β β β
β ββββββββββββββββββββΌββββββββββββββββββββββββββββββββββββ β
β β Service Layer β β
β β β β
β β ββββββββββββββββ ββββββββββββββββ ββββββββββββββ β β
β β β Semantic β β Citation β β File β β β
β β β Scholar β β Management β β Context β β β
β β β Service β β Service β β Service β β β
β β ββββββββββββββββ ββββββββββββββββ ββββββββββββββ β β
β β β β
β β ββββββββββββββββ ββββββββββββββββ β β
β β β RAG β β Project β β β
β β β Retrieval β β Initializer β β β
β β β Service β β Service β β β
β β ββββββββββββββββ ββββββββββββββββ β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β External Dependencies β β
β β β β
β β β’ Semantic Scholar API β β
β β β’ sentence-transformers (RAG) β β
β β β’ FAISS (vector indexing) β β
β β β’ bibtexparser (citations) β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
β File System
β
ββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββββββββββ
β Research Project β
β β
β .polyhedra/ papers/ β
β βββ embeddings.index βββ paper1.pdf β
β βββ metadata.json βββ paper2.pdf β
β βββ cache/ β
β notes/ β
β references.bib βββ summary.md β
β βββ ideas.md β
β README.md β
β literature-review/ β
β βββ draft.md β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Component Design
MCP Server (server.py)
Responsibility: Bridge between IDE and services.
class PolyhedraMCPServer:
"""Main MCP server implementing tool interface."""
def __init__(self):
self.semantic_scholar = SemanticScholarService()
self.citation_manager = CitationManager()
self.file_context = FileContextService()
self.rag_retrieval = RAGRetrievalService()
self.project_init = ProjectInitializer()
async def list_tools(self) -> list[Tool]:
"""Register all 10 tools with MCP."""
async def call_tool(self, name: str, arguments: dict) -> list[TextContent]:
"""Route tool calls to appropriate service."""
Key Features:
- Tool Registration: Defines schemas for 10 tools
- Request Routing: Maps tool names to service methods
- Error Wrapping: Catches exceptions, returns formatted errors
- Async Support: Uses asyncio for concurrent operations
Design Decisions:
- Single server instance per IDE process
- Stateless tool calls (no session management)
- Services instantiated once and reused
Semantic Scholar Service
Responsibility: Paper search and retrieval via Semantic Scholar API.
class SemanticScholarService:
"""Academic paper search via Semantic Scholar API."""
BASE_URL = "https://api.semanticscholar.org/graph/v1"
def __init__(self):
self.session = requests.Session()
self.cache = RequestCache()
async def search_papers(
self,
query: str,
year_range: Optional[str] = None,
limit: int = 10
) -> dict:
"""Search for papers by query."""
async def get_paper(
self,
paper_id: str,
fields: Optional[list[str]] = None
) -> dict:
"""Get detailed paper information."""
Features:
- Rate Limiting: Respects 100 req/5min limit
- Retry Logic: Exponential backoff on failures
- Caching: LRU cache for repeated queries
- Error Recovery: Returns cached data on network errors
API Integration:
# Search endpoint
GET /paper/search?query={query}&year={year}&limit={limit}
# Details endpoint
GET /paper/{paper_id}?fields={fields}
Cache Strategy:
- Search results: 1 hour TTL
- Paper details: 24 hour TTL
- Cache location:
.polyhedra/cache/
Citation Manager
Responsibility: BibTeX bibliography management.
class CitationManager:
"""Manage BibTeX citations in references.bib."""
def __init__(self, bib_file: str = "references.bib"):
self.bib_file = Path(bib_file)
self.parser = bibtexparser.bparser.BibTexParser()
def add_citation(self, citation_key: str, bibtex: str) -> dict:
"""Add citation to bibliography."""
def get_citations(self) -> list[dict]:
"""Get all citations from bibliography."""
Features:
- Validation: Checks BibTeX syntax
- Duplicate Detection: Prevents duplicate keys
- Atomic Writes: Tmp file + rename for safety
- Parsing: Converts BibTeX to structured JSON
File Format:
@article{vaswani2017attention,
title={Attention is all you need},
author={Vaswani, Ashish and ...},
journal={NeurIPS},
year={2017}
}
Lock Strategy:
- File lock for concurrent writes
- 5 second timeout
- Retry with exponential backoff
RAG Retrieval Service
Responsibility: Semantic search over collected papers using embeddings.
class RAGRetrievalService:
"""Semantic paper search using sentence transformers."""
MODEL = "sentence-transformers/all-MiniLM-L6-v2"
def __init__(self):
self.model = SentenceTransformer(self.MODEL)
self.index = None
self.papers = []
async def index_papers(
self,
papers: list[dict],
force_rebuild: bool = False
) -> dict:
"""Build FAISS index from papers."""
async def query_similar_papers(
self,
query: str,
limit: int = 10,
min_similarity: float = 0.7
) -> list[dict]:
"""Find similar papers to query."""
Architecture:
Papers β Sentence Transformer β Embeddings (384-dim) β FAISS Index
β
Query β Sentence Transformer β Query Embedding β FAISS Search β Similar Papers
Embedding Model:
- Model: all-MiniLM-L6-v2
- Dimensions: 384
- Size: ~80MB
- Speed: ~1000 sentences/sec on CPU
Index Structure:
{
"embeddings": np.ndarray, # (N, 384) float32
"papers": list[dict], # Paper metadata
"version": str, # Index version
"created_at": datetime # Build timestamp
}
Similarity Metric:
- Cosine similarity (dot product of normalized vectors)
- Range: [-1, 1], typical useful range: [0.5, 1.0]
File Context Service
Responsibility: Read/write project files safely.
class FileContextService:
"""Manage project file operations."""
def __init__(self, project_root: Optional[Path] = None):
self.project_root = project_root or Path.cwd()
def save_file(
self,
path: str,
content: str,
create_dirs: bool = True
) -> dict:
"""Write content to file."""
def get_context(
self,
paths: list[str]
) -> list[dict]:
"""Read content from files."""
Safety Features:
- Path Validation: Prevents directory traversal
- Atomic Writes: Tmp file + rename
- Encoding: UTF-8 with fallbacks
- Directory Creation: Automatic parent dir creation
Path Resolution:
# Relative to project root
path = "notes/summary.md"
full_path = project_root / path # /home/user/project/notes/summary.md
# Absolute paths rejected
path = "/etc/passwd" # Error: must be relative
# Traversal rejected
path = "../../../etc/passwd" # Error: outside project
Project Initializer
Responsibility: Create standardized research project structure.
class ProjectInitializer:
"""Initialize research project structure."""
DIRECTORIES = [
".polyhedra",
"papers",
"notes",
"literature-review",
"data"
]
def initialize(
self,
project_name: str,
base_path: Optional[Path] = None
) -> dict:
"""Create project structure."""
Created Structure:
project_name/
βββ .polyhedra/ # Tool data (index, cache)
βββ papers/ # Paper PDFs and metadata
βββ notes/ # Research notes
βββ literature-review/ # Literature review drafts
βββ data/ # Datasets
βββ references.bib # BibTeX bibliography (empty)
βββ README.md # Project overview (template)
Idempotency:
- Safe to run multiple times
- Only creates missing dirs/files
- Returns report of created vs. existing
Data Flow
Search Papers Flow
User β IDE AI β MCP Request
β
[Server: call_tool]
β
[SemanticScholarService]
β
Check Cache? ββYesβ Return cached
β No
API Request
β
[Semantic Scholar API]
β
Parse Response
β
Cache Result
β
Return to Server
β
Format as TextContent
β
Return via MCP
β
IDE AI β User
Timing:
- Cache hit: <10ms
- API request: 200-500ms
- With retry: up to 2 seconds
RAG Query Flow
User Query β IDE AI β MCP Request
β
[Server: call_tool]
β
[RAGRetrievalService]
β
Check Index Exists?
β Yes
Load Index from Disk
β
[Sentence Transformer Model]
β
Generate Query Embedding (384-dim)
β
[FAISS Index]
β
Search for Similar Embeddings
β
Return Top K Papers with Scores
β
Filter by min_similarity Threshold
β
Format Results with Metadata
β
Return via MCP
β
IDE AI β User
Timing:
- Model load (first time): 2-3 seconds
- Embedding generation: 10-50ms
- FAISS search: 1-5ms
- Total: 50-100ms (after first query)
Citation Management Flow
User + BibTeX β IDE AI β MCP Request
β
[Server: call_tool]
β
[CitationManager]
β
Acquire File Lock
β
Load references.bib
β
Parse BibTeX
β
Check Duplicate Key? ββYesβ Error
β No
Validate BibTeX Syntax
β
Append to Bibliography
β
Write to Temp File (references.bib.tmp)
β
Rename Temp β references.bib (atomic)
β
Release Lock
β
Return Success
β
Return via MCP
β
IDE AI β User
Concurrency:
- File lock prevents concurrent writes
- Timeout: 5 seconds
- Retry: 3 attempts with backoff
Technology Stack
Core Dependencies
| Package | Version | Purpose |
|---|---|---|
mcp |
1.0+ | Model Context Protocol SDK |
requests |
2.31+ | HTTP client for API calls |
sentence-transformers |
2.2+ | Embedding model for RAG |
faiss-cpu |
1.7+ | Vector similarity search |
bibtexparser |
1.4+ | BibTeX parsing |
aiofiles |
23.0+ | Async file operations |
Development Dependencies
| Package | Version | Purpose |
|---|---|---|
pytest |
8.0+ | Testing framework |
pytest-asyncio |
0.21+ | Async test support |
pytest-cov |
4.1+ | Coverage reporting |
ruff |
0.1+ | Linting and formatting |
Python Version
- Minimum: Python 3.11
- Recommended: Python 3.12
- Reason: Type hints, asyncio improvements, performance
External APIs
- Semantic Scholar API: v1
- No authentication required
- Rate limit: 100 req/5min
- Documentation: https://api.semanticscholar.org/
Integration Points
MCP Protocol
Communication: JSON-RPC over stdio
Request Format:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "search_papers",
"arguments": {
"query": "transformers",
"limit": 10
}
}
}
Response Format:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "{\"papers\": [...]}"
}
]
}
}
Error Format:
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32603,
"message": "Internal error",
"data": {
"details": "Network connection failed"
}
}
}
IDE Integration
Supported IDEs:
Cursor
- Config:
~/.cursor/mcp.json - Launch:
uvx --from polyhedra polyhedra
- Config:
VS Code + GitHub Copilot
- Config:
.vscode/settings.json - Extension: GitHub Copilot Chat
- MCP support: Via Copilot
- Config:
Windsurf
- Config:
~/.windsurf/mcp.json - Launch:
uvx --from polyhedra polyhedra
- Config:
VS Code + MCP Extension
- Config:
.vscode/settings.json - Extension: MCP Tools
- Launch: Direct MCP integration
- Config:
Configuration Schema:
{
"mcpServers": {
"polyhedra": {
"command": "uvx",
"args": ["--from", "polyhedra", "polyhedra"],
"env": {
"POLYHEDRA_PROJECT_ROOT": "/path/to/project"
}
}
}
}
File System
Project Structure Convention:
project-root/
βββ .polyhedra/ # Hidden tool directory
β βββ embeddings.index # FAISS index (binary)
β βββ metadata.json # Index metadata
β βββ cache/ # API response cache
β βββ search/ # Search results cache
β βββ papers/ # Paper details cache
β
βββ papers/ # Paper storage
β βββ *.pdf # Paper PDFs
β βββ *.json # Paper metadata
β
βββ notes/ # Research notes
β βββ *.md # Markdown notes
β
βββ literature-review/ # Review drafts
β βββ *.md # Markdown sections
β
βββ data/ # Research data
β βββ *.csv, *.json # Datasets
β
βββ references.bib # BibTeX bibliography
βββ README.md # Project overview
File Permissions:
- Read: All files in project
- Write: Files in project only (no traversal)
- Create: Directories and files in project
Performance Considerations
Caching Strategy
API Response Cache:
- Location:
.polyhedra/cache/ - Structure:
{endpoint}/{hash}.json - TTL: 1 hour (search), 24 hours (papers)
- Eviction: LRU, max 1000 entries
Embedding Cache:
- Location:
.polyhedra/embeddings.index - Format: FAISS IndexFlatIP + metadata JSON
- Update: Incremental (append new papers)
- Rebuild: Manual with
force_rebuild=true
Async Operations
Concurrent API Calls:
# Batch paper retrieval
papers = await asyncio.gather(*[
get_paper(paper_id) for paper_id in paper_ids
])
File I/O:
# Async file reading
async with aiofiles.open(path) as f:
content = await f.read()
Memory Management
Embedding Model:
- Loaded once, kept in memory
- ~150MB RAM
- Lazy loading on first RAG query
FAISS Index:
- Loaded on demand
- Memory: ~1.5MB per 1000 papers
- Unloaded after idle timeout (5 minutes)
Paper Metadata:
- Stored with index
- ~2KB per paper
- Total: ~2MB for 1000 papers
Rate Limiting
Semantic Scholar API:
class RateLimiter:
def __init__(self):
self.requests = deque()
self.max_requests = 100
self.window = 300 # 5 minutes
async def acquire(self):
now = time.time()
# Remove requests outside window
while self.requests and self.requests[0] < now - self.window:
self.requests.popleft()
# Wait if at limit
if len(self.requests) >= self.max_requests:
wait = self.requests[0] + self.window - now
await asyncio.sleep(wait)
self.requests.append(now)
Optimization Tips
- Batch Operations: Use
asyncio.gather()for concurrent requests - Cache Aggressively: API responses, embeddings, parsed BibTeX
- Lazy Load: Don't load embedding model until needed
- Index Incrementally: Append to index instead of rebuilding
- Limit Results: Default to 10 results, max 100
Security & Privacy
Data Privacy
No Data Transmission:
- All processing happens locally
- No telemetry or analytics
- No user tracking
API Calls:
- Only to Semantic Scholar (public API)
- No authentication tokens stored
- Query data not retained by API
File Access:
- Restricted to project directory
- No system file access
- Path traversal prevented
Input Validation
Path Validation:
def validate_path(path: str, project_root: Path) -> Path:
"""Ensure path is within project."""
full_path = (project_root / path).resolve()
# Check still within project
if not full_path.is_relative_to(project_root):
raise ValueError("Path outside project")
return full_path
BibTeX Validation:
def validate_bibtex(bibtex: str) -> bool:
"""Check BibTeX syntax."""
try:
parser.parse_string(bibtex)
return True
except Exception:
return False
Query Sanitization:
def sanitize_query(query: str) -> str:
"""Remove special characters from search query."""
# Remove control characters
# Limit length to 500 chars
# URL encode for API
Error Information Disclosure
Safe Errors:
# Good: Generic error
return {"error": "File not found"}
# Bad: Exposes system info
return {"error": f"Cannot read /home/user/.ssh/id_rsa"}
Error Messages:
- No system paths in errors
- No internal implementation details
- No stack traces to user (logged only)
Dependency Security
Pinned Versions:
- All dependencies pinned in
pyproject.toml - Regular security updates
- Automated vulnerability scanning (Dependabot)
Trusted Sources:
- PyPI packages only
- Verified publishers
- Popular, maintained projects
Deployment
Installation
Via pip:
pip install polyhedra
Via uv (recommended):
uv pip install polyhedra
uvx --from polyhedra polyhedra # Run directly
Configuration
Environment Variables:
POLYHEDRA_PROJECT_ROOT: Override project rootPOLYHEDRA_CACHE_DIR: Custom cache locationPOLYHEDRA_LOG_LEVEL: Logging level (DEBUG, INFO, WARNING, ERROR)
Example:
export POLYHEDRA_PROJECT_ROOT=/path/to/research
export POLYHEDRA_LOG_LEVEL=INFO
Logging
Log Locations:
- Console: stderr (captured by IDE)
- File:
.polyhedra/polyhedra.log(optional)
Log Format:
2024-01-15 10:30:45 INFO [server] Tool call: search_papers
2024-01-15 10:30:45 DEBUG [semantic_scholar] Query: transformers
2024-01-15 10:30:46 INFO [semantic_scholar] Found 25 papers
2024-01-15 10:30:46 INFO [server] Tool call completed: 1.2s
Testing Architecture
Test Structure
tests/
βββ test_server.py # MCP server integration tests
βββ test_services/
β βββ test_semantic_scholar.py
β βββ test_citation_manager.py
β βββ test_file_context.py
β βββ test_rag_retrieval.py
β βββ test_project_initializer.py
βββ test_integration_workflows.py # End-to-end workflows
βββ test_error_handling.py # Error scenarios
Test Coverage
- Unit Tests: 88-100% coverage per service
- Integration Tests: Full workflows tested
- Error Tests: All error paths covered
Test Strategy
- Unit Tests: Mock external dependencies (API, file system)
- Integration Tests: Real dependencies, test data
- E2E Tests: Full workflows with actual API calls (limited)
Future Extensibility
Planned Extensions
Additional APIs:
- arXiv direct integration
- Google Scholar (via SerpAPI)
- PubMed for biomedical papers
Enhanced RAG:
- Multiple embedding models
- Hybrid search (keyword + semantic)
- Re-ranking with cross-encoders
Collaboration:
- Shared indexes
- Team bibliographies
- Comment/annotation system
Export Formats:
- LaTeX integration
- Markdown citations
- Zotero/Mendeley import/export
Extension Points
Custom Services:
class CustomPaperService:
"""Implement your own paper source."""
async def search(self, query: str) -> list[dict]:
"""Custom search implementation."""
Custom Embeddings:
class CustomEmbeddingModel:
"""Use your own embedding model."""
def encode(self, texts: list[str]) -> np.ndarray:
"""Generate custom embeddings."""
Troubleshooting
For detailed troubleshooting, see:
References
- MCP Protocol: https://modelcontextprotocol.io
- Semantic Scholar API: https://api.semanticscholar.org
- Sentence Transformers: https://www.sbert.net
- FAISS: https://github.com/facebookresearch/faiss
Architecture documentation maintained by Polyhedra team. Last updated: January 2024.