Metadata-Version: 2.4
Name: thodr-mcp
Version: 0.1.0
Summary: MCP server for creating and managing Thodr mock API projects and routes from an AI IDE
Project-URL: Homepage, https://thodr.com
Project-URL: Repository, https://github.com/thodr-hq/thodr
Project-URL: Bug Tracker, https://github.com/thodr-hq/thodr/issues
Author: Thodr
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Testing :: Mocking
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.2.0
Description-Content-Type: text/markdown

# thodr-mcp

A local [MCP](https://modelcontextprotocol.io) (Model Context Protocol)
server that lets an AI coding assistant (Cursor, Claude Desktop, GitHub
Copilot, or any MCP-compatible IDE) create and manage Thodr mock API
projects and endpoints on your behalf, by forwarding tool calls to Thodr's
existing management REST API.

This server is **not** an AI model. It does not run any inference itself —
it is a thin, local process that validates inputs and makes REST calls to
`THODR_API_URL` using your personal access token. The IDE/agent supplies the
model; this server just exposes 5 specific tools that wrap Thodr's
projects/routes API. It does not "understand" OpenAPI specs, generate mock
data, or do anything beyond what each tool's description says.

## Getting a `THODR_TOKEN`

Thodr authenticates management API calls (and this server) with a Personal
Access Token (PAT).

1. Log in to the Thodr web app and go to **Settings → Access Tokens**.
2. Give the token a name (e.g. `my-ide`) and click **Generate**.
3. Copy the token shown in the amber box (it looks like `thodr_pat_...`).
   **It is shown once and cannot be retrieved again** — store it securely
   (e.g. your OS keychain or IDE's secret storage).

Prefer the API instead? While logged in, call `POST {THODR_API_URL}/auth/tokens`
with your session's bearer (JWT) token and a JSON body `{"name": "my-ide"}`:

```bash
curl -X POST https://thodr.com/api/auth/tokens \
  -H "Authorization: Bearer <your-jwt-from-the-logged-in-session>" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-ide"}'
```

## IDE configuration

Add an MCP server entry to your IDE's MCP config. The exact file location
differs by client — check your client's own MCP documentation (e.g.
Cursor's or Claude Desktop's settings docs) for where this JSON block goes:

```json
{
  "mcpServers": {
    "thodr": {
      "command": "uvx",
      "args": ["thodr-mcp"],
      "env": {
        "THODR_API_URL": "https://thodr.com/api",
        "THODR_TOKEN": "thodr_pat_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

If `THODR_TOKEN` is missing or empty, the server fails fast at startup with
a clear error on stderr instead of failing confusingly on the first tool
call.

## The 5 tools

This is a **read + create only** v1 — there are no delete tools. Manage
deletion (or anything else not listed below) from the Thodr web app.

| Tool | Description |
|---|---|
| `create_project(name, description?)` | Creates a new Thodr mock API project. Returns its id, name, slug, and `mock_base_url`. |
| `list_projects()` | Lists your Thodr projects, each with id, name, slug, route count, and `mock_base_url`. |
| `add_endpoint(project_id, method, path_pattern, response_status=200, response_body?, content_type="application/json", response_headers?, delay_ms=0)` | Adds a mock endpoint (route) to a project. Returns the created route and its full live mock URL. |
| `list_endpoints(project_id)` | Lists the mock endpoints (routes) for a project, each with its live mock URL. |
| `get_mock_url(project_slug, path_pattern, env_slug?)` | Pure string composition of the live mock URL for a project/path. Makes no network call. |

## Cost and privacy

- **$0 to run.** This server does no AI inference — it's a local process
  that makes plain REST calls within your existing Thodr plan's limits.
- Your `THODR_TOKEN` is sent only to `THODR_API_URL` as an `Authorization:
  Bearer` header. It is never logged, printed, or included in any error
  message this server produces.

## Local development

```bash
cd mcp-server
python3 -m venv .venv && source .venv/bin/activate   # or: virtualenv -p python3.12 .venv
pip install -e ".[dev]"
pip install pytest pytest-asyncio respx   # if the [dev] extra doesn't pull these in on your pip version
pytest tests/ -v
python -m thodr_mcp
```
