npm package: @lonyon0820/code-context-mcp
Description: Personal realtime code indexing with a local edge runtime and remote Qdrant/Ollama gateway
Latest version: 2.0.1

# code-context-mcp

本项目现在的目标不是“团队共享代码搜索平台”，而是：

```text
本地实时生产
+ 远程集中存储
+ 不共享个人索引结果
```

也就是每个用户在自己的机器上实时监听本地仓库，把增量更新推送到内网 gateway，再由 gateway 写入远程 Qdrant。搜索同样通过本地 edge runtime 发起，但默认只看当前用户、当前 workspace 的命名空间。

## 架构

```text
┌────────────────────────────┐
│ IDE / Agent / MCP Client   │
└─────────────┬──────────────┘
              │ stdio MCP
              ▼
┌────────────────────────────┐
│ code-context-mcp           │
│ thin client                │
└─────────────┬──────────────┘
              │ localhost IPC
              ▼
┌────────────────────────────┐
│ local edge runtime         │
│ - watch local repos        │
│ - chunk changed files      │
│ - persist local state      │
│ - queue pending retries    │
└─────────────┬──────────────┘
              │ authenticated HTTP
              ▼
┌────────────────────────────┐
│ internal gateway           │
│ - auth                     │
│ - namespace enforcement    │
│ - embedding                │
│ - qdrant read/write        │
└─────────────┬──────────────┘
              ▼
      remote Ollama + Qdrant
```

## 设计原则

- 实时性来自 **本地 watcher**
- 检索真相来自 **远程已确认索引**
- 用户之间 **不共享结果**
- 默认查询边界是 **当前 workspace**
- 断网或 gateway 故障时：
  - 本地记录 pending operations
  - worktree 标记为 `out_of_sync`
  - 恢复后自动 replay

## V1 非目标

- 不支持未保存 buffer 级别索引
- 不支持团队共享搜索
- 不支持断网时把本地 overlay 与远程结果做混合检索

## 快速开始

### 1. 安装

```bash
npm install -g @lonyon0820/code-context-mcp
```

### 2. 配置 gateway 和本地 runtime

```bash
code-context-cli setup
```

`setup` 会：

- 写入本地配置
- 校验 gateway 可达
- 更新 `~/.claude.json`
- 尝试启动本地 edge runtime

### 3. 查看 daemon 状态

```bash
code-context-cli daemon status
```

### 4. 注册本地仓库

```bash
code-context-cli index /absolute/path/to/repo -n my-repo
```

### 5. 搜索

```bash
code-context-cli search "where is request authentication handled?"
```

## 运行模式

### 用户侧

- `code-context-mcp`
  - MCP thin client
  - 不自己持有 watcher/index 生命周期
- `code-context-cli daemon start`
  - 后台启动本地 edge runtime
- `code-context-cli daemon run`
  - 前台运行本地 edge runtime

### 服务侧

- `code-context-cli gateway run`
  - 运行内部 gateway
  - 负责 auth、embedding、Qdrant 读写和 namespace enforcement

## 命名空间模型

远程索引按下面的维度隔离：

- `tenant_id`
- `user_id`
- `workspace_id`
- `repo_id`
- `worktree_id`
- `file_path`

其中：

- `workspace_id`：一个本地 daemon 安装实例一个
- `repo_id`：同一逻辑 git 仓库共享
- `worktree_id`：每个具体 checkout/root path 一个

## CLI 命令

```bash
code-context-cli setup
code-context-cli init
code-context-cli index <path> -n <name>
code-context-cli search <query> --limit 5 --threshold 0.3
code-context-cli list
code-context-cli daemon start
code-context-cli daemon status
code-context-cli gateway run
code-context-cli uninstall
```

## MCP 工具

| 工具 | 说明 |
|------|------|
| `codebase-retrieval` | 通过本地 edge runtime 查询当前 workspace 的远程已确认索引 |
| `index-repository` | 注册本地仓库并触发 baseline sync |
| `list-repositories` | 列出当前 workspace 下已注册的本地仓库及同步状态 |

## 配置说明

### 用户侧最关键的配置

- `gateway.url`
- `gateway.authToken`
- `runtime.host`
- `runtime.port`

### 服务侧最关键的配置

- `gatewayServer.host`
- `gatewayServer.port`
- `gatewayServer.tokens`
- `ollama.*`
- `qdrant.*`

### 本地状态

本地 edge runtime 会在 `~/.config/code-context-mcp/` 下维护：

- `config.yaml`
- `daemon.pid`
- `state.sqlite`

旧版 JSON registry/index-state 会在首次运行时导入到 SQLite。

## 服务端部署

现在推荐直接用 Docker 托管服务端：

- `gateway`
- `qdrant`
- `ollama`

### 1. 准备 gateway 配置

先复制一份服务端配置：

```bash
cp config.gateway.example.yaml config.gateway.yaml
```

然后至少修改：

- `gatewayServer.tokens`
- `ollama.model`
- `qdrant.vectorSize`

如果你使用 `qwen3-embedding:0.6b`，请确保：

```yaml
qdrant:
  vectorSize: 1024
```

### 2. 直接启动整套服务

```bash
docker compose up -d --build
```

启动后会有：

- `gateway` → `:4400`
- `qdrant` → `:6333`
- `ollama` → `:11434`

### 3. 查看日志

```bash
docker compose logs -f gateway
docker compose logs -f qdrant
docker compose logs -f ollama
```

### 4. 验证 gateway

```bash
curl -H "Authorization: Bearer <your-token>" http://127.0.0.1:4400/v1/runtime/health
```

如果正常，会返回当前 token 对应的 `tenantId` / `userId`。

## 运维与回滚

### 运维建议

- 用户机器只需要连通：
  - `gateway.url`
- gateway 机器需要连通：
  - `ollama.url`
  - `qdrant.url`
- 建议监控：
  - gateway 5xx
  - gateway 延迟
  - Qdrant 可用性
  - 本地 daemon `out_of_sync` worktree 数量

### 回滚建议

- 如果远程 gateway 或 namespace 路径出现问题：
  - 停掉本地 daemon
  - 回退到上一版本地-only 发布版本
  - 保留 `state.sqlite` 以便后续迁移或恢复
- 如果只是本地 daemon 升级失败：
  - 停止 daemon
  - 回滚本地安装包版本
  - 重新执行 `code-context-cli daemon start`
- 如果是服务端容器版本有问题：
  - 回退镜像或代码版本
  - `docker compose down`
  - 使用目标版本重新 `docker compose up -d --build`

## 开发

```bash
npm install
npm run lint
npm run build
npm run test
```