内容
# MCPedia
**本地代码库 RAG + MCP 服务器，用于您的代码仓库。**
MCPedia 将本地代码仓库转变为可搜索的知识库。它将源代码和文档索引到本地 LanceDB 存储中，通过混合搜索进行检索，通过本地或云 LLMs 回答问题，并将相同的代码仓库知识暴露为适用于 VS Code、Claude Code、MCP Inspector 等其他 MCP 客户端的 MCP 服务器。
MCPedia 的名称代表 **MCP + 百科全书**：一个本地的、以代码仓库为范围的百科全书，AI 助手可以通过模型上下文协议查询。
---
## 功能
- **本地代码仓库索引**，存储在 `.rag/store.lance` 下。
- **语法感知代码块**，适用于支持的语言，使用 Tree-sitter。
- **递归标记感知分割**，适用于 Markdown、散文、提取的 PDF/Office 文本、不支持的文件和超大代码段。
- **PDF 和 Office/OpenDocument ingestion**，适用于 `.pdf`、`.docx`、`.pptx`、`.xlsx`、`.odt`、`.ods`、`.odp` 和 `.rtf` 文件，可选使用 LibreOffice 驱动的备用方案，适用于旧版 `.doc`、`.ppt` 和 `.xls`。
- **混合检索**，结合向量搜索、全文本搜索和互惠排名重新排序。
- **官方 AI SDK**，适用于 Ollama、OpenAI、Anthropic 和 Gemini，在支持的情况下。
- **MCP stdio 服务器**，具有唯一的代码仓库特定工具名称，用于干净的跟踪。
- **多个本地 MCPedia 服务器**，一台机器上每个代码仓库一个。
- **Windows 诊断和修复**，适用于已知的 Tree-sitter 本机绑定问题。
MCPedia 不是云服务。索引是本地的。只有在您为嵌入或答案配置云提供商时，才会联系云提供商。
---
## 要求
- Node.js **22 或更高版本**
- npm
- Ollama，用于默认的完全本地设置
- Windows 用户：最新的 **Microsoft Visual C++ v14 Redistributable x64**，用于原生 Tree-sitter 解析
默认本地模型：
```powershell
ollama pull qwen3-embedding:8b
ollama pull gemma4:12b
```
MCPedia 与 **Ollama** 配合使用开箱即用。首先安装 Ollama，启动它，然后拉取上述两个模型，然后在运行 `mcpedia index` 或 `mcpedia ask` 与默认配置之前。OpenAI、Anthropic 和 Gemini 是您可以稍后在 `.rag/config.yaml` 中启用的可选替代方案。
---
## 从 npm 安装
发布后，用户应全局安装 MCPedia：
```powershell
npm install -g mcpedia
mcpedia --version
```
更新后：
```powershell
npm update -g mcpedia
```
卸载：
```powershell
npm uninstall -g mcpedia
```
---
## 快速入门
首先，确保已安装 Ollama 并且默认模型可用：
```powershell
ollama pull qwen3-embedding:8b
ollama pull gemma4:12b
```
然后，索引您要用作知识库的代码仓库：
```powershell
cd C:\Projects\MyKnowledgeBase
mcpedia init
mcpedia index
mcpedia search "where is validation implemented?"
mcpedia ask "explain the authentication flow"
```
为当前代码仓库启动 MCP 服务器：
```powershell
mcpedia mcp
```
该命令似乎正在等待。这是预期的：MCP 客户端通过 stdin/stdout 与其通信。
---
## 项目布局
在 `mcpedia init` 之后：
```text
MyKnowledgeBase/
├── .rag/
│ ├── config.yaml # 项目特定配置
│ └── store.lance/ # 本地 LanceDB 索引，在 mcpedia index 之后
└── ...您的源文件
```
每个代码仓库拥有自己的 `.rag` 目录。这将索引、提供商设置和 MCP 身份在多个本地项目中分开。
不要提交 `.rag/`。
推荐的 `.gitignore` 条目：
```gitignore
.rag/
```
---
## 我应该使用哪个命令？
| 任务 | 命令 |
|---|---|
| 创建 `.rag/config.yaml` | `mcpedia init` |
| 诊断 Windows Tree-sitter/本机问题 | `mcpedia doctor` |
| 列出、检测或预下载语法 | `mcpedia grammars` |
| 构建或重建本地索引 | `mcpedia index` |
| 打印实时代码仓库树 | `mcpedia tree` |
| 搜索索引代码/文档 | `mcpedia search` |
| 使用检索的上下文询问 LLM | `mcpedia ask` |
| 启动 MCP 服务器 | `mcpedia mcp` 从项目文件夹，或 `mcpedia mcp <path>` 在客户端配置中 |
在诊断发现、分块、嵌入或提供商调用时使用详细模式：
```powershell
mcpedia --verbose index
```
---
## 命令参考
### `mcpedia init`
**此命令存在的原因：** 创建每个项目的 `.rag/config.yaml` 文件。MCPedia 在代码仓库内存储代码仓库设置，而不是全局存储。
```powershell
mcpedia init
```
注意：
- 不会覆盖现有的配置文件。
- 生成一个包含所有公共选项的完整 YAML 文件。
- 在注册多个 MCP 服务器之前，请编辑 `mcp.name`、`mcp.title`、`mcp.description` 和 `mcp.instructions`。
安全重新生成：
```powershell
Copy-Item .rag\config.yaml .rag\config.backup.yaml
Remove-Item .rag\config.yaml
mcpedia init
```
---
### `mcpedia doctor`
**此命令存在的原因：** 诊断和修复 Windows x64 Tree-sitter 本机绑定问题。
```powershell
mcpedia doctor --check-only
mcpedia doctor
```
选项：
| 选项 | 含义 |
|---|---|
| `--check-only` | 仅检查，不修改文件 |
在受影响的 Windows 包上，`doctor` 检查 Tree-sitter 语言包二进制文件是否导入 `node.dll` 而不是 `node.exe`。如果需要，它会创建备份，仅修补确切的 PE 导入，在新的 Node 子进程中验证，并在验证失败时恢复原始文件。
禁用自动本机修复：
```powershell
$env:MCPEDIA_DISABLE_NATIVE_REPAIR = "1"
```
---
### `mcpedia grammars`
**此命令存在的原因：** 管理用于代码感知分块的 Tree-sitter 语法。
```powershell
mcpedia grammars --detect src\Program.cs
mcpedia grammars csharp typescript python
mcpedia grammars --list
mcpedia grammars --all
```
选项：
| 选项 | 含义 |
|---|---|
| `--detect <path>` | 显示文件路径的规范语法 |
| `--list` | 从语言包中列出规范语法名称 |
| `--all` | 下载/验证完整的语法包 |
示例：
```powershell
mcpedia grammars --detect C:\Projects\MyKnowledgeBase\src\Application\Service.cs
mcpedia grammars csharp
```
预期检测：
```text
C:\Projects\MyKnowledgeBase\src\Application\Service.cs: csharp
```
---
### `mcpedia index`
**此命令存在的原因：** 构建或重建本地可搜索索引。
```powershell
mcpedia index
mcpedia --verbose index
```
管道:
1. 使用 `files.include`、`files.exclude` 和 `.gitignore` 规则发现文件；
2. 跳过二进制、超大、生成、秘密和低信号文件；
3. 在可能的情况下，使用 Tree-sitter 结构化分割源代码；
4. 在需要时，退回到递归标记感知分割；
5. 使用配置的嵌入提供商嵌入块；
6. 将块和向量写入 LanceDB；
7. 为混合搜索构建全文/向量索引。
更改这些设置需要重新构建：
- 嵌入提供商/模型/维度；
- 文件包含/排除规则；
- 分块大小或重叠；
- 语言覆盖；
- 存储路径或表名。
显式重建：
```powershell
Remove-Item .rag\store.lance -Recurse -Force -ErrorAction SilentlyContinue
mcpedia index
```
---
### `mcpedia tree`
**此命令存在的原因：** 使用与索引相同的发现规则打印实时代码仓库树。它不需要索引。
```powershell
mcpedia tree
mcpedia tree src
mcpedia tree src --max-depth 3
mcpedia tree "C:\Projects\MyKnowledgeBase\src" --max-depth 4 --absolute-paths
```
选项：
| 选项 | 含义 |
|---|---|
| `<folderPath>` | 项目内可选的相对路径或绝对路径 |
| `--max-depth <n>` | 可选的深度限制；省略时表示无限制 |
| `--absolute-paths` | 为每个条目打印绝对路径 |
树输出以解析位置开始，例如：
```text
项目根目录：C:\Projects\MyKnowledgeBase
树路径：C:\Projects\MyKnowledgeBase\src
```
拒绝绝对路径超出项目根目录以外的路径。
---
### `mcpedia search`
**此命令存在的原因：** 在不调用答案模型的情况下检索相关索引块。
```powershell
mcpedia search "authentication middleware"
mcpedia search "where is tenant validation?" --top-k 12
```
选项：
| 选项 | 含义 |
|---|---|
| `--top-k <n>` | 最终结果的数量 |
当您想要引用、文件路径和源代码片段而不产生成本时，请使用 `search`。
---
### `mcpedia ask`
**此命令存在的原因：** 检索上下文，将其发送到配置的 LLM，并打印带有来源的接地答案。
```powershell
mcpedia ask "How does user authentication work?"
```
`ask` 使用：
- `embedding.*` 进行检索；
- `llm.*` 进行答案生成。
如果您只需要源代码片段，请改用 `mcpedia search`。
---
### `mcpedia mcp`
**此命令存在的原因：** 为索引的代码仓库启动_stdio MCP 服务器。MCP 客户端启动此命令，并通过 stdin/stdout 与其通信。
```powershell
# 使用当前目录作为项目根目录。
mcpedia mcp
# 推荐用于 VS Code、Claude Code 和多服务器配置：显式绑定服务器。
# 对于 MCP Inspector，请在项目内打开 PowerShell 并运行纯 `mcpedia mcp`。
mcpedia mcp C:\Projects\MyKnowledgeBase
# 等效终端形式。
mcpedia mcp --root C:\Projects\MyKnowledgeBase
```
参数和选项：
| 形式 | 含义 |
|---|---|
| `mcpedia mcp` | 提供当前工作目录。适用于快速本地测试。 |
| `mcpedia mcp <path>` | 提供位于 `<path>` 的项目。建议在 MCP 客户端配置中使用。 |
| `mcpedia mcp --root <path>` | 等效显式标志。在普通终端中有用，但某些启动器对嵌套 `--flags` 的处理较差。 |
环境替代：
```powershell
$env:MCPEDIA_ROOT = "C:\Projects\MyKnowledgeBase"
mcpedia mcp
```
为什么项目路径很重要：如果两个 MCPedia 服务器都注册为 `mcpedia mcp`，则两个服务器都可以从相同的客户端工作目录启动，并似乎提供相同的项目。为每个 MCPedia 注册提供一个显式项目路径。
手动运行此命令仅用于确认它保持活动。按 `Ctrl+C` 停止它。
---
## 配置要点
`mcpedia init` 编写一个完整的配置：
```text
.rag/config.yaml
```
YAML 值优先。当 `apiKey` 或 `baseUrl` 为 `null` 时，MCPedia 检查环境变量，然后检查提供商默认值。
### API 密钥
```yaml
embedding:
provider: openai
apiKey: null # null 读取 OPENAI_API_KEY
llm:
provider: anthropic
apiKey: null # null 读取 ANTHROPIC_API_KEY
```
内联密钥也有效，但不应提交：
```yaml
embedding:
apiKey: "sk-your-key"
```
支持的变量：
| 提供商 | API 密钥 | 基础 URL |
|---|---|---|
| Ollama | `OLLAMA_API_KEY` | `OLLAMA_HOST` |
| OpenAI | `OPENAI_API_KEY` | `OPENAI_BASE_URL` |
| Anthropic | `ANTHROPIC_API_KEY` | `ANTHROPIC_BASE_URL` |
| Gemini | `GEMINI_API_KEY`，然后 `GOOGLE_API_KEY` | `GEMINI_BASE_URL` |
### 嵌入
默认精度优先的本地设置：
```yaml
embedding:
provider: ollama
model: qwen3-embedding:8b
dimension: 4096
baseUrl: http://localhost:11434
apiKey: null
batchSize: 8
timeoutMs: 180000
maxRetries: 3
```
较低资源替代方案：
```yaml
# 平衡
model: qwen3-embedding:4b
dimension: 2560
batchSize: 8
```
```yaml
# 轻量级
model: qwen3-embedding:0.6b
dimension: 1024
batchSize: 16
```
更改嵌入模型或维度需要 `mcpedia index`.
### LLM 答案
默认本地答案模型：
```yaml
llm:
provider: ollama
model: gemma4:12b
maxTokens: 8192
temperature: 0.2
timeoutMs: 120000
maxRetries: 3
```
云示例：
```yaml
llm:
provider: anthropic
model: claude-sonnet-4-20250514
apiKey: null
```
```yaml
llm:
provider: openai
model: gpt-4.1
apiKey: null
```
### 文件发现
```yaml
files:
include:
- "**/*"
exclude:
- "**/node_modules/**"
- "**/dist/**"
- "**/.gitignore"
- "**/package-lock.json"
- "**/.env"
extensions: []
respectGitignore: true
followSymlinks: false
maxFileSizeBytes: 1000000
documentMaxFileSizeBytes: 50000000```
`extensions: []` 索引所有检测到的文本文件和支持的文档文件。支持的文档格式被提取为纯文本后进行分块：`.pdf`、`.docx`、`.docm`、`.dotx`、`.dotm`、`.pptx`、`.pptm`、`.ppsx`、`.ppsm`、`.potx`、`.potm`、`.xlsx`、`.xlsm`、`.xltx`、`.xltm`、`.odt`、`.ott`、`.ods`、`.ots`、`.odp`、`.otp` 和 `.rtf`。旧版二进制 Office 文件 `.doc`、`.ppt` 和 `.xls` 也被检测到，并在 `PATH` 上安装 LibreOffice 或 `soffice` 时被提取。
支持的文档文件仍在 `files.extensions` 包含代码/文本允许列表时被发现，因此像 `[".cs", ".md"]` 的现有配置不会意外隐藏 PowerPoint 文件。 使用 `files.exclude` 退出文档文件夹或文件模式。
```yaml
files:
extensions: [".cs", ".csproj", ".md", ".json"]
maxFileSizeBytes: 1000000
documentMaxFileSizeBytes: 50000000
```
为什么 MCPedia 默认排除元数据和生成的文件：
- `.gitignore`、lockfiles、构建输出、日志、源映射和本地机密通常对代码理解的信号较低；
- 排除它们降低了嵌入成本、索引大小和噪声结果；
- `.env.example` 仍可索引，因为它通常是有用的文档；
- PDF 和 Office 文件使用 `documentMaxFileSizeBytes`，因此常见的多兆字节的幻灯演示和手册不会被较小的源代码大小限制跳过；
- `.gitignore` 文件本身不会被嵌入，但其规则仍在 `respectGitignore: true` 时应用；
- 每个排除项都在 `.rag/config.yaml` 中可见且可移除。
### 分块
```yaml
chunking:
chunkSize: 2024
chunkOverlap: 256
encoding: o200k_base
codeAware: true
separators: []
languageOverrides: {}
```
`separators: []` 使用 MCPedia 的内置语义分隔符顺序。要自定义，请替换它与您自己的列表：
```yaml
chunking:
separators:
- "\n## "
- "\n### "
- "\n\n"
- "\n"
- ". "
- " "
- "" # 个别字符作为最终的后备
```
语言覆盖示例：
```yaml
chunking:
languageOverrides:
".foo": typescript
"SpecialFile": python
"src/generated/Legacy.cs": text
```
使用 `text` 强制递归文本分割一个文件或模式。
### 搜索
```yaml
search:
topK: 8
overfetch: 4
createVectorIndexThreshold: 256```
候选计数之前：
```text
topK × overfetch
```
### MCP 身份
使用有意义的名称为每个代码仓库，以便跟踪清晰显示使用了哪个知识库：
```yaml
mcp:
name: my-knowledge-base
title
description: Search and inspect this project's indexed code and documentation.
instructions: Use this server only for questions about this project. Keep these results separate from other connected project servers.
namespaceTools: true
toolNamePrefix: auto
tools:
search: true
tree: true
maxResults: 0
```
启用命名空间后，工具显示为：
```text
my_knowledge_base_search
my_knowledge_base_tree
```
---
## 分块工作原理
### Tree-sitter 结构化策略
对于支持的源代码文件，MCPedia 更倾向于使用语法感知的块而不是任意文本切割。
过程：
1. 从语言包目录中检测语言。
2. 使用 Tree-sitter 分析文件。
3. 遍历命名语法节点，例如类、方法、函数、导入和声明。
4. 使用配置的标记器测量每个节点。
5. 将相邻的兄弟节点打包在一起，同时保持在 `chunkSize` 以下。
6. 如果必要，递归到超大块，例如一个非常大的类。
7. 仅对无法结构化分割的超大叶子使用递归文本分割。
8. 存储文件路径、行范围、语言、策略和最佳努力符号名称。
这样可以保持函数、类和声明在一起，通常可以提高检索质量和跟踪可读性。
### 递归标记感知文本策略
MCPedia 对 Markdown、散文、支持语言不足、解析失败和超大语法叶子使用此策略。
过程：
1. 使用 Tiktoken 计数标记。
2. 从配置列表中选择第一个有用的分隔符。
3. 按该分隔符分割文本。
4. 仅递归分割仍然过大的部分。
5. 继续使用更细的分隔符，例如标题、段落、行、标点符号、单词，最后是单个字符作为最终的后备。
6. 贪婪地合并小块，直到每个块接近 `chunkSize`。
7. 将重叠向前传递，保持完整的上一个块，直到大约 `chunkOverlap` 个标记。
8. 删除空白块。
重要细节：
- 重叠是近似的，因为 MCPedia 保留了有意义的块而不是切割确切的标记窗口。
- 自定义 `separators` 列表取代内置列表。
- 更大的块可以改善广泛的上下文，但可能会降低精确检索。
- 更小的块可以改善精确度，但可能会分割重要的上下文。
---
## 在一个系统上运行多个 MCP 服务器
MCPedia 设计用于在同一台机器上运行多个本地知识库服务器。一个好的设置是 **每个存储库一个 MCPedia 服务器**。
每个存储库都应该有自己的：
```text
.rag/config.yaml
.rag/store.lance
```
示例存储库：
```text
C:\Projects\MyKnowledgeBase
C:\Projects\BillingApi
C:\Projects\ProductDocs
```
每个存储库还应该在其自己的 `.rag/config.yaml` 中具有唯一的 MCP 身份：
```yaml
mcp:
name: my-knowledge-base
title: MyKnowledgeBase
description: 搜索和检查该项目的索引代码和文档。
instructions: 仅将此服务器用于有关此项目的疑问。
namespaceTools: true
toolNamePrefix: auto
```
启用 `namespaceTools: true` 后，跟踪和 MCP 用户界面会显示项目特定的工具名称：
```text
my_knowledge_base_search
my_knowledge_base_tree
```
对于另一个存储库：
```yaml
mcp:
name: billing-api-knowledge
title: Billing API 知识
namespaceTools: true
toolNamePrefix: auto
```
工具变为：
```text
billing_api_knowledge_search
billing_api_knowledge_tree
```
这使得查看 AI 调用哪个知识库变得更加容易。
---
## 何时传递项目根目录
`mcpedia mcp` 必须知道哪个存储库包含 `.rag/config.yaml` 和 `.rag/store.lance`。
MCPedia 按以下顺序选择项目根目录：
1. 位置根目录：`mcpedia mcp C:\Projects\MyKnowledgeBase`。
2. 选项根目录：`mcpedia mcp --root C:\Projects\MyKnowledgeBase`。
3. 环境变量：`MCPEDIA_ROOT`。
4. 当前工作目录。
推荐规则：
```text
一个 MCPedia 服务器 = 一个唯一的客户端注册名称 + 一个明确的项目根目录 + 一个唯一的 mcp.name。
```
### 在多 MCP 设置中使用明确的根目录
当一个客户端注册多个 MCPedia 服务器时，请使用项目路径：
```powershell
mcpedia mcp C:\Projects\MyKnowledgeBase
mcpedia mcp C:\Projects\BillingApi
```
建议使用位置根目录形式，因为它避免了工具已经具有自己的标志的嵌套命令行标志解析问题。
**不要** 将多个服务器注册为仅 `mcpedia mcp`，除非每个客户端条目还提供不同的工作目录。否则，它们可能会解析相同的 `.rag/config.yaml` 并显示为重复项。
### 何时根目录是可选的
仅当您有意为当前目录提供服务时，根目录才是可选的：
```powershell
cd C:\Projects\MyKnowledgeBase
mcpedia mcp
```
这对于快速测试是可以的，但不建议用于全局/用户范围的 MCP 注册。
### 等效形式
以下所有形式都可以为同一个项目提供服务：
```powershell
mcpedia mcp C:\Projects\MyKnowledgeBase
mcpedia mcp --root C:\Projects\MyKnowledgeBase
$env:MCPEDIA_ROOT = "C:\Projects\MyKnowledgeBase"; mcpedia mcp
```
对于 VS Code 和 Claude Code 注册，首选明确的根目录。对于 MCP Inspector，最可靠的工作流程是从项目文件夹内运行 Inspector，并启动 MCPedia 时不带根目录参数。
## VS Code MCP 设置
VS Code 通过 JSON 配置支持 MCP 服务器。为每个 MCPedia 知识库使用 `servers` 对象中的唯一键。每个条目都应传递不同的项目根目录路径。
VS Code 在用户设置和工作区文件（如 `.vscode/mcp.json`）中支持 MCP 服务器配置。用户级配置适用于跨多个工作区的个人知识库。当 MCP 属于该存储库时，工作区级 `.vscode/mcp.json` 更佳。
### 工作区级 `.vscode/mcp.json`
在存储库中创建此文件：
```text
C:\Projects\MyKnowledgeBase\.vscode\mcp.json
```
示例：
```json
{
"servers": {
"myKnowledgeBase": {
"type": "stdio",
"command": "mcpedia",
"args": ["mcp", "C:\\Projects\\MyKnowledgeBase"],
"cwd": "C:\\Projects\\MyKnowledgeBase"
}
}
}
```
注释：
- `myKnowledgeBase` 是 VS Code 注册键。使其唯一且有意义。
- `args` 以服务器模式启动 MCPedia，并将项目根目录作为位置参数传递。
- `cwd` 对于显示或继承工作目录的客户端仍然有用。
- 如果此文件被提交，队友应使用在其机器上有效的路径或在克隆后替换绝对路径。
如果您的 VS Code 设置支持工作区变量，您可以使用：
```json
{
"servers": {
"projectKnowledge": {
"type": "stdio",
"command": "mcpedia",
"args": ["mcp", "${workspaceFolder}"],
"cwd": "${workspaceFolder}"
}
}
}
```
### 用户级多存储库设置
当您希望在 VS Code 中使用多个个人知识库时，请使用此设置：
```json
{
"servers": {
"myKnowledgeBase": {
"type": "stdio",
"command": "mcpedia",
"args": ["mcp", "C:\\Projects\\MyKnowledgeBase"],
"cwd": "C:\\Projects\\MyKnowledgeBase"
},
"billingApiKnowledge": {
"type": "stdio",
"command": "mcpedia",
"args": ["mcp", "C:\\Projects\\BillingApi"],
"cwd": "C:\\Projects\\BillingApi"
},
"productDocsKnowledge": {
"type": "stdio",
"command": "mcpedia",
"args": ["mcp", "C:\\Projects\\ProductDocs"],
"cwd": "C:\\Projects\\ProductDocs"
}
}
}
```
### 如果找不到 `mcpedia` 命令
使用您全局 npm 安装的显式 Node 入口点：
```json
{
"servers": {
"myKnowledgeBase": {
"type": "stdio",
"command": "node",
"args": [
"C:\\Users\\YourName\\AppData\\Roaming\\npm\\node_modules\\mcpedia\\dist\\index.js",
"mcp",
"C:\Projects\\MyKnowledgeBase"
],
"cwd": "C:\\Projects\\MyKnowledgeBase"
}
}
}
```
使用以下命令查找全局安装路径：
```powershell
npm root -g
```
VS Code 官方文档：https://code.visualstudio.com/docs/agents/reference/mcp-configuration
---
## Claude Code MCP 设置
Claude Code 可以使用 `claude mcp add` 注册 stdio MCP 服务器。双破折线 `--` 很重要：它之后的所有内容都是 Claude Code 运行的命令。
基本命令形式：`claude mcp add --transport stdio <name> -- mcpedia mcp <project>`。在您想要特定范围时，请在服务器名称之前添加 `--scope local`、 `--scope project` 或 `--scope user`。
对于 MCPedia，建议使用位置项目根目录：
```powershell
mcpedia mcp <project>
```
这样每个注册都绑定到一个存储库，而不依赖于客户端工作目录。
### Claude Code 范围
Claude Code 支持以下 MCP 注册范围:
| 范围 | 使用场景 | 可见性 |
|---|---|---|
| `local` | 您只想为当前项目和仅限于您使用服务器。 | 仅限当前项目。这是默认设置。 |
| `project` | 您希望团队/存储库共享 MCP 注册。 | 存储在项目中，通常通过 `.mcp.json`。 |
| `user` | 您希望在所有 Claude Code 项目中服务器对您可用。 | 用户范围/全局，适用于您在该机器上的帐户。 |
### 本地范围，仅限当前项目
如果省略 `--scope`，则这是默认值：
```powershell
cd C:\Projects\MyKnowledgeBase
claude mcp add --scope local --transport stdio myKnowledgeBase -- mcpedia mcp C:\Projects\MyKnowledgeBase
```
如果此处省略项目路径，它可能仍然有效，因为注册绑定到当前项目，但明确的路径更清晰、更安全。
### 用户范围，在任何地方都可用
将此用于您的个人知识库集合：
```powershell
claude mcp add --scope user --transport stdio myKnowledgeBase -- mcpedia mcp C:\Projects\MyKnowledgeBase
claude mcp add --scope user --transport stdio billingApiKnowledge -- mcpedia mcp C:\Projects\BillingApi
claude mcp add --scope user --transport stdio productDocsKnowledge -- mcpedia mcp C:\Projects\ProductDocs
```
对于 `--scope user`，强烈建议使用明确的项目路径。没有它，MCPedia 可能会提供 Claude Code 启动的目录。
### 项目范围，与存储库共享
当 MCP 注册应与项目一起并与队友共享时，请使用此设置：
```powershell
cd C:\Projects\MyKnowledgeBase
claude mcp add --scope project --transport stdio myKnowledgeBase -- mcpedia mcp C:\Projects\MyKnowledgeBase
```
项目范围对团队很有用，但请注意绝对 Windows 路径。队友可能需要在克隆后编辑路径。
### 替换不正确的本地注册
如果您之前仅注册了多个 MCPedia 服务器作为 `mcpedia mcp`，请删除并重新添加它们，并使用明确的根目录和您想要的范围：
```powershell
claude mcp remove myKnowledgeBase
claude mcp remove billingApiKnowledge
claude mcp add --scope user --transport stdio myKnowledgeBase -- mcpedia mcp C:\Projects\MyKnowledgeBase
claude mcp add --scope user --transport stdio billingApiKnowledge -- mcpedia mcp C:\Projects\BillingApi
```
管理 Claude Code MCP 服务器：
```powershell
claude mcp list
claude mcp get myKnowledgeBase
claude mcp remove myKnowledgeBase
```
在 Claude Code 中：
```text
/mcp
```
为每个存储库使用一个 Claude Code 服务器名称，例如 `myKnowledgeBase`、`billingApiKnowledge` 和 `productDocsKnowledge`。Claude Code 服务器名称帮助您管理注册；MCPedia 的 `mcp.name` 和命名空间工具名称帮助跟踪显示实际调用了哪个存储库。
Claude Code 还支持基于 JSON 的配置，支持 `.mcp.json`、用户配置和 `claude mcp add-json` 以实现高级工作流。
Claude Code 官方文档：https://code.claude.com/docs/en/mcp
---
## 使用 MCP Inspector 测试
MCP Inspector 是在将 MCPedia 服务器添加到 VS Code 或 Claude Code 之前调试它的最佳方式。
对于 Inspector，请使用 **本地文件夹工作流程**。打开 PowerShell 到已经包含 `.rag/config.yaml` 和 `.rag/store.lance` 的存储库，然后使用 MCPedia 以纯服务器模式启动 Inspector：
```powershell
cd C:\Projects\MyKnowledgeBase
npx -y @modelcontextprotocol/inspector mcpedia mcp
```
在 Inspector UI 中，准确使用：
```text
Transport: STDIO
Command: mcpedia
Arguments: mcp
```
**不要** 通过 Inspector 传递项目路径。在实践中，Windows 路径转发通过 Inspector 可能不一致。MCPedia 应该从 shell 工作目录接收项目根目录以进行 Inspector 测试。
浏览器 CLI 检查：
```powershell
cd C:\Projects\MyKnowledgeBase
npx -y @modelcontextprotocol/inspector --cli mcpedia mcp --method tools/list
```
预期工具是配置的命名空间名称，例如：
```text
my_knowledge_base_search
my_knowledge_base_tree
```
如果 Inspector UI 一直加载，首先从同一文件夹验证服务器本身：
```powershell
cd C:\Projects\MyKnowledgeBase
mcpedia mcp
```
它应该一直运行，直到您按 `Ctrl+C`。然后从同一文件夹再次运行 Inspector：
```powershell
npx -y @modelcontextprotocol/inspector mcpedia mcp
```
常见的 Inspector 错误：
```powershell
# 错误：缺少 MCPedia 服务器子命令。
npx -y @modelcontextprotocol/inspector mcpedia
```
对于 Windows 上的 Inspector，请不要传递项目路径，不要传递 `--root`，也不要依赖 `MCPEDIA_ROOT`。仅使用上述本地文件夹命令。
对于 VS Code 和 Claude Code，仍然建议使用明确的项目根目录，因为这些客户端可能会从不同的工作目录启动服务器。Inspector 是一个例外：从索引的项目文件夹运行它，仅使用 `mcpedia mcp`。
## Windows Tree-sitter 故障排除
Tree-sitter 为 MCPedia 提供更好的代码块。在 Windows 上，本地模块加载可能会因两个常见原因而失败。
### 1. 缺少 Microsoft Visual C++ 运行时
安装或修复最新的支持的 **Microsoft Visual C++ v14 Redistributable x64**。
使用管理员身份运行 PowerShell：
```powershell
$installer = Join-Path $env:TEMP "vc_redist.x64.exe"
Invoke-WebRequest "https://aka.ms/vc14/vc_redist.x64.exe" -OutFile $installer
Start-Process -FilePath $installer -ArgumentList "/install", "/passive", "/norestart" -Verb RunAs -Wait
```
验证：
```powershell
Test-Path "$env:WINDIR\System32\VCRUNTIME140.dll"
```
预期：
```text
True
```
### 2. 已发布 Windows 原生二进制文件中的 `node.dll` 导入
一些 Windows x64 版本的 Tree-sitter 语言包可能会导入 `node.dll`，而官方 Node.js for Windows 提供 `node.exe`。MCPedia 检测并安全修复此问题。
仅检查：
```powershell
mcpedia doctor --check-only
```
应用修复并验证：
```powershell
mcpedia doctor
```
然后验证语法：
```powershell
mcpedia grammars csharp
```
预期：
```text
✔ Tree-sitter grammar ready: csharp
```
如果索引之前回退到文本块，请重建：
```powershell
Remove-Item .rag\store.lance -Recurse -Force -ErrorAction SilentlyContinue
mcpedia index
```
---
## 故障排除
### `mcpedia: command not found`
检查全局 npm 二进制文件：
```powershell
npm bin -g
npm list -g --depth=0
```
重新安装：
```powershell
npm install -g mcpedia
```
### Ollama 模型未找到
```powershell
ollama pull qwen3-embedding:8b
ollama pull gemma4:12b
ollama list
```
### 嵌入维度不匹配
`dimension` 值必须与嵌入模型匹配。
示例：
```yaml
qwen3-embedding:8b -> 4096
qwen3-embedding:4b -> 2560
qwen3-embedding:0.6b -> 1024
```
更改模型或维度后：
```powershell
mcpedia index
```
### MCP 客户端无法连接
确保命令包含 `mcp` 子命令：
```text
command: mcpedia
args: ["mcp"]
```
从存储库根目录运行或将客户端 `cwd` 设置为存储库根目录。
### 索引速度慢或内存占用高
使用较小的嵌入模型或较小的批次：
```yaml
embedding:
model: qwen3-embedding:4b
dimension: 2560
batchSize: 4
timeoutMs: 300000
```
或索引较少的文件：
```yaml
files:
extensions: [".cs", ".csproj", ".md", ".json", ".yaml"]
```
---
## 安全和隐私
- LanceDB 索引位于 `.rag/store.lance` 下。
- 不要提交 `.rag/`。
- 不要在 YAML 中提交实际的 API 密钥。
- 默认情况下，`.env` 私钥和本地凭据被排除。
- 云提供商仅接收根据您的提供商配置发送用于嵌入或生成的文本，包括从 PDF 或 Office 文件中提取的文本（当索引这些文件时）。
- MCP 客户端可以调用工具，因此仅注册您愿意公开给该客户端的存储库。
---
## 许可证和支持
由 **Hamed Fathi** 创建。
在 **MIT License** 下发布。
如果 MCPedia 对您有帮助，请在 GitHub 仓库上给我们一个星。星、问题、讨论、文档改进和拉取请求都有助于改进项目。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器