Hardcover MCP

🚀 Hardcover MCP

Hardcover MCP 是一個模型上下文協議（MCP）服務器，它提供對 Hardcover.app GraphQL API 的只讀訪問。工具按照 books.*、users.* 和 series.* 進行命名空間劃分，同時還包含資源和提示，以指導進行安全、小流量的查詢。

這是一個非官方的、由社區維護的服務器，與 Hardcover.app 沒有關聯。

🚀 快速開始

本項目提供對 Hardcover.app GraphQL API 的只讀訪問，通過特定命名空間工具和資源提示確保查詢安全、低流量。

✨ 主要特性

• 提供對 Hardcover.app GraphQL API 的只讀訪問。
• 工具按 books.*、users.* 和 series.* 命名空間劃分。
• 包含資源和提示，指導安全、低流量查詢。

📦 安裝指南

安裝要求

• Python 3.11+
• 從 https://hardcover.app/account/api 獲取 Hardcover API 密鑰（只讀的 Bearer 令牌）

安裝步驟

# 選項 A：使用 uv（推薦）
uv pip install -e .

# 選項 B：使用 pip
python -m venv .venv
source .venv/bin/activate
pip install -e .

🔧 技術細節

傳輸協議

本服務器目前僅支持將 STDIO 作為傳輸協議。

💻 使用示例

基礎用法

1. 獲取 API 密鑰

從 https://hardcover.app/account/api 獲取 API 密鑰。精確複製提供的值（它已經以 Bearer 開頭）。

2. 為服務器導出密鑰

export HARDCOVER_API_KEY="Bearer <your-token>"

3. 直接啟動 MCP 服務器

uv run src/hardcover_mcp/main.py

高級用法

為 AI 聊天配置 STDIO（以 Codex 為例）

[mcp_servers.hardcover_mcp]
command = "uv"
args = ["run", "src/hardcover_mcp/main.py"]
env = { "HARDCOVER_API_KEY" = "API KEY heRE" }
cwd = "full_path_to/hardcover_mcp"

服務器會註冊 books.*、users.* 和 series.* 工具命名空間，以及 hardcover/tag-categories 等資源和 hardcover/fantasy-this-year 等使用提示。

運行測試套件

pytest

📚 詳細文檔

故障排除

• HARDCOVER_API_KEY environment variable is required：確保在啟動服務器的同一 shell 中設置了該變量，幷包含開頭的 Bearer 前綴。
• Hardcover API returned an error response 或 401/403：確認令牌有效且未過期。
• 響應緩慢或超時：減少 limit/offset 參數；API 實施了速率限制。從 limit<=10 開始。
• SSL/HTTP 傳輸問題：檢查本地網絡/代理設置，並使用穩定的連接重試。