Kodit: A Code Indexing MCP Server

Kodit

一个代码和文档智能服务，可为 Git 仓库建立索引，并通过 MCP 和 REST API 提供搜索功能。

AI 编码助手能够访问代码库中的真实示例时，效果会更好。Kodit 会为你的代码仓库建立索引，将源文件拆分成可搜索的代码片段，并将它们提供给任何兼容 MCP 的助手。当助手需要编写新代码时，它会先查询 Kodit，获取来自你自己项目的相关最新示例。

Kodit 也能处理文档。PDF、Word 文件、PowerPoint 演示文稿和电子表格会经过栅格化并建立索引，因此你可以在同一处搜索代码和文档。

你将获得：

• 多种搜索策略，包括 BM25 关键词搜索、语义向量搜索、正则表达式 grep 和文档视觉搜索，每种策略都作为独立的 MCP 工具提供，让助手针对每个查询选择合适的方法
• MCP 服务，可与 Claude Code、Cursor、Cline、Kilo Code 及任何其他兼容 MCP 的助手配合使用
• REST API，可通过编程方式访问搜索、代码仓库、增强内容和索引状态
• AI 增强内容（可选），包括架构文档、API 文档、数据库架构检测、示例指南和提交摘要，均由大模型生成
• 文档智能，使用多模态嵌入，对 PDF 页面、Office 文档和图片进行视觉搜索
• 基本运行无需外部依赖，内置嵌入模型并使用 SQLite 存储

快速开始

Docker（推荐）

docker run -p 8080:8080 registry.helix.ml/helix/kodit:latest

此命令会使用 SQLite 存储和内置嵌入模型启动 Kodit。无需 API 密钥。

预构建二进制文件

从发布页面下载二进制文件，然后：

chmod +x kodit
./kodit serve

验证是否正常运行

在 http://localhost:8080/docs 打开交互式 API 文档。

或者为一个小型代码仓库建立索引并运行搜索：

# Index a repository
curl http://localhost:8080/api/v1/repositories \
  -X POST -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "repository",
      "attributes": {
        "remote_uri": "https://gist.github.com/philwinder/7aa38185e20433c04c533f2b28f4e217.git"
      }
    }
  }'

# Check indexing progress
curl http://localhost:8080/api/v1/repositories/1/status

# Search (once indexing is complete)
curl http://localhost:8080/api/v1/search \
  -X POST -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "search",
      "attributes": {
        "keywords": ["orders"],
        "text": "code to get all orders"
      }
    }
  }'

连接 AI 助手

Kodit 在 /mcp 提供 MCP 端点。连接你的助手，即可开始将 Kodit 用作代码搜索工具。

Claude Code

claude mcp add --transport http kodit http://localhost:8080/mcp

Cursor

添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "kodit": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Cline

添加到 MCP Servers 配置（Remote Servers 标签页）：

{
  "mcpServers": {
    "kodit": {
      "autoApprove": [],
      "disabled": false,
      "timeout": 60,
      "type": "streamableHttp",
      "url": "http://localhost:8080/mcp"
    }
  }
}

Kilo Code

添加到 MCP 配置（Edit Project/Global MCP）：

{
  "mcpServers": {
    "kodit": {
      "type": "streamable-http",
      "url": "http://localhost:8080/mcp",
      "alwaysAllow": [],
      "disabled": false
    }
  }
}

如果在远程运行，请将 http://localhost:8080 替换为你的服务 URL。

鼓励助手使用 Kodit

某些助手可能不会自动调用 Kodit 工具。将以下内容添加到项目规则或系统提示词中，以确保助手使用 Kodit：

For every request that involves writing or modifying code, the assistant's first
action must be to call the kodit search MCP tools. Only produce or edit code after
the tool call returns results.

在 Cursor 中，将其保存为 .cursor/rules/kodit.mdc，并在 frontmatter 中设置 alwaysApply: true。

MCP 工具

Kodit 向已连接的 AI 助手提供以下工具：

