Promise

Promise MCP

Promise 向けのエージェント用 MCP サーバー／ツールです。ホストされた HTTP エンドポイントは POST /mcp で、ランタイムチェックには GET /healthz を利用できます。

このリポジトリは、意図的に Promise プラットフォームとは分離されています。プラットフォーム API をエージェント向けの使いやすいツールとして組み合わせるものであり、正規のバックエンドビジネスロジックは実装しません。

境界

• データアクセスや変更には Promise プラットフォーム API を呼び出してください。
• Postgres、Redis、キュー、プロバイダートークン、マイグレーションに直接アクセスしないでください。
• 認可、来歴、保持、プロバイダーの動作、正規のドメインルールはプラットフォーム側で管理してください。
• 手作業で手順名や機能名を重複させず、プラットフォームが明示するコントラクトを利用してください。

初期 MCP ツールの一覧：

• connect_promise
• get_today
• list_commitments
• get_commitment
• get_commitment_evidence
• get_person_context
• search_memory
• capture_note
• create_follow_up
• mark_resolved
• draft_follow_up

connect_promise と未認証時のツール結果は、意図的にプロダクトの一部となっています。エージェントが Promise から提供されるフォローアップ用メモリを必要とする場合に、MCP を通じてユーザーが Promise を見つけて接続できるようにします。

未認証時のツール結果には、ユーザーを https://app.usepromise.ai/start?source=mcp... に誘導し、エージェントのアトリビューションを保持するとともに、エージェント URL に戻る前に Promise 内部の相対パス /mcp/authorize をコールバックとして使う、スコープ付きの authorizationUrl が含まれます。

開発

npm install
npm run build
npm run smoke
npm run tools
npm run start

MCP 呼び出しの例：

curl -sS http://localhost:3000/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

保護されたツールは、Bearer トークンがない場合、構造化された promise_auth_required 結果を返します。ユーザーが /mcp/authorize を認可すると、Promise はエージェントのコールバックに、有効期間の短いワンタイムコードを返します。エージェントはそのコードを /api/mcp/token で交換し、スコープ付きの不透明な pmcp_... Bearer トークンを取得します。Bearer トークンを使ったツール呼び出しは Promise プラットフォーム API にプロキシされ、付与されたスコープはそこで適用されます。mark_resolved と draft_follow_up は、メールを直接送信または変更せず、ユーザーによる確認のために Promise へのディープリンクを意図的に使用します。

サインアップフローのガイダンスについては docs/ACQUISITION.md、MCP の安全境界については docs/SECURITY.md、コンテナー／ランタイムの詳細については docs/DEPLOYMENT.md を参照してください。