# Gyst MCP

Standalone Cursor MCP server for [Gyst](https://github.com/NathanHartkopf/gyst) — list and update clients, projects, and tickets from your editor.

## Quick start

1. **Generate a token** in Gyst → Settings → Cursor MCP.

2. **Clone and build** this repo:

   ```bash
   git clone https://github.com/NathanHartkopf/gyst-mcp.git
   cd gyst-mcp
   npm install && npm run build
   ```

3. **Add to `~/.cursor/mcp.json`:**

   ```json
   {
     "mcpServers": {
       "gyst": {
         "command": "node",
         "args": ["/absolute/path/to/gyst-mcp/dist/index.js"],
         "env": {
           "GYST_API_URL": "https://gyst.nathanh.app",
           "GYST_API_TOKEN": "gyst_your_token_here",
           "GYST_WORKSPACE": "/absolute/path/to/your/repo"
         }
       }
     }
   }
   ```

   - `GYST_API_TOKEN` — personal token from Gyst Settings (scopes access to your account only)
   - `GYST_API_URL` — your Gyst deployment URL (defaults to production if omitted in code)
   - `GYST_WORKSPACE` — optional; helps `get_projects_for_current_repo` when Cursor does not expose workspace roots

4. **Restart Cursor** to load the MCP server.

## Legacy direct-KV mode

For local development against Vercel KV directly (not recommended for end users):

```bash
vercel env pull .env.mcp --environment=production --yes
```

Configure with `GYST_ENV_FILE`, `KV_REST_API_URL`, `KV_REST_API_TOKEN`, and `ADMIN_EMAIL` instead of `GYST_API_TOKEN`.

## Tools

| Tool | Description |
|------|-------------|
| `list_clients` | List all clients (summary) |
| `get_client` | Full client details by ID |
| `list_projects` | List projects, optional `clientId` filter |
| `get_project` | Full project details by ID |
| `get_projects_for_current_repo` | Projects linked to the workspace GitHub repo |
| `list_tickets` | List tickets; optional filters |
| `get_ticket` | Full ticket details by ID |
| `get_ticket_by_key` | Full ticket details by key (e.g. `GYST-4`) |
| `create_ticket` | Create a ticket with auto-assigned key |
| `update_ticket` | Update ticket fields |
| `update_project` | Update project fields |
| `update_project_ticket_statuses` | Set a project's ticket status list |
| `update_ticket_status` | Change a ticket's status |
| `add_project_ai_dev_comment` | Post an **AI Dev** comment on a project |
| `add_ticket_ai_dev_comment` | Post an **AI Dev** comment on a ticket |
| `sync_ticket_dev_links` | Scan GitHub repos for commits/PRs matching a ticket key |

## Sample skill

See [`skills/complete-new-work/SKILL.md`](skills/complete-new-work/SKILL.md) for a Cursor agent skill that discovers open tickets, asks for confirmation, and runs the full delivery workflow.

## Development

```bash
npm run build
node scripts/test-mcp-tool.mjs
```