MCP Toolz

🚀 MCP Toolz

MCP Toolz 是一款強大的工具，可在 Claude Code 會話中保存上下文和待辦事項，還能從 ChatGPT、Claude、Gemini 和 DeepSeek 獲取反饋，助力高效開發。

🚀 快速開始

安裝

從 PyPI 安裝（推薦）

pip install mcp-toolz

從源代碼安裝（用於開發）

# 克隆倉庫
git clone https://github.com/taylorleese/mcp-toolz.git
cd mcp-toolz

# 創建並激活虛擬環境
python3 -m venv venv
source venv/bin/activate  # macOS/Linux
# 或者：venv\Scripts\activate  # Windows

# 以可編輯模式安裝幷包含開發依賴
pip install -e ".[dev]"

配置

# 將 API 密鑰設置為環境變量（AI 功能至少需要一個）
export OPENAI_API_KEY=sk-...           # 用於 ChatGPT
export ANTHROPIC_API_KEY=sk-ant-...    # 用於 Claude
export GOOGLE_API_KEY=...              # 用於 Gemini
export DEEPSEEK_API_KEY=sk-...         # 用於 DeepSeek

# 或者創建一個 .env 文件（如果從源代碼安裝）
cp .env.example .env
# 編輯 .env 並添加你的 API 密鑰

MCP 服務器設置（推薦）

使用 mcp-toolz 的主要方式是通過 Claude Code 中的 MCP 服務器：

1. 添加到 Claude Code 設置（將此 JSON 添加到你的 Claude Code MCP 設置中）： 如果通過 pip 安裝：

{
  "mcpServers": {
    "mcp-toolz": {
      "command": "python",
      "args": ["-m", "mcp_server"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "GOOGLE_API_KEY": "...",
        "DEEPSEEK_API_KEY": "sk-..."
      }
    }
  }
}

如果從源代碼安裝：

{
  "mcpServers": {
    "mcp-toolz": {
      "command": "python",
      "args": ["-m", "mcp_server"],
      "cwd": "/absolute/path/to/mcp-toolz",
      "env": {
        "PYTHONPATH": "/absolute/path/to/mcp-toolz/src"
      }
    }
  }
}

2. 配置 API 密鑰 - 將你的 API 密鑰添加到 env 部分（pip 安裝）或 .env 文件（源代碼安裝）。
3. 重啟 Claude Code 以加載 MCP 服務器。
4. 在 Claude Code 中使用 MCP 工具：
   • "Save this context about authentication"（保存有關身份驗證的上下文）
   • "Ask ChatGPT about the last context I saved"（詢問 ChatGPT 關於我上次保存的上下文）
   • "Show my active todos"（顯示我的活動待辦事項）
   • "Search contexts tagged with 'bug'"（搜索標記為 'bug' 的上下文）

所有 MCP 工具都自動可用 - 請參閱下面的 MCP 服務器工具。

✨ 主要特性

• 🔌 MCP 服務器：現已與 Claude Code 集成，實現全工具集成。
• 會話連續性：重啟 Claude Code 時不會丟失上下文，可恢復“上一個會話我在做什麼”。
• 項目組織：上下文和待辦事項按項目目錄自動組織。
• 會話跟蹤：每個 Claude Code 會話都有唯一的 ID，可隨時間跟蹤你的工作。
• AI 反饋：從 ChatGPT（OpenAI）、Claude（Anthropic）、Gemini（Google）和 DeepSeek 獲取關於你的代碼和決策的反饋。
• 上下文類型：保存對話、代碼片段、架構建議或錯誤跟蹤。
• 持久待辦事項：跨會話保存和恢復待辦事項列表，永遠不會忘記你上次的進度。
• 全文搜索：按內容、標籤、項目或會話查找任何內容。
• CLI + MCP：可通過 Claude Code MCP 工具或獨立的 CLI 命令使用。

📦 安裝指南

從 PyPI 安裝（推薦）

pip install mcp-toolz

從源代碼安裝（用於開發）

# 克隆倉庫
git clone https://github.com/taylorleese/mcp-toolz.git
cd mcp-toolz

