# agileplaceMCP_v3

AgilePlace demo-provisioning MCP server. Creates and shapes demo environments (boards, bulk cards, hierarchy) from Claude Desktop or Cursor. stdio transport, single-user.

## Modules

| Module | Role |
|---|---|
| `config.mjs` | Env-driven config + authed HTTP client (Bearer). |
| `boardCache.mjs` | Board-list warm on first use; lazy per-board card types; label → ID resolution. |
| `rateLimiter.mjs` | Throttles off `X-RateLimit-Remaining` / `Reset`; honors `Retry-After`; caps in-tool sleep and returns `retryAfter` instead of blocking. |
| `tools/createCards.mjs` | Bulk card creation. |
| `server.mjs` | stdio MCP entrypoint. |

## createCards

- Sequential, self-throttling writes.
- Max ~40 cards per call; larger batches rejected (chunk and retry).
- Per-card `clientKey` correlation, echoed on results.
- Error handling: retry (429 / 5xx / network), fail-card-continue (400 / 422 / 404), abort-batch (401 / 403), circuit breaker on repeated identical failures.
- Partial success returns `isError: false`; cards in `created[]` should not be resubmitted.

## Configuration

Set credentials in the host config `env` block (`claude_desktop_config.json` or Cursor `mcp.json`). Not in source.

```json
{
  "mcpServers": {
    "agileplace-v3": {
      "command": "node",
      "args": ["/absolute/path/to/src/server.mjs"],
      "env": {
        "AGILEPLACE_DEFAULT_URL": "https://<your-org>.leankit.com/io",
        "AGILEPLACE_DEFAULT_TOKEN": "<token>"
      }
    }
  }
}
```

Run standalone:

```bash
node src/server.mjs
```

## Status

- `createCards` — implemented.
- `updateCards` / `findCards` / `createBoard` — not yet implemented.
- Deferred: multi-environment routing, lane name resolution, OKR tools, whole-call idempotency, tasks extension.