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 文件。