使用说明
Wiki MCP服务器
用于Claude Code和LLM代理的持久文档上下文服务器（“库管理员”）。它加载本地Markdown文档，使用混合搜索（关键字+矢量）对其进行索引，并为文档查询提供快速、经济高效的答案。
状态： 第一阶段正在进行中——核心基础设施。看 状态.md 了解详情。
主要优势： 通过将上下文卸载到索引数据库，将重复文档查询的令牌成本降低90-97%。
特性
| 工具 | 描述 | 阶段 | 状态 |
|---|---|---|---|
query_docs |
使用混合/精确/概念搜索模式搜索文档 | 1（核心） | 计划 |
add_context |
将新文档添加到wiki | 1（核心） | 已计划 |
sync_docs |
手动触发文档同步 | 1（核心） | 计划 |
organize_inbox |
使用LLM | 2（组织） | 计划对00_Inbox中的文件进行分类和移动 |
核心能力
- 混合搜索： 结合SQLite FTS5（关键字）和句子转换器（矢量语义搜索）以实现高精度
- 上下文感知分块： 按标题拆分Markdown以保留层次结构和上下文
- 背景花园： 自动将文档组织到结构化分类中
- 自动摄入： 实时监视文件更改并立即更新索引
- 增量同步： 监控文件更改，仅重新索引修改过的文件
- 范围搜索： 按特定文件夹筛选搜索（例如，仅“API”或“规范”）
- 按项目隔离： 设计用于在项目中本地运行，保持索引独立
- 类型安全： 全类型Python代码库（严格
mypy/ruff合规性）
建筑
看 docs/TDD.md 查看完整的架构分解。
Wiki-MCP Server (The "Librarian")
+------------------------------------------------------------------+
| Server Layer <---- Search Engine ----> LLM Synthesizer |
| (MCP Protocol) (Logic Layer) (Haiku - Optional) |
+------------------------------------------------------------------+
|
+-------------+-------------+
v v
+--------------+ +--------------+
| SQLite DB | | Vector Store |
| (FTS5 BM25) | | (Semantic) |
+--------------+ +--------------+
^ ^
+-------------+-------------+
|
Ingestion Pipeline
(Sync Manager + Watcher)
^
|
+---------------+
| Context Garden|
| (docs/*.md) |
+---------------+
目录结构：背景花园
Wiki MCP使用“花园”结构来组织知识。默认情况下，它会查找 docs/ 目录。
docs/
├── 00_Inbox/ # Drop new, unclassified notes here
├── 10_Project_Specs/ # Requirements, PRDs, User Stories
├── 20_Architecture/ # System design, diagrams, schemas
├── 30_Patterns/ # Coding standards, snippets, idioms
├── 40_Reference/ # API docs, library notes
└── 90_Archive/ # Deprecated content
自组织
将原始笔记放入 docs/00_Inbox 并运行 organize_inbox 工具。服务器将使用LLM分析内容，并将其移动到具有适当元数据的正确文件夹中。
安装
先决条件
- Python 3.10+
pipvenv（推荐）
地方发展设置
-
克隆存储库：
git clone https://github.com/your-repo/wiki-mcp-server.git cd wiki-mcp-server -
创建虚拟环境：
python3 -m venv venv source venv/bin/activate -
安装依赖项：
pip install -r requirements.txt -
运行测试：
PYTHONPATH=. pytest -v tests/
用法
配置克劳德代码（或MCP客户端）
将服务器添加到MCP配置中（例如。， claude_desktop_config.json 或 settings.json):
{
"mcpServers": {
"wiki": {
"command": "python3",
"args": ["/absolute/path/to/wiki-mcp-server/server.py"],
"cwd": "${workspaceFolder}",
"env": {
"ANTHROPIC_API_KEY": "sk-...",
"DOCS_DIR": "docs"
}
}
}
}
cwd：确保服务器查找wiki.db和docs/在您当前的项目中DOCS_DIR：覆盖服务器查找markdown文件的位置（默认值：docs)
服务器CLI工具
您可以直接与服务器组件交互进行调试：
# Sync documentation manually
python3 -c "from src.db import Database; from src.sync import SyncManager; from src.vector import VectorStore; db=Database(); v=VectorStore(); s=SyncManager(db, v); s.sync_all()"
# Run the server (Stdio mode)
python3 server.py
MCP工具
| 工具 | 说明 |
|---|---|
| query_docs | 使用混合/精确/概念搜索模式搜索文档 |
| add_context | 向wiki添加新文档 |
| organize_inbox | 使用LLM对00_Inbox中的文件进行分类和移动 |
| sync_docs | 手动触发文档同步 |
query_docs
使用各种模式搜索文档。
参数：
query（必填）：搜索问题intent:exact,concept，或hybrid（默认）scope：要筛选的文件夹的可选列表（例如。，["10_Project_Specs"])mode:standard或code_only
退货： LLM综合答案与来源
add_context
创建新的文档文件。
参数：
topic：文档的主题/标题content：Markdown内容category：目标文件夹（默认为“00_Inbox”）
organize_inbox
使用LLM分类将收件箱中的文件排序到分类中。
sync_docs
强制手动重新同步所有文件。
环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
ANTHROPIC_API_KEY |
（必需） | 用于LLM合成的API密钥 |
DOCS_DIR |
docs |
用于监视markdown文件的目录 |
WIKI_DB_PATH |
wiki.db |
SQLite数据库的路径 |
RELEVANCE_THRESHOLD |
0.3 |
搜索结果的最低分数 |
配置
创建一个 config.json 在项目根目录中：
{
"model": "claude-3-5-haiku-20241022",
"max_tokens": 2000,
"relevance_threshold": 0.3,
"docs_dir": "MyDocs"
}
文档
| 文件 | 目的 |
|---|---|
| 状态.md | 当前进展和路线图 |
| docs/PRD.md | 产品要求和成功指标 |
| docs/TDD.md | 技术设计和架构 |
| docs/IMPLEMENTATION.md | 实施阶段和路线图 |
发展
运行测试
# All tests
PYTHONPATH=. pytest -v tests/
# Unit tests
PYTHONPATH=. pytest -v tests/unit/
# Integration tests
PYTHONPATH=. pytest -v tests/integration/
# Specific test
PYTHONPATH=. pytest -v tests/unit/test_processor.py::test_name
代码质量
# Type checking
mypy src/ --strict
# Linting and formatting
ruff check src/ tests/
ruff format src/ tests/
许可证
GPL-3.0-参见 许可证 了解详情。