# 創建並激活虛擬環境
python3 -m venv venv
source venv/bin/activate  # macOS/Linux
# 或者：venv\Scripts\activate  # Windows

# 以可編輯模式安裝幷包含開發依賴
pip install -e ".[dev]"

💻 使用示例

基礎用法

這裡是在 Claude Code 中使用 mcp-toolz 的實際示例：

示例 1：獲取多個 AI 對架構決策的觀點

提示：

I'm deciding between using Redis or Memcached for caching user sessions.
Save this as a context and ask ChatGPT for their analysis.
Use tags: caching, redis, memcached, architecture

發生的事情：

1. Claude Code 使用 context_save 保存你的架構決策。
2. 然後使用 ask_chatgpt 獲取 ChatGPT 的觀點。
3. 你可以比較多個 AI 的觀點以做出決策。 後續提示：

• "Ask Claude the same question for comparison"（詢問 Claude 同樣的問題以進行比較）
• "Ask Gemini for another perspective"（詢問 Gemini 另一種觀點）
• "What does DeepSeek think about this?"（DeepSeek 對此有什麼看法？）
• "Search my contexts tagged with 'architecture'"（搜索我標記為 'architecture' 的上下文）

示例 2：會話連續性 - 永不丟失進度

提示（工作會話結束時）：

Save my current todo list so I can restore it tomorrow

發生的事情：

1. Claude Code 使用 todo_save 快照你當前的工作狀態。
2. 待辦事項與項目路徑和時間戳一起保存。 第二天的提示：

What was I working on yesterday? Restore my todos.

發生的事情：

1. Claude Code 使用 todo_restore 獲取你上次的快照。
2. 顯示你確切的進度。
3. 你可以立即繼續工作。

示例 3：使用多個 AI 觀點進行調試

提示：

I'm getting "TypeError: Cannot read property 'map' of undefined" in my React component.
The error occurs in UserList.jsx when rendering the users array.
Save this as an error context and ask ChatGPT, Claude, and Gemini for debugging suggestions.
Tags: react, debugging, javascript

發生的事情：

1. Claude Code 使用 context_save 記錄錯誤。
2. 使用 ask_chatgpt 獲取 OpenAI 的調試方法。
3. 使用 ask_claude 獲取 Anthropic 的觀點。
4. 使用 ask_gemini 獲取 Google 的分析。
5. 你可以比較多個 AI 模型的不同調試策略。 後續提示：

• "Search for other contexts tagged with 'react' bugs"（搜索其他標記為 'react' 錯誤的上下文）
• "Show me contexts from my last session"（顯示我上一個會話的上下文）

示例 4：跟蹤性能優化想法

提示：

Save this performance optimization idea: "Lazy load images below the fold using
Intersection Observer API. Estimated 40% reduction in initial page load."
Type: suggestion, Tags: performance, optimization, images

發生的事情：

1. Claude Code 使用 context_save 保存類型為 "suggestion" 的上下文。
2. 上下文可搜索並與當前項目關聯。
3. 在所有未來會話中可用。 稍後的提示：

Search my contexts for performance optimization ideas

發生的事情：

1. Claude Code 使用 context_search 執行你的查詢。
2. 返回跨會話的所有匹配上下文。
3. 你可以回顧過去的優化想法。

示例 5：跨會話知識共享

提示（在項目 A 中）：

I figured out how to handle OAuth refresh tokens properly.
Save this so I can reference it in other projects:
"Store refresh tokens in httpOnly cookies, access tokens in memory only.
Rotate refresh tokens on each use. Set 7-day expiry on refresh, 15min on access."
Type: code, Tags: oauth, security, authentication

提示（稍後在項目 B 中）：

How did I implement OAuth refresh tokens in my last project?
Search for contexts about oauth and show me what I saved.

發生的事情：

1. Claude Code 使用 context_search 查找你的 OAuth 實現。
2. 跨項目檢索上下文。
3. 你可以重用自己的知識，無需從頭開始。

高級用法

共享上下文

mcp-toolz 使跨多個 Claude Code 會話或代理共享上下文和待辦事項變得容易。

