Download ide-integration/SETUP_GUIDE.md from polyHedra/PolyHedra: direct link, hf CLI and curl.
- Browser
- Download file 14.2 kB
-
https://huggingface.co/spaces/polyHedra/PolyHedra/resolve/main/ide-integration/SETUP_GUIDE.md
- Command line
-
hf download hf://spaces/polyHedra/PolyHedra/ide-integration/SETUP_GUIDE.md
-
curl -L -o SETUP_GUIDE.md https://huggingface.co/spaces/polyHedra/PolyHedra/resolve/main/ide-integration/SETUP_GUIDE.md
Polyhedra IDE Integration - Setup Guide
Complete instructions for setting up Polyhedra MCP Server with your IDE.
Table of Contents
- Prerequisites
- Cursor Setup
- VS Code + GitHub Copilot Setup
- Windsurf Setup
- VS Code + MCP Extension Setup
- Verification
- Troubleshooting
- Advanced Configuration
Prerequisites
Before setting up any IDE, ensure you have:
1. Install Polyhedra
# Using pip
pip install polyhedra
# Or using uv (recommended)
uv pip install polyhedra
Verify installation:
python -c "import polyhedra; print('Polyhedra installed successfully')"
2. Install uvx (Recommended)
# Install uv (includes uvx)
pip install uv
# Verify uvx is available
uvx --version
Why uvx? It automatically manages isolated environments for packages, making it ideal for MCP servers.
3. Test Server Manually
# Test the server starts correctly
uvx --from polyhedra polyhedra
You should see:
Polyhedra MCP server running on stdio
Press Ctrl+C to stop. If this works, you're ready to configure your IDE.
Cursor Setup
Time: 3 minutes
Step 1: Copy Configuration
# Windows (PowerShell)
Copy-Item ide-integration\cursor\mcp.json $HOME\.cursor\mcp.json
# macOS/Linux
cp ide-integration/cursor/mcp.json ~/.cursor/mcp.json
If ~/.cursor/ doesn't exist:
# Windows
New-Item -ItemType Directory -Path $HOME\.cursor
# macOS/Linux
mkdir -p ~/.cursor
Step 2: Copy AI Instructions (Optional)
Copy .cursorrules to your project root:
# Windows
Copy-Item ide-integration\cursor\.cursorrules .cursorrules
# macOS/Linux
cp ide-integration/cursor/.cursorrules .cursorrules
This tells Cursor's AI how to use Polyhedra tools effectively.
Step 3: Restart Cursor
- Quit Cursor completely
- Reopen Cursor
- Open any project
Step 4: Verify
In Cursor's chat (Cmd/Ctrl+L), type:
What Polyhedra tools are available?
Expected response should list 10 tools: search_papers, get_paper, etc.
Cursor Configuration Details
File Location: ~/.cursor/mcp.json
Configuration:
{
"mcpServers": {
"polyhedra": {
"command": "uvx",
"args": ["--from", "polyhedra", "polyhedra"],
"env": {},
"disabled": false
}
}
}
Custom Project Root (optional):
{
"mcpServers": {
"polyhedra": {
"command": "uvx",
"args": ["--from", "polyhedra", "polyhedra"],
"env": {
"POLYHEDRA_PROJECT_ROOT": "/path/to/my/research"
},
"disabled": false
}
}
}
VS Code + GitHub Copilot Setup
Time: 4 minutes
Requirements: GitHub Copilot subscription
Step 1: Ensure GitHub Copilot is Installed
- Open VS Code Extensions (Ctrl+Shift+X)
- Search for "GitHub Copilot"
- Install if not already installed
- Sign in with your GitHub account
Step 2: Copy Configuration
Create .vscode directory in your project if it doesn't exist:
# Windows
New-Item -ItemType Directory -Path .vscode -Force
# macOS/Linux
mkdir -p .vscode
Copy settings:
# Windows
Copy-Item ide-integration\vscode-copilot\settings.json .vscode\settings.json
# macOS/Linux
cp ide-integration/vscode-copilot/settings.json .vscode/settings.json
Step 3: Copy Copilot Instructions
Create .github directory:
# Windows
New-Item -ItemType Directory -Path .github -Force
# macOS/Linux
mkdir -p .github
Copy instructions:
# Windows
Copy-Item ide-integration\vscode-copilot\copilot-instructions.md .github\copilot-instructions.md
# macOS/Linux
cp ide-integration/vscode-copilot/copilot-instructions.md .github/copilot-instructions.md
Step 4: Restart VS Code
- Close VS Code
- Reopen your project
- Copilot should auto-detect the configuration
Step 5: Verify
Open Copilot Chat (Ctrl+Shift+I), type:
@workspace Search for papers on transformer models
Copilot should invoke the Polyhedra search_papers tool.
VS Code + Copilot Configuration Details
File Locations:
.vscode/settings.json- VS Code settings.github/copilot-instructions.md- Copilot AI instructions
Settings:
{
"github.copilot.chat.codeGeneration.instructions": [
{
"text": "When working on research projects, use the Polyhedra MCP tools..."
}
],
"mcp.servers": {
"polyhedra": {
"command": "uvx",
"args": ["--from", "polyhedra", "polyhedra"],
"env": {}
}
}
}
Windsurf Setup
Time: 3 minutes
Step 1: Copy Configuration
# Windows (PowerShell)
Copy-Item ide-integration\windsurf\mcp.json $HOME\.windsurf\mcp.json
# macOS/Linux
cp ide-integration/windsurf/mcp.json ~/.windsurf/mcp.json
If ~/.windsurf/ doesn't exist:
# Windows
New-Item -ItemType Directory -Path $HOME\.windsurf
# macOS/Linux
mkdir -p ~/.windsurf
Step 2: Restart Windsurf
- Quit Windsurf completely
- Reopen Windsurf
- Open any project
Step 3: Verify
In Windsurf's AI chat, type:
List available MCP tools
Should show 10 Polyhedra tools.
Windsurf Configuration Details
File Location: ~/.windsurf/mcp.json
Configuration:
{
"mcpServers": {
"polyhedra": {
"command": "uvx",
"args": ["--from", "polyhedra", "polyhedra"],
"env": {},
"disabled": false
}
}
}
VS Code + MCP Extension Setup
Time: 5 minutes
Requirements: MCP Tools extension
Step 1: Install MCP Extension
- Open VS Code Extensions (Ctrl+Shift+X)
- Search for "MCP Tools"
- Install the extension
- Reload VS Code if prompted
Step 2: Copy Configuration
Create .vscode directory:
# Windows
New-Item -ItemType Directory -Path .vscode -Force
# macOS/Linux
mkdir -p .vscode
Copy settings:
# Windows
Copy-Item ide-integration\vscode-mcp\settings.json .vscode\settings.json
# macOS/Linux
cp ide-integration/vscode-mcp/settings.json .vscode/settings.json
Step 3: Restart VS Code
- Close VS Code
- Reopen your project
Step 4: Verify
- Open MCP panel (should appear in sidebar)
- Check "Polyhedra" server is listed
- Expand to see 10 available tools
VS Code + MCP Configuration Details
File Location: .vscode/settings.json
Configuration:
{
"mcp.servers": {
"polyhedra": {
"command": "uvx",
"args": ["--from", "polyhedra", "polyhedra"],
"env": {}
}
}
}
Verification
After setup, verify your installation with these tests:
Test 1: Tool Discovery
Ask your IDE's AI:
What Polyhedra tools are available?
Expected: List of 10 tools (search_papers, get_paper, query_similar_papers, index_papers, add_citation, get_citations, save_file, get_context, init_project, get_project_status)
Test 2: Paper Search
Search for papers on "neural networks" from 2024
Expected: JSON response with paper results from Semantic Scholar
Test 3: Project Initialization
Initialize a research project called "test-project"
Expected: Creates directory structure with papers/, notes/, literature-review/, etc.
Test 4: File Operations
Save "Hello from Polyhedra" to notes/test.md
Expected: Creates notes/test.md with content
Test 5: Project Status
Show my project status
Expected: Overview of project structure and files
All Tests Passing?
✅ You're ready to use Polyhedra!
See docs/WORKFLOWS.md for research workflow examples.
Troubleshooting
Issue: Tools Not Appearing
Symptoms: IDE doesn't show Polyhedra tools
Solutions:
Verify config location:
# Cursor/Windsurf: User home ls ~/.cursor/mcp.json ls ~/.windsurf/mcp.json # VS Code: Project root ls .vscode/settings.jsonCheck uvx is in PATH:
uvx --versionIf not found, add to PATH or use full path in config
Restart IDE completely:
- Quit application (don't just close window)
- Reopen
Check logs:
- Cursor: Output panel → MCP
- VS Code: Output panel → MCP Server
- Windsurf: Developer tools → Console
Issue: Permission Errors
Symptoms: "Permission denied" or "Access denied"
Solutions:
Check file permissions:
# Make config readable chmod 644 ~/.cursor/mcp.jsonVerify Polyhedra installation:
pip show polyhedraTry with full path:
{ "command": "/path/to/uvx", "args": ["--from", "polyhedra", "polyhedra"] }
Issue: Server Won't Start
Symptoms: Error messages about server startup
Solutions:
Test server manually:
uvx --from polyhedra polyhedraIf this fails, the issue is with Polyhedra installation
Check Python version:
python --version # Should be 3.11+Reinstall Polyhedra:
pip uninstall polyhedra pip install polyhedraCheck for conflicts:
# Ensure no other MCP servers conflict # Check IDE settings for duplicate server names
Issue: Tools Execute But Fail
Symptoms: Tools are visible but return errors
Solutions:
Check project structure:
# Ensure you're in a project directory pwdInitialize project:
Initialize a research project called "my-research"Check network for API calls:
# Test Semantic Scholar API curl https://api.semanticscholar.org/graph/v1/paper/search?query=testReview error messages:
- Look for specific error types
- Check docs/ERROR_HANDLING.md
Issue: Slow Performance
Symptoms: Tools take long time to respond
Solutions:
First RAG query downloads model (~400MB):
- This is one-time
- Subsequent queries are fast
Check network speed:
- Semantic Scholar API calls require internet
- Use caching for repeated queries
Optimize queries:
- Limit search results (default: 10)
- Use specific year ranges
- Index papers once, query many times
Issue: RAG/Semantic Search Not Working
Symptoms: query_similar_papers fails or returns no results
Solutions:
Must index papers first:
Search for papers on "topic" Index the papers from my search Query similar papers about "research question"Model download on first use:
- Downloads sentence-transformers model
- Takes 30-60 seconds first time
- Check
.polyhedra/directory created
Check disk space:
- Model: ~400MB
- Index: ~1-2MB per 1000 papers
Still Having Issues?
Check documentation:
Enable debug logging:
{ "env": { "POLYHEDRA_LOG_LEVEL": "DEBUG" } }Run tests:
cd /path/to/polyhedra pytest tests/ -vFile an issue:
- GitHub: Include error messages, config, and steps to reproduce
Advanced Configuration
Custom Project Root
Override default project directory:
{
"mcpServers": {
"polyhedra": {
"command": "uvx",
"args": ["--from", "polyhedra", "polyhedra"],
"env": {
"POLYHEDRA_PROJECT_ROOT": "/home/user/my-research"
}
}
}
}
All file operations will be relative to this path.
Custom Cache Location
Change where embeddings and cache are stored:
{
"env": {
"POLYHEDRA_CACHE_DIR": "/path/to/custom/cache"
}
}
Useful for:
- Network drives
- Synced folders (Dropbox, etc.)
- Limited disk space on default location
Debug Logging
Enable detailed logs for troubleshooting:
{
"env": {
"POLYHEDRA_LOG_LEVEL": "DEBUG"
}
}
Logs will appear in IDE's output panel.
Multiple Polyhedra Instances
Run multiple instances for different projects:
{
"mcpServers": {
"polyhedra-project-a": {
"command": "uvx",
"args": ["--from", "polyhedra", "polyhedra"],
"env": {
"POLYHEDRA_PROJECT_ROOT": "/path/to/project-a"
}
},
"polyhedra-project-b": {
"command": "uvx",
"args": ["--from", "polyhedra", "polyhedra"],
"env": {
"POLYHEDRA_PROJECT_ROOT": "/path/to/project-b"
}
}
}
}
Tools will be prefixed with instance name.
Development Version
Use local development version instead of PyPI:
{
"command": "python",
"args": ["-m", "polyhedra.server"],
"env": {
"PYTHONPATH": "/path/to/polyhedra/src"
}
}
Restart IDE after code changes.
Quick Reference
Command Locations
| IDE | Config File | Location Type |
|---|---|---|
| Cursor | ~/.cursor/mcp.json |
User home |
| Windsurf | ~/.windsurf/mcp.json |
User home |
| VS Code | .vscode/settings.json |
Project root |
Installation Commands
# Install Polyhedra
pip install polyhedra
# Install uv (includes uvx)
pip install uv
# Test server
uvx --from polyhedra polyhedra
# Verify installation
python -c "import polyhedra; print('OK')"
Quick Test Commands
# After setup, test with:
What Polyhedra tools are available?
Search for papers on "neural networks" from 2024
Initialize a research project called "test"
Show my project status
Need More Help?
- API Documentation: docs/API.md
- Workflow Examples: docs/WORKFLOWS.md
- Error Handling: docs/ERROR_HANDLING.md
- Architecture: docs/ARCHITECTURE.md
- Main README: README.md
Happy researching! 🚀