Fatebook MCP

🚀 Fatebook MCP 服務器

Fatebook MCP 服務器是一個模型上下文協議（MCP）服務器，可與預測跟蹤平臺 Fatebook 集成。該服務器允許像 Claude 這樣的 AI 助手直接通過 MCP 創建、管理和跟蹤預測。

✨ 主要特性

• 創建問題：使用預測（0 - 100% 概率）進行預測
• 列出問題：通過過濾選項查看您的預測
• 獲取問題詳情：檢索特定問題的全面信息
• 添加預測：更新現有問題的預測概率
• 添加評論：添加評論以跟蹤您的推理過程
• 解決問題：將問題標記為已解決（是/否/不明確）
• 編輯問題：更新問題標題、解決日期和備註
• 刪除問題：刪除不再需要的問題
• 統計預測：跟蹤您的預測活動

📦 安裝指南

前提條件

• Python 3.13 或更高版本
• uv（推薦）或 pip
• 一個 Fatebook 賬戶和 API 密鑰

獲取您的 Fatebook API 密鑰

1. 登錄 Fatebook
2. 導航到 API 設置
3. 生成並複製您的 API 密鑰

選項 1：從 PyPI 安裝（推薦）

直接從 PyPI 安裝軟件包：

pip install fatebook-mcp

或者使用 uv：

uv add fatebook-mcp

選項 2：從源代碼安裝

用於開發或獲取最新功能：

1. 克隆倉庫：

git clone https://github.com/an1lam/fatebook-mcp.git
cd fatebook-mcp

2. 使用 uv 安裝依賴項：

uv sync

🚀 快速開始

使用 uvx 直接運行

安裝後測試服務器的最簡單方法是使用 uvx：

# 直接從 PyPI 運行（無需安裝）
uvx fatebook-mcp

# 或者在開發期間從本地目錄運行
uvx --from . fatebook-mcp

服務器將啟動並通過標準輸入輸出等待 MCP 客戶端連接。使用 Ctrl + C 停止它。

💻 使用示例

與 Claude Desktop 和 Claude Code 一起使用

Claude Desktop

將以下配置之一添加到您的 Claude Desktop 配置文件中：

• macOS：位置：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：位置：%APPDATA%\Claude\claude_desktop_config.json

選項 1：使用 PyPI 包（推薦）

{
  "mcpServers": {
    "fatebook": {
      "command": "uvx",
      "args": ["fatebook-mcp"],
      "env": {
        "FATEBOOK_API_KEY": "your-api-key-here"
      }
    }
  }
}

注意：如果 Claude Desktop 找不到 uvx，請使用完整路徑：

{
  "mcpServers": {
    "fatebook": {
      "command": "/Users/yourusername/.local/bin/uvx",
      "args": ["fatebook-mcp"],
      "env": {
        "FATEBOOK_API_KEY": "your-api-key-here"
      }
    }
  }
}

使用 which uvx 查找您的 uvx 路徑。

選項 2：開發/源代碼安裝

{
  "mcpServers": {
    "fatebook": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/fatebook-mcp",
        "run",
        "python",
        "-m",
        "fatebook_mcp"
      ],
      "env": {
        "FATEBOOK_API_KEY": "your-api-key-here"
      }
    }
  }
}

將 /path/to/fatebook-mcp 替換為您克隆此倉庫的實際路徑。

Claude Code (CLI)

對於 Claude Code，您可以通過多種方式添加此服務器：

選項 1：使用 PyPI 包（推薦）

# 使用 uvx 添加 Fatebook MCP 服務器
claude mcp add fatebook --env FATEBOOK_API_KEY=your-api-key-here -- uvx fatebook-mcp

# 驗證是否成功添加
claude mcp list

選項 2：從 Claude Desktop 導入

如果您已經在 Claude Desktop 中配置了此服務器，您可以導入這些設置：

claude mcp add-from-claude-desktop

選項 3：項目特定配置

在您的項目中創建一個 .mcp.json 文件： 使用 PyPI 包：

