kodit (Helixml)

Kodit

A code and document intelligence server that indexes Git repositories and provides search through MCP and REST APIs.

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

Kodit还处理文档。PDF、Word文件、PowerPoint演示文稿和电子表格都经过光栅化和索引，因此您可以在一个地方搜索代码和文档。

您将获得：

• 多种搜索策略 包括BM25关键字搜索、语义向量搜索、正则表达式grep和可视化文档搜索，每个都作为单独的MCP工具公开，以便您的助手为每个查询选择正确的方法
• MCP服务器 适用于Claude Code、Cursor、Cline、Kilo Code和任何其他MCP兼容助手
• REST API 用于对搜索、存储库、丰富和索引状态进行程序化访问
• 人工智能富集 （可选）包括体系结构文档、API文档、数据库模式检测、食谱示例和提交摘要，所有这些都由LLM生成
• 文档情报 使用多模式嵌入在PDF页面、Office文档和图像之间进行视觉搜索
• 不需要外部依赖 用于基本操作，内置嵌入模型和SQLite存储

快速入门

Docker（推荐）

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

这将使用SQLite存储和内置嵌入模型启动Kodit。不需要API密钥。

预构建二进制文件

从下载二进制文件 发布页面那么：

chmod +x kodit
./kodit serve

验证它是否正常工作

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

或者索引一个小型存储库并运行搜索：

# 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 mcp add --transport http kodit http://localhost:8080/mcp

光标

添加 ~/.cursor/mcp.json:

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

克莱恩

添加到MCP服务器配置（远程服务器选项卡）：

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

千码

添加到MCP配置（编辑项目/全局MCP）：

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

替换 http://localhost:8080 如果远程运行，请使用您的服务器URL。

鼓励助手使用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/rules/kodit.mdc 和 alwaysApply: true 正面。

MCP工具

Kodit将这些工具暴露给连接的AI助手：

富集工具(architecture_docs, api_docs, database_schema, cookbook, wiki, commit_description)需要配置LLM提供程序。请参阅配置参考下的扩展提供程序。

去图书馆

Kodit可以直接作为Go库嵌入。就是这样 螺旋 将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())
}

库选项

搜索选项

转到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规范自动生成的。请参阅上的交互式API文档 /docs 查看完整的端点列表。

生产部署

对于生产使用，请使用PostgreSQL（VectorChord）进行部署，以实现可扩展的向量搜索，并使用专用的LLM提供程序进行丰富。

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 头球默认情况下，搜索端点是打开的。

配置参考

配置是通过环境变量完成的。您还可以使用 .env 文件：

kodit serve --env-file .env

服务器

嵌入提供商

这些配置了一个外部嵌入模型。如果未设置，Kodit将使用其内置模型。

视觉嵌入提供商

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

丰富服务提供商

这些配置了用于生成体系结构文档、API文档、数据库架构、食谱、提交摘要和wiki页面的LLM。如果没有这个，Kodit会索引和搜索代码，但不会生成任何AI文档。

富集通常是索引中最慢的部分，因为每次富集都需要往返LLM提供者。增加 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

定期同步

分块

REST API

完整的API以交互方式记录在 /docs 在正在运行的Kodit实例上。OpenAPI 3.0规范可在 /docs/openapi.json.

关键端点：

所有写入端点都需要 Authorization: Bearer 标题时 API_KEYS 已设置。

索引如何工作

添加存储库时，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:token@github.com/username/repo.git

# SSH (ensure your SSH key is configured)
git@github.com:username/repo.git

隐私

Kodit尊重 .gitignore 和 .noindex 文件夹。与这些模式匹配的文件将被排除在索引之外。

存储后端

SQLite（默认）

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

PostgreSQL与VectorChord

对于较大的部署，请使用PostgreSQL VectorChord 扩展。这提供了可扩展的矢量搜索和并发访问。设置 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连接错误： 如果你看到 No valid session ID provided 重启Kodit服务器后，在助手中重新加载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

商业支持

螺旋 提供了一个基于Kodit构建的托管平台，具有其他功能，包括管理UI、存储库浏览、团队协作和托管基础设施。如需商业支持或企业集成，请联系 founders@helix.ml.

贡献

看 贡献.md 作为指导方针。

许可证

Apache 2.0