内容
# 项目上下文 MCP
[](https://www.npmjs.com/package/project-context-mcp)
[](LICENSE)
[](https://nodejs.org/)
`project-context-mcp` 是一个基于证据的本地 MCP 服务器和 CLI，用于导航代码库。它执行确定性的状态检查、精确和语义搜索、有界源代码读取、可选的源代码支持的跟踪适配器和显式的交接访问。
它旨在保持源代码证据本地：该工具仅与您配置的本地或自我托管的服务通信。搜索结果包括源代码路径和行范围，以便代理或开发人员可以验证底层代码。
## 功能
| 功能 | 描述 |
| --- | --- |
| 精确搜索 | 快速、确定性的 `rg` 搜索，配置源代码和排除规则。 |
| 语义搜索 | 项目隔离的嵌入，在持久的本地向量存储中，默认情况下针对当前文件哈希验证。 |
| 图形跟踪 | 可选的语言适配器返回源代码支持的调用者、被调用者、继承和实现关系。 |
| 有界读取 | 仅读取配置的项目文件，并返回有限的源代码范围。 |
| 交接 | 列表、读取、创建和更新显式的 Markdown 交接文档。 |
## 快速入门
全局安装 CLI：
```sh
npm install --global project-context-mcp
pctx --help
```
`pctx` 是简短的 CLI 别名。`project-context-mcp` 仍然可用作完全限定的命令。
要启用 C# 跟踪，请在核心旁边安装可选的 C# 适配器：
```sh
npm install --global project-context-mcp-csharp
```
然后在要检查的项目中添加 `.project-context.yml` 文件，并运行状态检查：
```sh
pctx status /path/to/project
pctx index /path/to/project
pctx search /path/to/project "session restore" auto code 10
```
在 Windows 上，引用包含空格的路径：
```powershell
pctx status 'C:\work\my project'
```
### 连接 MCP 客户端
在客户端配置中添加此标准 MCP 服务器条目：
```json
{
"mcpServers": {
"project-context-mcp": {
"command": "project-context-mcp",
"args": ["serve", "--mcp"]
}
}
}
```
服务器公开 `context_status`、`context_search`、`context_read`、`context_trace` 和 `context_handoff_*` 工具。首先使用 `context_status` 确认选定的项目和本地依赖项。
## 要求
- Node.js 20 或更高版本
- `rg`（ripgrep）用于精确搜索
- 为语义搜索配置的 Ollama 嵌入模型
核心包在没有 .NET 或语言适配器的情况下运行状态、精确搜索和语义搜索。C# 跟踪还需要 .NET 8 和 `project-context-mcp-csharp` 适配器包。
语义搜索需要 Ollama 嵌入模型，但默认情况下使用持久的本地向量存储，不需要 Milvus。精确搜索、有界读取、状态检查和交接访问不需要 Ollama 或 Milvus。`context_trace` 不需要任一服务。
## 跟踪适配器
`context_trace` 和 `project-context-mcp trace` 使用已安装的跟踪适配器。核心发现内置的 C# 候选项和 `PROJECT_CONTEXT_TRACE_ADAPTERS` 中用逗号分隔的包名称。它选择源代码扩展与项目匹配的单个适配器，或者在多个适配器匹配时需要 `language`。它从不扫描 `node_modules` 或自动安装包。
如果没有兼容的适配器，显式跟踪会报告安装提示。自动图形路由在跟踪不可用或不明确时回退到语义搜索。在 CLI 跟踪命令中，在 `max-results` 之后传递可选的语言，或在 `context_trace` 中传递可选的 `language` 字段。
## 项目配置
配置是可选的。当您要缩小索引源代码范围或添加项目特定的排除项时，在目标项目根目录中创建 `.project-context.yml`。下面的示例仅包含项目拥有的路径；它不包括用户主目录、帐户、令牌或机器特定设置。
```yaml
version: 1
sources:
code: [src]
documents: [README.md, docs]
exclude:
- node_modules/**
- .git/**
- "**/*.dll"
- "**/*.keystore"
```
### 语义搜索服务
语义搜索需要您为项目操作和配置 Ollama 嵌入模型。默认情况下，向量存储是本地且持久的，因此不需要 Milvus 服务。
```yaml
services:
ollama:
embeddingModel: <installed-embedding-model>
```
### Milvus 选择
仅当您明确选择时才使用 Milvus。配置您操作的 Milvus 服务的地址：
```yaml
services:
vectorStore:
backend: milvus
milvus:
address: <milvus-address>
```
为了保持向后兼容，包含 `services.milvus` 但不设置 `services.vectorStore.backend` 的配置仍选择 Milvus。当两者都存在时，显式的 `services.vectorStore.backend` 值优先。
切换向量存储后端需要重新索引。旧后端中的现有数据不会自动删除或迁移。
### 可选交接文档
默认情况下，交接文档被禁用，因为它们存在于用户级存储中。仅当您希望项目索引其自己的交接文档时才启用它们，并选择在您的机器上唯一的项目 slug：
```yaml
sources:
handoff:
enabled: true
projectSlug: example-project
```
在索引之前，将所有包含凭据、生成或第三方路径添加到 `exclude`。精确搜索、读取、索引、语义证据和 C# 跟踪都强制执行相同的策略。索引器从不写入项目源代码文件。
`PROJECT_CONTEXT_MILVUS_TOKEN` 启用身份验证的 Milvus 访问。`PROJECT_CONTEXT_STATE_ROOT` 和 `PROJECT_CONTEXT_HANDOFF_ROOT` 重定向本地状态和交接存储以进行测试或自动化；典型的安装不需要它们。
## CLI 参考
| 命令 | 用途 |
| --- | --- |
| `project-context-mcp status [project-root]` | 检查配置、依赖项和索引新鲜度。 |
| `project-context-mcp index <project-root> [--rebuild]` | 创建或增量更新语义索引。 |
| `project-context-mcp watch <project-root> [interval-ms]` | 使用文件系统事件和安全扫描保持索引最新。 |
| `project-context-mcp search <project-root> <query> [mode] [scope] [max-results]` | 在 `auto`、`exact`、`graph` 或 `semantic` 模式下搜索。 |
| `project-context-mcp trace <project-root> <symbol> <direction> [max-results] [language]` | 使用已安装的语言适配器跟踪关系。 |
| `project-context-mcp read <project-root> <path> [start-line] [end-line]` | 读取允许的有界文件范围。 |
| `project-context-mcp handoff save|update ...` | 创建或更新显式交接 Markdown。 |
| `project-context-mcp serve --mcp` | 启动 stdio MCP 服务器。 |
## 开发
```sh
git clone https://github.com/E-Hae/project-context.git
cd project-context
npm ci
npm run verify
npm --workspace adapters/csharp run verify
npm pack --dry-run
```
`npm run verify` 在没有 .NET 的情况下验证语言中立的核心。C# 适配器单独构建和验证其 Roslyn 工作线程。核心 tarball 包括 JavaScript 依赖项通知，但不包括工作线程和 Microsoft 二进制文件；C# 适配器 tarball 包括其工作线程和 Microsoft 第三方通知。
## 迁移到 2.0.0
`ask` CLI 命令和 `services.ollama.answerModel` 设置已被删除。使用具有 `context_search`、`context_read` 和 `context_trace` 的 MCP 客户端组合答案，并从现有项目配置中删除 `answerModel`。
## 许可证
项目上下文 MCP 采用 [MIT 许可证](LICENSE)。核心 JavaScript 依赖项通知在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 中；可选的 C# 适配器携带其捆绑的 Microsoft 工作线程依赖项的通知。
