MCPolly

MCPolly

AI エージェント向けの、エージェントネイティブなステータス、可観測性、ナレッジプラットフォームです。MCPolly は、AI エージェントが進捗、エラー、状態をリアルタイムで報告できる MCP サーバーで、人間があらゆる情報を一元的な Web ダッシュボードで監視できます。エージェントは、プロダクトドキュメントをインデックス化し、セマンティック検索を行うことで、常に同じ認識を保つこともできます。

Rust、Axum、SQLite、HTMX で構築されています。最小限のハードウェアでセルフホストできるよう設計されています。

アーキテクチャ

┌─────────────────┐   MCP Streamable HTTP   ┌──────────────────┐
│  AI Agent       │◄───────────────────────►│  MCPolly Server  │
│  (Cursor, etc.) │   JSON-RPC / SSE        │  (Axum + SQLite) │
└─────────────────┘   Bearer auth           └──────┬───────────┘
                                                   │
                                          ┌────────▼────────┐
                                          │   Web Dashboard  │
                                          │   (HTMX UI)      │
                                          └─────────────────┘
                                                   │
                                          ┌────────▼────────┐
                                          │  Ollama (local)  │
                                          │  all-MiniLM      │
                                          └─────────────────┘

MCPolly は、MCP Streamable HTTP プロトコル（SSE ストリーミングを使用した HTTP 上の JSON-RPC）に対応する /mcp エンドポイントを公開します。エージェントプラットフォームは直接接続でき、サブプロセスバイナリは必要ありません。

• MCPolly Server — エージェントデータを SQLite に保存し、Web UI を提供し、アラートルールを評価し、ベクトル埋め込みを管理して、MCP エンドポイントをホストする Axum HTTP サーバーです。
• Ollama — all-MiniLM モデル（384 次元）を使用してベクトル埋め込みを生成するローカル LLM サーバーです。
• mcpolly_mcp (任意) — HTTP MCP トランスポートに対応していないプラットフォーム向けの軽量な stdio バイナリです。stdio と MCPolly HTTP API を橋渡しします。

機能

エージェントの可観測性

• エージェントの登録とステータス追跡（starting、running、warning、error、completed、offline、paused、errored、stopping、stopped）
• 色分けされたエントリを表示するリアルタイムのアクティビティフィード
• すべてのエージェントを対象としたグローバルエラーフィード
• Webhook アラート（Discord、Slack、汎用）と再試行ロジック
• あらゆるステータス変更に対応する設定可能なアラート — error、completed、running、starting、warning、paused、stopped、offline、またはすべてのステータスを対象とするルール
• 応答のないエージェントの検出（バックグラウンドチェッカー）

Web ダッシュボード

• システム設定を検出するダークモード
• 初回起動時のセットアップウィザード（自動ログイン、MCP 設定スニペット付き）
• ログインページからのインスタンスリセット（すべてのキーを無効化し、新しいキーを生成して、セットアップウィザードを再表示）
• ヘルスストリップの概要（エージェントの合計数、実行中、エラー、オフラインの数）
• エージェントをすばやく絞り込むステータスフィルターピル
• タブ形式のコンテンツ（Activity、Errors、Info）を備えたエージェント詳細ページ
• エージェント、エラー、ナレッジを検索するグローバルコマンドバー（Cmd+K）
• 通知履歴を含むアラートルール管理
• セマンティック検索 UI を備えたナレッジページ
• API キー管理
• サーバー情報とセッション管理を備えた設定ページ
• ライブ更新のための 10 秒間隔の HTMX ポーリング

ナレッジレイヤー（ベクトル埋め込み）

• PRD、設計、カスタムドキュメントをベクトル埋め込みとしてインデックス化
• MCP ツールと Web UI を通じて、インデックス化されたすべてのコンテンツをセマンティック検索
• 関連するコンテキストを使って、プロダクトマネージャーエージェントやプロダクトデザイナーエージェントを起動
• sqlite-vec（プロセス内）と Ollama（ローカル、クラウド API キー不要）を利用

インストール

オプション 1：インストールスクリプト（推奨）

OS とアーキテクチャを検出し、GitHub Releases から適切なバイナリをダウンロードします。

curl -fsSL https://raw.githubusercontent.com/MCPolly/mcpolly/main/install.sh | bash

環境変数を使ってカスタマイズできます。

# Install only the MCP stdio bridge
MCPOLLY_BINARY=mcp curl -fsSL https://raw.githubusercontent.com/MCPolly/mcpolly/main/install.sh | bash

# Install to a custom directory
MCPOLLY_INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/MCPolly/mcpolly/main/install.sh | bash

# Install a specific version
MCPOLLY_VERSION=v0.2.0 curl -fsSL https://raw.githubusercontent.com/MCPolly/mcpolly/main/install.sh | bash

