内容
# 结构化知识文件系统
一个本地知识导航服务器，通过模型上下文协议（MCP）向AI代理公开结构化的文档。
结构化知识文件系统适用于已经具有有意义层次结构的文档，例如产品文档、工程指南、标准操作程序和Git管理的知识库。它保留了人类策划的结构，并为代理提供了三个专注的只读功能：
- `list_directory`：浏览知识树；
- `search`：在Markdown、MDX和文本文件中运行确定性搜索；
- `read_file`：在确认位置后读取源文档。
预期的工作流程是**浏览 → 搜索 → 读取**。代理不需要猜测路径，答案可以包括可追溯的源文件。
## 为什么要创建这个项目
许多知识系统立即将文档分割成块并建立向量索引。这个项目在层次结构本身具有意义时采取了不同的方法：
- 不需要数据库或向量索引；
- 文档保留在本地，不由服务器上传；
- 搜索结果包括仓库相对路径、行号和代码片段；
- 服务器是一个具有狭窄只读界面的小型Go二进制文件；
- 相同的工作流程适用于本地Git检出或策划的文档文件夹。
## 示例知识库
仓库中包含`example-knowledge/`，一个多级Markdown知识库，包含三个虚拟产品：
- 产品Alpha：订单管理和产品目录；
- 产品Beta：客户支持和身份验证；
- 产品Gamma：分析和数据管道。
可重用的评估问题和预期的源文件位于[`examples/evaluation.md`](examples/evaluation.md)。完整的MCP客户端设置和工具调用演练位于[`examples/mcp-usage.md`](examples/mcp-usage.md)。
## 要求
- 用于开发的Go 1.23或更高版本；
- MCP客户端，如Cursor、Claude Desktop或其他stdio兼容客户端。
MCP Go SDK通过Go Modules自动下载。ripgrep是可选的。
## 在本地运行
直接从仓库运行：
```powershell
go run .\cmd\structured-knowledge-filesystem --root C:\path\to\knowledge
```
或使用JSON配置文件：
```powershell
go run .\cmd\structured-knowledge-filesystem --config .\config.example.json
```
示例配置文件指向`example-knowledge/`。配置文件中的相对根目录相对于配置文件本身解析。
## 构建
构建一个平台本地二进制文件：
```powershell
go build -o structured-knowledge-filesystem.exe .\cmd\structured-knowledge-filesystem
```
二进制文件默认使用内置的Go搜索后端，因此不需要外部搜索可执行文件。
## 搜索后端
内置后端在进程中搜索Markdown、MDX和纯文本文件，并在省略`ripgrep_path`时选择。它将应用程序保留为单个跨平台二进制文件。
对于较大的仓库，可以选择安装ripgrep并配置其可执行文件：
```json
{
"root": "./example-knowledge",
"ripgrep_path": "rg"
}
```
两个后端返回相同的路径、行号、列和匹配文本。
## MCP客户端配置
将[`examples/mcp-client-config.json`](examples/mcp-client-config.json)中的`mcpServers`块复制到MCP客户端的配置文件中，并用机器上的绝对路径替换路径：
```json
{
"mcpServers": {
"structured-knowledge-filesystem": {
"command": "C:\\path\\to\\structured-knowledge-filesystem.exe",
"args": [
"--config",
"C:\\path\\to\\structured-knowledge-filesystem\\config.example.json"
]
}
}
}
```
MCP客户端通常会自动启动进程。标准输出保留用于MCP协议，因此启动诊断信息写入标准错误，应通过客户端的MCP日志检查。
## 测试和验证
运行完整的测试套件：
```powershell
go test ./...
```
推荐的发布前检查：
```powershell
go test -race ./...
go vet ./...
go build ./cmd/structured-knowledge-filesystem
```
CI工作流在Ubuntu、Windows和macOS上运行测试、竞争检测、检查和构建。
## 演示问题
将服务器连接到MCP客户端后，询问：
```text
产品Alpha中针对失败付款的重试策略在哪里？
```
预期行为是检查`product-alpha/order-management/`，搜索`PAYMENT_FAILED`，读取`payment-retry.md`，并在答案中引用源路径。
## 项目计划
产品方向、里程碑、范围和长期想法在[`PROJECT_PLAN.md`](PROJECT_PLAN.md)中记录。
