# devspace-memory-bridge

A non-invasive MCP bridge that makes DevSpace search tools memory-aware.

`devspace-memory-bridge` sits in front of a normal DevSpace server and augments selected search/list tool responses with structural context from `codebase-memory-mcp`. The model still calls ordinary DevSpace-style tools such as `grep`, `glob`, and `ls`; the bridge enriches the response locally before it reaches the client.

```text
ChatGPT / MCP client
  -> devspace-memory-bridge
    -> upstream DevSpace
    -> codebase-memory-mcp CLI
```

## Why this exists

Some coding agents support hooks that can automatically inject codebase context when the agent searches files. Other MCP clients do not expose that kind of hook surface. This project explores a practical middle ground: intercept only the DevSpace search/list tools at the local boundary, call the real DevSpace tool, call `codebase-memory-mcp`, and return one combined tool result.

The goal is not to replace DevSpace or `codebase-memory-mcp`. The goal is to connect them without patching either upstream project.

## What it does

Implemented:

- Records `workspaceId -> root` from `open_workspace` results.
- Passes unknown and non-memory tools through unchanged.
- Augments `grep` / `grep_files` with `search_graph` context.
- Augments `glob` / `find_files` with `search_graph` context.
- Augments `ls` / `list_directory` with lightweight architecture context.
- Transforms JSON-RPC JSON responses.
- Transforms request-scoped MCP SSE responses from `POST /mcp`.
- Streams standalone `GET /mcp` SSE responses through unchanged.
- Fails open by default: if memory lookup fails, the original DevSpace result is returned.

Intentionally not implemented yet:

- `bash` command interception.
- `read`, `edit`, or `write` augmentation.
- A full DevSpace replacement.
- A general-purpose MCP middleware framework.

Not yet validated end-to-end:

- ChatGPT Apps OAuth/resource-server registration through the bridge.
- Long-lived production deployment behind a public HTTPS tunnel.

## Tool behavior

The bridge treats upstream DevSpace as the source of truth. A normal request flow is:

```text
1. Client calls grep(pattern="TurnController")
2. Bridge forwards the call to upstream DevSpace
3. DevSpace returns normal grep results
4. Bridge extracts symbol hints from the search pattern
5. Bridge calls codebase-memory-mcp search_graph
6. Bridge appends "Codebase Memory Context" to the tool result
7. Client receives what still looks like a grep result
```

If step 5 fails, step 6 is skipped and the original DevSpace response is returned.

## Requirements

- Node.js 22 or newer.
- A running DevSpace server.
- `codebase-memory-mcp` available as a CLI command, or a compatible wrapper command.
- Upstream DevSpace should run with dedicated search/list tools enabled:

```bash
DEVSPACE_TOOL_MODE=full node /path/to/devspace/dist/cli.js serve
```

## Quick start

Start upstream DevSpace:

```bash
DEVSPACE_TOOL_MODE=full node /home/heppo/DEV/devspace/dist/cli.js serve
```

Start the bridge:

```bash
cd /home/heppo/DEV/devspace-memory-bridge

DEVSPACE_UPSTREAM_URL=http://127.0.0.1:7676 \
DEVSPACE_MEMORY_BRIDGE_PORT=7777 \
DEVSPACE_MEMORY_COMMAND=codebase-memory-mcp \
node src/index.js
```

Point the MCP client at the bridge instead of upstream DevSpace.

## Configuration

| Variable | Default | Purpose |
| --- | --- | --- |
| `DEVSPACE_UPSTREAM_URL` | `http://127.0.0.1:7676` | Real DevSpace server URL. |
| `DEVSPACE_MEMORY_BRIDGE_HOST` | `127.0.0.1` | Bridge bind host. |
| `DEVSPACE_MEMORY_BRIDGE_PORT` | `7777` | Bridge bind port. |
| `DEVSPACE_MEMORY_COMMAND` | `codebase-memory-mcp` | CLI command used for memory lookups. |
| `DEVSPACE_MEMORY_AUGMENT_TOOLS` | `grep,glob,ls` | Tools to augment. |
| `DEVSPACE_MEMORY_FAIL_OPEN` | `true` | Return normal DevSpace results if memory lookup fails. |
| `DEVSPACE_MEMORY_MAX_CONTEXT_CHARS` | `6000` | Max appended memory context length. |

## Tests

```bash
npm test
npm run check
```

Current test coverage focuses on the bridge logic rather than a live ChatGPT/DevSpace OAuth round trip:

- memory context formatting
- symbol hint extraction
- JSON-RPC tool response transformation
- fail-open behavior
- non-memory tool pass-through
- request-scoped SSE transformation

## Security model

This bridge sits in front of a local coding workspace. Treat it as sensitive infrastructure.

- Bind to localhost by default.
- Put authentication and HTTPS at the outer boundary if exposed remotely.
- Do not expose it directly to the public internet.
- Keep fail-open enabled unless you explicitly want memory failures to break tool calls.
- Review upstream DevSpace permissions and allowed roots before use.

## Design rules

- Do not patch DevSpace upstream.
- Do not patch `codebase-memory-mcp` upstream.
- Treat DevSpace as the source of truth for filesystem operations.
- Only append memory context after the upstream DevSpace call succeeds.
- Unknown tools must pass through unchanged.
- Memory failures must not break local coding tools.

## Status

Prototype. The core transformation behavior is implemented and tested, but production ChatGPT Apps registration through the bridge still needs end-to-end validation.

## License

MIT