対応プラットフォーム：Linux（x86_64、aarch64、armv7）、macOS（x86_64、Apple Silicon）、Windows（x86_64）。

オプション 2：ソースからビルド

git clone https://github.com/MCPolly/mcpolly.git
cd mcpolly
cargo build --release

バイナリは次の場所に生成されます。

• target/release/mcpolly（HTTP サーバー）
• target/release/mcpolly_mcp（MCP stdio ブリッジ）

オプション 3：Cargo でインストール

cargo install mcpolly --bin mcpolly_mcp

セットアップ

1. Ollama をインストールする（ベクトル埋め込み用）

# Install Ollama (https://ollama.ai)
curl -fsSL https://ollama.ai/install.sh | sh

# Pull the embedding model
ollama pull all-minilm

# Ollama runs on http://localhost:11434 by default

ベクトル埋め込みは任意です。MCPolly は Ollama がなくても動作しますが、セマンティック検索と、コンテキストを使ったエージェントの起動は利用できません。

2. MCPolly サーバーを起動する

PORT=3000 RUST_LOG=mcpolly=info ./mcpolly

SQLite データベース（mcpolly.db）は初回起動時に自動作成されます。Web ダッシュボードは http://localhost:3000 で利用できます。

3. API キーを取得する

初回起動時に、MCPolly はデフォルトの API キーを生成し、ブラウザーでセットアップウィザードを開きます。ウィザードにはキーが表示され、そのままコピーできる MCP 設定スニペットが用意されています。キーはサーバーのターミナルにも出力されます。

╔═══════════════════════════════════════════════════════════════╗
║  DEFAULT API KEY (save this — it will not be shown again!)   ║
║                                                               ║
║  mcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx          ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

Web UI の Settings ページ（http://localhost:3000/settings）から、追加のキーを作成できます。

API キーを忘れた場合：ログインページで「Forgot API key? Reset your instance」をクリックしてください。既存のキーがすべて無効になり、新しいキーが生成され、セットアップウィザードに戻ります。

4. MCP クライアントを設定する

AI エージェントプラットフォームの MCP 設定に MCPolly を追加します。

Cursor（HTTP — 推奨）

~/.cursor/mcp.json を編集します。

