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和模型上下文協議精心打造 ❤️