MCP 資源（被動發現）

Claude Code 可以通過 MCP 資源自動發現和讀取上下文/待辦事項： 上下文資源：

• mcp-toolz://contexts/project/recent - 當前項目的最近上下文
• mcp-toolz://contexts/project/sessions - 當前項目的最近 Claude Code 會話列表
• mcp-toolz://contexts/session/{session_id} - 特定會話的所有上下文 待辦事項資源：
• mcp-toolz://todos/recent - 最近 20 個待辦事項快照（所有項目）
• mcp-toolz://todos/active - 當前工作目錄的活動待辦事項 會話跟蹤： 通過 MCP 工具保存上下文時，它們會自動標記為：
• 當前項目目錄 (project_path)
• 會話 ID（每個 Claude Code 會話唯一）
• 會話時間戳（會話開始時）

未來： 一旦 ChatGPT Desktop 添加 MCP 支持，你也可以在那裡使用這些相同的工具。

共享數據庫設置

默認情況下，mcp-toolz 將所有數據存儲在 ~/.mcp-toolz/contexts.db 中，該數據庫會自動在同一臺機器上的所有項目之間共享，無需額外配置！ 對於高級用例（通過 Dropbox、iCloud 等在多臺機器上同步）：

1. 選擇數據庫的同步位置：

# 示例：使用同步文件夾（Dropbox、iCloud、網絡驅動器）
mkdir -p ~/Dropbox/mcp-toolz-shared

2. 更新 .env 文件 或 MCP 配置以指向同步數據庫：

# 在 .env 文件中
MCP_TOOLZ_DB_PATH=~/Dropbox/mcp-toolz-shared/contexts.db

或者在你的 MCP 配置中：

{
  "mcpServers": {
    "mcp-toolz": {
      "command": "python",
      "args": ["-m", "mcp_server"],
      "cwd": "/absolute/path/to/mcp-toolz",
      "env": {
        "PYTHONPATH": "/absolute/path/to/mcp-toolz/src",
        "MCP_TOOLZ_DB_PATH": "/Users/you/Dropbox/mcp-toolz-shared/contexts.db"
      }
    }
  }
}

3. 重啟 Claude Code - 它現在使用同步數據庫位置。

工作原理

• 上下文：按 project_path 組織（每個目錄有自己的上下文）
• 會話跟蹤：上下文標記有會話 ID 和時間戳，便於恢復
• 待辦事項：按 project_path 組織（每個目錄有自己的快照）
• 單個 SQLite 數據庫：所有數據存儲在一個數據庫中，按項目和會話過濾
• 自動更新：一個會話中所做的更改會立即對其他會話可見

使用案例

• 多臺機器：在筆記本電腦和臺式機之間保持上下文同步。
• 會話連續性：在重啟 Claude Code 後繼續你上次的工作。

CLI 使用（可選）

# 獲取 ChatGPT 對某件事的意見
./mcp-toolz context save-and-query \
  --type suggestion \
  --title "Redis caching strategy" \
  --content "Use Redis for session storage with 1-hour TTL" \
  --tags "caching,redis"

# 保存你當前的待辦事項
./mcp-toolz todo save \
  --todos '[
    {"content":"Fix auth bug","status":"in_progress","activeForm":"Fixing auth bug"},
    {"content":"Write tests","status":"pending","activeForm":"Writing tests"}
  ]' \
  --context "Working on authentication"

# 列出所有內容
./mcp-toolz context list
./mcp-toolz todo list

# 稍後恢復待辦事項
./mcp-toolz todo restore

📚 詳細文檔

MCP 服務器工具

MCP 服務器現已與 Claude Code 集成，並提供以下工具： 上下文工具：