{
  "mcpServers": {
    "mcpolly": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}

これにより、HTTP 経由で MCPolly サーバーの MCP エンドポイントに直接接続します。バイナリのインストールは不要です。

Cursor（stdio — 代替）

プラットフォームが HTTP MCP トランスポートをサポートしていない場合は、stdio バイナリを使用します。

{
  "mcpServers": {
    "mcpolly": {
      "command": "/path/to/mcpolly_mcp",
      "env": {
        "MCPOLLY_URL": "http://localhost:3000",
        "MCPOLLY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Code

MCPolly は HTTP トランスポート経由で Claude Code に接続します。設定方法は 2 つあります。

オプション A：CLI（ユーザーレベル。すべてのプロジェクトで利用可能）

claude mcp add mcpolly --transport http http://localhost:3000/mcp \
  --header "Authorization: Bearer your-api-key-here"

オプション B：プロジェクトレベルの .mcp.json（リポジトリにコミット）

プロジェクトのルートに .mcp.json を作成します。

{
  "mcpServers": {
    "mcpolly": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}

これにより、ユーザーごとの設定は不要で、プロジェクト内のすべての Claude Code セッションで MCPolly が自動的に利用可能になります。

MCPolly ツールを自動承認する（許可の確認を表示しない）：

プロジェクトまたはユーザー設定の許可リストに mcp__mcpolly__* を追加します。

# Project-level (.claude/settings.json — shared with team)
# or user-level (~/.claude/settings.json — personal)

{
  "permissions": {
    "allow": [
      "mcp__mcpolly__*"
    ]
  }
}

これにより、Claude Code は毎回確認を求めることなく、バックグラウンドで MCPolly のすべてのツールを呼び出せるようになります。

接続を確認する：

claude mcp list

MCPolly のステータスが connected と表示されます。Claude Code セッション内からテストすることもできます。

「mcpolly を使って、登録済みのエージェントをすべて一覧表示してください。」

CLAUDE.md によるエージェント連携の自動化

Claude Code が自動的に自身を登録し、各タスクでステータスを報告するようにするには、プロジェクトの CLAUDE.md に以下を追加します。

## Agent Observability

At the start of every task:
1. Call `register_agent` with your agent name and a brief description.
2. Call `post_status` with state `starting` and a summary of the task.

As you work, call `post_status` at major milestones (state: `running`).

On completion, call `post_status` with state `completed`.

If you encounter an unrecoverable error, call `post_error` before stopping.

5. すべてのエージェントセッションで MCPolly を有効にする（グローバル設定）

すべてのプロジェクトで、すべての Claude Code セッションが MCPolly に自動的に登録し、ステータスを報告するようにするには、MCP サーバーとエージェントへの指示の両方をグローバルに設定します。

手順 1：MCPolly をグローバル MCP サーバーとして追加する

claude mcp add mcpolly --transport http http://localhost:3000/mcp \
  --header "Authorization: Bearer your-api-key-here"

これにより、プロジェクトごとの .mcp.json ファイルがなくても、すべての Claude Code セッションで MCPolly の MCP ツールを利用できるようになります。

手順 2：MCPolly ツールをグローバルに自動承認する

~/.claude/settings.json を編集します（存在しない場合は作成してください）。

{
  "permissions": {
    "allow": [
      "mcp__mcpolly__*"
    ]
  }
}

これにより、Claude Code が MCPolly のツールを呼び出すたびに許可を求めるプロンプトが表示されなくなります。

手順 3：グローバル CLAUDE.md にエージェントへの指示を追加する

GLOBAL_CLAUDE.md の内容を ~/.claude/CLAUDE.md に追記します（存在しない場合は作成してください）。

cat /path/to/mcpolly/GLOBAL_CLAUDE.md >> ~/.claude/CLAUDE.md

または、手動で以下を追加します。

## Agent Observability

At the start of every task:
1. Call `register_agent` with your agent name and a brief description.
2. Call `post_status` with state `starting` and a summary of the task.

As you work, call `post_status` at major milestones (state: `running`).

On completion, call `post_status` with state `completed`.

If you encounter an unrecoverable error, call `post_error` before stopping.

グローバルな ~/.claude/CLAUDE.md ファイルは、すべての Claude Code セッションに自動的に読み込まれます。これを設定すると、どのプロジェクトのエージェントも MCPolly に自身を登録し、作業中にステータスを報告し、完了またはエラーを通知するようになります。

6. 確認する

新しい Cursor エージェントセッションを開き、エージェントの一覧表示を依頼します。

「mcpolly を使って、登録済みのエージェントをすべて一覧表示してください。」

エージェント連携の自動化

MCPolly を設定すると、手動で指示しなくても、すべての AI エージェントセッションが自動的に自身を登録し、ステータスを報告するようにできます。

仕組み

用意されている Cursor ルールファイルを、任意のプロジェクトにコピーします。

mkdir -p .cursor/rules
cp /path/to/mcpolly/.cursor/rules/mcpolly.mdc .cursor/rules/

このルールファイルにより、そのプロジェクトのすべての Cursor エージェントに以下を指示します。

1. 各タスクの開始時に MCPolly に登録する
2. 主な手順を進めながらステータスを報告する
3. タスクの完了時に完了を報告する
4. 問題が発生した場合にエラーを報告する

MCP ツール

設定が完了すると、以下の MCP ツールを AI エージェントで利用できます。

エージェント管理

ツール	説明
register_agent	新しいエージェントを登録します（名前＋説明）。エージェント ID を返します。同じ名前での登録は冪等です。
post_status	ステータス更新（状態＋メッセージ）を投稿します。状態：starting、running、warning、error、completed、offline、paused、errored。
post_error	重大度（error、warning、critical）を指定してエラーを報告します。設定済みのアラートをトリガーします。
list_agents	登録済みのすべてのエージェントと現在のステータスを一覧表示します。
get_agent_activity	特定のエージェントの最近のアクティビティタイムラインを取得します。

ベクトル埋め込み

ツール	説明
update_prd_embeddings	意味検索用に PRD ドキュメントをインデックス化します（Markdown をチャンクに分割し、Ollama 経由で埋め込みを生成します）。
update_design_embeddings	意味検索用にデザインドキュメントをインデックス化します。
search_embeddings	自然言語を使ってインデックス化済みのドキュメントを検索します。類似度順にランク付けした結果を返します。
list_embedding_sources	チャンク数とタイムスタンプを含む、インデックス化済み埋め込みソースをすべて一覧表示します。
delete_embeddings	指定したソース名の埋め込みをすべて削除します。

エージェントの起動

ツール	説明
spawn_product_manager	埋め込みから関連するコンテキストを取得して、プロダクトマネージャーエージェントを起動します。
spawn_product_designer	関連する PRD とデザインのコンテキストを取得して、プロダクトデザイナーエージェントを起動します。

環境変数

MCPolly サーバー

変数	デフォルト	説明
PORT	3000	HTTP サーバーのポート
DATABASE_URL	mcpolly.db	SQLite データベースファイルのパス
RUST_LOG	info	ログレベル（trace、debug、info、warn、error）
OLLAMA_URL	http://localhost:11434	Ollama API のベース URL
OLLAMA_EMBEDDING_MODEL	all-minilm	埋め込みモデル名

MCP バイナリ（mcpolly_mcp）

変数	必須	説明
MCPOLLY_URL	はい	MCPolly HTTP サーバーのベース URL
MCPOLLY_API_KEY	はい	認証用 API キー

API エンドポイント

JSON API（/api/v1/...、API キーヘッダーが必要）

メソッド	パス	説明
GET	/api/v1/agents	すべてのエージェントを一覧表示します
POST	/api/v1/agents/register	エージェントを登録します
GET	/api/v1/agents/:id	エージェントの詳細を取得します
GET	/api/v1/agents/:id/activity	エージェントのアクティビティを取得します
GET	/api/v1/agents/:id/errors	エージェントのエラーを取得します
POST	/api/v1/status	ステータス更新を投稿します
POST	/api/v1/errors	エラーを投稿します
GET/POST	/api/v1/alerts	アラートルールを一覧表示／作成します
GET	/api/v1/alerts/history	アラート通知の履歴
DELETE	/api/v1/alerts/:id	アラートルールを削除します
GET/POST	/api/v1/keys	API キーを一覧表示／作成します
DELETE	/api/v1/keys/:id	API キーを無効化します
POST	/api/v1/embeddings/index	ドキュメントをインデックス化します
GET	/api/v1/embeddings/search	意味検索
GET	/api/v1/embeddings/sources	埋め込みソースを一覧表示します
DELETE	/api/v1/embeddings/sources/:name	埋め込みを削除します
GET	/api/v1/server/info	サーバーのバージョン、稼働時間、DB サイズ

アラート条件

アラートルールは、エージェントのステータス変更に対して設定できます。

条件	発生するタイミング
any_status	エージェントからステータス更新があったとき
agent_completed	エージェントが completed 状態を投稿したとき
agent_running	エージェントが running 状態を投稿したとき
agent_starting	エージェントが starting 状態を投稿したとき
agent_error	エージェントが error または errored 状態を投稿したとき
agent_warning	エージェントが warning 状態を投稿したとき
agent_paused	エージェントが paused 状態を投稿したとき
agent_stopped	エージェントが stopped 状態を投稿したとき
agent_stopping	エージェントが stopping 状態を投稿したとき
agent_offline	エージェントから応答がなくなったとき（バックグラウンドチェッカー）

対応チャネル：Discord、Slack、汎用 Webhook（プレーンな JSON POST）。

MCP エンドポイント

パス	説明
/mcp	MCP Streamable HTTP エンドポイント（JSON-RPC + SSE）

開発

ローカル開発サーバー

PORT=3000 RUST_LOG=mcpolly=info cargo run --bin mcpolly

MCP バイナリのビルド

cargo build --bin mcpolly_mcp

リリースビルド

cargo build --release

アップグレード

アップグレードスクリプトを使用すると、実行中の MCPolly インスタンスを安全に更新できます。

./upgrade.sh

スクリプトは次の処理を行います。

1. GitHub Releases から新しいバイナリをダウンロードして検証します
2. SQLite データベースをバックアップします（最新の 5 件のバックアップを保持します）
3. サービスを正常に停止します
4. バイナリを差し替えます
5. 再起動してヘルスチェックを行います。新しいバージョンの起動に失敗した場合は、自動的にロールバックします

オプション：

# Upgrade to a specific version
MCPOLLY_VERSION=v0.3.0 ./upgrade.sh

# Dry run (see what would happen without changing anything)
MCPOLLY_DRY_RUN=1 ./upgrade.sh

# Skip database backup
MCPOLLY_SKIP_BACKUP=1 ./upgrade.sh

アップグレードスクリプトは、インストール先、systemd サービスの種類（ユーザーまたはシステム）、データベースのパスを自動検出します。

デプロイ

MCPolly は最小限のハードウェアで動作するように設計されています。月額 4 ドルの VPS で十分です。

前提条件

• Ollama がインストールされ、all-minilm モデルを取得した状態で実行されていること（埋め込み用）
• ポート 3000（または設定済みのポート）が利用可能であること

systemd サービス

/etc/systemd/system/mcpolly.service を作成します。

[Unit]
Description=MCPolly Agent Observability Server
After=network.target

[Service]
Type=simple
User=mcpolly
WorkingDirectory=/opt/mcpolly
ExecStart=/opt/mcpolly/mcpolly
Environment=PORT=3000
Environment=RUST_LOG=mcpolly=info
Environment=DATABASE_URL=/opt/mcpolly/data/mcpolly.db
Environment=OLLAMA_URL=http://localhost:11434
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now mcpolly

リバースプロキシ（Caddy）

mcpolly.example.com {
    reverse_proxy localhost:3000
}

Caddy は Let's Encrypt を使用して TLS を自動的に処理します。

ライセンス

MIT