kompa-mcp-server

Kompa のソーシャルリスニングデータ — バズ、センチメント内訳、トレンドライン、ホットトピック、ユニーク著者 — を、任意の MCP クライアントから呼び出せるツールとして公開する MCP（Model Context Protocol）サーバーです。スタンドアロンのチャット UI を使う代わりに、Claude（Desktop または Code）の中で直接 Kompa データについてチャットできるように作られています。

このパッケージは kompa-chat の Next.js アプリから独立しています — 同じ Kompa GraphQL API とログインフローを再利用し、プレーンな MCP サーバーに移植しただけです。エントリポイントは 2 つあります:

• build/index.js — stdio トランスポート。ローカル設定で設定する Claude Desktop / Code など、子プロセスを起動するローカル MCP クライアント向けです。

• build/http.js — Streamable HTTP トランスポート。マルチテナント対応です。ホストされた 1 つのコネクタ URL で多数の顧客にサービスを提供できます。完全な VPS デプロイガイド（systemd + Caddy + 顧客のオンボーディング）は DEPLOY.md を参照してください。

アカウントとトピック設定

専用の API キーシステムはありません。各顧客は既に Kompa のユーザー名/パスワードを持っているので、ここではそれをツール呼び出しで使用します:

configure_account({ username, password, topicIds: ["topic-id-1", ...] })

会話の最初に一度だけ呼び出してください（資格情報やトピックに触れると Claude が自動的に呼び出しますし、明示的に依頼しても構いません）。他のすべてのツールは、configure_account を再度呼び出すまで、そのアカウントと topic_ids を再利用します。毎回の呼び出しで設定を繰り返す必要はありませんが、呼び出しごとに topicIds を渡して上書きすることもできます。

これはヘッダーベースの認証の代わりに存在します。コネクタ向けの Claude のカスタムリクエストヘッダーが現在は限定ベータ（gated beta）であるためです — DEPLOY.md の「Auth model」の注記を参照してください。

stdio エントポイントでは、ツール呼び出しを完全にスキップできます。KOMPA_USERNAME / KOMPA_PASSWORD / KOMPA_DEFAULT_INDEXES 環境変数を設定すれば、その場合アカウントは起動時に事前設定されます。

ツール

すべてのデータツールは fromDate / toDate（"YYYY-MM-DD HH:mm:ss"）、任意の types、query、sentiments、および任意の topicIds（未指定の場合は configure_account で設定した topicIds にフォールバック）を受け入れます。

セットアップ

npm install
npm run build

参考用に .env.example をコピーしてください（stdio エントリポイントにのみ関係あります — 上記の通り）。

スタンドアロンで使う（公開前に）

{
  "mcpServers": {
    "kompa": {
      "command": "node",
      "args": ["/absolute/path/to/kompa-mcp-server/build/index.js"]
    }
  }
}

任意の MCP クライアントから、ビルド済みのエントリファイルを直接参照してください:

• Claude Desktop — このブロックを claude_desktop_config.json に追加します（Settings → Developer → Edit Config）。

• Claude Code — 同じ mcpServers ブロックをプロジェクトルートの .mcp.json に追加するか、以下を実行します:

  claude mcp add kompa -- node /absolute/path/to/kompa-mcp-server/build/index.js

設定を編集したらクライアントを再起動し、チャットで 「My Kompa account is X/Y, topic ID Z — what's the sentiment breakdown for query 'foo' between 2026-08-01 and 2026-08-21?」 のように発言してみてください — Claude が configure_account を呼び出し、続けてデータツールを呼び出します。

npm への公開

ユーザーがローカルパスではなく npx kompa-mcp-server でインストールできるようになります:

npm login
npm publish --access public

すると、MCP 設定は次のようになります:

{
  "mcpServers": {
    "kompa": {
      "command": "npx",
      "args": ["-y", "kompa-mcp-server"]
    }
  }
}

Claude Code のプラグインマーケットプレイスへの公開

Claude Code も、Team / Enterprise 組織向けの claude.ai 自体も、git リポジトリから直接プラグインマーケットプレイスを追加できます — ここでは npm に公開する必要はありません。marketplace-example/plugins/kompa-mcp/.claude-plugin/plugin.json はローカルパッケージではなく、ホスト済みの HTTP コネクタを指すためです（DEPLOY.md 参照）。レイアウト:

marketplace-example/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── kompa-mcp/
        └── .claude-plugin/
            └── plugin.json      # edit the connector URL in here first

メンテナーとして:

1. marketplace-example/plugins/kompa-mcp/.claude-plugin/plugin.json 内の url を実際にデプロイしたドメイン（https://mcp.yourdomain.com/mcp）に編集します。

2. marketplace-example/ のレイアウトを含むリポジトリ（フォルダ名をリポジトリルートにしたい名前に変更してください）を GitHub にプッシュします — public か、 自分の Organization だけが使うなら private で構いません（private の場合は、インストールする全員が GitHub の資格情報でリポジトリアクセス権を持っている必要があります）。

3. リポジトリの URL を共有します。

Claude Code ユーザーとしてインストールする場合:

/plugin marketplace add https://github.com/<you>/<marketplace-repo>
/plugin install kompa-mcp-plugin@<marketplace-name>

claude.ai の Team / Enterprise 組織の場合（CLI なし、GUI のみ）:

1. 組織オーナー: Organization settings → Connectors/Plugins → Add plugin marketplace → "Add from a repository" → 同じ GitHub URL を貼り付けます。

2. メンバー: Customize → Plugins で、マーケットプレイスから kompa-mcp-plugin を探し、「install / connect」をクリックします。

組織を持たない Free / Pro / Max の個人アカウントでは、このリポジトリベースのマーケットプレイス方式は使えません — 代わりに PLUGIN.md の ZIP アップロードフローを利用してください。

メモ / 制限事項

• ログインは kompa-chat の auth.ts と同じユーザー名+パスワードフローを使います — OAuth なし、ブラウザ操作の自動化はありません。

• アクセストークンはプロセス内でユーザーごとにキャッシュされ、有効期限の 5 分前にリフレッシュされます。

• topicIds は、アカウントがアクセスできる有効な Kompa プロジェクトのインデックス ID である必要があります。このサーバーがそれらを発見したり一覧表示したりすることはありません。

• HTTP モードでは、アカウント / トピック設定はその MCP セッションのメモリ内にのみ保持されます。会話 / セッションを閉じると破棄され、次のセッションでは再度 configure_account を呼び出す必要があります。