JinDaGe - harvestr-mcp MCP Details

article

README

🚀 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 令牌

登录到您的 Harvestr.io 账户。
导航至设置 > 集成 > API 访问令牌。
点击 创建新令牌 并复制生成的令牌。

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())

可用工具

用户相关工具

| 工具 | 描述 | |------|-------------| | harvestr_list_users | 列出所有用户 | | harvestr_get_user | 根据 ID 检索特定用户 | | harvestr_list_user_attribute_values | 列出用户的属性值 | | harvestr_update_user_attribute_values | 更新用户的属性值 |

公司相关工具

| 工具 | 描述 | |------|-------------| | harvestr_list_companies | 列出所有公司（可选：按 externalUid 过滤） | | harvestr_create_company | 创建新公司 | | harvestr_get_company | 根据 ID 检索特定公司 | | harvestr_update_company | 更新公司信息 | | harvestr_list_company_attribute_values | 列出公司的属性值 | | harvestr_update_company_attribute_values | 更新公司的属性值 |

组件相关工具

| 工具 | 描述 | |------|-------------| | harvestr_list_components | 列出所有组件（可选：按 parentId 过滤） | | harvestr_get_component | 根据 ID 检索特定组件 |

发现相关工具

| 工具 | 描述 | |------|-------------| | harvestr_list_discoveries | 列出所有发现（可选：按 parentId 过滤，包含字段） | | harvestr_get_discovery | 根据 ID 检索特定发现 | | harvestr_get_discovery_state | 获取发现的当前状态 | | harvestr_list_discovery_feedback | 列出发现的所有反馈 |

发现状态相关工具

| 工具 | 描述 | |------|-------------| | harvestr_list_discovery_states | 列出所有发现状态 | | harvestr_get_discovery_state_by_id | 根据 ID 检索特定发现状态 |

消息相关工具

| 工具 | 描述 | |------|-------------| | harvestr_list_messages | 列出所有消息 | | harvestr_get_message | 根据 ID 检索特定消息 | | harvestr_list_message_feedback | 列出消息的所有反馈 |

反馈相关工具

| 工具 | 描述 | |------|-------------| | harvestr_list_feedback | 列出所有反馈（可选：按 messageId、discoveryId 过滤） | | harvestr_get_feedback | 根据 ID 检索特定反馈 |

属性相关工具

| 工具 | 描述 | |------|-------------| | harvestr_list_user_attributes | 列出所有用户属性定义 | | harvestr_list_company_attributes | 列出所有公司属性定义 |

📚 详细文档

开发环境搭建

# 克隆并进入仓库
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 文件。

harvestr-mcp