Harvestr MCP

🚀 Harvestr MCP Server

Harvestr.io は、顧客のフィードバック、発見、コンポーネントを管理するための製品管理プラットフォームです。このサーバーは、そのための Model Context Protocol (MCP) サーバーです。

FastMCP を使用して構築されており、クリーンで Python らしい 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

永続的な設定を行うには、シェルプロファイル (~/.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 Inspector でのテスト (オプション)

サーバーのツールを対話的にテストするには、次のコマンドを実行します。

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

これにより、利用可能なすべてのツールを探索およびテストできる Web インターフェイスが開きます。

📦 インストール

uv を使用する (推奨)

uv pip install -e .

pip を使用する

pip install -e .

💻 使用例

サーバーの起動

Stdio トランスポート (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 Inspector でのテスト

サーバーの対話的なテストを行うには、次のコマンドを実行します。

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

コードフォーマット

このプロジェクトは Ruff を使用してリントとフォーマットを行っています。

# 問題をチェック
ruff check .

# 問題を自動修正
ruff check --fix .

# コードをフォーマット
ruff format .

📚 ドキュメント

詳細な API ドキュメントについては、Harvestr API Docs を参照してください。

📄 ライセンス

MIT ライセンス - 詳細は LICENSE を参照してください。