Metadata-Version: 2.4
Name: agentdraft-mcp
Version: 0.1.0
Summary: MCP server for AgentDraft — expose the scheduling source of truth to MCP-aware AI clients (Claude Desktop, Cursor, Cline, etc.)
Author-email: AgentDraft Labs <hello@agentdraft.io>
License: MIT
Project-URL: Homepage, https://agentdraft.io
Project-URL: Documentation, https://agentdraft.io/docs
Project-URL: Repository, https://github.com/GipsyChef/agentdraft
Project-URL: Issues, https://github.com/GipsyChef/agentdraft/issues
Project-URL: Changelog, https://github.com/GipsyChef/agentdraft/blob/main/sdks/mcp/CHANGELOG.md
Keywords: mcp,model-context-protocol,calendar,scheduling,ai-agents,agentdraft
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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 :: Office/Business :: Scheduling
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0
Requires-Dist: agentdraft>=0.1.0
Dynamic: license-file

# agentdraft-mcp — MCP server for AgentDraft

[![PyPI](https://img.shields.io/pypi/v/agentdraft-mcp.svg)](https://pypi.org/project/agentdraft-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

An [MCP](https://modelcontextprotocol.io/) server that exposes
[AgentDraft](https://agentdraft.io) — the scheduling source of truth
for AI agents — as a set of tools any MCP-aware AI client can call.

Use this if your agent runtime is Claude Desktop, Claude Code, Cursor,
Cline, an OpenAI Agents SDK app, or any other MCP host. The server is
a thin wrapper around the [`agentdraft`](https://pypi.org/project/agentdraft/)
Python SDK — same auth, same errors, same semantics as the REST API
and the language SDKs.

## Install

```bash
pip install agentdraft-mcp
```

Requires Python 3.10+ and a valid `avs_live_…` agent key from the
AgentDraft dashboard.

## Configure your MCP client

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
(macOS) or the equivalent on Windows/Linux:

```json
{
  "mcpServers": {
    "agentdraft": {
      "command": "agentdraft-mcp",
      "env": {
        "AGENTDRAFT_API_KEY": "avs_live_..."
      }
    }
  }
}
```

### Cursor / Cline / generic stdio host

```json
{
  "mcpServers": {
    "agentdraft": {
      "command": "python",
      "args": ["-m", "agentdraft_mcp"],
      "env": {
        "AGENTDRAFT_API_KEY": "avs_live_..."
      }
    }
  }
}
```

For local development against a dev backend, also set
`AGENTDRAFT_BASE_URL=http://localhost:8080`.

## Tools

| Tool | Purpose |
|---|---|
| `whoami` | Confirm the API key and return the agent's identity, priority, scopes |
| `get_availability` | List slots open to the calling agent in [start, end) |
| `create_hold` | Reserve a slot tentatively (30 s TTL) |
| `release_hold` | Release a hold so other agents can claim it |
| `commit_booking` | Finalize a booking — atomic compare-and-swap |
| `cancel_booking` | Cancel a committed booking the calling agent owns |

All times are ISO 8601 strings (`2026-06-01T14:00:00Z`). All write
tools accept an `idempotency_key` for safe retries.

## How conflicts surface

When two agents race for the same slot, exactly one wins. Losing
agents receive a structured outranked payload — not a string error:

```json
{
  "error": "outranked",
  "winning_booking_id": "bkg_…",
  "winning_agent_id": "agt_…",
  "winning_agent_priority": 1,
  "your_priority": 3,
  "message": "Your booking was outranked. Read winning_agent_id and propose an alternate slot rather than retrying."
}
```

Your agent should branch on this and propose an alternate, not retry
the same slot.

## How this differs from the AgentDraft SDKs

| | Python/TS SDK | MCP server |
|---|---|---|
| **Caller** | App code you wrote | An AI client (Claude Desktop, etc.) |
| **Transport** | HTTPS direct to api.agentdraft.io | stdio between the MCP host and this process |
| **Auth** | `Client(api_key=…)` | `AGENTDRAFT_API_KEY` env var |
| **Semantics** | Same | Same |
| **Errors** | Typed Python exceptions | Structured JSON in the tool result |

Use the SDK when *you* are writing the agent. Use this MCP server when
*someone else's* agent runtime (Claude Desktop, Cursor, Cline,
generic MCP host) needs to call AgentDraft on a user's behalf without
custom code.

## Links

- Protocol spec: <https://agentdraft.io/spec>
- API docs: <https://agentdraft.io/docs>
- Python SDK: [`agentdraft`](https://pypi.org/project/agentdraft/)
- TypeScript SDK: [`@agentdraft/sdk`](https://www.npmjs.com/package/@agentdraft/sdk)
- Source: <https://github.com/GipsyChef/agentdraft>
- Issues: <https://github.com/GipsyChef/agentdraft/issues>

## Security

Found a vulnerability? See [SECURITY.md](SECURITY.md). Do **not** open
a public issue for a security report.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). This package lives inside the
[`GipsyChef/agentdraft`](https://github.com/GipsyChef/agentdraft)
monorepo under `sdks/mcp/`.

## License

MIT — see [LICENSE](LICENSE).
