Harvestr MCP

🚀 Harvestr MCP 服務器

Harvestr MCP 服務器是一個基於 Model Context Protocol (MCP) 的服務器，為 Harvestr.io 服務。Harvestr.io 是一個產品管理平臺，用於管理客戶反饋、發現和組件。

它基於 FastMCP 構建，能夠以簡潔、Pythonic 的方式進行 MCP 開發。

✨ 主要特性

• 公司管理：列出、創建、更新和管理公司及其屬性。
• 組件瀏覽：瀏覽產品組件及其層次結構。
• 發現追蹤：訪問功能請求、錯誤報告和見解，並跟蹤其狀態。
• 反饋管理：管理與消息和發現相關的客戶反饋。
• 消息訪問：訪問客戶通信內容。
• 用戶管理：列出用戶並管理其屬性。
• 屬性定義：訪問用戶和公司的自定義字段定義。

🚀 快速開始

前提條件

• Python 3.10 或更高版本
• uv（推薦）或 pip
• 具有 API 訪問權限的 Harvestr.io 賬戶

1. 克隆並安裝項目

# 克隆倉庫
git clone https://github.com/your-org/harvestr-mcp.git
cd harvestr-mcp

# 使用 uv 安裝（推薦）
uv pip install -e .

# 或者使用 pip 安裝
pip install -e .

2. 獲取 Harvestr API 令牌

1. 登錄到您的 Harvestr.io 賬戶。
2. 導航至 設置 > 集成 > API 訪問令牌。
3. 點擊 創建新令牌 並複製生成的令牌。

3. 配置 API 令牌

將您的 API 令牌設置為環境變量：

# Linux/macOS
export HARVESTR_API_TOKEN="your-api-token-here"

# Windows (PowerShell)
$env:HARVESTR_API_TOKEN="your-api-token-here"

# Windows (CMD)
set HARVESTR_API_TOKEN=your-api-token-here

若要進行持久化配置，請將 export 命令添加到您的 shell 配置文件（~/.bashrc、~/.zshrc 等）中：

echo 'export HARVESTR_API_TOKEN="your-api-token-here"' >> ~/.bashrc
source ~/.bashrc

⚠️ 重要提示

請像對待密碼一樣對待您的 API 令牌。切勿將其提交到版本控制系統或公開分享。

4. 運行服務器

# 使用 FastMCP CLI（推薦）
fastmcp run src/harvestr_mcp/server.py:mcp

# 或者直接使用 Python 運行
python -m harvestr_mcp.server

5. 使用 MCP 檢查器進行測試（可選）

若要交互式地測試服務器工具，請執行以下命令：

npx @modelcontextprotocol/inspector fastmcp run src/harvestr_mcp/server.py:mcp

這將打開一個 Web 界面，您可以在其中探索和測試所有可用工具。

📦 安裝指南

使用 uv 安裝（推薦）

uv pip install -e .

使用 pip 安裝

pip install -e .

💻 使用示例

運行服務器

標準輸入輸出傳輸（用於與 MCP 客戶端進行本地交互）

# 使用 FastMCP CLI
fastmcp run src/harvestr_mcp/server.py:mcp

# 或者直接使用 Python
python -m harvestr_mcp.server

HTTP 傳輸（用於遠程訪問）

fastmcp run src/harvestr_mcp/server.py:mcp --transport http --port 8000

與 Claude Desktop 配合使用

將以下內容添加到您的 Claude Desktop 配置文件（Linux/Mac 系統為 ~/.config/claude/claude_desktop_config.json，Windows 系統為 %APPDATA%\Claude\claude_desktop_config.json）中：

{
  "mcpServers": {
    "harvestr": {
      "command": "uv",
      "args": ["run", "fastmcp", "run", "/path/to/harvestr-mcp/src/harvestr_mcp/server.py:mcp"],
      "env": {
        "HARVESTR_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

與 FastMCP 客戶端配合使用

import asyncio
from fastmcp import Client

async def main():
    async with Client("http://localhost:8000/mcp") as client:
        # 列出所有公司
        companies = await client.call_tool("harvestr_list_companies")
        print(companies)

        # 獲取特定發現
        discovery = await client.call_tool(
            "harvestr_get_discovery",
            {"discovery_id": "abc123", "include_fields": True}
        )
        print(discovery)

asyncio.run(main())

可用工具

用戶相關工具

公司相關工具

組件相關工具

發現相關工具

發現狀態相關工具

消息相關工具

反饋相關工具

屬性相關工具

📚 詳細文檔

開發環境搭建

# 克隆並進入倉庫
git clone https://github.com/your-org/harvestr-mcp.git
cd harvestr-mcp

# 使用 uv 安裝開發依賴（推薦）
uv pip install -e ".[dev]"

# 或者使用 pip 安裝
pip install -e ".[dev]"

運行測試

測試套件使用 pytest 和 pytest-asyncio 來支持異步測試：

# 運行所有測試
pytest

# 運行並輸出詳細信息
pytest -v

# 運行特定測試文件
pytest tests/test_client.py

# 運行特定測試類
pytest tests/test_server.py::TestUserTools

# 運行並統計覆蓋率（如果已安裝）
pytest --cov=harvestr_mcp

測試結構

tests/
├── __init__.py
├── conftest.py      # 共享測試夾具和配置
├── test_client.py   # Harvestr API 客戶端測試
├── test_types.py    # Pydantic 模型測試
└── test_server.py   # MCP 服務器工具測試

使用 MCP 檢查器進行測試

若要交互式地測試服務器，請執行以下命令：

npx @modelcontextprotocol/inspector fastmcp run src/harvestr_mcp/server.py:mcp

代碼格式化

本項目使用 Ruff 進行代碼檢查和格式化：

# 檢查問題
ruff check .

# 自動修復問題
ruff check --fix .

# 格式化代碼
ruff format .

API 文檔

有關詳細的 API 文檔，請參閱 Harvestr API 文檔。

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。