工具	描述
kodit_repositories	列出所有已索引的代码库
kodit_semantic_search	在代码中进行语义相似度搜索
kodit_keyword_search	BM25 关键词搜索
kodit_visual_search	搜索文档页面图像
kodit_grep	正则表达式模式匹配
kodit_ls	根据 glob 模式列出文件
kodit_read_resource	根据 URI 读取文件内容
kodit_architecture_docs	代码库的架构文档
kodit_api_docs	公共 API 文档
kodit_database_schema	数据库架构文档
kodit_cookbook	用法示例和模式
kodit_commit_description	提交说明
kodit_wiki	Wiki 目录
kodit_wiki_page	读取指定的 Wiki 页面
kodit_version	服务版本

丰富内容工具（architecture_docs、api_docs、database_schema、cookbook、wiki、commit_description）需要配置大模型提供商。请参阅配置参考中的丰富内容提供商。

Go 库

Kodit 可直接作为 Go 库嵌入使用。Helix 就是这样将 Kodit 集成到其平台中的。

import "github.com/helixml/kodit"

client, err := kodit.New(
    kodit.WithSQLite(".kodit/data.db"),
)
if err != nil {
    log.Fatal(err)
}
defer client.Close()

// Index a repository
_, _, err = client.Repositories.Add(ctx, &service.RepositoryAddParams{
    URL: "https://github.com/kubernetes/kubernetes",
})

// Search
results, err := client.Search.Query(ctx, "create a deployment",
    service.WithLimit(10),
)

for _, result := range results.Enrichments() {
    fmt.Println(result.Subtype(), result.Content())
}

库选项

选项	描述
WithSQLite(path)	使用 SQLite 存储
WithPostgresVectorchord(dsn)	使用 PostgreSQL 和 VectorChord
WithOpenAI(apiKey)	使用 OpenAI 生成嵌入和文本
WithAnthropic(apiKey)	使用 Anthropic Claude 生成文本（需要单独的嵌入提供商）
WithTextProvider(p)	自定义文本生成提供商
WithEmbeddingProvider(p)	自定义嵌入提供商
WithRAGPipeline()	跳过大模型丰富处理，仅进行索引和搜索
WithFullPipeline()	要求完成所有丰富处理（没有文本提供商时会报错）
WithDataDir(dir)	数据目录（默认值：~/.kodit）
WithCloneDir(dir)	代码库克隆目录
WithAPIKeys(keys...)	用于 HTTP 身份验证的 API 密钥
WithWorkerCount(n)	后台工作线程数（默认值：1）
WithPeriodicSyncConfig(cfg)	自动代码库同步设置

搜索选项

选项	描述
WithSemanticWeight(w)	语义搜索相对于关键词搜索的权重（0.0 到 1.0）
WithLimit(n)	最大结果数
WithOffset(n)	分页偏移量
WithLanguages(langs...)	按编程语言筛选
WithRepositories(ids...)	按代码库 ID 筛选
WithMinScore(score)	最低分数阈值
WithEnrichmentTypes(types...)	将结果筛选为指定的丰富内容类型
WithSnippets(include)	在结果中包含代码片段
WithDocuments(include)	在结果中包含丰富内容文档

Go HTTP 客户端

可使用生成的 HTTP 客户端，从 Go 调用远程 Kodit 服务：

go get github.com/helixml/kodit/clients/go

import koditclient "github.com/helixml/kodit/clients/go"

client, err := koditclient.NewClient("https://kodit.example.com")

// List repositories
resp, err := client.GetRepositories(ctx, nil)

// Search
text := "create a deployment"
resp, err := client.PostSearch(ctx, koditclient.PostSearchJSONRequestBody{
    Data: &koditclient.DtoSearchData{
        Attributes: &koditclient.DtoSearchAttributes{
            Text: &text,
        },
    },
})

类型会根据 OpenAPI 规范自动生成。完整的端点列表请参阅 /docs 中的交互式 API 文档。

生产环境部署

