ctxpp (Cavenine)

ctx++

ctx++

为AI编码代理提供快速、准确的代码库智能。

ctx++是一个MCP（模型上下文协议）服务器，它为AI代理提供了对大型代码库的精确、结构化的理解。它使用原生树型解析提取符号，在SQLite中使用全文和矢量搜索对其进行索引，并跟踪调用图以自动映射特征在文件之间的组装方式——不需要手动维护文档。

______________________________________________________________________

为什么选择ctx++

ctx++围绕三个原则构建：

1. 永远不要超时。 SQLite具有索引向量和FTS搜索功能，这意味着无论代码库大小如何，查询都很快。MCP服务器在2秒内加载，所有工具调用都在MCP超时窗口内完成。
2. 返回正确的代码，而不仅仅是匹配的代码。 调用图遍历通过遍历真实的调用关系来查找功能中涉及的所有内容，就像高级工程师阅读代码一样。
3. 最小设置。 一个Go二进制加号 奥拉玛 用于嵌入。没有云服务，没有API密钥，没有Docker。

______________________________________________________________________

工具

______________________________________________________________________

支持的语言

想添加另一种语言吗？看 docs/ADDING-LANGUAGE-SUPPORT.md 获取分步实施模板和PR清单。

______________________________________________________________________

先决条件

• 转到1.24+ 从源头进行建设
• 奥拉玛 语义搜索嵌入

# Install Ollama, then pull the default embedding model:
ollama pull bge-m3

没有Ollama，ctx++仍然可以工作，但只提供关键字搜索。语义搜索和特征遍历质量取决于嵌入。

______________________________________________________________________

安装

go install github.com/cavenine/ctxpp@latest

或者从源代码构建：

git clone https://github.com/cavenine/ctxpp
cd ctxpp
make build

______________________________________________________________________

快速开始

1.为你的项目建立索引

ctxpp index --path /path/to/your/project

这创造了 .ctxpp/index.db 在项目根中。添加到 .gitignore:

.ctxpp/

后续运行仅重新处理更改的文件。分支开关通过文件监视器自动自愈。

如果解析器逻辑发生了变化，但源文件没有发生变化，请强制对支持的文件进行完全重新分析：

ctxpp index --path /path/to/your/project --force

2.添加到MCP配置中

以下示例使用Ollama bge-m3 （默认设置）。如果Ollama没有跑步，忽略 CTXPP_OLLAMA_* --ctx++将退回到仅关键字搜索。

