muovi

@muovi/mcp-server

Muovi 向けの Model Context Protocol (MCP) サーバー — 信頼を第一に考える LATAM の地域サービスマーケットプレイスです。

このパッケージを使うと、MCP 対応クライアント（Claude Desktop、Cursor、Claude Code、その他あらゆる MCP ホスト）から、Muovi の審査済み LATAM サービス専門家の検索、サービスカタログと都市一覧の閲覧、レビューの確認、プラットフォーム上のタスク作成フローへのユーザーの直接リンク、ユーザー自身が公開するタスクの下書き保存ができます。Muovi の公開 /v1 REST API を薄くラップしたものです。

Stdio モード。 このパッケージには、標準入力／標準出力経由で JSON-RPC を扱う npx で実行可能なバイナリが含まれています。ホスト型 HTTP/SSE 版は別途追跡されています（Muovi MOB-142）。

公開する機能

muovi_create_task_draft は Muovi に下書きを保存しますが、それ以外のすべてのツールは読み取り専用です。

ツール	ラップ対象	目的
muovi_search_professionals	GET /v1/professionals	1 つのサービスと 1 つのバリオを指定して、最大 5 人の専門家を取得します。service と neighborhood はどちらも必須です。すべての結果には、そのバリオを含む対応エリアがあり、match には検索したサービス、バリオ、都市が示されます。検索対象の職種を申告している専門家がレビュー評価順に先に表示され、本人確認、身元調査、専門資格も評価に反映されます。登録事業が別の職種である専門家は最後に表示されます。評価やレビューによるフィルターはありません。各結果には、rating、review_count、verifications、最大 3 件の portfolio 画像 URL、id、profile_url（https://muovi.com.ar/profile/<id>）が含まれ、neighborhoods は含まれません。
muovi_get_professional	GET /v1/professionals/{id}	検索結果の id を使って、専門家 1 人の公開プロフィール全体（自己紹介、ポートフォリオ、専門分野、確認済み情報）を取得します。以前のリンクにある ProSite スラッグも受け付けます。
muovi_list_services	GET /v1/services	現在のサービスカタログ全体です。住宅関連の職種（electricidad、plomería、gas、pintura、carpintería、cerrajería、albañilería、herrería、techista）、清掃、園芸、エアコンのほか、引っ越し／運搬サービスの mudanzas（引っ越し業者）と fletes（小口貨物）も含まれます。
muovi_list_cities	GET /v1/cities	Muovi がサービスを提供するアルゼンチンのすべての都市と、その近隣地域を取得します。
muovi_get_reviews	GET /v1/professionals/{id}/reviews	同じ id を使って、専門家のレビューを新しい順にページ分割して取得します。
muovi_create_task_link	（純粋なフォーマッター）	1 人の専門家（検索結果の id である professional_id）と 1 つのサービスに対する、Muovi のタスク作成ページへのリンクを生成します。https://muovi.com.ar/post-task/v2?pro=<id>&vertical=<service>&source=assistant-link。結果に含まれるすべての専門家に対して使えます。引数がない場合や形式が正しくない場合は、ツールエラーになります。HTTP 呼び出しは行いません。
muovi_get_service_requirements	GET /v1/services/{service_slug}/requirements	サービスごとに Muovi が尋ねる質問（キー、スペイン語の質問、種類、選択可能な項目、必須かどうか）を一覧表示します。これにより、エージェントは下書きを保存する前にユーザーへ質問できます。
muovi_create_task_draft	POST /v1/task-handovers	タスクの下書き（サービス、説明、任意の地域、希望時間、専門家）を保存し、誰も開かなかった場合は 24 時間で有効期限が切れるリンクを返します。ユーザーはリンクを開いて下書きを確認し、サインインして公開します。このツールが公開することはありません。professional_id（検索結果の id）を指定すると、公開されたタスクは最初の 24 時間その専門家に送られ、その後すべての人に公開されます。open_to_others: true を指定すると、最初からすべての人に公開され、専門家にも通知されます。ユーザーは確認フォームでこの選択を変更できます。

情報漏えい防止ポリシー

Muovi はプラットフォーム内でのみ利用できます。電話番号、メールアドレス、WhatsApp の連絡先は公開 API から返されません。利用者と専門家の連絡は、各専門家の profile_url からアクセスできる Muovi アプリ内の会話フローでのみ行われます。

