Homespun

@homespunapps/mcp

Homespun 向けの薄い stdio Model Context Protocol サーバーです。任意の MCP クライアント（Claude Desktop、Cursor、Windsurf、Cline、独自のホスト）から、実際に動作するマルチユーザーの Web アプリを 1 回の呼び出しでデプロイし、その後もデータの操作を続けられます。アプリ専用の URL でのホスティング、マジックリンクによる認証、ロールごとの権限を備えた共有リアルタイムデータベース、メール通知、ファイル添付がすべて含まれています。

これは再実装ではなくラッパーです。リレーとのすべての I/O は @homespunapps/core を経由し、設定は homespun CLI と共有されるため（~/.config/homespun/config.json）、CLI とこのサーバーは同じエージェント IDを使用します。

実行要件：Node.js >= 20

バイナリは homespun-mcp です。stdio 経由で MCP を使用し、MCP ホストから起動することを想定しているため、対話形式で実行するものではありません。

クイックスタート

グローバルインストールは不要です。MCP クライアントで npx @homespunapps/mcp を指定してください。初回使用時に API キーが設定されていない場合、サーバーはホスト型リレーに対して新しいエージェントを自動登録し、共有 CLI ストアにキーを保存します。それ以外の設定は不要です。

Claude Desktop

claude_desktop_config.json を編集します（macOS の場合：~/Library/Application Support/Claude/claude_desktop_config.json）。

{
  "mcpServers": {
    "homespun": {
      "command": "npx",
      "args": ["-y", "@homespunapps/mcp"]
    }
  }
}

自動登録の代わりに既存のエージェントキーを指定するには、env ブロックを追加します。

{
  "mcpServers": {
    "homespun": {
      "command": "npx",
      "args": ["-y", "@homespunapps/mcp"],
      "env": { "HOMESPUN_API_KEY": "hs_..." }
    }
  }
}

Cursor

~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクト）に追加します。

{
  "mcpServers": {
    "homespun": {
      "command": "npx",
      "args": ["-y", "@homespunapps/mcp"],
      "env": { "HOMESPUN_API_KEY": "hs_..." }
    }
  }
}

汎用 MCP ホスト

command + args + env を指定するクライアントであれば、同じ方法で使用できます。

{
  "mcpServers": {
    "homespun": {
      "command": "npx",
      "args": ["-y", "@homespunapps/mcp"],
      "env": {
        "HOMESPUN_URL": "https://homespun.dev",
        "HOMESPUN_API_KEY": "hs_..."
      }
    }
  }
}

グローバルにインストールする場合（npm i -g @homespunapps/mcp）は、args を指定せずに "command": "homespun-mcp" を使用します。

設定

環境変数はすべて省略可能です。デフォルトではホスト型リレーを対象とし、初回使用時に自動登録します。

変数	デフォルト	用途
HOMESPUN_URL	https://homespun.dev	リレーのベース URL。別のリレーを指定する場合に設定します。
HOMESPUN_API_KEY	(自動登録)	エージェント API キー。未設定の場合、サーバーは初回使用時にエージェントを登録し、キーを ~/.config/homespun/config.json（CLI と共有）に保存します。
HOMESPUN_TOKEN	(なし)	HOMESPUN_API_KEY の別名です（シークレット名を *_TOKEN とするホスト向け）。両方が設定されている場合は HOMESPUN_API_KEY が優先されます。
HOMESPUN_AGENT_NAME	homespun-mcp	自動登録されるエージェントの表示名です。
HOMESPUN_REGISTER_SECRET	(なし)	登録シークレットです。REGISTRATION_MODE=secret で動作するリレーでのみ使用します。

設定の優先順位は CLI と同じです。環境変数が保存済みプロファイルより優先され、保存済みプロファイルがない場合はデフォルトのリレー URL が使用されます。

ツール

このサーバーは**homespun CLIと完全に同等**です。CLI が提供するすべての機能をここから利用できます。

MCP ツールはリクエストとレスポンスの形式であるため、長時間継続する「監視」はありません。変更を確認するには、前回の呼び出しで得たカーソルを使って get_feed_events をポーリングします（ロングポーリングには wait を渡します。指定できる秒数は 0～30 秒です）。1 つのコレクションを監視するには、前回の next_cursor を since として指定し、list_rows を再度呼び出します。各ツールの説明には、モデル向けにこのパターンが記載されています。

