@context-engine-bridge/context-engine-mcp-bridge 0.0.13 → 0.0.14

package/AGENTS.md

@@ -0,0 +1,319 @@
+<!-- Parent: ../AGENTS.md -->
+# Context-Engine MCP Bridge
+
+## Purpose
+
+TypeScript/Node.js MCP bridge server that acts as a proxy between MCP clients (Claude Code, Cursor, Windsurf) and the Context Engine backend. Provides SSE/HTTP transport, OAuth 2.0 authentication, and transparent path mapping between local and container filesystems.
+
+## Key Responsibilities
+
+1. **MCP Protocol Translation**: Converts stdio/HTTP requests from MCP clients to HTTP requests for the Python backend
+2. **Authentication**: Manages OAuth 2.0 flows and session persistence for multi-user environments
+3. **Path Mapping**: Translates container paths (`/work/repo/...`) to local workspace paths for client consumption
+4. **Session Management**: Maintains per-connection session state and default collection/workspace settings
+5. **Tool Routing**: Routes `memory.*` tools to memory server, other tools to indexer server
+
+## Architecture
+
+```
+┌────────────────────────────────────────────────────────┐
+│  MCP Client (Claude Code, etc.)                        │
+└──────────────┬─────────────────────────────────────────┘
+               │ stdio or HTTP
+┌──────────────▼─────────────────────────────────────────┐
+│  ctx-mcp-bridge (src/mcpServer.js)                     │
+│  ┌─────────────────────────────────────────────────┐   │
+│  │  MCP SDK Server (stdio/HTTP transport)          │   │
+│  │  - tools/list → merge indexer + memory tools    │   │
+│  │  - tools/call → route to appropriate backend    │   │
+│  └────────────────┬────────────────────────────────┘   │
+│                   │                                     │
+│  ┌────────────────▼─────────────┐  ┌─────────────────┐ │
+│  │  MCP HTTP Client (indexer)   │  │  HTTP Client    │ │
+│  │  http://localhost:8003/mcp   │  │  (memory)       │ │
+│  └──────────────────────────────┘  └─────────────────┘ │
+└────────────────────────────────────────────────────────┘
+               │
+┌──────────────▼─────────────────────────────────────────┐
+│  Python Backend (indexer_mcp.py, memory_mcp.py)        │
+└────────────────────────────────────────────────────────┘
+```
+
+## Core Files
+
+### src/mcpServer.js (800+ lines)
+
+Main MCP server implementation. Key functions:
+
+- `createBridgeServer()`: Initializes MCP server with dual backend clients
+- `initializeRemoteClients()`: Connects to indexer and memory servers via StreamableHTTPClientTransport
+- `ListToolsRequestSchema` handler: Merges tools from both backends, deduplicates
+- `CallToolRequestSchema` handler: Routes tools, injects session ID, handles retries
+- `selectClientForTool()`: Routes `memory.*` tools to memory server, others to indexer
+- `fetchBridgeCollectionState()`: Queries `/bridge/state` for active collection overrides
+- Session retry logic: Detects `"No valid session ID"` errors and reinitializes clients
+
+**Environment Variables**:
+- `CTXCE_INDEXER_URL`: Default `http://localhost:8003/mcp`
+- `CTXCE_MEMORY_URL`: Default `http://localhost:8002/mcp` (optional)
+- `CTXCE_SESSION_ID`: Explicit session ID (overrides derived session)
+- `CTXCE_TOOL_TIMEOUT_MSEC`: Tool call timeout (default 300000 = 5 min)
+- `CTXCE_TOOL_RETRY_ATTEMPTS`: Retry count for transient errors (default 2)
+- `CTXCE_BRIDGE_STATE_TOKEN`: Auth token for `/bridge/state` endpoint
+
+### src/oauthHandler.js (586 lines)
+
+OAuth 2.0 implementation (RFC9728 Protected Resource Metadata + RFC7591 Dynamic Client Registration):
+
+- **Endpoints**:
+  - `GET /.well-known/oauth-authorization-server`: OAuth metadata
+  - `POST /oauth/register`: Dynamic client registration (auto-approve local clients)
+  - `GET /oauth/authorize`: Authorization flow (shows login page or auto-approves if session exists)
+  - `POST /oauth/store-session`: Stores session from login page, returns auth code
+  - `POST /oauth/token`: Exchanges auth code for bearer token
+
+- **Security**:
+  - PKCE code_challenge validation (TODO: currently skipped for local bridge)
+  - Client ID and redirect URI validation against registered clients
+  - Origin/Referer header validation (localhost-only for `/oauth/store-session`)
+  - 10-minute auth code expiry, 24-hour token expiry
+  - Binds to `127.0.0.1` only (no remote access)
+
+- **Storage**: In-memory `tokenStore`, `pendingCodes`, `registeredClients` (not persisted across restarts)
+
+### src/resultPathMapping.js (507 lines)
+
+Bidirectional path translation between container and client filesystems:
+
+**Request Path Mapping** (`maybeRemapToolArgs`):
+- Detects `/work/<repo>/...` container paths in tool args
+- Extracts repo-relative POSIX path (e.g., `/work/myrepo/src/main.py` → `src/main.py`)
+- Handles `path`, `under`, `root`, `subdir`, `path_glob`, `not_glob` parameters
+- Recursively processes nested objects and arrays
+
+**Response Path Mapping** (`maybeRemapToolResult`):
+- Parses JSON from `content[].text` or `structuredContent`
+- For each hit object:
+  - Computes `rel_path` from container path
+  - Joins `rel_path` to workspace root to produce `client_path`
+  - Prefers existing `host_path` if it exists and is within workspace
+  - Optionally overrides `hit.path` with `client_path` (default: enabled via `CTXCE_BRIDGE_OVERRIDE_PATH=1`)
+- Remaps `related_paths` arrays to absolute local paths
+
+**Environment Variables**:
+- `CTXCE_BRIDGE_MAP_PATHS=1`: Enable/disable path mapping (default: enabled)
+- `CTXCE_BRIDGE_OVERRIDE_PATH=1`: Replace `path` field with `client_path` (default: enabled)
+- `CTXCE_BRIDGE_CLIENT_PATH_STRICT=0`: Use `workspace_join` always vs preferring `host_path`
+- `CTXCE_BRIDGE_PATH_DIAGNOSTICS=0`: Add debug fields `client_path_source`, `client_path_joined`
+
+### src/authConfig.js (not shown, ~100 lines)
+
+Auth entry persistence to `~/.ctxce/auth.json`:
+
+- `loadAuthEntry(backendUrl)`: Load session for specific backend
+- `saveAuthEntry(backendUrl, {sessionId, userId, expiresAt})`: Persist session
+- `deleteAuthEntry(backendUrl)`: Remove session
+- `loadAnyAuthEntry()`: Find any stored session (fallback)
+
+### src/authCli.js (285 lines)
+
+CLI commands for auth management:
+
+- `ctxce auth login`: Calls `/auth/login` or `/auth/login/password`, saves session
+- `ctxce auth status`: Checks stored session, prints human or JSON output
+- `ctxce auth logout`: Deletes stored session
+
+**Fallback logic**: If `--backend-url` omitted, tries stored sessions, then `CTXCE_UPLOAD_ENDPOINT`, then `http://localhost:8004`
+
+### src/cli.js (124 lines)
+
+Main CLI dispatcher:
+
+- `ctxce mcp-serve`: Starts stdio MCP bridge (default mode for MCP clients)
+- `ctxce mcp-http-serve`: Starts HTTP MCP bridge on port 30810 (used by VS Code extension)
+- `ctxce auth <subcmd>`: Delegates to `authCli.js`
+
+**Flags**:
+- `--workspace` / `--path`: Workspace root (default: cwd)
+- `--indexer-url`: Override indexer URL
+- `--memory-url`: Override memory URL (or omit to disable)
+- `--port`: HTTP port (for `mcp-http-serve`)
+
+### bin/ctxce.js (2 lines)
+
+Shebang wrapper: `#!/usr/bin/env node`, imports `runCli()` from `src/cli.js`
+
+## Key Features
+
+### 1. Tool Routing
+
+```javascript
+function selectClientForTool(name, indexerClient, memoryClient) {
+  const lowered = name.toLowerCase();
+  if (memoryClient && lowered.includes("memory")) {
+    return memoryClient;
+  }
+  return indexerClient;
+}
+```
+
+Tools starting with `memory.` or containing "memory" route to memory server; all others route to indexer.
+
+### 2. Session Injection
+
+Bridge injects `session` parameter into all tool calls:
+1. Explicit `CTXCE_SESSION_ID` env var
+2. Stored auth session from `~/.ctxce/auth.json`
+3. Fallback: `ctxce-<workspace-hash>` (deterministic per workspace)
+
+### 3. Retry Logic
+
+Automatic retry on transient errors (timeouts, network errors, 502/503/504):
+- Default: 2 attempts with 200ms delay
+- Detects session errors (`"No valid session ID"`) and reinitializes clients
+- Configurable via `CTXCE_TOOL_RETRY_ATTEMPTS` and `CTXCE_TOOL_RETRY_DELAY_MSEC`
+
+### 4. Collection State Override
+
+Queries `/bridge/state?collection=...&repo_name=...` on startup to resolve active collection:
+- Prefers `serving_collection` from backend over `ctx_config.json`
+- Falls back to `default_collection` from `ctx_config.json`
+- Logs active collection for transparency
+
+### 5. Path Mapping Examples
+
+**Request**: Client sends `path: "/Users/dev/myrepo/src/main.py"`
+→ Bridge normalizes to `src/main.py` (repo-relative)
+→ Backend receives `path: "src/main.py"`
+
+**Response**: Backend returns `path: "/work/myrepo/src/main.py"`, `container_path: "/work/myrepo/src/main.py"`
+→ Bridge computes `rel_path: "src/main.py"`, `client_path: "/Users/dev/myrepo/src/main.py"`
+→ Client receives `path: "/Users/dev/myrepo/src/main.py"` (if `CTXCE_BRIDGE_OVERRIDE_PATH=1`)
+
+## Usage Patterns
+
+### Stdio Mode (for MCP clients)
+
+```bash
+ctxce mcp-serve --workspace /path/to/repo
+```
+
+Add to Claude Desktop `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "context-engine": {
+      "command": "ctxce",
+      "args": ["mcp-serve", "--workspace", "/path/to/repo"]
+    }
+  }
+}
+```
+
+### HTTP Mode (for VS Code extension)
+
+```bash
+ctxce mcp-http-serve --workspace /path/to/repo --port 30810
+```
+
+Extension uses HTTP transport to avoid stdio buffering issues.
+
+### Authentication Flow
+
+1. User initiates OAuth via browser: `GET /oauth/authorize?client_id=...&redirect_uri=...&code_challenge=...`
+2. Bridge checks for existing session in `~/.ctxce/auth.json`
+3. If no session, shows login page with backend URL input
+4. User submits credentials, page POSTs to backend `/auth/login`
+5. Backend returns `session_id`, page POSTs to `/oauth/store-session`
+6. Bridge saves session to `~/.ctxce/auth.json`, generates auth code, redirects with code
+7. Client exchanges code for bearer token via `/oauth/token`
+8. Client includes `Authorization: Bearer <token>` in subsequent MCP requests
+
+## Testing
+
+No automated tests currently. Manual testing via:
+
+1. Start backend: `docker-compose up -d`
+2. Run bridge: `ctxce mcp-http-serve --workspace /path/to/repo`
+3. Test OAuth flow: Open `http://127.0.0.1:30810/oauth/authorize?client_id=test&redirect_uri=http://localhost/callback&code_challenge=...`
+4. Test MCP tools: Use MCP client (Claude Code) or `curl` to POST tool calls to `/mcp`
+
+## Debugging
+
+Set `CTXCE_DEBUG_LOG=/tmp/ctxce.log` to log all bridge activity:
+```bash
+export CTXCE_DEBUG_LOG=/tmp/ctxce.log
+ctxce mcp-serve --workspace /path/to/repo
+tail -f /tmp/ctxce.log
+```
+
+Common issues:
+- **Session errors**: Check `~/.ctxce/auth.json` has valid `sessionId`
+- **Path mapping issues**: Set `CTXCE_BRIDGE_PATH_DIAGNOSTICS=1` to see `client_path_source`
+- **Tool routing issues**: Check tool name includes `"memory"` for memory server routing
+- **Timeout errors**: Increase `CTXCE_TOOL_TIMEOUT_MSEC` for slow queries
+
+## Integration Points
+
+### Upstream (MCP Clients)
+- **Claude Code**: Uses stdio transport via `claude_desktop_config.json`
+- **Cursor**: Supports MCP via settings
+- **VS Code Extension**: Uses HTTP transport on port 30810
+
+### Downstream (Python Backend)
+- **indexer_mcp.py**: Provides 30+ search/graph tools on port 8003
+- **memory_mcp.py**: Provides memory storage tools on port 8002
+- **upload_service.py**: Auth backend on port 8004 (`/auth/login`, `/bridge/state`)
+
+## Security Considerations
+
+1. **Local-only binding**: HTTP server binds to `127.0.0.1` only (no remote access)
+2. **Origin validation**: `/oauth/store-session` requires `Origin` or `Referer` header from localhost
+3. **Client validation**: OAuth endpoints validate `client_id` and `redirect_uri` against registered clients
+4. **Session persistence**: `~/.ctxce/auth.json` stores sessions (file permissions: 0600)
+5. **Token expiry**: Auth codes expire in 10 min, bearer tokens in 24 hours
+6. **PKCE**: Code challenge method `S256` supported (validation TODO)
+
+## Configuration Files
+
+### ~/.ctxce/auth.json
+
+```json
+{
+  "http://localhost:8004": {
+    "sessionId": "sess_abc123",
+    "userId": "user-456",
+    "expiresAt": 1704974400
+  }
+}
+```
+
+### ctx_config.json (in workspace)
+
+```json
+{
+  "default_collection": "myrepo-abc123",
+  "default_mode": "refrag",
+  "default_under": "src/",
+  "repo_name": "myrepo"
+}
+```
+
+Bridge reads this on startup and sends to backend via `set_session_defaults`.
+
+## Future Enhancements
+
+1. **PKCE validation**: Implement `code_verifier` hash validation in `/oauth/token`
+2. **Persistent storage**: Migrate OAuth state to Redis/SQLite (currently in-memory)
+3. **Token refresh**: Support `refresh_token` grant type for long-lived sessions
+4. **Multi-workspace**: Allow clients to switch workspaces without restarting bridge
+5. **Rate limiting**: Add per-client rate limits for tool calls
+6. **Metrics**: Expose Prometheus metrics for tool call latency, error rates
+
+## Related Documentation
+
+- [MCP SDK Documentation](https://modelcontextprotocol.io/docs)
+- [OAuth 2.0 RFC9728](https://www.rfc-editor.org/rfc/rfc9728.html) (Protected Resource Metadata)
+- [OAuth 2.0 RFC7591](https://www.rfc-editor.org/rfc/rfc7591.html) (Dynamic Client Registration)
+- [Context Engine Python Backend](../scripts/AGENTS.md)
+- [VS Code Extension Integration](../README.md#vs-code-extension)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@context-engine-bridge/context-engine-mcp-bridge",
-  "version": "0.0.13",
+  "version": "0.0.14",
   "description": "Context Engine MCP bridge (http/stdio proxy combining indexer + memory servers)",
   "bin": {
     "ctxce": "bin/ctxce.js",