seenpaid

seenpaid

どの投稿が収益を生んだのか、AI エージェントに尋ねましょう。

その答えを提供するのが seenpaid.com です。Stripe の売上を、それを生み出した正確な投稿と結び付ける、ホスト型クラウド製品です。このリポジトリはその製品ではありません。その下層にあるオープンな投稿レイヤーです。25 個のプラットフォームアダプターを備えたセルフホスト可能なサービスで、配信をキューに登録して再試行し、MCP（Model Context Protocol）経由で AI エージェントに公開するため、エージェントがあなたに代わって投稿をスケジュールできます。独自のインスタンスにエージェントを接続することも、収益の答えも知りたい場合は seenpaid.com に接続することもできます。MCP の形式は同じで、機能の深さが異なります。

これは何か

• BullMQ を基盤とした公開パイプラインです。投稿を一度スケジュールすると、接続されているすべてのプラットフォームに対して、個別のジョブとして配信され、失敗時には再試行されます。
• 1 つのインターフェースで利用できる 25 個のプラットフォームアダプターです。各プラットフォームで実際に使われている方式に応じて、OAuth、Webhook、API キー、独自の認証情報を貼り付ける方式に対応しています。（ホスト型製品の seenpaid.com では、自分で開発者アプリを登録しなくても顧客が接続できるプラットフォームとして、21 個を案内しています。セルフホストでは自分の認証情報を用意するため、25 個すべてを利用できます。どちらの数字も正確ですが、混同しないでください。）
• REST API と 16 個のツールを備えた MCP サーバーです。スケジュール設定、編集、メディア、アカウントの状態確認に対応し、スクリプトからも AI エージェントからも同じ方法で操作できます。
• 単一の運用者向けに設計されています。API キーは 1 つで、ログイン画面はなく、マルチテナントの概念もありません。デプロイしてキーを設定すれば、すぐに使えます。

これは何ではないか

• 収益のアトリビューション機能はありません。 このリポジトリはクリックを追跡したり、売上と投稿を結び付けたり、どの投稿が収益を生んだかを教えたりしません。それは難易度の高いホスト型サービスである seenpaid.com の機能であり、意図的にこのリポジトリには含めていません。
• 複数ユーザーのアカウント、チーム、ロールには対応していません。 1 つのインスタンスに運用者は 1 人です。それが必要な場合は、クラウド製品をご利用ください。
• 課金、プラン、利用制限はありません。 利用量を計測する対象はありません。これはサブスクリプションではなく、自分で実行するソフトウェアです。

「どの投稿が収益を生んだのか」を知りたい場合、このリポジトリだけでは答えられません。インスタンスのデータを seenpaid.com に接続するか、その目的でセルフホストに時間をかける前に、SELF_HOST.md を読んで現実的なトレードオフを確認してください。

クイックスタート

git clone <this-repo>
cd seenpaid
cp .env.example .env
# fill in API_KEY and TOKEN_ENCRYPTION_KEY (openssl rand -hex 32 for each)
docker compose up -d
docker compose exec api npm run db:migrate

API は http://localhost:3001 でリッスンしています。プラットフォームとエージェントの接続方法を含む詳しい手順は、SELF_HOST.md をご覧ください。

16 個の MCP ツール

MCP 対応エージェントを POST /mcp（Bearer API_KEY）に接続すると、次のツールを利用できます。

ツール	機能
list_accounts	接続済みアカウント — プラットフォーム、ハンドル、ID、ステータス
list_posts	ステータス、予約時刻、配信先、公開エラーを含む投稿一覧
get_post	1 件の投稿の全情報
schedule_post	1 つ、複数、またはすべてのプラットフォームに予約投稿、または即時公開
bulk_schedule	1 回の呼び出しで 1 週間分の投稿を予約。1 件の失敗で残りが止まることはありません
update_post	下書きまたは予約済み投稿のキャプションや時刻を編集
cancel_post	公開前にキャンセル。すでに公開された配信先には影響しません
delete_post	完全に削除 — cancel_post の使用を推奨
list_media	新しい順のメディアライブラリ
add_media_from_url	公開 URL から画像または動画を取り込み
generate_image	テキストプロンプトから画像を生成。キーは不要で、ライブラリに保存
get_account_health	利用可能なアカウントを確認 — 大量投稿の前に確認してください
get_connect_url	アカウント接続用に人間が開くリンク（OAuth には人間の操作が必要です）
disconnect_account	アカウントの接続を解除
get_platform_requirements	キャプションの制限、メディア必須の有無、プラットフォームごとの注意事項
validate_post	公開せずに、プラットフォームごとにキャプションをドライランで検証