このサーバーでは、このポリシーを二重に適用します。

1. /v1 API がサーバー側で連絡先データを除去します。
2. このパッケージのすべてのツールのレスポンスも、ローカルの情報漏えい検出器（Muovi の Web リポジトリにある src/lib/anti-leakage/detector.ts の Node 対応ミラー）を通過します。エージェントとの境界で漏えいが検出された場合、ツールは LLM クライアントに安定したエラーを返し、ペイロードの表示を拒否します。

このサーバーを統合するホストは、いかなるフィールドからもプラットフォーム外の連絡先情報を生成してはいけません。連絡手段として認められているのは、ユーザーを profile_url に誘導すること（必要に応じてディープリンクのクエリ文字列を付加）のみです。

インストールと設定

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）を開き、mcpServers の下にサーバーを追加します。

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

Muovi API キーをお持ちの場合（以下の認証（任意）を参照）、env 経由で渡します。

{
  "mcpServers": {
    "muovi": {
      "command": "npx",
      "args": ["-y", "@muovi/mcp-server"],
      "env": {
        "MUOVI_API_KEY": "your-key-here"
      }
    }
  }
}

設定を編集した後、Claude Desktop を再起動してください。

Cursor

~/.cursor/mcp.json（またはワークスペースの .cursor/mcp.json）に追加します。

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

Claude Code

Claude Code CLI でサーバーを登録します。

claude mcp add muovi --command "npx" --args "-y" "@muovi/mcp-server"

または、Claude Code の設定に手動で追加します。

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

手動設定／スクリプト

npx -y @muovi/mcp-server

このプロセスは標準入力から JSON-RPC を読み取り、標準出力に応答します。すべてのログ出力は標準エラー出力に送られます。

認証（任意）

すべての /v1 エンドポイントは、デフォルトでは公開されており、認証は不要です。クライアントに Muovi API キーが発行されている場合（より高いレート制限のティア）、サーバーの環境に MUOVI_API_KEY を設定すると、このパッケージはすべてのリクエストで X-API-Key ヘッダーとして転送します。

テスト用に API のベース URL を上書きすることもできます。

MUOVI_API_BASE_URL=https://staging.muovi.com.ar/api/v1 npx -y @muovi/mcp-server

muovi_create_task_link は、MUOVI_WEB_BASE_URL がパスのない https オリジンの場合はその URL 上にリンクを作成し、それ以外の場合は https://muovi.com.ar 上に作成します。

エージェントのワークフロー例

これらのツールを使用する Claude との一般的な会話の例です。

1. ユーザーが「パレルモで、適切な資格を持つ電気技師」と尋ねます。
2. エージェントが muovi_list_services を呼び出し、「電気技師」を electricidad に対応付けます。
3. エージェントが muovi_list_cities を呼び出し、palermo が caba の有効な近隣地区であることを確認します。
4. エージェントが { service: "electricidad", neighborhood: "palermo", has_matricula: true } を指定して muovi_search_professionals を呼び出し、最大 5 人の専門家を取得します。サービスと barrio の両方を指定しない場合、ツールはそれらを求めるエラーを返すため、エージェントはまずユーザーに確認します。
5. エージェントが検索結果を表示し、選択肢を 2 つ提示します。1 人の専門家への依頼、または複数の専門家から見積もりを受け取る一般依頼です。
6. 特定の専門家を選ぶ場合、エージェントはその検索結果の id を指定して muovi_get_professional と muovi_get_reviews を呼び出せます。
7. エージェントは { professional_id, service_slug: "electricidad" } を指定して muovi_create_task_link を呼び出し、生成された URL を提示します。または、ユーザーがすでに作成済みの下書きにアクセスできるよう、{ service_slug: "electricidad", professional_id, description } を指定して muovi_create_task_draft を呼び出します。一般依頼の場合は、専門家を指定せずに muovi_create_task_draft を呼び出します。
8. ユーザーがリンクを開くと Muovi に移動し、下書きを確認してサインインし、プラットフォーム内のフローで依頼を公開します。

依頼が公開され、支払いと紛争の手続きが行われるのは、ステップ 8 のプラットフォーム内のフローです。

ローカル開発

