iflow-mcp_possible055-relace-mcp 0.2.5.dev4

Unofficial Relace MCP Server - Fast code merging via Relace API

English | 简体中文

Unofficial Relace MCP Server

Unofficial — Personal project, not affiliated with Relace.

Built with AI — Developed entirely with AI assistance (Antigravity, Codex, Cursor, Github Copilot, Windsurf).

MCP server providing AI-powered code editing and intelligent codebase exploration tools.

Without	With agentic_search + fast_apply
Manual grep, misses related files	Ask naturally, get precise locations
Edits break imports elsewhere	Traces imports and call chains
Full rewrites burn tokens	Describe changes, no line numbers
Line number errors corrupt code	10,000+ tokens/sec merging

Features

• Fast Apply — Apply code edits at 10,000+ tokens/sec via Relace API
• Agentic Search — Agentic codebase exploration with natural language queries
• Agentic Retrieval — Two-stage semantic + agentic code retrieval (requires MCP_SEARCH_RETRIEVAL=1)
• Cloud Search — Semantic code search over cloud-synced repositories

Quick Start

Prerequisites: uv, git, ripgrep (recommended)

Using Relace (default) or RELACE_CLOUD_TOOLS=1: get your API key from Relace Dashboard, then add to your MCP client:

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "relace": {
      "command": "uv",
      "args": ["tool", "run", "relace-mcp"],
      "env": {
        "RELACE_API_KEY": "rlc-your-api-key",
        "MCP_BASE_DIR": "/absolute/path/to/your/project"
      }
    }
  }
}

Claude Code

claude mcp add relace \
  --env RELACE_API_KEY=rlc-your-api-key \
  --env MCP_BASE_DIR=/absolute/path/to/your/project \
  -- uv tool run relace-mcp

Windsurf

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "relace": {
      "command": "uv",
      "args": ["tool", "run", "relace-mcp"],
      "env": {
        "RELACE_API_KEY": "rlc-your-api-key",
        "MCP_BASE_DIR": "/absolute/path/to/your/project"
      }
    }
  }
}

VS Code

.vscode/mcp.json

{
  "mcp": {
    "servers": {
      "relace": {
        "type": "stdio",
        "command": "uv",
        "args": ["tool", "run", "relace-mcp"],
        "env": {
          "RELACE_API_KEY": "rlc-your-api-key",
          "MCP_BASE_DIR": "${workspaceFolder}"
        }
      }
    }
  }
}

Codex CLI

~/.codex/config.toml

[mcp_servers.relace]
command = "uv"
args = ["tool", "run", "relace-mcp"]

[mcp_servers.relace.env]
RELACE_API_KEY = "rlc-your-api-key"
MCP_BASE_DIR = "/absolute/path/to/your/project"

Configuration

Variable	Required	Description
RELACE_API_KEY	✅*	API key from Relace Dashboard
RELACE_CLOUD_TOOLS	❌	Set to 1 to enable cloud tools
MCP_SEARCH_RETRIEVAL	❌	Set to 1 to enable agentic_retrieval tool
SEARCH_LSP_TOOLS	❌	LSP tools: 1 (all on), auto (detect installed servers), 0 (off, default)
MCP_BASE_DIR	❌	Project root (auto-detected via MCP Roots → Git → CWD)
MCP_LOGGING	❌	File logging: off (default), safe, full
MCP_DOTENV_PATH	❌	Path to .env file for centralized config

* Optional if both: (1) APPLY_PROVIDER and SEARCH_PROVIDER are non-Relace providers, and (2) RELACE_CLOUD_TOOLS=false.

For .env usage, encoding settings, custom LLM providers, and more, see docs/advanced.md.

Tools

Core tools (fast_apply, agentic_search) are always available. Cloud tools require RELACE_CLOUD_TOOLS=1. agentic_retrieval requires MCP_SEARCH_RETRIEVAL=1.

For detailed parameters, see docs/tools.md.

Language Support

LSP tools use external language servers installed on your system.

Language	Language Server	Install Command
Python	basedpyright	(bundled)
TypeScript/JS	typescript-language-server	npm i -g typescript-language-server typescript
Go	gopls	go install golang.org/x/tools/gopls@latest
Rust	rust-analyzer	rustup component add rust-analyzer

Dashboard

Real-time terminal UI for monitoring operations.

pip install relace-mcp[tools]
relogs

For detailed usage, see docs/dashboard.md.

Benchmark

Evaluate agentic_search performance using the Loc-Bench code localization dataset.

# Install benchmark dependencies
pip install relace-mcp[benchmark]

# Build dataset from Hugging Face
uv run python -m benchmark.cli.build_locbench --output artifacts/data/raw/locbench_v1.jsonl

# Run evaluation
uv run python -m benchmark.cli.run --dataset artifacts/data/raw/locbench_v1.jsonl --limit 20

For grid search, analysis tools, and metrics interpretation, see docs/benchmark.md.

Platform Support

Platform	Status	Notes
Linux	✅ Fully supported	Primary development platform
macOS	✅ Fully supported	All features available
Windows	⚠️ Partial	bash tool unavailable; use WSL for full functionality

Troubleshooting

Error	Solution
RELACE_API_KEY is not set	Set the key in your environment or MCP config
NEEDS_MORE_CONTEXT	Include 1–3 anchor lines before/after target block
FILE_TOO_LARGE	File exceeds 10MB; split file
ENCODING_ERROR	Set RELACE_DEFAULT_ENCODING explicitly
AUTH_ERROR	Verify API key is valid and not expired
RATE_LIMIT	Too many requests; wait and retry
CONNECTION_TIMEOUT	Check network connection or increase timeout setting
INVALID_PATH	File path doesn't exist or no permission; verify path and access rights
SYNTAX_ERROR	Invalid edit_snippet format; ensure placeholder syntax is correct
NO_MATCH_FOUND	No search results; try broader query or run cloud_sync first
CLOUD_NOT_SYNCED	Repository not synced to Relace Cloud; run cloud_sync first
CONFLICT_DETECTED	Edit conflict; file was modified, re-read before editing

Development

git clone https://github.com/possible055/relace-mcp.git
cd relace-mcp
uv sync --extra dev
uv run pytest

License

MIT