• context_save - 保存新上下文（自動包含會話信息）
• context_search - 按查詢或標籤搜索
• context_get - 按 ID 獲取
• context_list - 列出最近的
• context_delete - 按 ID 刪除 AI 反饋工具：
• ask_chatgpt - 獲取 ChatGPT 對上下文的分析（支持自定義問題）
• ask_claude - 獲取 Claude 對上下文的分析（支持自定義問題）
• ask_gemini - 獲取 Gemini 對上下文的分析（支持自定義問題）
• ask_deepseek - 獲取 DeepSeek 對上下文的分析（支持自定義問題） 待辦事項工具：
• todo_search - 搜索快照
• todo_get - 按 ID 獲取
• todo_list - 列出最近的
• todo_save - 保存快照
• todo_restore - 獲取活動/特定快照
• todo_delete - 按 ID 刪除 會話跟蹤： 通過 MCP 工具保存上下文時，它們會自動標記為：
• 當前項目目錄 (project_path)
• 會話 ID（每個 Claude Code 會話唯一）
• 會話時間戳（會話開始時）

命令參考

上下文命令

# 保存並立即查詢 ChatGPT
./mcp-toolz context save-and-query \
  --type <type> \
  --title "Title" \
  --content "..." \
  --tags "tag1,tag2"

# 保存但不查詢
./mcp-toolz context save --type code --file path/to/file.py

# 詢問 ChatGPT 或 Claude 關於現有上下文
./mcp-toolz context ask-chatgpt <context-id> [--question "Your question"]
./mcp-toolz context ask-claude <context-id> [--question "Your question"]

# 瀏覽和搜索
./mcp-toolz context list [--limit N] [--type TYPE]
./mcp-toolz context search "query"
./mcp-toolz context show <context-id>

# 刪除
./mcp-toolz context delete <context-id>

上下文類型：

• suggestion - 架構決策、實施計劃
• code - 代碼片段、實現
• conversation - 討論、問答會話
• error - 錯誤消息、堆棧跟蹤、調試

待辦事項命令

# 保存當前待辦事項
./mcp-toolz todo save \
  --todos '[{"content":"...","status":"pending","activeForm":"..."}]' \
  --context "What you're working on"

# 恢復（默認為當前項目的活動快照）
./mcp-toolz todo restore [<snapshot-id>]

# 瀏覽和搜索
./mcp-toolz todo list [--project-path PATH]
./mcp-toolz todo search "query"
./mcp-toolz todo show <snapshot-id>

# 刪除
./mcp-toolz todo delete <snapshot-id>

待辦事項狀態： pending（待辦）、in_progress（進行中）、completed（已完成）

獲取幫助

./mcp-toolz --help
./mcp-toolz context --help
./mcp-toolz todo --help

常見工作流程

獲取多個 AI 觀點

在評估實現方案時，比較不同 AI 模型的見解：

./mcp-toolz context save-and-query \
  --type suggestion \
  --title "Microservices vs Monolith for e-commerce" \
  --content "Building platform with 5 services. Start microservices or monolith first?" \
  --tags "architecture,scalability"

AI 的響應會立即顯示在你的控制檯中。你還可以詢問特定問題或獲取 Claude 的觀點：

# 詢問關於上下文的特定問題
./mcp-toolz context ask-chatgpt <context-id> --question "What are the scalability concerns?"

# 獲取 Claude 的一般意見
./mcp-toolz context ask-claude <context-id>

# 或者詢問 Claude 特定問題
./mcp-toolz context ask-claude <context-id> --question "How would you handle database migrations?"

用兩種觀點進行調試

./mcp-toolz context save-and-query \
  --type error \
  --title "CORS issue in production" \
  --content "Error: blocked by CORS policy. Headers: ..." \
  --tags "debugging,cors,production"

會話連續性

# 工作會話結束時
./mcp-toolz todo save \
  --todos '[
    {"content":"Implement login","status":"completed","activeForm":"Implementing login"},
    {"content":"Add OAuth","status":"in_progress","activeForm":"Adding OAuth"},
    {"content":"Write tests","status":"pending","activeForm":"Writing tests"}
  ]' \
  --context "Day 2 of auth feature"

# 下一個會話
./mcp-toolz todo restore

跨 Claude Code 會話共享

# 會話 1：保存有趣的討論
./mcp-toolz context save \
  --type conversation \
  --title "Performance optimization ideas" \
  --content "..." \
  --tags "performance"

# 會話 2：查找並查看
./mcp-toolz context search "performance"
./mcp-toolz context show <context-id>

