code-context-mcp

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

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

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

架构

┌────────────────────────────┐
│ 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. 安装

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

2. 配置 gateway 和本地 runtime

code-context-cli setup

setup 会：

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

3. 查看 daemon 状态

code-context-cli daemon status

4. 注册本地仓库

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

5. 搜索

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 命令

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 配置

先复制一份服务端配置：

cp config.gateway.example.yaml config.gateway.yaml

然后至少修改：

• gatewayServer.tokens
• ollama.model
• qdrant.vectorSize

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

qdrant:
  vectorSize: 1024

2. 直接启动整套服务

docker compose up -d --build

启动后会有：

• gateway → :4400
• qdrant → :6333
• ollama → :11434

3. 查看日志

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

4. 验证 gateway

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

开发

npm install
npm run lint
npm run build
npm run test