CodeWeave MCP

CodeWeave is a project-scoped Model Context Protocol (MCP) server that lets an AI coding client inspect, edit, and validate one configured Git repository. It is designed for local Windows development and remote use from ChatGPT through a secure tunnel or a temporary HTTPS development tunnel.

CodeWeave exposes six focused tools:

Tool	Purpose
code_context	Find task context, definitions, references, exact text, changes, repository maps, and file outlines.
code_fetch	Read exact line ranges, complete files, continuation handles, and task logs.
prepare_patch	Validate and preview broad or multi-file changes without modifying the repository.
apply_prepared_patch	Apply a previously prepared patch plan atomically.
apply_patch	Apply focused exact edits, unified diffs, or complete-file operations.
run_task	Run only the tests, linters, formatters, type checks, or builds explicitly allow-listed in config.toml.

Safety model

CodeWeave is bound to one project root. File access is resolved beneath that root, symlink escapes are rejected, patch writes are guarded by Git snapshots and optional SHA-256 checks, and task execution is restricted to configured argument arrays rather than arbitrary shell commands.

The default configuration uses a local bearer token. Secrets and machine-specific files are excluded from Git:

• .mcp-token
• config.toml
• .venv/
• SQLite indexes and logs
• generated tunnel policy files

The public /health response intentionally omits local filesystem paths.

Requirements

• Windows 10 or newer with PowerShell
• Python 3.11, 3.12, or 3.13
• Git
• A Git repository for CodeWeave to operate on
• Optional: OpenAI Secure MCP Tunnel, ngrok, or another HTTPS deployment path

Install

git clone <repository-url>
Set-Location codeweave
.\scripts\install.ps1

The installer creates .venv, installs the package in editable mode, copies config.example.toml to config.toml, and generates a private .mcp-token.

Edit config.toml and set the repository root:

[project]
root = 'C:\path\to\your\project'

Then validate and index the repository:

.\scripts\doctor.ps1
.\scripts\index.ps1

Run locally

Start the server in one PowerShell window:

.\scripts\start-server.ps1

Verify the MCP handshake in another window:

.\scripts\test-local.ps1

The local endpoints are:

• MCP: http://127.0.0.1:8812/mcp
• Health: http://127.0.0.1:8812/health

Connect to ChatGPT

ChatGPT needs an HTTPS-accessible remote MCP endpoint; it does not connect directly to a localhost URL. The preferred private-network option is OpenAI Secure MCP Tunnel. For short-lived development, the included ngrok script creates a temporary public endpoint and injects the local bearer token upstream.

See docs/chatgpt-setup.md for the complete end-to-end setup, including:

• OpenAI Secure MCP Tunnel
• ngrok development setup
• Cloudflare Tunnel and hosted deployment considerations
• ChatGPT developer-mode configuration
• verification prompts and troubleshooting

Availability of custom MCP apps, developer mode, and write actions depends on the current ChatGPT plan and workspace policy. Use the current OpenAI documentation linked in the setup guide as the source of truth.

Connect to Other AI Clients (Claude, Perplexity)

CodeWeave can also connect to other Model Context Protocol (MCP) clients such as Claude Desktop and Perplexity.

See docs/claude-perplexity-setup.md for the detailed setup instructions, including:

• Claude Desktop stdio-to-SSE bridge setup using mcp-remote
• Perplexity macOS/web custom connector configuration

Configuration

Start from config.example.toml.

Authentication modes

[server]
host = "127.0.0.1"
port = 8812
auth_mode = "bearer" # bearer | none
token_env = "CODEWEAVE_MCP_TOKEN"

• bearer is the default and is required by the included ngrok workflow.
• none is accepted only when the server binds to a loopback host. It is intended for a private transport such as OpenAI Secure MCP Tunnel, where the MCP listener remains inaccessible from the network.

Allow-listed tasks

run_task can execute only configured tasks. Commands are arrays and are never passed through a shell.

[tasks.pytest]
command = [
  "C:/path/to/your/project/.venv/Scripts/python.exe",
  "-m",
  "pytest",
  "-q",
  "{target}"
]
cwd = "."
timeout_seconds = 900

The optional {target} placeholder is replaced with a validated project-relative path. Absolute paths, parent traversal, missing targets, option-like targets, and symlink escapes are rejected.

Typical tool workflow

For investigation and a focused edit:

1. Call code_context with the coding task.
2. Use a returned project-relative path with code_fetch when exact content is needed.
3. Use apply_patch with exact replacements and the file hash returned by code_fetch.
4. Run an allow-listed validation task with run_task.

For a broad change, use prepare_patch, review its preview, and then call apply_prepared_patch with the returned plan ID.

Development

.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m ruff check .

The continuous-integration workflow runs tests and Ruff on supported Python versions.

Documentation

• ChatGPT connection guide
• Claude & Perplexity connection guide
• Architecture
• Security policy
• Contributing
• Changelog

Project status

CodeWeave is an independent open-source project and is not an OpenAI product. Review the server, its configured project root, and every enabled write/task capability before connecting it to an AI client.