{
  "markdown": "# TimeZest MCP Server\n\n[![Docker Image](https://img.shields.io/badge/docker-ghcr.io%2Fwyre--ai%2Ftimezest--mcp-blue)](https://ghcr.io/wyre-ai/timezest-mcp)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n\nMCP (Model Context Protocol) server for [TimeZest](https://timezest.com) scheduling platform. Enables LLM agents to create and manage technician scheduling requests with PSA integration.\n\n## Features\n\n- 🎯 **Decision-tree navigation** - organized tool discovery\n- 📅 **Full scheduling lifecycle** - create, view, cancel requests\n- 🔗 **PSA integration** - ConnectWise, Autotask, Halo support\n- 🌍 **IANA timezone handling** - explicit timezone management\n- 🚀 **Dual trigger modes** - PSA workflows or booking URLs\n- 🛡️ **Gateway-ready** - stateless per-request design\n- 🔍 **TQL filtering** - TimeZest Query Language support\n- ✨ **Elicitation support** - interactive user prompts\n- 📇 **Interactive scheduling-request card (MCP Apps)** - `timezest_scheduling_get` renders as a card in MCP Apps hosts; neutral by default, brandable via `window.__BRAND__` injection or `MCP_BRAND_*` env vars\n\n## Quick Start\n\n### Docker (Recommended)\n\n```bash\ndocker run -it --rm \\\n  -e TIMEZEST_API_TOKEN=your-api-token \\\n  ghcr.io/wyre-ai/timezest-mcp:latest\n```\n\n### npm\n\n```bash\nnpm install -g @wyre-ai/timezest-mcp\nTIMEZEST_API_TOKEN=your-token timezest-mcp\n```\n\n## Configuration\n\n| Environment Variable | Required | Description |\n|---------------------|----------|-------------|\n| `TIMEZEST_API_TOKEN` | Yes | TimeZest API token |\n| `MCP_TRANSPORT` | No | Transport mode: `stdio` (default) or `http` |\n| `MCP_HTTP_PORT` | No | HTTP port (default: 8080) |\n| `AUTH_MODE` | No | Set to `gateway` for WYRE gateway integration |\n| `LOG_LEVEL` | No | Log level: `debug`, `info` (default), `warn`, `error` |\n\n## Tool Domains\n\nThe server uses decision-tree navigation to organize tools by domain:\n\n### Navigation\n- `timezest_navigate` - Enter a domain to access its tools\n- `timezest_status` - Show available domains and current state\n\n### Agents\n- `timezest_agents_list` - List individual technicians\n- `timezest_agents_get` - Get agent details\n\n### Teams\n- `timezest_teams_list` - List teams (round-robin scheduling)\n- `timezest_teams_get` - Get team details\n\n### Appointment Types\n- `timezest_appointment_types_list` - List available service types\n- `timezest_appointment_types_get` - Get appointment type details\n\n### Resources\n- `timezest_resources_list` - List all resources (agents + teams)\n\n### Scheduling (Core Domain)\n- `timezest_scheduling_list` - List scheduling requests\n- `timezest_scheduling_get` - Get request details\n- `timezest_scheduling_create_request` - **Create new request** (key tool)\n- `timezest_scheduling_cancel` - Cancel request\n\n## Usage Examples\n\n### Basic Navigation\n\n```\nUser: \"Show me TimeZest domains\"\nTools: timezest_status\n\nUser: \"Go to scheduling\"\nTools: timezest_navigate(domain=\"scheduling\")\n```\n\n### Create a Scheduling Request\n\n```\nUser: \"Book a technician for server repair at Customer Corp tomorrow\"\nTools: timezest_scheduling_create_request({\n  \"appointmentTypeId\": \"repair-onsite\",\n  \"triggerMode\": \"pod\",\n  \"endUser\": {\n    \"name\": \"John Doe\",\n    \"company\": \"Customer Corp\",\n    \"email\": \"john@customer.com\"\n  },\n  \"timeRange\": {\n    \"earliestDate\": \"2024-02-01\",\n    \"earliestTime\": \"09:00\",\n    \"latestDate\": \"2024-02-01\", \n    \"latestTime\": \"17:00\",\n    \"timezone\": \"America/New_York\"\n  },\n  \"associatedEntities\": [\n    {\"type\": \"connectwise\", \"id\": \"12345\", \"number\": \"T20240001\"}\n  ]\n})\n```\n\n### PSA Integration\n\nLink scheduling requests to PSA tickets:\n\n```json\n{\n  \"associatedEntities\": [\n    {\"type\": \"connectwise\", \"id\": \"12345\", \"number\": \"T20240001\"},\n    {\"type\": \"autotask\", \"id\": \"67890\"},\n    {\"type\": \"halo\", \"id\": \"11111\"}\n  ]\n}\n```\n\n### Trigger Modes\n\n- **`pod`**: Fires the configured PSA workflow (creates calendar entries, updates tickets)\n- **`generate_url`**: Returns a shareable booking URL for customers\n\n## TQL Filtering\n\nTimeZest Query Language examples:\n\n```\n# Active agents in IT department\nfilter: \"active:true AND department:\\\"IT Support\\\"\"\n\n# Recent scheduling requests\nfilter: \"createdAt:>=2024-01-01 AND status:pending\"\n\n# Specific customer requests  \nfilter: \"endUser.company:\\\"Important Customer\\\"\"\n```\n\n## Timezone Handling\n\n**CRITICAL**: Always specify IANA timezones explicitly. TimeZest interprets scheduling windows in the specified timezone.\n\n```json\n{\n  \"timeRange\": {\n    \"earliestDate\": \"2024-02-01\",\n    \"earliestTime\": \"09:00\", \n    \"timezone\": \"America/New_York\"  // ✅ Required\n  }\n}\n```\n\n## Development\n\n### Local Setup\n\n```bash\n# Clone and install\ngit clone https://github.com/WYRE-AI/timezest-mcp.git\ncd timezest-mcp\nnpm install\n\n# Development with file dependency (replace before publish)\n# Edit package.json: \"@wyre-technology/node-timezest\": \"file:../node-timezest\"\n\n# Build and test\nnpm run build\nnpm test\n\n# Run locally\nTIMEZEST_API_TOKEN=your-token npm run dev\n```\n\n### Docker Development\n\n```bash\n# Build image\ndocker build -t timezest-mcp --build-arg NODE_AUTH_TOKEN=$GITHUB_TOKEN .\n\n# Run container\ndocker run -it --rm \\\n  -e TIMEZEST_API_TOKEN=your-token \\\n  -e LOG_LEVEL=debug \\\n  timezest-mcp\n```\n\n## MCP Integration\n\n### Claude Desktop\n\nAdd to your MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"timezest\": {\n      \"command\": \"npx\",\n      \"args\": [\"@wyre-ai/timezest-mcp\"],\n      \"env\": {\n        \"TIMEZEST_API_TOKEN\": \"your-api-token\"\n      }\n    }\n  }\n}\n```\n\n### WYRE Gateway\n\nThe server is designed for the WYRE MCP Gateway with:\n- Per-request server instances (stateless)\n- Header-based credential injection\n- Structured error responses\n- Decision-tree tool organization\n\n## API Coverage\n\n| TimeZest API | Coverage | Notes |\n|--------------|----------|-------|\n| Agents | ✅ List, Get | Individual technicians |\n| Teams | ✅ List, Get | Round-robin scheduling |\n| Appointment Types | ✅ List, Get | Service type definitions |\n| Resources | ✅ List | Unified agents + teams |\n| Scheduling Requests | ✅ CRUD | Core scheduling functionality |\n| TQL Filtering | ✅ All endpoints | TimeZest Query Language |\n| PSA Integration | ✅ All systems | ConnectWise, Autotask, Halo |\n| Webhooks | ❌ N/A | TimeZest doesn't provide webhooks |\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.\n\n## License\n\nApache 2.0 - see [LICENSE](LICENSE) file for details.\n\n## Links\n\n- [TimeZest API Documentation](https://developer.timezest.com/)\n- [TimeZest Help Center](https://help.timezest.com/)\n- [MCP Protocol](https://modelcontextprotocol.io/)\n- [WYRE Technology](https://wyre.technology/)",
  "bytes": 6633,
  "sha": "43925cbeb86e810c8f206f559d7ac4cf8827f7aee2c2a073de4be5bbc1920bcd",
  "repo_slug": "wyre-ai/timezest-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_wyre_ai_timezest_mcp_09fb7773/readme"
}