ツール一覧をコンパクトに保つため（50 以上のツールをそのまま並べるとクライアントのコンテキストが肥大化し、選択精度が低下します）、頻繁に使う操作の名詞は個別のツールとして維持し、一方で動詞が複数ある管理操作の名詞は、必須の action 列挙型を持つ 1 つのツールにまとめています。

ホットパス（個別）ツール

ツール	説明
deploy_app	v2 アプリをデプロイします。HTML ドキュメントと機能マニフェストを、専用の URL でホストします。新規作成する場合は app_id を省略し、既存のアプリをそのまま再デプロイする場合は指定します（URL、データ、メンバーは変わりません）。html または html_path と、任意の assets、visibility、slug、dry_run、force を指定します。
list_rows	コレクション内の行を一覧表示します。以前の next_cursor を since として渡すと、コレクションの現在の状態をポーリングする用途にも使えます。
get_row	key で行を1つ取得します（クライアント側でスキャンするのではなく、専用のリレールートを使います）。
add_row	行を作成します。key がすでに存在する場合は既存の行を返し（deduped: true）、コレクションの read リストがその行へのアクセスを許可していない場合は row_not_found を返します。作成を表す唯一の動詞です。
update_row	既存の行の data を置き換えます。任意で if_match による楽観ロックを指定できます。
delete_row	行をソフト削除します。任意で if_match を指定できます。
get_feed_events	人間またはエージェントを問わず、すべての書き込み元による行の作成、更新、削除について、アプリの変更フィードをポーリングします。任意で wait（0～30秒）のロングポーリングを指定できます。

統合ツール（1つのツールに必須の action を指定）

ツール	アクション
apps	list · show · update · share_link_rotate · delete · wake · domain_set · domain_status · domain_remove
members	add · list · set_role · remove · roles
grants	mint · list · revoke
ingest	list · rotate · set_signing_secret · clear_signing_secret
attachments	upload · fetch · presign · finalize · download · show · list · delete · mint_token · revoke_token · list_tokens
taste	get · set · clear
key	list · mint · revoke
feedback	create · list
agent	whoami · claim · logout
community	publish · unpublish · get_config_contract · install · list_pending · get_submission · approve · reject · set_trust_level
publisher	claim · get · update
review	create · respond · report · remove · unhold

単機能ツール

ツール	説明
get_skill	リレーの自動更新ガイドを取得し（認証不要）、ワークフローを自分で学べます。

添付ファイルではファイルパスを受け渡します。upload は絶対パスの file_path を読み込み、download は絶対パスの out_path に書き込みます（省略した場合は base64 を返します）。実際のメディアでは、presign の後に PUT を行い、さらに finalize することで、ツール呼び出しを介したバイトデータの転送を避けられます。

データプリミティブは1つです。 アプリが保存するものはすべてコレクションです。コレクションは名前付きで、変更やクエリが可能な行の集合です。各行は key、data ペイロード、楽観ロック用の version、author を持ちます。書き込みはすべて、アプリの順序付き変更フィードにも記録されます。変更可能な状態ではなく、ジャーナル（監査証跡や提出ログなど）が必要な場合は、マニフェストでコレクションに appendOnly: true を宣言してください。

公開されていない機能（およびその理由）

• CLI の config show は agent → whoami に置き換えられています（解決されたリレー URL、アクティブなプロファイル、キーが設定されているかどうかを表示し、シークレットは表示しません）。
• agent register はツールではありません。サーバーは初回使用時に自動登録され、CLI のキーストアを共有します。その後、agent → claim で人間に紐付けます。
• demo（対話型のターミナルツアー）と CLI のセルフアップデーターはターミナルでの使用を想定しており、エージェントでの用途はありません。そのため省略されています。

一般的なフロー

1. アプリのコレクションと、各コレクションの読み取り、書き込み、削除を許可するロールを宣言した x-homespun-manifest と、HTML を指定して deploy_app を実行します。{ app_id, url, ... } が返されます。
2. url を所有者に渡し、ほかのユーザーは members（action: add）で招待します。
3. get_feed_events に wait: 25 を指定してループ内で実行し、以前の cursor を since として渡すことで、ユーザーの操作を確認します。
4. list_rows／add_row／update_row で同じデータを読み書きし、app_id を指定して再度 deploy_app を実行し、変更を反映します。

MCP レジストリ

server.json（このパッケージ内）には、公式 MCP レジストリのメタデータが含まれています。そこへの公開は、メンテナーが後続の手順として行います。

ライセンス

MIT。詳細は LICENSE をご覧ください。