在生产环境中使用时，请部署 PostgreSQL（VectorChord）以实现可扩展的向量搜索，并为丰富内容配置专用的大模型提供商。

Docker Compose

将以下内容保存为 docker-compose.yaml：

services:
  kodit:
    image: registry.helix.ml/helix/kodit:latest
    ports:
      - "8080:8080"
    command: ["serve"]
    restart: unless-stopped
    depends_on:
      - vectorchord
    environment:
      DATA_DIR: /data
      DB_URL: postgresql://postgres:mysecretpassword@vectorchord:5432/kodit

      # Enrichment LLM (optional, enables AI-generated docs)
      ENRICHMENT_ENDPOINT_BASE_URL: http://ollama:11434
      ENRICHMENT_ENDPOINT_MODEL: ollama/qwen3:1.7b

      # External embedding provider (optional, replaces built-in model)
      # EMBEDDING_ENDPOINT_API_KEY: sk-proj-xxxx
      # EMBEDDING_ENDPOINT_MODEL: openai/text-embedding-3-small

      LOG_LEVEL: INFO
      API_KEYS: ${KODIT_API_KEYS:-}
    volumes:
      - kodit-data:/data

  vectorchord:
    image: tensorchord/vchord-suite:pg17-20250601
    environment:
      POSTGRES_DB: kodit
      POSTGRES_PASSWORD: mysecretpassword
    volumes:
      - vectorchord-data:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  kodit-data:
  vectorchord-data:

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vectorchord
spec:
  replicas: 1
  selector:
    matchLabels:
      app: vectorchord
  template:
    metadata:
      labels:
        app: vectorchord
    spec:
      containers:
        - name: vectorchord
          image: tensorchord/vchord-suite:pg17-20250601
          env:
            - name: POSTGRES_DB
              value: kodit
            - name: POSTGRES_PASSWORD
              value: mysecretpassword
          ports:
            - containerPort: 5432
---
apiVersion: v1
kind: Service
metadata:
  name: vectorchord
spec:
  selector:
    app: vectorchord
  ports:
    - port: 5432
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: kodit
spec:
  replicas: 1
  selector:
    matchLabels:
      app: kodit
  template:
    metadata:
      labels:
        app: kodit
    spec:
      containers:
        - name: kodit
          image: registry.helix.ml/helix/kodit:latest # pin to a specific version
          args: ["serve"]
          env: [] # see Configuration Reference for environment variables
          ports:
            - containerPort: 8080
          readinessProbe:
            httpGet:
              path: /
              port: 8080
            initialDelaySeconds: 10
            periodSeconds: 5
---
apiVersion: v1
kind: Service
metadata:
  name: kodit
spec:
  type: LoadBalancer
  selector:
    app: kodit
  ports:
    - port: 8080

身份验证

将 API_KEYS 环境变量设为以逗号分隔的密钥列表。写入端点（创建代码库、触发同步）需要在 Authorization: Bearer <key> 请求头中提供有效密钥。搜索端点默认开放。

配置参考

通过环境变量进行配置。也可以使用 .env 文件：

kodit serve --env-file .env

服务端

变量	默认值	说明
HOST	0.0.0.0	监听地址
PORT	8080	监听端口
DATA_DIR	~/.kodit	模型、克隆副本和数据库的数据目录
DB_URL	(empty)	PostgreSQL 连接字符串（为空时使用 SQLite）
LOG_LEVEL	INFO	日志详细程度：DEBUG、INFO、WARN、ERROR
LOG_FORMAT	pretty	日志格式：pretty 或 json
API_KEYS	(empty)	用于写入端点的逗号分隔 API 密钥
WORKER_COUNT	1	后台工作线程数
SEARCH_LIMIT	10	默认搜索结果数量上限
DISABLE_TELEMETRY	false	禁用匿名使用情况遥测
HTTP_CACHE_DIR	(empty)	用于将 HTTP POST 响应缓存到磁盘的目录；避免开发期间重复调用 API
REPORTING_LOG_TIME_INTERVAL	5	进度报告间隔，单位为秒