これがすべての機能です。get_analytics、get_top_posts、その他の収益関連機能はありません。これらは、非公開ソースのアトリビューションエンジンが必要なため、ホスト型の seenpaid.com MCP サーバーでのみ利用できます。このリポジトリには、そのエンジンは含まれていません。

クライアント設定をそのままコピーして使う場合は、mcp-connector/README.md を参照してください。

対応プラットフォーム

プラットフォーム	接続方法
X (Twitter)	独自の OAuth 1.0a アプリキーを使用
Bluesky	アプリパスワード
LinkedIn	OAuth
Instagram	OAuth (Meta)
Facebook	OAuth (Meta)
TikTok	OAuth
Discord	Webhook URL
Telegram	ボットトークン + チャンネル
Mastodon	OAuth
Nostr	秘密鍵 (nsec/hex)
Dev.to	API キー
Hashnode	個人用アクセストークン
Medium	インテグレーショントークン
Reddit	OAuth
Threads	OAuth
Tumblr	OAuth
Pinterest	OAuth
VK	OAuth
Slack	受信 Webhook URL
WordPress	アプリケーションパスワード
Ghost	管理者 API キー
Lemmy	インスタンスのログイン情報
汎用 Webhook	URL + 署名シークレット（任意）
Micro.blog	アプリトークン
Matrix	ホームサーバー + アクセストークン + ルーム

各アダプターは src/platforms/ にあります。認証情報を設定したプラットフォームのみ利用できます。それ以外はアプリの残りの部分を妨げることなく、明確なエラーを返して正常に失敗します。プラットフォームごとの環境変数の全リストは SELF_HOST.md を参照してください。

アーキテクチャ

src/
  platforms/        25 adapters + registry — one publish()/OAuth interface
  domain/features/
    posts/          Create/list/cancel a post; fans out to per-platform jobs
    accounts/        Connect/list/disconnect a platform account
    media/           Presigned upload, URL ingestion, optional free AI image generation
  jobs/              BullMQ queue + worker: the actual publish pipeline
  entry-points/
    api/             REST API (Express)
    mcp/             The 16-tool MCP server
  auth/              Single-operator API-key auth (see below)
  data-access/       Drizzle ORM schema, repositories, migrations

認証モデル

これは、SaaS 製品に必要なマルチテナントの JWT/RBAC システムとは意図的に異なります。セルフホストではユーザーは自分だけなので、認証には共有シークレットを 1 つ使います。.env に API_KEY を設定し、すべてのリクエストで Authorization: Bearer <key>（または X-Api-Key: <key>）として送信します。サインアップ、ログイン UI、セッション、パスワードハッシュ化はありません。これは多くの単一運用者向けセルフホストツールの認証方式に合わせたものです。シークレットを 1 つ使い、すべてのリクエストで検証するだけなので、それ以上考える必要はありません。

1 つのインスタンスで複数ユーザーやロールベースのアクセスが必要な場合（たとえば、複数のクライアント向けに代理店が運用する場合）は、意図的に対象範囲から外しています。提案方法については CONTRIBUTING.md を参照してください。

ライセンス

コア（mcp-connector/ を除くすべて）は AGPL-3.0 ライセンスです。LICENSE を参照してください。簡単に言うと、自由にセルフホスト、変更、再配布できますが、変更したバージョンを他者向けのネットワークサービスとして運用する場合は、変更後のソースコードも提供する必要があります。これは、変更がプロジェクトに還元されないまま、プロジェクトが非公開ソースの競合サービスに複製されるのを防ぐためのものです。

mcp-connector/（エージェント接続用のクライアント側設定のみ）は MIT ライセンスです。mcp-connector/LICENSE を参照してください。ライセンス上の制約を気にせず、エージェントのディレクトリやその他のツールに自由にコピーできます。

貢献

PR を作成する前に CONTRIBUTING.md をご確認ください。変更の範囲と対応時間について説明しています。