# 或者詢問 AI 特定問題
./mcp-toolz context ask-chatgpt <context-id> --question "What's the performance impact?"
./mcp-toolz context ask-claude <context-id> --question "Are there any security concerns?"

環境變量

# 必需（AI 功能至少需要一個）
OPENAI_API_KEY=sk-...                              # 你的 OpenAI API 密鑰
ANTHROPIC_API_KEY=sk-ant-...                       # 你的 Anthropic API 密鑰
GOOGLE_API_KEY=...                                 # 你的 Google API 密鑰（用於 Gemini）
DEEPSEEK_API_KEY=sk-...                            # 你的 DeepSeek API 密鑰

# 可選
MCP_TOOLZ_DB_PATH=~/.mcp-toolz/contexts.db                    # 共享數據庫位置（默認）
MCP_TOOLZ_MODEL=gpt-5                                         # OpenAI 模型（默認：gpt-5）
MCP_TOOLZ_CLAUDE_MODEL=claude-sonnet-4-5-20250929             # Claude 模型
MCP_TOOLZ_GEMINI_MODEL=gemini-2.0-flash-thinking-exp-01-21   # Gemini 模型
MCP_TOOLZ_DEEPSEEK_MODEL=deepseek-chat                        # DeepSeek 模型

故障排除

"Error 401: Invalid API key"

• 驗證 API 密鑰是否設置在 .env 中（OPENAI_API_KEY 和/或 ANTHROPIC_API_KEY）。
• 檢查你的 OpenAI/Anthropic 賬戶是否啟用了計費。
• ./mcp-toolz 包裝器會自動取消設置 shell 環境變量以使用 .env。

"No module named context_manager"

• 使用 ./mcp-toolz 輔助腳本（推薦）。
• 或者在直接運行 Python 之前設置 PYTHONPATH=src。

命令未找到

• 激活虛擬環境：source venv/bin/activate。
• 使腳本可執行：chmod +x mcp-toolz。

待辦事項無法恢復

• 檢查你是否在同一項目目錄中。
• 使用 ./mcp-toolz todo list 查看所有快照。
• 恢復特定快照：./mcp-toolz todo restore <snapshot-id>。

🔧 技術細節

項目結構

mcp-toolz/
├── src/
│   ├── mcp_server/          # Claude Code 的 MCP 服務器
│   │   └── server.py        # MCP 工具和資源
│   ├── context_manager/     # CLI 和存儲
│   │   ├── cli.py          # 基於 Click 的 CLI
│   │   ├── storage.py      # SQLite 操作
│   │   ├── openai_client.py # ChatGPT API 客戶端
│   │   └── anthropic_client.py # Claude API 客戶端
│   └── models.py           # Pydantic 數據模型
├── data/
│   └── contexts.db         # SQLite 數據庫
├── requirements.txt
├── requirements-dev.txt
└── mcp-toolz               # 輔助腳本

開發

貢獻者設置

# 克隆並安裝
git clone https://github.com/taylorleese/mcp-toolz.git
cd mcp-toolz
python3 -m venv venv
source venv/bin/activate
pip install -r requirements-dev.txt

# 安裝 pre-commit 鉤子（重要！）
pre-commit install

# 複製並配置 .env
cp .env.example .env
# 編輯 .env 並添加你的 API 密鑰

運行測試

source venv/bin/activate
pytest

代碼質量

# 運行所有檢查（在安裝 pre-commit 後提交時自動運行）
pre-commit run --all-files

# 單個工具
black .
ruff check .
mypy src/

📄 許可證

本項目採用 MIT 許可證。

💡 使用建議

1. 使用描述性標題 - 方便後續搜索。
2. 添加相關標籤 - 有助於組織和查找上下文。
3. 內容具體 - 更多細節 = 更好的 AI 響應。
4. 比較 AI 意見 - 在重要決策上同時獲取 ChatGPT 和 Claude 的觀點。
5. 審查 AI 建議 - 它們是有用的意見，而非規則。
6. 定期保存待辦事項 - 養成在會話結束時保存的習慣。