PolyHedra / ide-integration /SETUP_GUIDE.md
yf176
Deploy Polyhedra to HF Spaces
891fe52
|
Raw History Blame Contribute Delete
14.2 kB

Polyhedra IDE Integration - Setup Guide

Complete instructions for setting up Polyhedra MCP Server with your IDE.

Table of Contents

  1. Prerequisites
  2. Cursor Setup
  3. VS Code + GitHub Copilot Setup
  4. Windsurf Setup
  5. VS Code + MCP Extension Setup
  6. Verification
  7. Troubleshooting
  8. 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

  1. Quit Cursor completely
  2. Reopen Cursor
  3. 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

  1. Open VS Code Extensions (Ctrl+Shift+X)
  2. Search for "GitHub Copilot"
  3. Install if not already installed
  4. 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

  1. Close VS Code
  2. Reopen your project
  3. 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

  1. Quit Windsurf completely
  2. Reopen Windsurf
  3. 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

  1. Open VS Code Extensions (Ctrl+Shift+X)
  2. Search for "MCP Tools"
  3. Install the extension
  4. 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

  1. Close VS Code
  2. Reopen your project

Step 4: Verify

  1. Open MCP panel (should appear in sidebar)
  2. Check "Polyhedra" server is listed
  3. 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:

  1. Verify config location:

    # Cursor/Windsurf: User home
    ls ~/.cursor/mcp.json
    ls ~/.windsurf/mcp.json
    
    # VS Code: Project root
    ls .vscode/settings.json
    
  2. Check uvx is in PATH:

    uvx --version
    

    If not found, add to PATH or use full path in config

  3. Restart IDE completely:

    • Quit application (don't just close window)
    • Reopen
  4. 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:

  1. Check file permissions:

    # Make config readable
    chmod 644 ~/.cursor/mcp.json
    
  2. Verify Polyhedra installation:

    pip show polyhedra
    
  3. Try with full path:

    {
      "command": "/path/to/uvx",
      "args": ["--from", "polyhedra", "polyhedra"]
    }
    

Issue: Server Won't Start

Symptoms: Error messages about server startup

Solutions:

  1. Test server manually:

    uvx --from polyhedra polyhedra
    

    If this fails, the issue is with Polyhedra installation

  2. Check Python version:

    python --version  # Should be 3.11+
    
  3. Reinstall Polyhedra:

    pip uninstall polyhedra
    pip install polyhedra
    
  4. Check 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:

  1. Check project structure:

    # Ensure you're in a project directory
    pwd
    
  2. Initialize project:

    Initialize a research project called "my-research"
    
  3. Check network for API calls:

    # Test Semantic Scholar API
    curl https://api.semanticscholar.org/graph/v1/paper/search?query=test
    
  4. Review error messages:

Issue: Slow Performance

Symptoms: Tools take long time to respond

Solutions:

  1. First RAG query downloads model (~400MB):

    • This is one-time
    • Subsequent queries are fast
  2. Check network speed:

    • Semantic Scholar API calls require internet
    • Use caching for repeated queries
  3. 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:

  1. Must index papers first:

    Search for papers on "topic"
    Index the papers from my search
    Query similar papers about "research question"
    
  2. Model download on first use:

    • Downloads sentence-transformers model
    • Takes 30-60 seconds first time
    • Check .polyhedra/ directory created
  3. Check disk space:

    • Model: ~400MB
    • Index: ~1-2MB per 1000 papers

Still Having Issues?

  1. Check documentation:

  2. Enable debug logging:

    {
      "env": {
        "POLYHEDRA_LOG_LEVEL": "DEBUG"
      }
    }
    
  3. Run tests:

    cd /path/to/polyhedra
    pytest tests/ -v
    
  4. File 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?

Happy researching! 🚀