嵌入提供方

这些变量用于配置外部嵌入模型。如果未设置，Kodit 将使用其内置模型。

变量	默认值	说明
EMBEDDING_ENDPOINT_BASE_URL	(empty)	嵌入服务的基础 URL
EMBEDDING_ENDPOINT_MODEL	(empty)	模型标识符
EMBEDDING_ENDPOINT_API_KEY	(empty)	API 密钥
EMBEDDING_ENDPOINT_MAX_TOKENS	0	每次请求的最大令牌数（0 = 提供方默认值）
EMBEDDING_ENDPOINT_MAX_BATCH_CHARS	16000	每批嵌入的最大总字符数
EMBEDDING_ENDPOINT_MAX_BATCH_SIZE	1	每批的最大项目数
EMBEDDING_ENDPOINT_TIMEOUT	60	请求超时时间，单位为秒
EMBEDDING_ENDPOINT_NUM_PARALLEL_TASKS	1	并发嵌入请求数
EMBEDDING_ENDPOINT_EXTRA_PARAMS	(empty)	以 JSON 编码的嵌入提供方额外参数
EMBEDDING_ENDPOINT_QUERY_INSTRUCTION	(empty)	为非对称检索添加到查询前的指令
EMBEDDING_ENDPOINT_DOCUMENT_INSTRUCTION	(empty)	为非对称检索添加到文档前的指令
EMBEDDING_ENDPOINT_SOCKET_PATH	(empty)	本地提供方的 Unix 套接字路径（可替代 BASE_URL）
EMBEDDING_ENDPOINT_MAX_RETRIES	5	请求失败时的最大重试次数
EMBEDDING_ENDPOINT_INITIAL_DELAY	2.0	初始重试延迟，单位为秒
EMBEDDING_ENDPOINT_BACKOFF_FACTOR	2.0	重试退避倍数

视觉嵌入提供方

这些变量用于配置提供图像和文本视觉嵌入的远程服务。如果未设置，Kodit 将使用内置的 SigLIP2 模型。

变量	默认值	说明
VISION_EMBEDDING_ENDPOINT_BASE_URL	(empty)	视觉嵌入服务的基础 URL
VISION_EMBEDDING_ENDPOINT_MODEL	(empty)	模型标识符
VISION_EMBEDDING_ENDPOINT_API_KEY	(empty)	API 密钥
VISION_EMBEDDING_ENDPOINT_MAX_TOKENS	0	每次请求的最大令牌数（0 = 提供方默认值）
VISION_EMBEDDING_ENDPOINT_MAX_BATCH_CHARS	16000	每个嵌入批次的最大总字符数
VISION_EMBEDDING_ENDPOINT_MAX_BATCH_SIZE	1	每个批次的最大项目数
VISION_EMBEDDING_ENDPOINT_TIMEOUT	60	请求超时时间，单位为秒
VISION_EMBEDDING_ENDPOINT_NUM_PARALLEL_TASKS	1	并发视觉嵌入请求数
VISION_EMBEDDING_ENDPOINT_EXTRA_PARAMS	(empty)	以 JSON 编码的视觉嵌入提供方额外参数
VISION_EMBEDDING_ENDPOINT_QUERY_INSTRUCTION	(empty)	为非对称检索添加到查询前的指令
VISION_EMBEDDING_ENDPOINT_DOCUMENT_INSTRUCTION	(empty)	为非对称检索添加到文档前的指令
VISION_EMBEDDING_ENDPOINT_SOCKET_PATH	(empty)	本地提供方的 Unix 套接字路径（可替代 BASE_URL）
VISION_EMBEDDING_ENDPOINT_MAX_RETRIES	5	请求失败时的最大重试次数
VISION_EMBEDDING_ENDPOINT_INITIAL_DELAY	2.0	初始重试延迟，单位为秒
VISION_EMBEDDING_ENDPOINT_BACKOFF_FACTOR	2.0	重试退避倍率

内容增强提供方

