Knowledge MCP

🚀 知识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文件获取详细信息。

🤝 贡献

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

开发标准

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

🙏 致谢

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

📞 支持

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

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