Windjammer MCP Server

Version: 0.31.0
Status: Beta
Protocol: Model Context Protocol (MCP) 2025-06-18

Overview

The Windjammer Model Context Protocol (MCP) server enables AI assistants (Claude, ChatGPT, and others) to deeply understand, analyze, and generate Windjammer code. It provides a standardized interface for AI-powered development tools to interact with Windjammer codebases.

Key Features:

🤖 AI-Native: Built specifically for AI assistant integration
🎯 Rich Tools: Parse, analyze, generate, and refactor Windjammer code
🔧 Refactoring: Extract functions, inline variables, rename symbols
🔍 Deep Understanding: Leverages same Salsa database as LSP for consistency
⚡ Fast: Incremental computation with sub-millisecond cached queries
🛡️ Secure: Input validation, sandboxing, and resource limits
📚 Comprehensive: 9 tools covering code understanding, generation, refactoring, and errors
🌐 HTTP Transport: Streamable HTTP support with session management (MCP 2025-06-18)

Quick Start

Installation

cargo install windjammer-mcp

Or build from source:

cd crates/windjammer-mcp
cargo build --release

Running the Server

# Run with stdio transport (default)
windjammer-mcp

# Or explicitly
windjammer-mcp stdio

# Show server info
windjammer-mcp info

Integration with Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "windjammer": {
      "command": "/path/to/windjammer-mcp",
      "args": ["stdio"]
    }
  }
}

Integration with Other AI Assistants

The MCP server uses JSON-RPC 2.0 over stdio, making it compatible with any AI assistant that supports MCP:

# Python example
import subprocess
import json

# Start the server
server = subprocess.Popen(
    ["windjammer-mcp", "stdio"],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    text=True
)

# Send initialize request
request = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
        "protocolVersion": "2024-11-05",
        "capabilities": {},
        "clientInfo": {"name": "my-client", "version": "1.0.0"}
    }
}

server.stdin.write(json.dumps(request) + "\n")
server.stdin.flush()

# Read response
response = json.loads(server.stdout.readline())
print(response)

Available Tools

1. `parse_code`

Parse Windjammer code and return AST structure.

Input:

{
  "code": "fn main() { println!(\"Hello\") }",
  "include_diagnostics": true
}

Output:

{
  "success": true,
  "ast": { ... },
  "diagnostics": []
}

Use Cases:

Validate syntax before code generation
Extract structure from existing code
Detect parse errors

2. `analyze_types`

Perform type inference and analysis.

Input:

{
  "code": "let x = 42; let y = x + 1",
  "cursor_position": {"line": 1, "column": 9}
}

Output:

{
  "success": true,
  "inferred_types": {
    "x": "i64",
    "y": "i64"
  },
  "type_at_cursor": "i64"
}

Use Cases:

Understand inferred types in code
Verify type correctness
Get type information at specific positions

3. `generate_code`

Generate Windjammer code from natural language.

Input:

{
  "description": "Create a function that filters even numbers from a vector"
}

Output:

{
  "success": true,
  "code": "fn filter_evens(numbers: Vec<int>) -> Vec<int> {\n    numbers.iter().filter(|&n| n % 2 == 0).collect()\n}",
  "explanation": "This function uses Windjammer's iterator methods to filter even numbers."
}

Use Cases:

Bootstrap new functions from descriptions
Generate boilerplate code
Learn idiomatic Windjammer patterns

4. `explain_error`

Explain compiler errors in plain English.

Input:

{
  "error": "error[E0308]: mismatched types\\n  expected `i64`, found `&str`",
  "code_context": "let x: int = \"hello\""
}

Output:

{
  "success": true,
  "explanation": "You're trying to assign a string (\\\"hello\\\") to a variable declared as an integer (int). Windjammer requires types to match exactly.",
  "suggestion": "Change the type to `string` or change the value to a number like `42`.",
  "corrected_code": "let x: string = \"hello\"  // or: let x: int = 42"
}

Use Cases:

Help beginners understand errors
Provide quick fixes for common mistakes
Learn from error messages

5. `get_definition`

Find the definition of a symbol.

Input:

{
  "symbol": "add",
  "file": "src/main.wj",
  "position": {"line": 5, "column": 10}
}

Output:

{
  "success": true,
  "definition": {
    "file": "src/lib.wj",
    "range": {
      "start": {"line": 10, "column": 0},
      "end": {"line": 12, "column": 1}
    },
    "signature": "fn add(a: int, b: int) -> int"
  }
}

Use Cases:

Navigate to function/type definitions
Understand symbol origins
Explore codebase structure

6. `search_workspace`

Search for code patterns across the workspace.

Input:

{
  "query": "functions that return Result<T, Error>",
  "file_pattern": "src/**/*.wj"
}

Output:

{
  "success": true,
  "results": [
    {
      "file": "src/lib.wj",
      "matches": [
        {
          "line": 15,
          "signature": "fn read_file(path: string) -> Result<string, Error>",
          "context": "..."
        }
      ]
    }
  ]
}

Use Cases:

Find examples of specific patterns
Locate functions by signature
Understand how features are used

7. `extract_function`

Extract selected code into a new function (refactoring tool).

Input:

{
  "code": "fn main() {\n    let x = 1;\n    let y = 2;\n    println!(\"{}\", x + y);\n}",
  "range": {
    "start": {"line": 1, "column": 4},
    "end": {"line": 2, "column": 17}
  },
  "function_name": "calculate_sum",
  "make_public": false
}

Output:

{
  "success": true,
  "refactored_code": "fn calculate_sum(x: int, y: int) -> int {\n    x + y\n}\n\nfn main() {\n    let result = calculate_sum(1, 2);\n    println!(\"{}\", result);\n}",
  "function_signature": "fn calculate_sum(x: int, y: int) -> int",
  "captured_variables": ["x", "y"]
}

Use Cases:

Refactor complex functions into smaller, testable units
Extract reusable logic
Improve code organization

8. `inline_variable`

Inline a variable by replacing uses with its value (refactoring tool).

Input:

{
  "code": "fn main() {\n    let x = 42;\n    println!(\"{}\", x);\n}",
  "position": {"line": 1, "column": 8}
}

Output:

{
  "success": true,
  "refactored_code": "fn main() {\n    println!(\"{}\", 42);\n}",
  "occurrences_replaced": 1,
  "variable_name": "x"
}

Use Cases:

Simplify code by removing unnecessary variables
Reduce indirection
Prepare for further refactoring

9. `rename_symbol`

Rename a symbol with workspace-wide updates (refactoring tool).

Input:

{
  "code": "fn add(a: int, b: int) -> int { a + b }",
  "position": {"line": 0, "column": 7},
  "new_name": "sum"
}

Output:

{
  "success": true,
  "refactored_code": "fn sum(a: int, b: int) -> int { a + b }",
  "occurrences_renamed": 3,
  "old_name": "add",
  "files_affected": ["src/main.wj", "src/lib.wj"]
}

Use Cases:

Rename functions, variables, types safely
Improve naming consistency
Refactor APIs without breaking code

Architecture

Shared Database with LSP

The MCP server shares the same Salsa-powered incremental computation database with the Windjammer LSP. This ensures:

✅ Consistency: Same parsing and analysis results
✅ Performance: Cached computations benefit both LSP and MCP
✅ Accuracy: No divergence between IDE and AI tools

┌──────────────┐     ┌──────────────┐
│  LSP Client  │     │ MCP Client   │
│  (VSCode)    │     │  (Claude)    │
└──────┬───────┘     └──────┬───────┘
       │                    │
       ▼                    ▼
┌──────────────────────────────────┐
│   Shared Salsa Database          │
│   - Incremental parsing          │
│   - Type inference cache         │
│   - Symbol resolution            │
└──────────────────────────────────┘

Security

Input Validation: All inputs validated against JSON schemas
Resource Limits: Code size limited to 1MB, timeouts on operations
Sandboxing: Analysis runs in isolated database instances
No File System Access: By default (without explicit permission)

Examples

Example 1: Parse and Validate Code

import json

request = {
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
        "name": "parse_code",
        "arguments": {
            "code": "fn add(a: int, b: int) -> int { a + b }",
            "include_diagnostics": true
        }
    }
}

# Send to server...
# Response will include AST and any parse errors

Example 2: Generate Code from Description

request = {
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
        "name": "generate_code",
        "arguments": {
            "description": "HTTP server that responds 'Hello World' on GET /"
        }
    }
}

# Response includes generated Windjammer code

Example 3: Explain an Error

request = {
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
        "name": "explain_error",
        "arguments": {
            "error": "cannot find value `foo` in this scope",
            "code_context": "println!(foo)"
        }
    }
}

# Response includes plain English explanation and suggestions

Development

Building

cargo build --release

Testing

cargo test

Benchmarking

cargo bench

Protocol Reference

Initialization

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "client-name",
      "version": "1.0.0"
    }
  }
}

Tool List

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

Tool Call

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "tool_name",
    "arguments": { ... }
  }
}

Shutdown

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "shutdown"
}

Roadmap

v0.31.1 (Current)

Core MCP server with stdio transport
Tools: parse, analyze, generate, explain, search, get_definition
Refactoring tools: extract_function, inline_variable, rename_symbol
Streamable HTTP transport (MCP 2025-06-18 spec)
Session management with Mcp-Session-Id header
Integration with LSP database
Performance benchmarks
Unit tests

v0.32.0 (Future)

OAuth 2.0 authentication
MCP client library for custom AI integrations
Workspace-wide refactoring
Advanced type analysis tools

v0.33.0 (Future)

Custom tool plugins
Multi-language support
Production deployment guides
AI agent integration examples

Contributing

We welcome contributions! See ../../CONTRIBUTING.md for guidelines.

License

Windjammer MCP is dual-licensed under either:

MIT License (../../LICENSE-MIT)
Apache License, Version 2.0 (../../LICENSE-APACHE)

at your option.

windjammer-mcp 0.45.0

Windjammer MCP Server

Overview

Quick Start

Installation

Running the Server

Integration with Claude Desktop

Integration with Other AI Assistants

Available Tools

1. parse_code

2. analyze_types

3. generate_code

4. explain_error

5. get_definition

6. search_workspace

7. extract_function

8. inline_variable

9. rename_symbol

Architecture

Shared Database with LSP

Security

Examples

Example 1: Parse and Validate Code

Example 2: Generate Code from Description

Example 3: Explain an Error

Development

Building

Testing

Benchmarking

Protocol Reference

Initialization

Tool List

Tool Call

Shutdown

Roadmap

v0.31.1 (Current)

v0.32.0 (Future)

v0.33.0 (Future)

Contributing

License

Links

1. `parse_code`

2. `analyze_types`

3. `generate_code`

4. `explain_error`

5. `get_definition`

6. `search_workspace`

7. `extract_function`

8. `inline_variable`

9. `rename_symbol`