Knowledge Mcp

笔记 TypeScript

🚀 知识MCP服务器

知识MCP服务器是一个生产就绪的模型上下文协议（MCP）服务器，为AI助手提供集中式知识管理。它具备项目特定文档、可搜索的知识库、集成的待办事项管理，以及基于Git的版本控制，能在不同会话间持久保存AI记忆。

🚀 快速开始

本项目是一个生产就绪的模型上下文协议（MCP）服务器，为AI助手提供集中式知识管理。具备项目文档管理、高级搜索、待办事项管理等功能，还支持Git版本控制。

✨ 主要特性

📝 项目知识管理：集中存储项目说明和文档。
🔍 高级搜索：对所有知识文档进行全文搜索，并提供上下文结果。
📋 待办事项系统：内置任务管理，支持Markdown格式和进度跟踪。
🔐 安全至上：全面的输入验证、路径清理和抽象边界。
⚡ 高性能：通过复杂的文件锁定优化并发操作。
📊 请求跟踪：使用唯一的跟踪ID进行调试和监控。
🔄 Git集成：自动进行版本控制，并生成描述性提交消息。
🧪 经过实战检验：133个全面测试，覆盖所有功能和边缘情况。

📦 安装指南

NPM（推荐）

npm install -g @spothlynx/knowledge-mcp

从源代码安装

git clone https://github.com/sven-borkert/knowledge-mcp.git
cd knowledge-mcp
pnpm install
pnpm run build
npm link

💻 使用示例

基础用法

MCP客户端配置

在MCP客户端配置中添加以下内容：

{
"mcpServers": {
"knowledge": {
"command": "knowledge-mcp",
"args": []
}
}
}

Claude桌面端配置

在~/Library/Application Support/Claude/claude_desktop_config.json中添加以下内容：

{
"mcpServers": {
"knowledge": {
"command": "knowledge-mcp"
}
}
}

直接执行

# 启动MCP服务器
knowledge-mcp

# 开发模式，支持自动重新加载
pnpm run dev

高级用法

特定客户端配置

Claude Code

# 全局范围（所有项目） - 确保始终使用最新版本
claude mcp add knowledge-mcp npx -- -y @spothlynx/knowledge-mcp@latest

# 仅针对当前项目
claude mcp add --scope project knowledge-mcp npx -- -y @spothlynx/knowledge-mcp@latest

# 开发模式（使用本地构建）
claude mcp add knowledge-mcp node "$(pwd)/dist/knowledge-mcp/index.js"

Claude桌面端

在~/Library/Application Support/Claude/claude_desktop_config.json中添加以下内容：

{
"mcpServers": {
"knowledge": {
"command": "npx",
"args": ["-y", "@spothlynx/knowledge-mcp@latest"]
}
}
}

通用MCP配置

对于其他支持MCP的客户端：

{
"mcpServers": {
"knowledge-mcp": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@spothlynx/knowledge-mcp@latest"],
"env": {}
}
}
}

📚 详细文档

核心工具

项目管理

get_project_main(project_id) - 获取项目主说明。
update_project_main(project_id, content) - 更新项目说明。
update_project_section(project_id, section_header, new_content) - 更新特定部分。
add_project_section(project_id, section_header, content, position?, reference_header?) - 添加新部分。
remove_project_section(project_id, section_header) - 删除部分。
delete_project(project_id) - 删除整个项目。

知识文档

create_knowledge_file(project_id, filename, title, introduction, keywords, chapters) - 创建结构化文档。
get_knowledge_file(project_id, filename) - 获取完整文档。
delete_knowledge_file(project_id, filename) - 删除文档。
update_chapter(project_id, filename, chapter_title, new_content, new_summary?) - 更新章节。
add_chapter(project_id, filename, chapter_title, content, position?, reference_chapter?) - 添加章节。
remove_chapter(project_id, filename, chapter_title) - 删除章节。

章节迭代

list_chapters(project_id, filename) - 列出所有章节（仅标题和摘要）。
get_chapter(project_id, filename, chapter_title | chapter_index) - 获取单个章节内容。
get_next_chapter(project_id, filename, current_chapter_title | current_index) - 获取下一章节。

搜索与发现

search_knowledge(project_id, query) - 对所有文档进行全文搜索。

待办事项管理

list_todos(project_id) - 列出所有待办事项列表。
create_todo(project_id, description, tasks?) - 创建新的待办事项列表。
get_todo_tasks(project_id, todo_number) - 获取待办事项列表中的任务。
add_todo_task(project_id, todo_number, title, content?) - 添加任务。
complete_todo_task(project_id, todo_number, task_number) - 标记任务为已完成。
get_next_todo_task(project_id, todo_number) - 获取下一个未完成的任务。
remove_todo_task(project_id, todo_number, task_number) - 删除任务。
delete_todo(project_id, todo_number) - 删除整个待办事项列表。

服务器操作

get_server_info() - 获取服务器版本和配置。
get_storage_status() - 获取Git仓库状态。
sync_storage() - 强制进行Git提交和同步。

