本地知识mcp（FastAPI）
将本地目录作为知识库的MCP风格服务器。
1）功能
list_docs：查看文档列表read_doc：读取文档search_docs：搜索关键字行upsert_doc：创建/续订文档（overwrite/append)rebuild_summary：汇总/重新组织多个文档并将其保存为新文件KNOWLEDGE_BACKEND=github设置时，在本地同步GitHub存储库并进行操作。sync_status：查看GitHub同步状态（舞台/非舞台/新分支的状态）create_pr：将转储的更改提交到新分支+推送，并创建PR比较URL
2）安全设计
KNOWLEDGE_ROOT只能访问子路径
USE_GIT_ROOT=true从面运行时的当前目录开始向上.git查找，查找后将其用作知识根
- 脱离路径（
../）防止：解析后检查根prefix
- 扩展名allowlist（
ALLOWED_EXTENSIONS，默认.md,.txt)
- 只读模式（
READ_ONLY=true）阻止写入系列工具
- 可选令牌身份验证（
MCP_API_TOKEN)
- Cursor连接指南：
CURSOR_MCP_SETUP.md
3）运行
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# 필요시 .env 값 수정
uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload如果您想立即将Git repo用作知识库：
export USE_GIT_ROOT=true
export ALLOWED_EXTENSIONS=.md,.txt,.py,.ts要以同步模式写入GitHub远程存储：
KNOWLEDGE_BACKEND=github
GITHUB_REPO=owner/repo
GITHUB_REF=main
GITHUB_TOKEN=ghp_xxx # private repo 또는 rate limit 완화용
ALLOWED_EXTENSIONS=.md,.txt,.py,.ts上面的值 .env如果放入，服务器将在启动时自动读取。
KNOWLEDGE_BACKEND=github时：
- 查询（
list_docs,read_doc,search_docs）是动作战git pull运行并检索并返回本地文件。 - 修改（
upsert_doc,rebuild_summary）在更改本地文件后git add记录为staged状态。 - 仅限PR
sync_status使用工具检查状态。create_pr可以使用工具提交分支+push+PR URL。 - MCP清单(
GET /mcp/manifest,tools/list）的descriptionsource: github:@将自动标记。 - GitHub工作文件夹
KNOWLEDGE_ROOT/__是。
4）快速测试
curl http://127.0.0.1:8000/health
curl -X POST http://127.0.0.1:8000/mcp/call \
-H 'content-type: application/json' \
-d '{"name":"list_docs","arguments":{}}'4-1）Notion快速同步（MVP）
Notion集成令牌和根页面ID .env放入并运行 KNOWLEDGE_ROOT 下面 NOTION_SYNC_SUBDIR 文件夹（默认） notion）同步Markdown。
set -a; source .env; set +a
python scripts/sync_notion.py同步后验证MCP导航：
curl -s http://127.0.0.1:8000/mcp/call \
-H 'content-type: application/json' \
-d '{"name":"list_docs","arguments":{}}'如果已打开令牌：
-H "Authorization: Bearer $MCP_API_TOKEN"5）MCP端点
POST /mcp：JSON-RPC风格的MCP请求（initialize,tools/list,tools/call,ping)GET /mcp/manifest：调试工具/模式列表POST /mcp/call：运行单个工具进行调试GET /mcp/sse：可选SSE heartbeat/manifest流
6）Cursor连接示例
根据Cursor版本的不同，MCP连接方式可能会有所不同，请使用以下两种方式中的一种。
A.支持HTTP（远程/本地URL）连接
- MCP服务器URL
http://127.0.0.1:8000/mcp注册为 - 使用令牌时
Authorization: Bearer添加标题 ALLOWED_ORIGINS包含Cursor请求的Origin
B.仅允许基于stdio
- 保留此FastAPI服务器，并设置单独的stdio代理
/mcp转发 - 或将相同的工具逻辑打包到stdio MCP服务器
Cursor Streamable HTTP如果支持，则可以粘贴此服务器。
7）工具输入/输出示例
list_docs
{
"subdir": "project-a"
}read_doc
{
"path": "project-a/notes.md"
}search_docs
{
"query": "latency",
"limit": 20,
"case_sensitive": false
}GitHub后端 search_docs将在允许的扩展名文件中循环浏览内容。 如果文档数较多，API调用数可能会增加。
upsert_doc
{
"path": "project-a/meeting.md",
"content": "# Weekly Notes\n...",
"mode": "overwrite"
}rebuild_summary
{
"paths": ["project-a/notes.md", "project-a/spec.md"],
"output_path": "project-a/summary.md",
"style": "spec"
}rebuild_summary转交给 paths是 仅文件路径 允许。 Backend/FastAPI 相同的文件夹路径，绝对路径（/foo.md）被服务器拒绝。 有效值为 KNOWLEDGE_ROOT 标准的相对路径（project-a/notes.md）。
8）下一步建议
- 如果需要提高搜索质量
search_docs用BM25/嵌入索引替换 rebuild_summary将拆分为外部LLM调用版本（目前为基于规则的摘要）- 生产中添加令牌验证+TLS+审计日志
9）MCP标准学习文档（官方）
- MCP官方文档主页：https://modelcontextprotocol.io/introduction
- MCP规格索引：https://modelcontextprotocol.io/specification
- 最新规格发行说明（2025-11-25）：https://modelcontextprotocol.io/specification/2025-11-05/changelog#2025-11-25
- “传输”（Transports）文档：https://modelcontextprotocol.io/specification/2025-11-05/basic/transports
- Streamable HTTP安全注意事项（包括Origin验证）：https://modelcontextprotocol.io/specification/2025-11-05/basic/transports#security-warning
- 공식 Python SDK：https://github.com/modelcontextprotocol/python-sdk
- 光标MCP문서: https://docs.cursor.com/context/model-context-protocol