{
  "mcpServers": {
    "fatebook": {
      "command": "uvx",
      "args": ["fatebook-mcp"],
      "env": {
        "FATEBOOK_API_KEY": "your-api-key-here"
      }
    }
  }
}

如果找不到 uvx，請使用完整路徑（使用 which uvx 查找）：

{
  "mcpServers": {
    "fatebook": {
      "command": "/Users/yourusername/.local/bin/uvx",
      "args": ["fatebook-mcp"],
      "env": {
        "FATEBOOK_API_KEY": "your-api-key-here"
      }
    }
  }
}

使用開發/源代碼安裝：

{
  "mcpServers": {
    "fatebook": {
      "command": "uv",
      "args": ["--directory", "/path/to/fatebook-mcp", "run", "python", "-m", "fatebook_mcp"],
      "env": {
        "FATEBOOK_API_KEY": "your-api-key-here"
      }
    }
  }
}

將 /path/to/fatebook-mcp 替換為您克隆此倉庫的實際路徑。

示例截圖

Claude Desktop

• 創建和跟蹤預測：
• 查看您的預測：

Claude Code

🔧 技術細節

開發與測試

額外設置

除了使用 MCP 服務器所需的上述設置外，獨立運行 MCP 服務器並運行其測試需要獲取您的 API 密鑰並將其導出到您的環境中。 您可以直接導出它：

export FATEBOOK_API_KEY="your-api-key-here"

或者創建一個 .env 文件：

FATEBOOK_API_KEY=your-api-key-here

運行集成測試

運行集成測試以驗證您的設置：

uv run pytest test_client.py

這將測試所有可用的端點並確認服務器正常工作。 注意：只有當您擁有測試用戶的正確 API 密鑰時，這些測試才會成功。如果您在開發過程中需要運行這些測試，請暫時給我（作者）發電子郵件。

本地運行服務器

• 使用 uvx（推薦）：

uvx --from . fatebook-mcp

• 使用 uv run 和模塊：

uv run python -m fatebook_mcp

服務器將啟動並等待 MCP 客戶端連接。

測試與兼容性

此 MCP 服務器已在以下環境中進行測試：

• Claude Code (CLI)
• Claude Desktop
• MCP Inspector

由於 MCP 是一個不斷發展的協議，某些功能或 MCP 客戶端可能無法完全支持。如果您在其他 MCP 實現中遇到問題，請將其作為 GitHub 問題報告。

故障排除

uvx 命令未找到

如果 Claude Desktop 顯示 uvx 的“命令未找到”錯誤：

1. 查找您的 uvx 路徑：

which uvx

2. 在您的配置中使用完整路徑：

"command": "/Users/yourusername/.local/bin/uvx"

3. 常見的 uvx 位置：
   • macOS：/Users/yourusername/.local/bin/uvx
   • Linux：/home/yourusername/.local/bin/uvx

API 密鑰問題

• 確保您的 API 密鑰有效且處於活動狀態
• 檢查 API 密鑰是否已正確設置在環境或配置中
• 嘗試在請求中直接提供 API 密鑰

連接問題

• 驗證您的 Claude Desktop 配置中的服務器路徑是否正確
• 檢查是否已安裝並可訪問 Python 3.13+
• 確保使用 uv sync 正確安裝了 uv 依賴項

問題格式

• 日期應採用 YYYY - MM - DD 格式
• 預測值必須介於 0.0 和 1.0 之間
• 創建問題時會提供問題 ID

📚 詳細文檔

有關 Fatebook API 的更多詳細信息，請參閱：

• Fatebook API 設置
• OpenAPI 規範

🤝 貢獻

歡迎貢獻！請隨時提交問題或拉取請求。

🛠️ 支持

如果遇到以下問題：

• 此 MCP 服務器：在 GitHub 上打開一個問題
• Fatebook API：聯繫 Fatebook 支持
• MCP/Claude Desktop：請參閱 MCP 文檔