这些变量用于配置大模型，以生成架构文档、API 文档、数据库架构、操作指南、提交摘要和 Wiki 页面。若未配置，Kodit 会为代码建立索引并提供搜索，但不会生成任何 AI 文档。

变量	默认值	说明
ENRICHMENT_ENDPOINT_BASE_URL	(empty)	大模型服务的基础 URL
ENRICHMENT_ENDPOINT_MODEL	(empty)	模型标识符
ENRICHMENT_ENDPOINT_API_KEY	(empty)	API 密钥
ENRICHMENT_ENDPOINT_NUM_PARALLEL_TASKS	1	并发内容增强请求数
ENRICHMENT_ENDPOINT_TIMEOUT	60	请求超时时间，单位为秒
ENRICHMENT_ENDPOINT_EXTRA_PARAMS	(empty)	以 JSON 编码的大模型额外参数
ENRICHMENT_ENDPOINT_MAX_TOKENS	0	每个响应的最大令牌数（0 = 提供方默认值）
ENRICHMENT_ENDPOINT_SOCKET_PATH	(empty)	本地提供方的 Unix 套接字路径（可替代 BASE_URL）
ENRICHMENT_ENDPOINT_MAX_RETRIES	5	请求失败时的最大重试次数
ENRICHMENT_ENDPOINT_INITIAL_DELAY	2.0	初始重试延迟，单位为秒
ENRICHMENT_ENDPOINT_BACKOFF_FACTOR	2.0	重试退避倍率
ENRICHMENT_ENDPOINT_MAX_BATCH_CHARS	16000	每个批次的最大总字符数
ENRICHMENT_ENDPOINT_MAX_BATCH_SIZE	1	每个批次的最大项目数
ENRICHMENT_ENDPOINT_QUERY_INSTRUCTION	(empty)	为非对称检索添加到查询前的指令
ENRICHMENT_ENDPOINT_DOCUMENT_INSTRUCTION	(empty)	为非对称检索添加到文档前的指令

内容增强通常是索引过程中最慢的部分，因为每次增强都需要与大模型提供方进行一次往返通信。增加 NUM_PARALLEL_TASKS 可以加快处理速度，但请遵守提供方的速率限制。请从较低值开始，之后再逐步增加。

提供方示例：

# OpenAI
ENRICHMENT_ENDPOINT_BASE_URL=https://api.openai.com/v1
ENRICHMENT_ENDPOINT_MODEL=gpt-4o-mini
ENRICHMENT_ENDPOINT_API_KEY=sk-proj-xxxx

# Ollama (local)
ENRICHMENT_ENDPOINT_BASE_URL=http://localhost:11434
ENRICHMENT_ENDPOINT_MODEL=ollama/qwen3:1.7b

# Helix (private cloud)
ENRICHMENT_ENDPOINT_BASE_URL=https://app.helix.ml/v1
ENRICHMENT_ENDPOINT_MODEL=Qwen/Qwen3-8B
ENRICHMENT_ENDPOINT_API_KEY=your-helix-key

定期同步

变量	默认值	说明
PERIODIC_SYNC_ENABLED	true	按固定间隔自动同步代码仓库
PERIODIC_SYNC_INTERVAL_SECONDS	1800	同步间隔（默认：30 分钟）
PERIODIC_SYNC_RETRY_ATTEMPTS	3	同步失败时的重试次数

分块

变量	默认值	描述
CHUNK_SIZE	1500	每个文本块的字符数
CHUNK_OVERLAP	200	相邻文本块之间的重叠字符数
CHUNK_MIN_SIZE	50	文本块的最小大小

REST API

完整 API 文档可在运行中的 Kodit 实例的 /docs 路径交互式查看。OpenAPI 3.0 规范位于 /docs/openapi.json。

主要端点：

