Metadata-Version: 2.4
Name: suppa-mcp
Version: 1.0.4
Summary: MCP server for the Suppa platform (modern.suppa.me) — Tasks, Docs, Entities, Forms, with multi-tenant Google auth
Project-URL: Homepage, https://github.com/Andrii-Herasymchuk/skills
Project-URL: Repository, https://github.com/Andrii-Herasymchuk/skills
Author-email: Andrii Herasymchuk <cloud.developers@modern-expo.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai-tools,claude,mcp,model-context-protocol,suppa
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: keyring>=24.0.0
Requires-Dist: mcp[cli]>=1.0.0
Description-Content-Type: text/markdown

# Suppa 2.0 MCP Server

MCP (Model Context Protocol) server for the [Suppa platform](https://modern.suppa.me) — provides AI agents with tools to manage Tasks, Docs/Pages, Entities, and Forms.

## Why MCP?

- **API key stays local** — never sent to the AI agent, stored only in `.env`
- **Works with any MCP client** — Claude Desktop, VS Code Copilot, Cursor, Windsurf, etc.
- **No CORS/proxy issues** — runs locally, makes direct HTTPS calls to Suppa
- **50+ tools** covering Tasks, Documents, Entity schema, Forms, and 1.0→2.0 migration

## Quick Start

### 1. Install

**Recommended — zero-install via PyPI.** Point your MCP client at `uvx`
([uv](https://docs.astral.sh/uv/)); it fetches and runs the latest release on
demand (the Python equivalent of `npx`), so there's nothing to install or update:

```json
{ "mcpServers": { "suppa": { "command": "uvx", "args": ["suppa-mcp"] } } }
```

Or install the command explicitly:

```bash
uv tool install suppa-mcp       # or: pipx install suppa-mcp  /  pip install suppa-mcp
```

This provides a `suppa-mcp` command that any MCP client can launch directly.

**From source instead:**

```bash
# from a local clone
cd suppa2.0-mcp-server && pip install -e .

# or straight from the repository
pip install "git+https://git.modern-expo.com/asu/me-development/skills.git#subdirectory=suppa2.0-mcp-server"
```

### 2. Configure

```bash
cp .env.example .env
# Edit .env and set SUPPA_API_KEY
```

Then verify your token and connectivity without any client:

```bash
suppa-mcp --check
# OK: connected to https://modern.suppa.me — 139 entities visible.
```

### 3. Connect to your AI agent

Ready-to-copy configs are in [`examples/`](examples). Replace `YOUR_TOKEN_HERE`
with your Suppa token. All clients use the same `suppa-mcp` command.

**Claude Desktop** — merge [`examples/claude_desktop_config.json`](examples/claude_desktop_config.json)
into `claude_desktop_config.json` (Windows: `%APPDATA%/Claude/`, macOS:
`~/Library/Application Support/Claude/`):
```json
{
  "mcpServers": {
    "suppa": {
      "command": "suppa-mcp",
      "env": {
        "SUPPA_API_KEY": "YOUR_TOKEN_HERE",
        "SUPPA_BASE_URL": "https://modern.suppa.me"
      }
    }
  }
}
```

**VS Code Copilot** — already wired in [`.vscode/mcp.json`](../.vscode/mcp.json);
it prompts for the token in a masked input. Start the `suppa` server from the
MCP view.

**Cursor / Windsurf / Cline** — use [`examples/cursor_mcp.json`](examples/cursor_mcp.json)
or [`examples/generic_mcp.json`](examples/generic_mcp.json).

> If a client reports `suppa-mcp` not found, its launcher can't see your Python
> Scripts dir on PATH. Use the explicit-interpreter fallback
> [`examples/claude_desktop_config.python-fallback.json`](examples/claude_desktop_config.python-fallback.json)
> (`command` = full path from `where.exe python`, `args` = `["-m","suppa_mcp"]`,
> `cwd` = this project).


## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `SUPPA_API_KEY` | (required) | JWT token or API key |
| `SUPPA_BASE_URL` | `https://modern.suppa.me` | Platform URL |
| `SUPPA_LANG` | `en` | Language (`en`/`uk`) |
| `SUPPA_TZ` | `Europe/Kyiv` | Timezone |
| `SUPPA_TASKS_ENTITY_ID` | `37` | Entity ID for file uploads |

## Available Tools (52 total)

### Tasks (16 tools)
| Tool | Description |
|------|-------------|
| `suppa_get_me` | Current user profile |
| `suppa_search_tasks` | Search with filters (my, active, overdue, etc.) |
| `suppa_count_tasks` | Count matching tasks |
| `suppa_get_task` | Full task details |
| `suppa_create_task` | Create task |
| `suppa_update_task` | Update task fields |
| `suppa_delete_task` | Soft-delete task |
| `suppa_move_task` | Move to another stage |
| `suppa_close_task` | Close (completed stage) |
| `suppa_add_comment` | Comment with @mentions |
| `suppa_get_comments` | List task comments |
| `suppa_attach_file` | Upload & attach file |
| `suppa_list_workflows` | Available workflows |
| `suppa_list_stages` | Stages in a workflow |
| `suppa_list_task_types` | Task type options |
| `suppa_search_users` | Find users by name |

### Docs & Pages (13 tools)
| Tool | Description |
|------|-------------|
| `suppa_list_docs` | List documents |
| `suppa_get_doc` | Document with page tree |
| `suppa_create_doc` | Create document |
| `suppa_update_doc` | Update document |
| `suppa_delete_doc` | Delete document |
| `suppa_list_pages` | Pages in a document |
| `suppa_get_page` | Page metadata |
| `suppa_create_page` | Create page |
| `suppa_update_page` | Update page |
| `suppa_delete_page` | Delete page |
| `suppa_get_blocks` | Raw block data |
| `suppa_read_page` | Readable text output |
| `suppa_create_blocks` | Add blocks to page |
| `suppa_insert_block` | Insert at position |
| `suppa_update_block` | Edit block content |
| `suppa_delete_block` | Remove block |
| `suppa_reorder_blocks` | Reorder blocks |

### Entity & Schema (8 tools)
| Tool | Description |
|------|-------------|
| `suppa_list_entities` | All entities/tables |
| `suppa_describe_entity` | Full schema |
| `suppa_search_records` | Query any entity |
| `suppa_create_entity` | Create new table |
| `suppa_add_field` | Add field to entity |
| `suppa_add_enum_values` | Add enum options |
| `suppa_list_field_types` | Available types |
| `suppa_create_record` | Insert record |
| `suppa_update_record` | Update record |
| `suppa_delete_record` | Delete record |

### Forms (6 tools)
| Tool | Description |
|------|-------------|
| `suppa_list_forms` | List forms |
| `suppa_get_form` | Form with schema |
| `suppa_create_form` | Create form |
| `suppa_update_form` | Update form |
| `suppa_generate_form_schema` | Auto-generate from entity |
| `suppa_add_field_to_form` | Add field to form |
| `suppa_list_form_field_types` | Field type catalog |

### Migration
| Tool | Description |
|------|-------------|
| `suppa_migrate_entities_from_v1` | Replicate Suppa 1.0 entities/fields into 2.0 (dry-run by default; supports reviewable plan files) |

### System
| Tool | Description |
|------|-------------|
| `suppa_health_check` | Health check for stdio clients (config-only or deep connectivity check) |

## Authentication

The server authenticates with a single bearer token supplied via `SUPPA_API_KEY`:

- **User JWT** (account token, e.g. copied from the browser cookie `accessToken`) —
  full access to all domains including Tasks and the `$current-user` magic value.
- **Integrator API key** — works for Docs, Entities, Forms and Users. Task
  endpoints and `$current-user` may return empty results because they are scoped
  to a real user. Use a user JWT for Task workflows.

The token is read only from the environment, sent solely in the `Authorization`
header to `SUPPA_BASE_URL`, and is **never** exposed to the AI agent.

## Development

```bash
# Run directly (stdio)
python -m suppa_mcp

# Verify config + connectivity (no client needed)
python -m suppa_mcp --check

# Test with MCP inspector
mcp dev src/suppa_mcp/server.py
```

## Auto-start Claude at login (stdio)

For Claude Desktop / VS Code, stdio is the preferred model: the MCP client
spawns this server on demand and reconnects automatically.

To make startup reliable, install a login task that runs a preflight health
check (`suppa-mcp --check`) and then starts Claude if it is not already running.

```powershell
cd suppa2.0-mcp-server
./scripts/install-claude-startup.ps1 -Python C:\Python314\python.exe
```

The installed task (`SuppaClaudeStartup`) runs:

- `scripts/start-claude-with-suppa.ps1` at user logon,
- connectivity check first (fails fast if token/config is invalid),
- Claude launch only when check passes.

Manage it:

```powershell
Start-ScheduledTask -TaskName SuppaClaudeStartup
Get-ScheduledTask -TaskName SuppaClaudeStartup
./scripts/uninstall-claude-startup.ps1
```

## Troubleshooting

**`mcp dev` fails with `spawn uv ENOENT`** — the MCP Inspector launches the server
with [`uv`](https://github.com/astral-sh/uv). Install it and make sure it is on
your `PATH`, then **restart VS Code** (so the new `PATH` is picked up):

```powershell
python -m pip install uv
# add the user Scripts dir to PATH if `uv --version` is not found, e.g.
#   %APPDATA%\Python\Python3xx\Scripts
```

**`ModuleNotFoundError: No module named 'typing_extensions'` (or `suppa_mcp`)
when running `mcp dev`** — you have **multiple Python versions** and the `mcp`
launcher belongs to a different interpreter than the one where `pip install -e .`
ran. Check with:

```powershell
where.exe python   # interpreter that has suppa_mcp installed
where.exe mcp      # the CLI's interpreter — must be the same Python
```

Fix by using one interpreter, ideally a project virtual environment:

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .
mcp dev src/suppa_mcp/server.py
```

> You do **not** need `uv` or `mcp dev` for normal use — MCP clients (VS Code
> Copilot, Claude, Cursor) launch the server directly via `python -m suppa_mcp`,
> as configured in `.vscode/mcp.json`. The inspector is only a debugging tool.