开源代码 (opencode.json 在项目根目录中）：

{
  "mcp": {
    "ctxpp": {
      "type": "local",
      "command": ["ctxpp", "mcp"],
      "enabled": true,
      "environment": {
        "CTXPP_PROJECT": "/path/to/your/project",
        "CTXPP_OLLAMA_URL": "http://localhost:11434",
        "CTXPP_OLLAMA_MODEL": "bge-m3"
      }
    }
  }
}

克劳德代码 (.mcp.json):

{
  "mcpServers": {
    "ctxpp": {
      "command": "ctxpp",
      "args": ["mcp"],
      "env": {
        "CTXPP_PROJECT": "/path/to/your/project",
        "CTXPP_OLLAMA_URL": "http://localhost:11434",
        "CTXPP_OLLAMA_MODEL": "bge-m3"
      }
    }
  }
}

光标/风帆 (.cursor/mcp.json 或 .windsurf/mcp.json):

{
  "mcpServers": {
    "ctxpp": {
      "command": "ctxpp",
      "args": ["mcp"],
      "env": {
        "CTXPP_PROJECT": "/path/to/your/project",
        "CTXPP_OLLAMA_URL": "http://localhost:11434",
        "CTXPP_OLLAMA_MODEL": "bge-m3"
      }
    }
  }
}

3.使用它

向您的AI代理询问有关代码库的任何信息：

use ctxpp to show me everything involved in account authentication

use ctxpp to find where FetchAccount is defined and what calls it

use ctxpp_blast_radius to tell me what breaks if I change the Account struct

______________________________________________________________________

Olama集成

ctx++使用 奥拉玛 用于基于嵌入的语义搜索。默认模型为 bge-m3 （BAAI的BGE-M31024维），这是通过与真实代码库上的多个模型进行面对面质量基准测试而选择的。

ollama pull bge-m3

ctx++自动检测Ollama开启 localhost:11434 在启动时。如果Ollama未运行，ctx++将退回到仅关键字搜索并打印警告。

为了使用不同的嵌入模型（例如。， all-minilm 以牺牲一些搜索质量为代价进行更快的索引）：

"environment": {
  "CTXPP_PROJECT": "/path/to/your/project",
  "CTXPP_OLLAMA_MODEL": "all-minilm"
}

______________________________________________________________________

AWS基岩集成

对于没有本地GPU的环境，ctx++可以使用 亚马逊Titan文本嵌入V2 通过AWS Bedrock。质量与Ollama/bge-m3默认值相当（kubernetes基准测试为4.7/5对4.8/5）。

先决条件：通过配置AWS凭据 ~/.aws/credentials, AWS_PROFILE，或IAM角色。身份需要 bedrock:InvokeModel 许可 amazon.titan-embed-text-v2:0.

集 CTXPP_EMBED_BACKEND=bedrock 以及以下env变量：

开源代码 (opencode.json 在项目根目录中）：

{
  "mcp": {
    "ctxpp": {
      "type": "local",
      "command": ["ctxpp", "mcp"],
      "enabled": true,
      "environment": {
        "CTXPP_PROJECT": "/path/to/your/project",
        "CTXPP_EMBED_BACKEND": "bedrock",
        "CTXPP_BEDROCK_REGION": "us-east-1",
        "CTXPP_BEDROCK_MODEL": "amazon.titan-embed-text-v2:0",
        "CTXPP_BEDROCK_DIMS": "1024",
        "CTXPP_EMBED_CONCURRENCY": "100"
      }
    }
  }
}

克劳德代码 (.mcp.json):

{
  "mcpServers": {
    "ctxpp": {
      "command": "ctxpp",
      "args": ["mcp"],
      "env": {
        "CTXPP_PROJECT": "/path/to/your/project",
        "CTXPP_EMBED_BACKEND": "bedrock",
        "CTXPP_BEDROCK_REGION": "us-east-1",
        "CTXPP_BEDROCK_MODEL": "amazon.titan-embed-text-v2:0",
        "CTXPP_BEDROCK_DIMS": "1024",
        "CTXPP_EMBED_CONCURRENCY": "100"
      }
    }
  }
}

光标/风帆 (.cursor/mcp.json 或 .windsurf/mcp.json):

{
  "mcpServers": {
    "ctxpp": {
      "command": "ctxpp",
      "args": ["mcp"],
      "env": {
        "CTXPP_PROJECT": "/path/to/your/project",
        "CTXPP_EMBED_BACKEND": "bedrock",
        "CTXPP_BEDROCK_REGION": "us-east-1",
        "CTXPP_BEDROCK_MODEL": "amazon.titan-embed-text-v2:0",
        "CTXPP_BEDROCK_DIMS": "1024",
        "CTXPP_EMBED_CONCURRENCY": "100"
      }
    }
  }
}

或者从命令行进行初始索引：

export CTXPP_EMBED_BACKEND=bedrock
export CTXPP_BEDROCK_REGION=us-east-1
export CTXPP_BEDROCK_MODEL=amazon.titan-embed-text-v2:0
export CTXPP_BEDROCK_DIMS=1024
export CTXPP_EMBED_CONCURRENCY=100   # increase to 200 for large repos
ctxpp index --path /path/to/your/project

与Ollama的权衡：

|| Ollama（本地GPU）|基岩| |--|--|--| |每个查询的嵌入延迟|~25ms|100-460ms| |索引时间（kubernetes，318K符号）|47m|~7.5h| |需要GPU |是|否| |成本|免费（本地）| AWS API定价| |水平缩放|受GPU限制|高（100-200并发）| |质量（kubernetes基准测试）|4.8/5 |4.7/5|

Bedrock是CI/CD管道、云托管代理或没有GPU的开发人员机器的正确选择。对于使用GPU的交互式开发，Ollama更快。

______________________________________________________________________

OpenAI兼容嵌入集成

ctx++还可以使用任何公开OpenAI的提供者 POST /v1/embeddings API这包括OpenAI、OpenAI兼容代理、vLLM、LiteLLM、LocalAI和Ollama的OpenAI兼容端点。

集 CTXPP_EMBED_BACKEND=openai 并配置：

• CTXPP_OPENAI_URL
• CTXPP_OPENAI_MODEL
• CTXPP_OPENAI_DIMS
• CTXPP_OPENAI_API_KEY （本地未经身份验证的服务器可选）

OpenAI托管嵌入的示例：

{
  "mcpServers": {
    "ctxpp": {
      "command": "ctxpp",
      "args": ["mcp"],
      "env": {
        "CTXPP_PROJECT": "/path/to/your/project",
        "CTXPP_EMBED_BACKEND": "openai",
        "CTXPP_OPENAI_URL": "https://api.openai.com",
        "CTXPP_OPENAI_MODEL": "text-embedding-3-small",
        "CTXPP_OPENAI_DIMS": "1536",
        "CTXPP_OPENAI_API_KEY": "${OPENAI_API_KEY}"
      }
    }
  }
}

Ollama的OpenAI兼容端点示例：

export CTXPP_EMBED_BACKEND=openai
export CTXPP_OPENAI_URL=http://localhost:11434
export CTXPP_OPENAI_MODEL=bge-m3
export CTXPP_OPENAI_DIMS=1024
ctxpp index --path /path/to/your/project

此后端仅可选择加入。自动检测仍然更喜欢TEI，然后是Ollama，然后是捆绑回退。

______________________________________________________________________

配置

所有配置都是通过环境变量进行的。

______________________________________________________________________

CLI参考

ctxpp index [--path/-p 
] [--force]  Index or reindex a project (default: $CTXPP_PROJECT or current directory)
ctxpp backfill [--path/-p 
]  Re-embed symbols missing embedding vectors
ctxpp mcp                          Start the MCP server over stdio
ctxpp version                      Print version

______________________________________________________________________

建筑

ctx++是用Go编写的，基于以下内容构建：

• 去找树保姆 --原生C树保姆绑定，用于跨所有支持的语言进行快速、准确的AST解析
• SQLite 通过 modernc.org/sqlite （纯Go，无CGO），FTS5用于全文搜索，暴力余弦相似度用于向量搜索
• 奥拉玛 用于嵌入生成（默认模型： bge-m3)
• MCP-SDK 用于基于stdio的MCP传输

该指数位于单一 .ctxpp/index.db 每个项目的文件。模式跟踪文件、符号、嵌入、调用边和导入边。所有查询都会命中索引列——没有全表扫描，也没有将整个索引加载到内存中。

看 PRD.md 用于完整的架构和设计决策。

______________________________________________________________________

特征遍历的工作原理

当你问的时候 ctxpp_feature_traverse 关于一个符号（例如。 "HandleLogin"):

1. 关键字搜索在索引中找到具有该确切名称的符号
2. 调用图通过BFS从每个种子向外遍历——这个函数调用什么？这些函数叫什么？
3. 结果以BFS顺序返回（种子优先，然后是直接被调用者，然后是传递被调用者），直到配置的深度（默认值：3跳）

这为您提供了以符号为根的完整调用树，有助于理解函数的编排，而无需手动读取每个文件。使用 ctxpp_blast_radius 对于相反的方向：这个函数叫什么？

______________________________________________________________________

许可证

麻省理工学院