# @muovi/mcp-server

[![npm version](https://img.shields.io/npm/v/%40muovi%2Fmcp-server.svg)](https://www.npmjs.com/package/@muovi/mcp-server)

**Model Context Protocol (MCP) server for [Muovi](https://muovi.com.ar)** — LATAM's trust-first local services marketplace.

This package lets MCP-aware clients (Claude Desktop, Cursor, Claude Code, and any other MCP host) discover Muovi's verified LATAM service professionals, browse the service catalog and city list, read reviews, deep-link a user into the on-platform task-creation flow, and save a task draft the user publishes themselves. It is a thin wrapper over Muovi's public [`/v1` REST API](https://muovi.com.ar/openapi.yaml).

**Stdio mode.** The package ships an `npx`-runnable binary that speaks JSON-RPC over stdin/stdout. The hosted HTTP/SSE variant is tracked separately (Muovi MOB-142).

## What it exposes

Every tool is read-only except `muovi_create_task_draft`, which saves a draft on Muovi:

| Tool | Wraps | Purpose |
| --- | --- | --- |
| `muovi_search_professionals` | `GET /v1/professionals` | Up to 5 professionals for one service in one barrio. `service` and `neighborhood` are both required; every result has a coverage area that includes the barrio, and `match` names the service, barrio and city searched. Results list professionals who declare the searched trade first, ordered by review score, with verified identity, background check and matrícula counting toward it; professionals whose registered business is in another trade come last; there is no rating or review filter. Each result has one `rating`, one `review_count`, its `verifications`, up to 3 `portfolio` image URLs, an `id` and a `profile_url` (`https://muovi.com.ar/profile/<id>`), and no `neighborhoods`. |
| `muovi_get_professional` | `GET /v1/professionals/{id}` | Fetch a single pro's full public profile (bio, portfolio, specialties, verifications) by the `id` from the search. A ProSite slug from an older link is also accepted. |
| `muovi_list_services` | `GET /v1/services` | The full live service catalog — home trades (electricidad, plomería, gas, pintura, carpintería, cerrajería, albañilería, herrería, techista), limpieza, jardinería, aire acondicionado, plus moving/hauling: `mudanzas` (movers) and `fletes` (light freight). |
| `muovi_list_cities` | `GET /v1/cities` | Every Argentine city Muovi serves, with neighborhoods. |
| `muovi_get_reviews` | `GET /v1/professionals/{id}/reviews` | Paginated reviews for a pro, most-recent first, by the same `id`. |
| `muovi_create_task_link` | (pure formatter) | Builds a link to Muovi's own task creation for one professional (`professional_id`, the search's `id`) and one service: `https://muovi.com.ar/post-task/v2?pro=<id>&vertical=<service>&source=assistant-link`. It works for every professional in the results. A missing or malformed argument is a tool error. Makes no HTTP call. |
| `muovi_get_service_requirements` | `GET /v1/services/{service_slug}/requirements` | Lists the questions Muovi asks for one service (key, question in Spanish, type, accepted options, required or not), so the agent can ask the user before saving a draft. |
| `muovi_create_task_draft` | `POST /v1/task-handovers` | Saves a task draft (service, description, optional zone, preferred time and professional) and returns a link that expires in 24 hours if nobody opens it. The user opens it, reviews the draft, signs in and publishes it; the tool publishes nothing. With `professional_id` (the search's `id`), the published task goes to that pro first for 24 hours and then opens to everyone; with `open_to_others: true` it opens to everyone right away and that pro is still told. The user can change that choice on the review form. |

## Anti-leakage policy

Muovi is on-platform-only. **Phone, email, and WhatsApp handles are never returned** by the public API — contact between consumers and professionals happens exclusively through Muovi's in-app conversation flow, reachable from each pro's `profile_url`.

This server enforces the policy twice:

1. The `/v1` API strips contact data server-side.
2. Every tool response in this package also runs through a local anti-leakage detector (a Node-compatible mirror of [`src/lib/anti-leakage/detector.ts`](https://github.com/muovi-latam/muovi-web/blob/main/src/lib/anti-leakage/detector.ts) in the Muovi web repo). If a leak is detected at the agent boundary the tool returns a stable error to the LLM client and refuses to surface the payload.

Hosts that integrate this server **must not** synthesise off-platform contact handles from any field. Driving the user to `profile_url` (optionally with the deep-link query string) is the only sanctioned contact channel.

## Installation & configuration

### Claude Desktop

Open `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) and add the server under `mcpServers`:

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

If you have a Muovi API key (see [Authentication](#authentication-optional) below), pass it via env:

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

Restart Claude Desktop after editing the config.

### Cursor

Add to `~/.cursor/mcp.json` (or your workspace's `.cursor/mcp.json`):

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

### Claude Code

Register the server with the Claude Code CLI:

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

Or add it manually to your Claude Code settings:

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

### Manual / scripting

```bash
npx -y @muovi/mcp-server
```

The process reads JSON-RPC on stdin and replies on stdout. All log output goes to stderr.

## Authentication (optional)

All `/v1` endpoints are public and unauthenticated by default. If your client has been issued a Muovi API key (higher rate-limit tier), set `MUOVI_API_KEY` in the server's environment and the package will forward it as the `X-API-Key` header on every request.

You can also override the API base URL for testing:

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

`muovi_create_task_link` builds its link on `MUOVI_WEB_BASE_URL` when that is an https origin with no path, and on `https://muovi.com.ar` otherwise.

## Example agent workflow

A typical Claude conversation that uses these tools:

1. User asks for "an electrician in Palermo who's properly licensed".
2. Agent calls `muovi_list_services` to map "electrician" → `electricidad`.
3. Agent calls `muovi_list_cities` to confirm `palermo` is a valid neighborhood under `caba`.
4. Agent calls `muovi_search_professionals` with `{ service: "electricidad", neighborhood: "palermo", has_matricula: true }` and gets up to 5 professionals. Without both a service and a barrio the tool answers an error asking for them, so the agent asks the user first.
5. Agent shows the results and offers two choices: a task for one of those professionals, or a general request to get offers from several.
6. For one professional, the agent can call `muovi_get_professional` and `muovi_get_reviews` with that result's `id`.
7. Agent calls `muovi_create_task_link` with `{ professional_id, service_slug: "electricidad" }` and surfaces the resulting URL — or calls `muovi_create_task_draft` with `{ service_slug: "electricidad", professional_id, description }` so the user lands on a draft already written. For a general request it calls `muovi_create_task_draft` without a professional.
8. User follows the link, lands on Muovi, reviews the draft, signs in, and publishes the task in the on-platform flow.

Step 8 — the on-platform flow — is where the task is published, and where payments and disputes run.

## Local development

This package is the standalone [`muovi-latam/mcp-server`](https://github.com/muovi-latam/mcp-server) repo. Clone it, install, and run tests:

```bash
git clone git@github.com: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/
```

The OpenAPI drift test parses `public/openapi.yaml` and asserts each tool's input schema matches the corresponding operation's parameters exactly — adding a query param to `/v1` requires updating the corresponding tool (and vice versa).

## Publishing

`npm publish` is intentionally **not** wired into CI. Releases are cut manually from a clean tag:

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

`prepublishOnly` runs `clean + build + test` before any publish.

### MCP Registry (mcp-publisher)

Beyond npm, this server is listed in the [Model Context Protocol registry](https://registry.modelcontextprotocol.io) via the committed [`server.json`](./server.json) manifest. Publishing to the registry is a **manual step — there is deliberately no CI auto-publish** (the registry is a low-frequency, human-gated surface, and namespace auth is interactive).

**Committed namespace:** `ar.com.muovi/mcp-server` — the reverse-DNS form of `muovi.com.ar`. This value lives in **both** `server.json` (`name`) and `package.json` (`mcpName`) and the two **must stay byte-identical** (the `server-json` test enforces equality). It must also match the identity you authenticate as with `mcp-publisher` (see below).

#### One-time namespace ownership setup

Prove ownership of the `ar.com.muovi` namespace once, before the first publish:

- **DNS (preferred):** add the TXT record that `mcp-publisher login dns` prints to the `muovi.com.ar` zone, then authenticate against that domain. This ties the namespace to the domain we already control.
- **GitHub OAuth (fallback):** `mcp-publisher login github` — authenticates via the `muovi-latam` GitHub org. Only use this if DNS verification is unavailable; the authenticated identity still has to line up with the committed `ar.com.muovi/mcp-server` namespace.

If the committed namespace and the authenticated identity disagree, `mcp-publisher publish` will reject the manifest — fix the namespace (in both files) or the login, do not force it.

#### Publish steps

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

`validate` is the step that confirms the manifest matches the current registry schema version — run it every time; the pinned `$schema` in `server.json` is a hint, not a guarantee the live schema hasn't moved.

#### Version-bump discipline

The `server-json` test asserts that four version fields agree. On **every** version bump, update all of them together, then re-publish to both npm and the registry:

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

#### Honest gating notes

The manifest advertises capabilities that are not yet fully live. Keep these caveats in mind (and do not overstate them to users):

- **Remote transport** (`remotes[].url` = `https://mcp.muovi.com.ar/`) is only truthful once that endpoint reliably answers JSON-RPC `initialize` over streamable-HTTP. That hosted surface is tracked in **MOB-207**; until it lands, the **stdio** package (`npx @muovi/mcp-server`) is the only transport that actually works.
- **`muovi_create_task_draft`** answers "not available" while task handovers are switched off on the server (`TASK_HANDOVERS_ENABLED`), which is the default.
- **`muovi_get_professional`** and **`muovi_get_reviews`** remain broken against production until **MOB-263** deploys the backing `/v1` endpoints. The tools are registered and pass drift checks, but live calls will fail until then.

## License

[MIT](./LICENSE).

## Links

- [Muovi](https://muovi.com.ar)
- [Public `/v1` API spec](https://muovi.com.ar/openapi.yaml)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [Report an issue](https://github.com/muovi-latam/mcp-server/issues)