资源

服务器提供只读资源供浏览：

knowledge://projects/{project_id}/main - 项目主说明。
knowledge://projects/{project_id}/files - 知识文件列表。
knowledge://projects/{project_id}/chapters/{filename} - 章节列表。

🔧 技术细节

存储结构

~/.knowledge-mcp/
├── index.json                 # 项目名称到目录的映射
├── activity.log              # 请求活动日志（Git忽略）
└── projects/
└── {project-slug}/        # 简化的项目目录
├── main.md            # 项目主说明
├── knowledge/         # 知识文档
│   └── *.md           # 单个知识文件
└── TODO/              # 待办事项列表
└── {number}/      # 编号的待办事项目录
├── index.md   # 待办事项元数据
└── tasks/     # 单个任务文件
└── *.md

安全特性

路径验证：防止目录遍历攻击。
输入清理：使用Zod模式进行全面验证。
抽象边界：内部路径从不向客户端暴露。
原子操作：文件操作使用临时文件 + 重命名模式。
请求跟踪：所有操作使用唯一的跟踪ID。

并发与性能

文件锁定：基于队列的锁定防止竞态条件。
原子更新：所有文件操作都是原子性的。
高效搜索：优化的全文搜索，支持结果限制。
内存管理：对大文档进行可控的内存使用。

测试

项目包含全面的测试覆盖：

# 运行所有测试
pnpm run test:all

# 运行特定测试套件
npx tsx test/suites/01-project-main.test.ts

# 生成HTML测试报告
pnpm run test:all && open test-results/html/merged-results.html

测试覆盖

11个全面测试套件，共133个测试。
在CI/CD管道中成功率达100%。
覆盖边缘情况，包括并发、Unicode和错误条件。
安全测试，针对抽象边界和输入验证。
性能测试，针对高负载场景。

开发

前提条件

Node.js 18+
pnpm（推荐）或npm
TypeScript 5.7+

开发工作流

# 安装依赖
pnpm install

# 启动开发服务器，支持自动重新加载
pnpm run dev

# 构建生产版本
pnpm run build

# 运行类型检查
pnpm run type-check

# 运行代码检查
pnpm run lint

# 格式化代码
pnpm run format

# 运行所有质量检查
pnpm run analyze

代码质量

项目强制执行高标准的代码质量：

TypeScript：严格模式，全面的类型检查。
ESLint：全面的代码检查，支持TypeScript。
Prettier：一致的代码格式化。
静态分析：零警告策略。
测试覆盖：所有功能都经过彻底测试。

文档

技术规范 - 完整的API参考和架构。
错误处理指南 - 错误代码和调试。
MCP安全指南 - 安全最佳实践。
发布指南 - 发布和部署流程。

⚠️ 重要提示

项目ID自动检测：从Git仓库或当前目录名称自动检测项目ID。
路径清理：所有路径都经过清理，不允许使用../或绝对路径。
关键词限制：关键词必须是字母数字 + 点、下划线、连字符。
章节数量限制：每个文档最多50个章节。
文件扩展名：知识文件必须使用.md扩展名。
章节标题前缀：章节标题必须包含##前缀（例如，"## 配置"）。
自动提交：所有更改都会自动提交，并带有描述性消息。
存储同步：如果配置了Git远程仓库，存储将与origin/main同步。

🔍 错误代码

常见错误及其含义：

PROJECT_NOT_FOUND：项目尚不存在（使用update_project_main创建）。
DOCUMENT_NOT_FOUND：知识文件未找到。
FILE_ALREADY_EXISTS：文件/章节已存在（使用更新操作）。
CHAPTER_NOT_FOUND：文档中未找到章节标题。
SECTION_NOT_FOUND：main.md中未找到部分标题。
TODO_NOT_FOUND：待办事项列表不存在。
INVALID_INPUT：参数验证失败。
FILE_SYSTEM_ERROR：文件操作失败。
GIT_ERROR：Git操作失败。

每个错误都包含一个traceId，用于调试。

📄 许可证

本项目采用MIT许可证，请参阅LICENSE文件获取详细信息。

🤝 贡献

分叉仓库。
创建功能分支：git checkout -b feature/amazing-feature。
进行更改并添加测试。
确保所有测试通过：pnpm run test:all。
运行质量检查：pnpm run analyze。
提交更改：git commit -m 'Add amazing feature'。
推送到分支：git push origin feature/amazing-feature。
打开拉取请求。

开发标准

所有新功能必须包含全面的测试。
代码必须通过所有静态分析检查。
API更改时必须更新文档。
必须考虑安全问题。

🙏 致谢

模型上下文协议：优秀的MCP规范。
TypeScript社区：出色的工具和生态系统。
贡献者：使本项目变得更好。

📞 支持

问题反馈：GitHub Issues
文档：技术规范
MCP协议：官方文档

使用TypeScript和模型上下文协议精心打造 ❤️

0 条评论
分类：笔记