{"_id":"@appoinly/mcp","name":"@appoinly/mcp","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@appoinly/mcp","version":"0.1.0","type":"module","description":"MCP server for Appoinly — lets AI assistants browse services, check availability and book appointments through a tenant's Appoinly public API key (stdio transport)","keywords":["mcp","modelcontextprotocol","appoinly","booking","appointments","scheduling","claude"],"homepage":"https://appoinly.eu","license":"MIT","bin":{"appoinly-mcp":"dist/index.js"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"engines":{"node":">=20"},"scripts":{"build":"tsc -p tsconfig.json","dev":"tsc -p tsconfig.json --watch","start":"node dist/index.js","test":"vitest run --passWithNoTests","typecheck":"tsc -p tsconfig.json --noEmit","prepublishOnly":"tsc -p tsconfig.json"},"dependencies":{"@modelcontextprotocol/sdk":"^1.17.0","zod":"^3.24.1"},"devDependencies":{"@appoinly/tsconfig":"workspace:*","@types/node":"^22.10.2","vitest":"^2.1.8"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/mschizasart/appoinly-platform.git","directory":"packages/mcp-server"},"_id":"@appoinly/mcp@0.1.0","gitHead":"969ce077177f27ea1802e1a21e8b4cbb2eedc25d","bugs":{"url":"https://github.com/mschizasart/appoinly-platform/issues"},"_nodeVersion":"20.18.1","_npmVersion":"10.8.2","dist":{"integrity":"sha512-1vUOPinrbcdz9AbYqIgxPXvd2juwj4sSTjhfphHRc3m6WQuR9HdVvDV2Xgce8VOo6WrklXg36voMtLIeItnTgQ==","shasum":"0a651d12e473eee278a9b3a548aa17885b82014a","tarball":"https://registry.npmjs.org/@appoinly/mcp/-/mcp-0.1.0.tgz","fileCount":11,"unpackedSize":32594,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDLWzmZcIxykAKoZNoGO2thjiL7HOzaRNFqiV2hBYNEIwIhAKaEOAx1ilwjjo5rxibWOkcgGSSUeC3YQ45ZQZDCFCSx"}]},"_npmUser":{"name":"apps4lease","email":"support@apps4lease.cloud"},"directories":{},"maintainers":[{"name":"apps4lease","email":"support@apps4lease.cloud"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp_0.1.0_1787949477096_0.8594929918619243"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-28T20:37:56.899Z","0.1.0":"2026-08-28T20:37:57.298Z","modified":"2026-08-28T20:37:57.655Z"},"maintainers":[{"name":"apps4lease","email":"support@apps4lease.cloud"}],"description":"MCP server for Appoinly — lets AI assistants browse services, check availability and book appointments through a tenant's Appoinly public API key (stdio transport)","homepage":"https://appoinly.eu","keywords":["mcp","modelcontextprotocol","appoinly","booking","appointments","scheduling","claude"],"repository":{"type":"git","url":"git+https://github.com/mschizasart/appoinly-platform.git","directory":"packages/mcp-server"},"bugs":{"url":"https://github.com/mschizasart/appoinly-platform/issues"},"license":"MIT","readme":"# appoinly-mcp\n\n> **The npm name `appoinly-mcp` is NOT yet published, and until it is, do not\n> tell anyone to run `node ./packages/mcp-server/dist/index.js   # local path until the npm name is claimed`.** An unclaimed name that public\n> documentation instructs people to execute is a supply-chain attack waiting to\n> be registered by someone else: `-y` suppresses the confirmation prompt, a\n> `postinstall` then runs on the customer's workstation, and the Claude Desktop\n> config alongside it hands that process a write-scoped `APPOINLY_API_KEY`.\n>\n> Before publishing anything: claim `appoinly-mcp` AND the `@appoinly` scope on\n> npm, enable 2FA on the account, and prefer publishing as `@appoinly/mcp` so\n> the scope itself is the trust boundary. Until then, install from a local path.\n\n\nAn [MCP](https://modelcontextprotocol.io) server that exposes a tenant's\n**existing Appoinly public REST API** (`/v1/public/*`) as tools, so MCP\nclients (Claude Desktop, Claude Code, …) can browse services, check\navailability and book appointments.\n\nIt is a **thin HTTP client** — no database access, no backend imports. Every\ntool call goes over HTTPS with the tenant's API key, so API-side scopes and\nrate limits apply unchanged.\n\n## Tools\n\n| Tool                 | Public API call                | Notes                                          |\n| -------------------- | ------------------------------ | ---------------------------------------------- |\n| `list_services`      | `GET /v1/public/services`      | ids, prices (cents), durations                 |\n| `list_staff`         | `GET /v1/public/staff`         | staff with the service ids each performs       |\n| `get_availability`   | `GET /v1/public/availability`  | free slots per day (`startMinute` based)       |\n| `create_appointment` | `POST /v1/public/appointments` | 409 `slot_unavailable` when the slot was taken |\n| `list_appointments`  | `GET /v1/public/appointments`  | filter by date range / status, paginated       |\n| `find_customer`      | `GET /v1/public/customers`     | lookup by exact email                          |\n| `create_customer`    | `POST /v1/public/customers`    | 409 `email_exists` returns the existing id     |\n\n## Configuration\n\n| Env var            | Required | Default                   | Meaning                                             |\n| ------------------ | -------- | ------------------------- | --------------------------------------------------- |\n| `APPOINLY_API_KEY` | yes      | —                         | Tenant API key (`apk_…`), Settings → API keys       |\n| `APPOINLY_API_URL` | no       | `https://api.appoinly.eu` | API origin (self-hosted / staging installs)         |\n\nBooking and customer tools mutate data, so the key needs the **write** scope\n(read-only keys can still use `list_*`, `get_availability`, `find_customer`).\n\n## Install (recommended)\n\nOnce published to npm, no clone or build needed:\n\n```sh\nnode ./packages/mcp-server/dist/index.js   # local path until the npm name is claimed\n```\n\nClaude Desktop config using npx:\n\n```json\n{\n  \"mcpServers\": {\n    \"appoinly\": {\n      \"command\": \"npx\",\n      \"args\": [\"/absolute/path/to/appoinly/packages/mcp-server/dist/index.js\"],\n      \"env\": { \"APPOINLY_API_KEY\": \"apk_your_key_here\" }\n    }\n  }\n}\n```\n\n## Build & run (from source)\n\n```sh\npnpm --filter appoinly-mcp build\nAPPOINLY_API_KEY=apk_… node packages/mcp-server/dist/index.js\n```\n\nTransport is **stdio**: the process reads MCP messages on stdin and answers on\nstdout (diagnostics go to stderr). It is started by the MCP client — you don't\nrun it as a daemon.\n\n## Claude Desktop\n\nAdd to `claude_desktop_config.json` (macOS:\n`~/Library/Application Support/Claude/claude_desktop_config.json`, Windows:\n`%APPDATA%\\Claude\\claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"appoinly\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/appoinly/packages/mcp-server/dist/index.js\"],\n      \"env\": {\n        \"APPOINLY_API_KEY\": \"apk_your_key_here\",\n        \"APPOINLY_API_URL\": \"https://api.appoinly.eu\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop afterwards; the tools appear under the \"appoinly\"\nserver. For Claude Code:\n\n```sh\nclaude mcp add appoinly \\\n  -e APPOINLY_API_KEY=apk_your_key_here \\\n  -- node /absolute/path/to/appoinly/packages/mcp-server/dist/index.js\n```\n\n## Docker (optional)\n\n`docker-compose.prod.yml` ships a commented-out `mcp` service stub. stdio MCP\nservers are launched by the client, so the compose service is only useful as a\nbuild/packaging vehicle — leave it commented unless you need the image.\n","readmeFilename":"README.md","_rev":"1-1a9639148b51642d757b3784b3b099d7"}