{"_id":"@canera/mcp-server","name":"@canera/mcp-server","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@canera/mcp-server","version":"0.1.0","description":"MCP server that connects Claude (and other MCP clients) to a Canera workspace via the user's personal MCP token.","keywords":["mcp","claude","canera","modelcontextprotocol","anthropic"],"license":"MIT","author":{"name":"Canera"},"homepage":"https://github.com/flamurhbreznica/canera-tracking/tree/master/mcp-server","repository":{"type":"git","url":"git+https://github.com/flamurhbreznica/canera-tracking.git","directory":"mcp-server"},"bugs":{"url":"https://github.com/flamurhbreznica/canera-tracking/issues"},"type":"module","bin":{"canera-mcp":"dist/index.js"},"main":"dist/index.js","scripts":{"build":"tsc","dev":"tsc --watch","start":"node dist/index.js","prepublishOnly":"npm run build"},"engines":{"node":">=18.18"},"publishConfig":{"access":"public"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.4","axios":"^1.7.7","zod":"^3.23.8","zod-to-json-schema":"^3.23.5"},"devDependencies":{"@types/node":"^22.7.0","typescript":"^5.6.0"},"gitHead":"2085c5ac425a0af8c47067585bb8b1f80535e4bb","_id":"@canera/mcp-server@0.1.0","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-Qlecai6Teh5iXno1gzHpiu4xqli+wACV4NmPuLaN0dUsv2qsVae0gJLItHU5/s12NcYNxridECb/rkOGl4JitQ==","shasum":"3e24354a7194242f772934f0be7e00c610d0ab01","tarball":"https://registry.npmjs.org/@canera/mcp-server/-/mcp-server-0.1.0.tgz","fileCount":15,"unpackedSize":36329,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICnMa8DTzT6QNV6Btx8nPMmJ2A3NpTCCs9pv5tlSSwoaAiEA3CH/333D1AcXP6fpJ4+/0IbJC579DBj9gZnZa2Lbfu0="}]},"_npmUser":{"name":"flamurbreznica","email":"flamur.breznica@canera.ch"},"directories":{},"maintainers":[{"name":"flamurbreznica","email":"flamur.breznica@canera.ch"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-server_0.1.0_1778616528891_0.7445344405310583"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-12T20:08:48.800Z","0.1.0":"2026-05-12T20:08:49.079Z","modified":"2026-05-12T20:08:49.295Z"},"maintainers":[{"name":"flamurbreznica","email":"flamur.breznica@canera.ch"}],"description":"MCP server that connects Claude (and other MCP clients) to a Canera workspace via the user's personal MCP token.","homepage":"https://github.com/flamurhbreznica/canera-tracking/tree/master/mcp-server","keywords":["mcp","claude","canera","modelcontextprotocol","anthropic"],"repository":{"type":"git","url":"git+https://github.com/flamurhbreznica/canera-tracking.git","directory":"mcp-server"},"author":{"name":"Canera"},"bugs":{"url":"https://github.com/flamurhbreznica/canera-tracking/issues"},"license":"MIT","readme":"# @canera/mcp-server\n\nAn [MCP](https://modelcontextprotocol.io/) server that connects Claude — or any\nMCP-aware client — to a Canera workspace. Each user generates a personal token\nin Canera's settings; the MCP server authenticates as that user, with the\nscopes they pick at creation time.\n\nPhases 1–5 are live: read tools, write tools, and admin-tier tools (leave\napprove/reject, leave cancellation review, pipeline stage moves).\n\n---\n\n## Install\n\n```bash\n# from npm (recommended)\nnpm install -g @canera/mcp-server\n\n# or run on demand\nnpx -y @canera/mcp-server\n```\n\n## Configure Claude Code\n\nAdd a `canera` entry to your `mcp.json` (Claude Code → settings → \"Open\nconfiguration file\"):\n\n```json\n{\n  \"mcpServers\": {\n    \"canera\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@canera/mcp-server\"],\n      \"env\": {\n        \"CANERA_API_URL\": \"https://trackingapp-v3.apps.trudocloud.net/api/v1\",\n        \"CANERA_TOKEN\": \"mcp_paste_yours_here\"\n      }\n    }\n  }\n}\n```\n\nTo generate the token: in Canera, go to **Settings → Integrations → Claude\n(MCP) → Connect**, pick scopes, copy the token from the post-create dialog.\n\nRestart Claude Code. The Canera tools appear in the tool list.\n\n## Environment variables\n\n| Variable | Required | Purpose |\n|---|---|---|\n| `CANERA_API_URL` | yes | Base URL up to and including `/api/v1`. No trailing slash needed. |\n| `CANERA_TOKEN` | yes | Personal MCP token starting with `mcp_`. |\n| `CANERA_TIMEOUT_MS` | no | HTTP timeout per request. Default 30000. |\n\n## Tools\n\nEach tool description in MCP also lists the required scope.\n\n### Read\n\n| Tool | Scope | What it does |\n|---|---|---|\n| `whoami` | — | Returns the profile of the token owner. Useful as a connectivity check. |\n| `list_my_timesheet` | `timesheet:read` | Time entries between two dates. |\n| `get_weekly_grid` | `timesheet:read` | Weekly grid view starting on the given Monday. |\n| `list_my_tasks` | `tasks:read` | Tasks, filterable by project / status / search. |\n| `get_task` | `tasks:read` | One task by id. |\n| `list_my_projects` | `projects:read` | Projects visible to the user. |\n| `list_my_leave` | `leave:read` | Leave requests (own; HR sees all). |\n| `list_pipeline_candidates` | `pipeline:read` | HR pipeline candidates the user can see. |\n| `get_candidate` | `pipeline:read` | One candidate with CVs, ratings, comments. |\n| `list_notifications` | `notifications:read` | The user's notifications. |\n| `unread_count` | `notifications:read` | Unread notification count. |\n\n### Write\n\n| Tool | Scope | What it does |\n|---|---|---|\n| `create_time_entry` | `timesheet:write` | Add a time entry. |\n| `update_time_entry` | `timesheet:write` | Edit a time entry (approved entries are immutable). |\n| `delete_time_entry` | `timesheet:write` | Permanently delete a time entry. |\n| `submit_week` | `timesheet:write` | Submit a date range of draft entries for approval. |\n| `create_task` | `tasks:write` | Create a new task. |\n| `update_task` | `tasks:write` | Patch task fields. |\n| `change_task_status` | `tasks:write` | Convenience: change only the status. |\n| `comment_on_task` | `tasks:write` | Add a (optionally @-mentioning) comment. |\n| `request_leave` | `leave:write` | Submit a new leave request. |\n| `cancel_leave_request` | `leave:write` | Cancel own leave (approved → pending_cancellation). |\n| `add_candidate` | `pipeline:write` | Add to the HR pipeline (needs `hr_pipeline.manage`). |\n| `comment_on_candidate` | `pipeline:write` | Add a comment to a candidate. |\n| `rate_candidate` | `pipeline:write` | Score a candidate 1–10 (upsert). |\n| `mark_notifications_read` | `notifications:manage` | Mark some or all notifications read. |\n\n### Admin\n\nThese tools require both the scope on the token **and** the corresponding\npermission on the user (e.g. `leave.approve`, `hr_pipeline.manage`). Granting\nthe scope alone does not bypass the user's permission check.\n\n| Tool | Scope | What it does |\n|---|---|---|\n| `approve_leave` | `leave:admin` | Approve a pending leave request. Cannot approve own. |\n| `reject_leave` | `leave:admin` | Reject a pending leave request with a required reason. |\n| `approve_leave_cancellation` | `leave:admin` | Approve a pending cancellation; restores balance. |\n| `reject_leave_cancellation` | `leave:admin` | Reject a pending cancellation; leave stays approved. |\n| `move_candidate_stage` | `pipeline:admin` | Move a candidate to a different pipeline stage. |\n\nIf a token is missing the required scope, the underlying API call returns 422\nwith a \"Token missing required scope\" detail, surfaced to the MCP client.\n\n**Destructive operations** (`delete_time_entry`, `cancel_leave_request`) are\nintentionally annotated as such in their tool descriptions so Claude warns the\nuser before invoking them.\n\n## Security\n\n* Tokens are hashed (SHA-256) at rest. The plaintext is shown exactly once at\n  creation. If you lose it, revoke and re-issue.\n* Tokens inherit the owning user's permissions; they cannot exceed them.\n* Tokens expire (default 90 days). The Canera UI lists active and revoked tokens\n  with a per-row revoke button.\n* All MCP traffic is logged server-side to `mcp_audit_log` (retained 1 year).\n* Never check `CANERA_TOKEN` into source control or share it in chat — anyone\n  who has it can act as you, within the token's scopes.\n\n## Develop locally\n\n```bash\ngit clone <this repo>\ncd mcp-server\nnpm install\nnpm run build\nCANERA_API_URL=http://127.0.0.1:3000/api/v1 \\\nCANERA_TOKEN=mcp_dev_token \\\nnode dist/index.js\n```\n\nThe server speaks JSON-RPC over stdio. To test interactively, use the\n[`@modelcontextprotocol/inspector`](https://github.com/modelcontextprotocol/inspector).\n\n## Troubleshooting\n\n* **\"Missing required environment variable\"** — `mcp.json`'s `env` block is\n  wrong. Confirm both keys are present and not empty.\n* **\"Token may be revoked, expired, or missing required scope\"** — open\n  Canera → Settings → Integrations → Claude (MCP). If you see the token marked\n  Revoked or Expired, create a fresh one.\n* **Tools don't appear in Claude Code** — restart Claude Code after editing\n  `mcp.json`. Check Claude Code's MCP server logs (the wrench icon).\n* **Connection works but list_my_tasks returns 0** — the token authenticates as\n  your user; tasks are filtered by what your account can see. Use `whoami` to\n  confirm which user the token is bound to.\n","readmeFilename":"README.md","_rev":"1-d87eb2ad0b8a14eda1162bc64c29a5a6"}