方法	路径	描述
POST	/api/v1/repositories	添加要索引的代码库
GET	/api/v1/repositories	列出已索引的代码库
GET	/api/v1/repositories/{id}/status	索引进度
POST	/api/v1/repositories/{id}/sync	触发同步
DELETE	/api/v1/repositories/{id}	移除代码库
POST	/api/v1/search	综合搜索（关键词 + 语义）
GET	/api/v1/search/semantic	仅语义搜索
GET	/api/v1/search/keyword	仅关键词搜索
GET	/api/v1/search/visual	在文档页面中进行视觉搜索
GET	/api/v1/search/grep	正则表达式模式搜索
GET	/api/v1/search/ls	按 glob 列出文件

设置 API_KEYS 后，所有写入端点都需要 Authorization: Bearer <key> 标头。

索引工作原理

添加代码库后，Kodit 会运行以下处理流程：

1. 克隆 Git 代码库到本地存储
2. 扫描提交、分支和标签，以提取元数据
3. 提取代码片段：将源文件拆分为相互重叠的文本块
4. 构建搜索索引：使用 BM25（关键词）和向量嵌入（语义）
5. 生成扩展内容（若配置了 LLM 提供商）：架构文档、API 文档、数据库架构、示例集、提交摘要和 Wiki 页面

Kodit 会跟踪同步期间发生变化的文件，并仅重新处理修改过的内容。代码库会按可配置的间隔自动同步（默认：每 30 分钟）。

支持的来源

Kodit 可索引任何可通过 HTTPS、SSH 或 Git 协议访问的 Git 代码库，包括 GitHub、GitLab、Bitbucket、Azure DevOps 和可自托管的服务。

私有代码库

私有代码库支持使用个人访问令牌或 SSH 密钥访问：

# HTTPS with token
https://username:[email protected]/username/repo.git

# SSH (ensure your SSH key is configured)
[email protected]:username/repo.git

隐私

Kodit 遵循 .gitignore 和 .noindex 文件中的规则。匹配这些规则的文件不会被纳入索引。

存储后端

SQLite（默认）

无需配置。Kodit 会在数据目录中创建 SQLite 数据库，并使用 FTS5 进行关键词搜索、使用进程内向量存储。适合单用户和小团队部署。

PostgreSQL 与 VectorChord

对于较大规模的部署，请使用带有 VectorChord 扩展的 PostgreSQL。它支持可扩展的向量搜索和并发访问。将 DB_URL 环境变量设为你的连接字符串。

推荐的 Docker 镜像为 tensorchord/vchord-suite:pg17-20250601，其中包含 PostgreSQL 17、VectorChord、vchord_bm25 和 pg_tokenizer。

从源代码构建

git clone https://github.com/helixml/kodit.git
cd kodit
make tools          # Install development tools
make download-model # Download the built-in embedding model
make build          # Build the binary
./bin/kodit version
./bin/kodit serve

运行测试：

make test                         # All tests
make test PKG=./internal/foo/...  # Specific package
make check                        # Format, vet, lint, and test

故障排除

**重启后出现 MCP 连接错误：**如果重启 Kodit 服务后看到 No valid session ID provided，请在助手中重新加载 MCP 客户端。MCP 会话在服务重启后不会保留。

**没有搜索结果：**调用 GET /api/v1/repositories/{id}/status，确认索引已完成。如果状态显示错误，请使用 LOG_LEVEL=DEBUG 检查服务日志。

**未生成扩展内容：**生成扩展内容需要 LLM 提供商。请确认已设置 ENRICHMENT_ENDPOINT_BASE_URL 和 ENRICHMENT_ENDPOINT_MODEL。未设置这些变量时，Kodit 会索引和搜索代码，但不会生成 AI 文档。

遥测

Kodit 会收集有限的匿名遥测数据（仅使用元数据，不包含用户数据），以指导开发。使用以下方式禁用：

DISABLE_TELEMETRY=true

商业支持

Helix 提供基于 Kodit 构建的托管平台，并提供管理 UI、仓库浏览、团队协作和托管基础设施等额外功能。如需商业支持或企业集成，请联系 [email protected]。

贡献

请参阅 CONTRIBUTING.md 了解指南。

许可证

Apache 2.0