Skip to content

Development Setup

This guide walks through setting up a local development environment for contributing to Code Scalpel.

Prerequisites

  • Python 3.10+ (3.13 also supported)
  • Git
  • Virtual environment (venv or conda)

Clone the Repository

# Clone via HTTPS
git clone https://github.com/your-org/code-scalpel.git

# Or via SSH
git clone git@github.com:your-org/code-scalpel.git

cd code-scalpel

Create Virtual Environment

python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate   # Windows

conda create -n code-scalpel python=3.10
conda activate code-scalpel

Install Dependencies

# Install in development mode with all extras
pip install -e ".[dev]"

# This installs:
# - Core dependencies
# - Test dependencies (pytest, pytest-cov, etc.)
# - Lint tools (ruff, black, pyright)
# - Documentation tools

Verify Installation

# Run tests
pytest tests/ -v

# Check linting
ruff check src/ tests/

# Check formatting
black --check src/ tests/

# Type checking
pyright src/

IDE Setup

VS Code

Install recommended extensions:

// .vscode/extensions.json
{
  "recommendations": [
    "ms-python.python",
    "ms-python.vscode-pylance",
    "charliermarsh.ruff",
    "ms-python.black-formatter"
  ]
}

Settings for the project:

// .vscode/settings.json
{
  "python.defaultInterpreterPath": "./venv/bin/python",
  "editor.formatOnSave": true,
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter"
  },
  "python.analysis.typeCheckingMode": "basic"
}

PyCharm

  1. Open project folder
  2. Configure interpreter: venv/bin/python
  3. Enable Black formatter
  4. Enable Ruff linter

Project Structure

code-scalpel/
├── src/code_scalpel/       # Main source code
│   ├── mcp/                # MCP server and tools
│   │   ├── server.py       # Main MCP server
│   │   └── tools/          # Tool implementations
│   ├── core/               # Core analysis engine
│   ├── parsers/            # Language parsers
│   └── licensing/          # Tier management
├── tests/                  # Test suite
│   ├── tools/              # Tool tests
│   └── core/               # Core engine tests
├── docs/                   # Documentation
├── .code-scalpel/          # Configuration files
└── website/                # Website docs (this site)

Running the MCP Server

# Run locally
uvx codescalpel mcp

# Or via uvx (for testing MCP integration)
uvx codescalpel

Common Tasks

Run Specific Tests

# Single test file
pytest tests/tools/test_analyze.py

# Single test function
pytest tests/tools/test_analyze.py::test_analyze_python

# With pattern
pytest -k "analyze" tests/

Run with Coverage

pytest --cov=src/code_scalpel --cov-report=html tests/
# Open htmlcov/index.html to view report

Auto-Format Code

# Format all files
black src/ tests/

# Check only (no changes)
black --check src/ tests/

Troubleshooting

"Module not found" errors

Make sure you installed in development mode:

pip install -e ".[dev]"

Test failures due to tier

Some tests require Pro/Enterprise license files. Community tests run by default:

# Run only community tier tests
pytest -m "not pro and not enterprise" tests/

Import errors in IDE

Ensure your IDE is using the correct Python interpreter from the virtual environment.