このパッケージは、単独で公開されている muovi-latam/mcp-server リポジトリです。クローンして、インストールし、テストを実行します。

git clone [email protected]:muovi-latam/mcp-server.git
cd mcp-server
npm install
npm test            # unit + integration + OpenAPI drift checks
npm run typecheck   # strict TypeScript
npm run build       # emits dist/

OpenAPI の差分テストでは、public/openapi.yaml を解析し、各ツールの入力スキーマが対応する操作のパラメーターと完全に一致することを検証します。/v1 にクエリパラメーターを追加する場合は、対応するツールも更新する必要があります（逆の場合も同様です）。

公開

npm publish は意図的に CI に組み込まれていません。リリースは、クリーンなタグから手動で作成します。

npm version patch    # or minor / major
npm publish --access public
git push --follow-tags

prepublishOnly は公開前に clean + build + test を実行します。

MCP Registry（mcp-publisher）

npm 以外にも、このサーバーはコミット済みの server.json マニフェストを通じて Model Context Protocol レジストリに掲載されています。レジストリへの公開は手動の手順です。CI による自動公開は意図的に行いません（レジストリへの公開頻度は低く、人による承認が必要なうえ、名前空間の認証は対話形式で行われるためです）。

コミット済みの名前空間： ar.com.muovi/mcp-server — muovi.com.ar の逆 DNS 形式です。この値は server.json（name）と package.json（mcpName）の両方に記載されており、2 つの値はバイト単位で完全に一致させる必要があります（server-json テストで一致を検証します）。また、mcp-publisher で認証する際の ID とも一致している必要があります（下記を参照）。

名前空間の所有権を一度だけ設定する

初回公開の前に、ar.com.muovi 名前空間の所有権を一度証明します。

• DNS（推奨）： mcp-publisher login dns が表示する TXT レコードを muovi.com.ar ゾーンに追加し、そのドメインで認証します。これにより、すでに管理しているドメインに名前空間を紐付けます。
• GitHub OAuth（代替手段）： mcp-publisher login github — muovi-latam GitHub 組織を通じて認証します。DNS 検証が利用できない場合にのみ使用してください。認証済み ID は、コミット済みの ar.com.muovi/mcp-server 名前空間と一致している必要があります。

コミット済みの名前空間と認証済み ID が一致しない場合、mcp-publisher publish はマニフェストを拒否します。名前空間（両方のファイル）またはログインを修正してください。無理に公開しないでください。

公開手順

mcp-publisher validate ./server.json   # checks against the live registry schema
mcp-publisher publish                   # publishes server.json under the authenticated namespace

validate は、マニフェストが現在のレジストリスキーマバージョンと一致していることを確認する手順です。毎回実行してください。server.json に固定されている $schema は参考情報であり、実際のスキーマが変更されていないことを保証するものではありません。

バージョン更新の手順

server-json テストでは、4 つのバージョンフィールドが一致していることを検証します。バージョンを更新するたびに、これらすべてをまとめて更新してから、npm とレジストリの両方に再公開してください。

1. package.json → version
2. src/server.ts → PACKAGE_VERSION
3. server.json → version
4. server.json → packages[0].version

正確な公開条件に関する注意事項

マニフェストには、まだ完全には稼働していない機能が記載されています。次の点に留意し、ユーザーに誇張して伝えないでください。

• リモートトランスポート（remotes[].url = https://mcp.muovi.com.ar/）が正確な記載となるのは、そのエンドポイントがストリーミング可能な HTTP 経由で JSON-RPC initialize に安定して応答するようになってからです。このホスト型エンドポイントは MOB-207 で追跡されています。対応が完了するまでは、実際に動作するトランスポートは stdio パッケージ（npx @muovi/mcp-server）のみです。
• サーバー側でタスクの引き継ぎが無効になっている場合（TASK_HANDOVERS_ENABLED。デフォルト設定）、muovi_create_task_draft は「利用不可」と応答します。
• MOB-263 でバックエンドとなる /v1 エンドポイントがデプロイされるまでは、muovi_get_professional と muovi_get_reviews は本番環境で動作しません。ツールは登録済みで差分チェックにも合格しますが、それまでは実際の呼び出しに失敗します。

ライセンス

MIT。

リンク

• Muovi
• 公開 /v1 API 仕様
• Model Context Protocol
• 問題を報告