Metadata-Version: 2.4
Name: platform-2step-mcp
Version: 0.13.1
Summary: MCP server for Platform-2Step API with human-in-the-loop confirmation
Author: AgendaPro
License: MIT
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: jsonschema>=4.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Description-Content-Type: text/markdown

# Platform-2Step MCP

MCP server that enables AI agents (Claude, GPT, etc.) to interact with AgendaPro's Platform API safely through a human-in-the-loop confirmation system.

All mutations require human confirmation — the AI agent can only create pending operations, never execute them directly.

## Prerequisites

- **Python 3.11+** — check with `python3 --version`
- **uv** (recommended) — Python package manager

### Install uv

```bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
irm https://astral.sh/uv/install.ps1 | iex
```

After installing, restart your terminal or run `source ~/.bashrc` (or `~/.zshrc`).

## Quick Setup (recommended)

The fastest way to configure the MCP for Claude Code:

```bash
uvx --from platform-2step-mcp platform-mcp-setup
```

This command:
- Creates or updates `~/.claude.json` with the production server config (user scope — global, available in all projects)
- Preserves all your other Claude Code config (theme, sessions, project state, other MCP servers)
- Is idempotent: running it again updates the config without breaking anything

For staging environment:

```bash
uvx --from platform-2step-mcp platform-mcp-setup --env staging
```

For project scope (writes to `<cwd>/.mcp.json` instead, only affects the current project — useful for sharing via git):

```bash
uvx --from platform-2step-mcp platform-mcp-setup --scope project
```

> **Note**: `uvx` downloads and runs the package from PyPI automatically — no manual install needed.

## Authentication

Before using the MCP, you must authenticate once. The MCP uses OAuth 2.0 Device Flow — your browser opens automatically and you click "Authorize".

```bash
# Production
PLATFORM_2STEPS_BFF_URL=https://ap-api.agendapro.com/platform-2steps-bff \
  uvx --from platform-2step-mcp platform-mcp-auth login

# Staging
PLATFORM_2STEPS_BFF_URL=https://ap-api.agendaprodev.com/platform-2steps-bff \
  uvx --from platform-2step-mcp platform-mcp-auth login
```

You'll see:

```
============================================================
AUTENTICACIÓN REQUERIDA
============================================================

Abriendo navegador... Tu código es: ABCD-1234

Esperando autenticación en el navegador...
Expira en 10 minutos.
============================================================

¡Autenticación exitosa!
```

Tokens are cached at `~/.platform-mcp/tokens.json` and reused automatically.

### Auth CLI commands

| Command | Description |
| ------- | ----------- |
| `platform-mcp-auth login` | Authenticate (interactive) |
| `platform-mcp-auth login --force` | Re-authenticate even if tokens are valid |
| `platform-mcp-auth status` | Check if tokens are valid |
| `platform-mcp-auth logout` | Clear cached tokens |

> **Important**: Always set `PLATFORM_2STEPS_BFF_URL` before running auth commands.

### Setup CLI commands

| Command | Description |
| ------- | ----------- |
| `platform-mcp-setup` | Configure for production, user scope (`~/.claude.json`) |
| `platform-mcp-setup --env staging` | Configure for staging |
| `platform-mcp-setup --scope project` | Configure project scope (`<cwd>/.mcp.json`) |
| `platform-mcp-setup --force` | Recreate config if the JSON file is corrupted |

## Manual Configuration

If you prefer to configure manually instead of using `platform-mcp-setup`:

### Claude Code (user scope — global)

Edit `~/.claude.json` and add the entry under `mcpServers` at the root level (preserve all other top-level keys):

```json
{
  "mcpServers": {
    "platform-2step": {
      "command": "uvx",
      "args": ["platform-2step-mcp"],
      "env": {
        "PLATFORM_2STEPS_BFF_URL": "https://ap-api.agendapro.com/platform-2steps-bff",
        "API_HOST_PUBLIC": "mcp.agendapro.com"
      }
    }
  }
}
```

> **Warning**: `~/.claude.json` contains your full Claude Code state (theme, sessions, project state, OAuth tokens). Use `platform-mcp-setup` instead of editing manually to avoid corruption.

### Claude Code (project scope — shareable via git)

Create `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "platform-2step": {
      "command": "uvx",
      "args": ["platform-2step-mcp"],
      "env": {
        "PLATFORM_2STEPS_BFF_URL": "https://ap-api.agendapro.com/platform-2steps-bff",
        "API_HOST_PUBLIC": "mcp.agendapro.com"
      }
    }
  }
}
```

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

```json
{
  "mcpServers": {
    "platform-2step": {
      "command": "uvx",
      "args": ["platform-2step-mcp"],
      "env": {
        "PLATFORM_2STEPS_BFF_URL": "https://ap-api.agendapro.com/platform-2steps-bff",
        "API_HOST_PUBLIC": "mcp.agendapro.com"
      }
    }
  }
}
```

### Cursor

In Cursor, go to **Settings > MCP** and add a new server, or create a `.cursor/mcp.json` file in your project root:

