使用说明

ctx++

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

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

为什么选择ctx++

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

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

工具

工具	说明
`ctxpp_index`	索引或重新索引代码库。安装后运行一次；增量更新会自动发生。
`ctxpp_search`	按标识符名称（关键字）或自然语言（语义）搜索。返回带有文件路径和行号的符号定义。
`ctxpp_file_skeleton`	返回包含签名和行范围的文件中的所有符号，而不读取全文。了解文件的API表面的廉价方法。
`ctxpp_feature_traverse`	给定一个确切的符号名称，通过BFS向外遍历调用图来返回相关符号。自动生成的功能中心。
`ctxpp_blast_radius`	给定一个符号，返回代码库中引用它的每个位置。回答“如果我更改了这个符号，会有什么问题？”

支持的语言

语言	扩展名	提取的符号
去吧	`.go`	函数、方法、结构、接口、类型、常量、变量
Java `.java`	类、接口、枚举、方法、构造函数、字段
Kotlin	`.kt`, `.kts`	函数、方法、类、接口、属性、导入
JavaScript	`.js`, `.mjs`, `.cjs`, `.jsx`	函数、类、方法、箭头函数
TypeScript	`.ts`, `.tsx`, `.mts`, `.cts`	函数、类、接口、类型别名、枚举
生锈	`.rs`	函数、结构、枚举、特征、impl方法、类型别名
C `.cs`	类、接口、方法、字段、导入
C `.c`, `.h`	函数、结构、枚举、类型定义、类函数宏
C `.cpp`, `.cc`, `.cxx`, `.hpp`, `.hh`, `.hxx`	函数、方法、类、结构、枚举、命名空间、模板
SQL	`.sql`	表、视图、索引、函数、过程、触发器
Markdown	`.md`, `.mdx`	标题（作为章节）
HTML	`.html`, `.htm`	标题、脚本/样式块
壳牌	`.sh`, `.bash`, `.zsh`, `.dash`	功能
原蟾蜍	`.proto`	消息、服务、RPC、枚举
HTTP	`.http`, `.rest`	命名请求
文本/配置	`.txt`, `.env`, `Makefile`, `Dockerfile`, `LICENSE`等等。	文件级文档符号

想添加另一种语言吗？看 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，然后是捆绑回退。

配置

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

变量	默认值	描述
`CTXPP_PROJECT`	`.`	指向项目根目录的索引路径
`CTXPP_OLLAMA_URL`	`http://localhost:11434`	API终点
`CTXPP_OLLAMA_MODEL`	`bge-m3`	Ollama嵌入模型
`CTXPP_EMBED_BACKEND`	（自动检测）	嵌入后端： `auto`, `ollama`, `tei`, `openai`, `bedrock`，或 `bundled`
`CTXPP_OPENAI_URL`	`https://api.openai.com`	与OpenAI兼容的嵌入API基础URL
`CTXPP_OPENAI_MODEL`	（必须与 `openai`)	OpenAI兼容的嵌入模型
`CTXPP_OPENAI_API_KEY`	（可选）	OpenAI兼容提供商的承载令牌
`CTXPP_OPENAI_DIMS`	（必须与 `openai`)	为选定的OpenAI兼容模型嵌入维度
`CTXPP_WORKERS`	CPU数量	用于初始索引的并行工作器
`CTXPP_EMBED_CONCURRENCY`	`10`	最大并发嵌入请求（主要是基岩）

CLI参考

ctxpp index [--path/-p <path>] [--force]  Index or reindex a project (default: $CTXPP_PROJECT or current directory)
ctxpp backfill [--path/-p <path>]  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"):

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

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

许可证

麻省理工学院

使用说明

ctx++

为什么选择ctx++

工具

支持的语言

先决条件

安装

快速开始

1.为你的项目建立索引

2.添加到MCP配置中

3.使用它

Olama集成

AWS基岩集成

OpenAI兼容嵌入集成

配置

CLI参考

建筑

特征遍历的工作原理

许可证

相关 MCP

实时文档检索服务

代码索引分析工具

YouTube字幕提取服务

代码运行服务

代码分析服务器

GitHub仓库解析工具