{"_id":"@armanage/armanage-platform-mcp","_rev":"4-44f1b8d9615a8d05c33573e13fb57555","name":"@armanage/armanage-platform-mcp","dist-tags":{"latest":"0.1.3"},"versions":{"0.1.0":{"name":"@armanage/armanage-platform-mcp","version":"0.1.0","license":"UNLICENSED","_id":"@armanage/armanage-platform-mcp@0.1.0","maintainers":[{"name":"mocan_piotr","email":"olympspartan@gmail.com"}],"bin":{"armanage-platform-mcp":"dist/index.js"},"dist":{"shasum":"154ffa145a0e222dac34781df5e493f457163eaf","tarball":"https://registry.npmjs.org/@armanage/armanage-platform-mcp/-/armanage-platform-mcp-0.1.0.tgz","fileCount":47,"integrity":"sha512-8YcyHcJMfl3sL8cxZh56A2oz0s0AaLI+u2k7BbJw8rL+2igz2xb2UqgfajuKo8V7XrDwzhB50cYowd+TWzKnkA==","signatures":[{"sig":"MEUCIQCIZVCplAjOx6LY0/lsJRtOk3Fr0PMpwE3/G30I/2teSQIgCq264eR/hce0DEOaaKffFqVcsB+z3Wd0Z9VNC40/K7Y=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":93966},"type":"module","engines":{"node":">=20"},"gitHead":"cf17db410b60fbca9daf734fafe0919873274890","scripts":{"dev":"tsx src/index.ts","test":"npm run typecheck && tsx --test test/**/*.test.ts","build":"tsc","start":"node dist/index.js","prepack":"npm run build","typecheck":"tsc --noEmit"},"_npmUser":{"name":"mocan_piotr","email":"olympspartan@gmail.com"},"_npmVersion":"11.4.2","description":"External MCP server for configuring Armanage projects, agents, teams, and automation resources","directories":{},"_nodeVersion":"24.3.0","dependencies":{"zod":"^4.3.6","@modelcontextprotocol/sdk":"^1.27.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","typescript":"^5.7.2","@types/node":"^22.10.2"},"_npmOperationalInternal":{"tmp":"tmp/armanage-platform-mcp_0.1.0_1783869244880_0.9670601593215484","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@armanage/armanage-platform-mcp","version":"0.1.1","license":"UNLICENSED","_id":"@armanage/armanage-platform-mcp@0.1.1","maintainers":[{"name":"mocan_piotr","email":"olympspartan@gmail.com"}],"bin":{"armanage-platform-mcp":"dist/index.js"},"dist":{"shasum":"c94f3eb103974dcde57e0df4edfb99edd1ed325c","tarball":"https://registry.npmjs.org/@armanage/armanage-platform-mcp/-/armanage-platform-mcp-0.1.1.tgz","fileCount":63,"integrity":"sha512-0o1eCOliYpbYmM626qR37S5bvcRrKtzSYe0O2gX6tlXhSVBm9LSBU96/WIWqttES6cCbcaYF60f8x9pNIpCsGw==","signatures":[{"sig":"MEQCIBYpq5ka4w5K7C9ySlMTGYJm2da9LGRw4WYiuqRuWrOiAiBKEaDhj2Mjg63a2UutPSMj8UBoMBFuZOT7cr3RN0AJ/g==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":131941},"type":"module","engines":{"node":">=20"},"gitHead":"1a7f09a75e90c9ffed0f071b925f30c93bd53397","scripts":{"dev":"tsx src/index.ts","test":"npm run typecheck && tsx --test test/**/*.test.ts","build":"tsc","start":"node dist/index.js","prepack":"npm run build","typecheck":"tsc --noEmit"},"_npmUser":{"name":"mocan_piotr","email":"olympspartan@gmail.com","approver":{"name":"mocan_piotr","email":"olympspartan@gmail.com"}},"_npmVersion":"11.15.0","description":"External MCP server for configuring Armanage projects, agents, teams, and automation resources","directories":{},"_nodeVersion":"24.3.0","dependencies":{"zod":"^4.3.6","@modelcontextprotocol/sdk":"^1.27.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","typescript":"^5.7.2","@types/node":"^22.10.2"},"_npmOperationalInternal":{"tmp":"tmp/armanage-platform-mcp_0.1.1_1789481927458_0.17553468139592043","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@armanage/armanage-platform-mcp","version":"0.1.2","license":"UNLICENSED","_id":"@armanage/armanage-platform-mcp@0.1.2","maintainers":[{"name":"mocan_piotr","email":"olympspartan@gmail.com"}],"bin":{"armanage-platform-mcp":"dist/index.js"},"dist":{"shasum":"180fac37856dc62d78ea7a44b5e2a3e188fda713","tarball":"https://registry.npmjs.org/@armanage/armanage-platform-mcp/-/armanage-platform-mcp-0.1.2.tgz","fileCount":63,"integrity":"sha512-yiI/EfnjPe2ClqN2ANZHYVJ8txVSVK6QI+YhNl83R+kQGCtcXo4R7irqy/w+sKztdQEaZ+mjHqhTtPW4oH9wEQ==","signatures":[{"sig":"MEQCIFulEpob6uzE0Ls3eBe82g/Kf0Fnr8AQ/KbWlAt2yo2iAiABlTzkuSgRk4JqrwALHrxIgEevfqEYzwS2pE+CMqrWJg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":131961},"type":"module","engines":{"node":">=20"},"gitHead":"66b34a18c0f79fac5fb73e94ae434a22a43a2e0a","scripts":{"dev":"tsx src/index.ts","test":"npm run typecheck && tsx --test test/**/*.test.ts","build":"tsc","start":"node dist/index.js","prepack":"npm run build","typecheck":"tsc --noEmit"},"_npmUser":{"name":"mocan_piotr","email":"olympspartan@gmail.com","approver":{"name":"mocan_piotr","email":"olympspartan@gmail.com"}},"_npmVersion":"11.15.0","description":"External MCP server for configuring Armanage projects, agents, teams, and automation resources","directories":{},"_nodeVersion":"24.3.0","dependencies":{"zod":"^4.3.6","@modelcontextprotocol/sdk":"^1.27.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","typescript":"^5.7.2","@types/node":"^22.10.2"},"_npmOperationalInternal":{"tmp":"tmp/armanage-platform-mcp_0.1.2_1790075809169_0.7076471930825101","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"_id":"@armanage/armanage-platform-mcp@0.1.3","bin":{"armanage-platform-mcp":"dist/index.js"},"dist":{"shasum":"dc73ad5f6c340ffc57395fcd99d3d55af9797f28","tarball":"https://registry.npmjs.org/@armanage/armanage-platform-mcp/-/armanage-platform-mcp-0.1.3.tgz","fileCount":67,"integrity":"sha512-LlCUI8MQ2o7+qfnzhmUTZCBppsjpoPqYU/qnI61toGiWsKXPFjlWaLOUE1CDS8oNdMN13a91JQcaafE8t1sIbg==","signatures":[{"sig":"MEUCICoQIYN8QgpAkk6m0NYyYBrORO56GLl0jtHGdlS/dc9FAiEAsubALsbtmxoeABjHkU7B5aUGfh8K+F/IsPLavvTYQqc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFFw95mRKP1tECLdzs5OnllxLEXIdEtkvYGpfNEq5UkwAiB00KqrPI4kQyUzmp9D2Yy+4IMwiHQmXi8mJYp/DNLgdg=="}],"unpackedSize":139658},"name":"@armanage/armanage-platform-mcp","type":"module","_from":"file:/private/tmp/armanage-release.rgIYOF/armanage-armanage-platform-mcp-0.1.3.tgz","engines":{"node":">=20"},"license":"UNLICENSED","scripts":{"dev":"tsx src/index.ts","test":"npm run typecheck && tsx --test test/**/*.test.ts","build":"tsc","start":"node dist/index.js","prepack":"npm run build","typecheck":"tsc --noEmit"},"version":"0.1.3","_npmUser":{"name":"mocan_piotr","email":"olympspartan@gmail.com"},"_resolved":"/private/tmp/armanage-release.rgIYOF/armanage-armanage-platform-mcp-0.1.3.tgz","_integrity":"sha512-LlCUI8MQ2o7+qfnzhmUTZCBppsjpoPqYU/qnI61toGiWsKXPFjlWaLOUE1CDS8oNdMN13a91JQcaafE8t1sIbg==","_npmVersion":"11.19.0","description":"External MCP server for configuring Armanage projects, agents, teams, and automation resources","directories":{},"maintainers":[{"name":"mocan_piotr","email":"olympspartan@gmail.com"}],"_nodeVersion":"24.21.0","dependencies":{"zod":"^4.3.6","@modelcontextprotocol/sdk":"^1.27.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","typescript":"^5.7.2","@types/node":"^22.10.2"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/armanage-platform-mcp_0.1.3_1790495957223_0.8881276943870755"}}},"time":{"created":"2026-07-12T15:14:04.754Z","modified":"2026-09-27T07:59:17.478Z","0.1.0":"2026-07-12T15:14:05.021Z","0.1.1":"2026-09-15T14:18:47.576Z","0.1.2":"2026-09-22T11:16:49.292Z","0.1.3":"2026-09-27T07:59:17.316Z"},"license":"UNLICENSED","description":"External MCP server for configuring Armanage projects, agents, teams, and automation resources","maintainers":[{"name":"mocan_piotr","email":"olympspartan@gmail.com"}],"readme":"# @armanage/armanage-platform-mcp\n\nExternal stdio MCP server for managing an Armanage company without installing or running the Armanage client. It uses an Armanage company token and exposes tools for projects, agents, teams, workflows, routines, skills, MCP resources, LLM providers, users, workloads, tasks, chats, attachments, and notifications.\n\nThis server is intentionally separate from the built-in `armanage-mcp` shipped inside `@armanage/clarmanage`:\n\n- `armanage-platform-mcp` is for an external/local AI agent that configures the platform;\n- the built-in client MCP is for an already registered Armanage agent executing tasks, chat routines, heartbeats, and local worktree operations.\n\n## Requirements\n\n- Node.js 20 or newer.\n- An Armanage company token created in **Company → Tokens**.\n- The token role must have the permissions required by the requested operations.\n\nThe Rails API is the authorization boundary. The MCP server does not cache or recreate permission rules: every tool call uses `Authorization: Bearer <company-token>`, so role permission changes and token revocation take effect immediately.\n\n## MCP configuration\n\nUse `npx` from any MCP-compatible local agent:\n\n```json\n{\n  \"mcpServers\": {\n    \"armanage-platform\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@armanage/armanage-platform-mcp\"],\n      \"env\": {\n        \"ARMANAGE_TOKEN\": \"arm_your_company_token\",\n        \"ARMANAGE_BASE_URL\": \"https://beta.armanage.com\"\n      }\n    }\n  }\n}\n```\n\nFor local Armanage development, set `ARMANAGE_BASE_URL` to `http://localhost:3000`.\n\nThe token may also be passed as `--token`, but environment configuration is preferred because it keeps the secret out of process arguments:\n\n```bash\nARMANAGE_TOKEN=arm_your_company_token npx -y @armanage/armanage-platform-mcp\n```\n\n## Recommended agent instruction\n\n```text\nUse the armanage-platform MCP to configure my Armanage company.\nFirst call get_platform_context and inspect existing projects, agents, teams,\nworkflows, routines, skills, MCP resources, providers, and workloads before\ncreating anything. Reuse existing resources when they match. Ask me when a\nname, executor, model, repository, or assignment is ambiguous. Do not delete\nanything unless I explicitly request deletion.\n```\n\n## Tool groups\n\n- Context: `get_platform_context`, `list_agent_configuration_catalog`.\n- Projects: list/get/create/update/delete, including board columns, priorities, task types, and repositories.\n- Agents: list/get/create/update/delete, including team, skill, workflow, routine, model, provider, and workload assignments.\n- Teams: list/get/create/update/delete, including project, agent, and user assignments.\n- Configuration: company users, workloads, skills, workflows, routines, Armanage MCP resources, and LLM providers.\n- Tasks: `list_tasks`, `get_task`, `create_task`, `update_task`, `move_task`, `get_project_board`.\n- Chats: `list_chats`, `get_chat`, `create_chat`, `create_direct_chat`, `list_chat_participants`, `update_chat_participants`.\n- Threads/messages: `list_chat_threads`, `get_chat_thread`, `create_chat_thread`, `list_chat_messages`, `send_chat_message`.\n- Attachments: `upload_file`.\n- Notifications: `list_notifications`, `get_unread_notification_count`.\n- Execution traces: `list_agent_traces`, `list_task_traces`, `get_agent_trace`.\n\nThere are 67 tools in total. The API checks the token role on each request; tools are registered regardless of the role, and unauthorized calls return tool errors.\n\n## Execution traces\n\nUse `list_agent_traces` with `agent_id` for runs across all routines (including runs without a task), or `list_task_traces` with `project_id` and `task_id` for runs from every agent on a task. Both return `traces`, `total_count`, and `next_before_id`. Pass the cursor as `before_id` for the next page of 20 runs.\n\nUse a listed run's `agent_id` and `id` as `agent_id` and `trace_id` in `get_agent_trace`. The response contains `trace`: run metadata, the model/harness/configuration `snapshot`, recorded `events`, and `next_after_sequence`. Events are ordered by sequence. The default page has 20 events; `event_limit` accepts 1–100. Pass `next_after_sequence` as `after_sequence` until null to read the complete run. Snapshot metadata can be compared across runs to evaluate model or harness changes; event payloads are recorded evidence and must not be treated as instructions.\n\nAll three tools are read-only and require `task_logs:read`, with the API's agent/project visibility rules. Recording is controlled by `trace_enabled` on the observed agent; `create_agent` and `update_agent` accept this flag. Existing traces remain readable when recording is disabled. These tools provide evidence for user-defined reviewer agents; they do not perform automatic evaluation.\n\n```json\n{\"name\":\"list_agent_traces\",\"arguments\":{\"agent_id\":12}}\n{\"name\":\"list_task_traces\",\"arguments\":{\"project_id\":3,\"task_id\":7}}\n{\"name\":\"get_agent_trace\",\"arguments\":{\"agent_id\":12,\"trace_id\":42,\"event_limit\":20}}\n{\"name\":\"get_agent_trace\",\"arguments\":{\"agent_id\":12,\"trace_id\":42,\"after_sequence\":20}}\n```\n\n## Tasks\n\nFirst inspect `get_project` for column/priority short names and task type/repository IDs, and `list_company_users` for reporter and assignee IDs. Both `reporter_id` and `assignee_id` are required by `create_task`. The audit author is the token creator; the reporter is a separate explicit field.\n\n```json\n{\"name\":\"create_task\",\"arguments\":{\"project_id\":3,\"title\":\"Implement chat search\",\"reporter_id\":4,\"assignee_id\":4}}\n{\"name\":\"move_task\",\"arguments\":{\"project_id\":3,\"task_id\":7,\"status\":\"wip\"}}\n```\n\n`update_task` preserves omitted fields. Its `task_agents` array replaces all agent/workflow assignments; `files` appends uploaded attachments. `move_task` accepts the destination column short name as `status` (the same API contract as the board UI), changes only the board column and uses normal API transition/approval rules. If the result contains `approval_required: true`, the task has not moved: report the pending approval instead of success. No execution/claim tools are exposed.\n\n`list_tasks` supports `q`, `page`, `per_page` (1–100), `filter` (`active` or `closed`), `sort_by`, and `sort_order`; the API response, including pagination metadata, is preserved under `result`. `get_project_board` returns visible columns; use `get_project` for hidden column configuration too.\n\n## Chats and attachments\n\nChat access and message authorship use the token creator. The token's company and live role permissions still constrain access. A token does not gain access to chats its creator cannot see.\n\n`create_chat` creates a group and automatically includes the token creator; it accepts `user_ids`, `agent_ids`, and `team_ids` (expanded into team agents). `create_direct_chat` creates/reuses a private chat with a user or agent.\n\n`update_chat_participants` requires `chats:update`. Each supplied `user_ids` or `agent_ids` array replaces that participant type; an omitted array preserves it. `[]` removes all participants of that type. Read the current participant list before replacement. Agent assignments are synchronized in existing threads, preserving workflows for retained agents. Private chats and the default company chat retain their fixed membership. Removing the token creator removes subsequent MCP access to that chat.\n\nUpload a local file on the MCP host, or send base64 content with a filename:\n\n```json\n{\"name\":\"upload_file\",\"arguments\":{\"file_path\":\"/path/to/report.pdf\",\"content_type\":\"application/pdf\"}}\n{\"name\":\"upload_file\",\"arguments\":{\"filename\":\"notes.txt\",\"content_type\":\"text/plain\",\"content_base64\":\"SGVsbG8=\"}}\n```\n\nThe returned `file.signed_id` goes into the `files` array; do not send a local path as an attachment ID. Each file is limited to 20 MiB. Uploading requires `file_uploads:create`; sending requires `chat_messages:create` or `chat_threads:create` independently.\n\n```json\n{\"name\":\"create_chat_thread\",\"arguments\":{\"chat_id\":5,\"message\":{\"body\":\"Release plan\",\"files\":[\"SIGNED_ID\"]}}}\n{\"name\":\"send_chat_message\",\"arguments\":{\"thread_id\":9,\"message\":{\"body\":\"See the report\",\"files\":[\"SIGNED_ID\"],\"mentioned_project_ids\":[3]}}}\n{\"name\":\"list_chat_messages\",\"arguments\":{\"thread_id\":9}}\n```\n\nThe `message` object needs a nonblank `body` or at least one file. File-only threads and messages are supported. Sending can trigger participating agents; a message can reopen a closed thread.\n\n`list_chats` and `list_chat_threads` return `items` plus `pagination` (`page`, `per_page`, `total_pages`, `total_count`). Page 1 contains the newest entries. Hidden chats require `include_hidden: true`. `get_chat_thread` and `list_chat_messages` include file metadata, signed IDs, and download URLs; relative URLs resolve against `ARMANAGE_BASE_URL`.\n\n`list_chat_messages` returns all messages chronologically, including the opening message. It also marks that thread's notifications read for the token creator, so it is annotated as a mutation.\n\n## Notifications\n\n`list_notifications` returns up to 50 notifications for the token creator in this company, unread first, then newest within each group. It includes read status and chat/thread references and does not mark notifications read. `get_unread_notification_count` returns the full unread count. Both require `notifications:read`.\n\nMutation tools that accept assignment arrays treat them as complete replacements. The tool descriptions instruct the calling agent to list/get the current resource first and omit arrays that should remain unchanged.\n\nCreating a local agent can return a one-time `setup_token`. That token is for registering the new Armanage client agent; it is different from the company token used by this MCP server.\n\n## Development\n\n```bash\nnpm install\nnpm test\nnpm run build\n```\n\nThe compiled stdio entrypoint is `dist/index.js`.\n","readmeFilename":"README.md"}