```json
{
  "mcpServers": {
    "platform-2step": {
      "command": "uvx",
      "args": ["platform-2step-mcp"],
      "env": {
        "PLATFORM_2STEPS_BFF_URL": "https://ap-api.agendapro.com/platform-2steps-bff",
        "API_HOST_PUBLIC": "mcp.agendapro.com"
      }
    }
  }
}
```

## Using Multiple Environments

To use both staging and production simultaneously, configure separate token paths:

```json
{
  "mcpServers": {
    "platform-2step-staging": {
      "command": "uvx",
      "args": ["platform-2step-mcp"],
      "env": {
        "PLATFORM_2STEPS_BFF_URL": "https://ap-api.agendaprodev.com/platform-2steps-bff",
        "API_HOST_PUBLIC": "mcp.agendaprodev.com",
        "PLATFORM_MCP_TOKEN_PATH": "~/.platform-mcp/tokens-staging.json"
      }
    },
    "platform-2step-prod": {
      "command": "uvx",
      "args": ["platform-2step-mcp"],
      "env": {
        "PLATFORM_2STEPS_BFF_URL": "https://ap-api.agendapro.com/platform-2steps-bff",
        "API_HOST_PUBLIC": "mcp.agendapro.com",
        "PLATFORM_MCP_TOKEN_PATH": "~/.platform-mcp/tokens-prod.json"
      }
    }
  }
}
```

Authenticate each environment separately:

```bash
# Staging
PLATFORM_2STEPS_BFF_URL=https://ap-api.agendaprodev.com/platform-2steps-bff \
PLATFORM_MCP_TOKEN_PATH=~/.platform-mcp/tokens-staging.json \
uvx --from platform-2step-mcp platform-mcp-auth login

# Production
PLATFORM_2STEPS_BFF_URL=https://ap-api.agendapro.com/platform-2steps-bff \
PLATFORM_MCP_TOKEN_PATH=~/.platform-mcp/tokens-prod.json \
uvx --from platform-2step-mcp platform-mcp-auth login
```

## Available Tools

Once connected, the MCP provides these tools to the AI agent:

### Read (no confirmation needed)

- **Categories**: `list_categories`, `get_category`
- **Services**: `list_services`, `get_service`
- **Bookings**: `list_bookings`, `get_booking`
- **Locations**: `list_locations`, `get_location`
- **Providers**: `list_providers`, `get_provider`
- **Memberships**: `list_memberships`, `get_membership`
- **Clients**: `list_clients`, `get_client`
- **Users**: `get_user`
- **Custom Attributes**: `list_custom_attributes`

### Mutations (require human confirmation)

- **Batch operations**: `create_batch` — creates up to 50 operations (create, update, delete) that must be confirmed by the user in the AgendaPro frontend

### Analytics (read-only SQL)

- `query_analytics_db` — execute SQL against synced analytics data
- `get_analytics_status` — check data sync status
- `refresh_analytics_data` — trigger data refresh

## Troubleshooting

### "Not authenticated" error

```
Error: Not authenticated. Run 'platform-mcp-auth login' first.
```

Your tokens expired or were never created. Run:

```bash
PLATFORM_2STEPS_BFF_URL=https://ap-api.agendapro.com/platform-2steps-bff \
  uvx --from platform-2step-mcp platform-mcp-auth login
```

### "Configuration error: PLATFORM_2STEPS_BFF_URL is required"

The environment variable is not set. Make sure it's in your `~/.claude.json` (Claude Code, user scope) config under `mcpServers.platform-2step.env`, or run `platform-mcp-setup` to configure it automatically.

### MCP tools not showing in Claude

1. Check the MCP server is running: look for errors in Claude Code's MCP logs
2. Verify auth: `PLATFORM_2STEPS_BFF_URL=https://ap-api.agendapro.com/platform-2steps-bff uvx --from platform-2step-mcp platform-mcp-auth status`
3. Restart Claude Code after config changes

### "uvx: command not found"

Install uv first (see [Prerequisites](#prerequisites)).

### JSON parse error when running platform-mcp-setup

If your `~/.claude.json` has invalid JSON, use `--force` to recreate it:

```bash
uvx --from platform-2step-mcp platform-mcp-setup --force
```

> **Warning**: `--force` recreates the file. **All other Claude Code state** (theme, sessions, project state, other MCP servers) in the corrupted file will be lost. Back up `~/.claude.json` first if possible.

## Environment Variables

| Variable | Required | Default | Description |
| -------- | -------- | ------- | ----------- |
| `PLATFORM_2STEPS_BFF_URL` | Yes | — | BFF URL for API integration (staging or production) |
| `API_HOST_PUBLIC` | No | Falls back to `PLATFORM_2STEPS_BFF_URL` | Public hostname for browser-facing URLs (e.g., `mcp.agendapro.com`) |
| `PLATFORM_MCP_TOKEN_PATH` | No | `~/.platform-mcp/tokens.json` | Token storage location |
| `LOG_LEVEL` | No | `INFO` | Logging level (DEBUG, INFO, WARNING, ERROR) |
| `DEBUG_HTTP` | No | `false` | Enable cURL-style HTTP request/response logging |

## Documentation

For comprehensive documentation including architecture, security, and development guides, see **[CLAUDE.md](./CLAUDE.md)**.

## License

MIT
