Content
# 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
```powershell
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:
```toml
[project]
root = 'C:\path\to\your\project'
```
Then validate and index the repository:
```powershell
.\scripts\doctor.ps1
.\scripts\index.ps1
```
## Run locally
Start the server in one PowerShell window:
```powershell
.\scripts\start-server.ps1
```
Verify the MCP handshake in another window:
```powershell
.\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](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](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`](config.example.toml).
### Authentication modes
```toml
[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.
```toml
[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
```powershell
.\.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](docs/chatgpt-setup.md)
- [Claude & Perplexity connection guide](docs/claude-perplexity-setup.md)
- [Architecture](docs/architecture.md)
- [Security policy](SECURITY.md)
- [Contributing](CONTRIBUTING.md)
- [Changelog](CHANGELOG.md)
## 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.
Connection Info
You Might Also Like
No recommendations available