@tasqmate/mcp 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Paul Cedrick Artigo
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,157 @@
1
- # Temporary Holding Version
1
+ # @tasqmate/mcp
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ An MCP stdio server for [Tasqmate](https://github.com/pxlabz/tasq): tasks, projects,
4
+ threads, comments and agent mentions, for harnesses that speak the Model
5
+ Context Protocol rather than a shell.
6
+
7
+ **The CLI is the source of truth.** `tasqmate` and its skill file define
8
+ what an agent can do in Tasqmate; this package adds convenience, not capability.
9
+ Every tool here mirrors one CLI command, takes the same option names, and
10
+ returns the same JSON that command prints under `--json`. If the two ever
11
+ disagree, the CLI is right. An agent that can run a shell should use the CLI.
12
+
13
+ ## Install
14
+
15
+ Nothing to install: point your harness at `bunx @tasqmate/mcp`.
16
+
17
+ ## Environment
18
+
19
+ The same three variables the CLI reads.
20
+
21
+ | Variable | Required | Meaning |
22
+ | -------------------- | -------- | ------------------------------------------------------------------------------- |
23
+ | `TASQMATE_API_KEY` | yes | A Tasqmate agent key (`tq_ag_…`). The server refuses to start without one. |
24
+ | `TASQMATE_WORKSPACE` | no | Default workspace slug. Every tool takes a `workspace` input that overrides it. |
25
+ | `TASQMATE_API_URL` | no | API base URL. Defaults to `https://tasqmate.pxlabz.com`. |
26
+
27
+ The `TASQ_*` names from before the Tasqmate rename still work when the new one is unset.
28
+
29
+ ## Claude Code
30
+
31
+ ```sh
32
+ claude mcp add tasqmate -e TASQMATE_API_KEY=tq_ag_… -e TASQMATE_WORKSPACE=acme -- bunx @tasqmate/mcp
33
+ ```
34
+
35
+ ## Codex, and anything else that reads `mcpServers`
36
+
37
+ ```json
38
+ {
39
+ "mcpServers": {
40
+ "tasqmate": {
41
+ "command": "bunx",
42
+ "args": ["@tasqmate/mcp"],
43
+ "env": {
44
+ "TASQMATE_API_KEY": "tq_ag_…",
45
+ "TASQMATE_WORKSPACE": "acme"
46
+ }
47
+ }
48
+ }
49
+ }
50
+ ```
51
+
52
+ ## Coming from `@pxlabz/tasq-mcp`
53
+
54
+ The server used to be published as `@pxlabz/tasq-mcp`, which now forwards to this package until 15 January 2027, so an existing config keeps working. To move, swap `@pxlabz/tasq-mcp` for `@tasqmate/mcp` in the config and rename the variables to `TASQMATE_*`. The tool names are unchanged, and an entry you added as `tasq` can keep that name.
55
+
56
+ ## Dependencies
57
+
58
+ `@modelcontextprotocol/sdk` and `zod`. The zod dependency is pinned to exactly
59
+ `4.3.6`: Bun hoists one copy for the whole workspace, and 4.6.x re-hoists the
60
+ root copy and breaks `apps/api`'s typecheck, so the pin holds until the repo
61
+ moves together.
62
+
63
+ ## Tools
64
+
65
+ Thirty-seven tools, stdio transport only. No resources, no prompts. There is no
66
+ tool that sends a project update: an agent drafts, and a person sends. There
67
+ is no tool that shares a project with a guest either: no agent may share,
68
+ so `tasqmate project share` and the web Share dialog are the only ways in.
69
+
70
+ | Tool | Mirrors | Inputs |
71
+ | ---------------- | ---------------------- | ---------------------------------------------------------------------------- |
72
+ | `task_list` | `tasqmate task list` | `workspace`, `team`, `status`, `assignee`, `priority`, `project`, `cycle`, `q`, `includeArchived` |
73
+ | `task_view` | `tasqmate task view` | `workspace`, `id` |
74
+ | `task_create` | `tasqmate task create` | `workspace`, `title`, `team`, `description`, `priority`, `project`, `labels`, `due`, `start`, `parent`, `fields` |
75
+ | `task_update` | `tasqmate task update` | `workspace`, `id`, `title`, `description`, `priority`, `status`, `due`, `start`, `parent`, `fields` |
76
+ | `task_request_approval` | `tasqmate task request-approval` | `workspace`, `id`, `approver` |
77
+ | `field_list` | `tasqmate field list` | `workspace`, `all` |
78
+ | `time_log` | `tasqmate time log` | `workspace`, `task`, `duration`, `day`, `note`, `billable` (`yes`/`no`/`unset`) |
79
+ | `time_list` | `tasqmate time list` | `workspace`, `task` |
80
+ | `time_edit` | `tasqmate time edit` | `workspace`, `entryId`, `duration`, `day`, `note` (`null` clears), `billable` |
81
+ | `time_delete` | `tasqmate time delete` | `workspace`, `entryId` |
82
+ | `client_hours` | `tasqmate clients hours` | `workspace`, `client`, `month` (`YYYY-MM`), `billableOnly` |
83
+ | `my_week` | `tasqmate week` | `workspace`, `day` (`YYYY-MM-DD`) |
84
+ | `time_draft_get` | `tasqmate timesheet show` | `workspace`, `draftId`: the draft from a `timesheet_due` or `timesheet_reply` event, with the member's day |
85
+ | `time_draft_save` | `tasqmate timesheet save` | `workspace`, `draftId`, `lines` (`task`, `duration`, `billable?`, `evidence?`), `message?` |
86
+ | `client_billing` | `tasqmate clients billing` | `workspace`, `client` |
87
+ | `billing_period_close` | `tasqmate clients close` | `workspace`, `client`, `month` (admins) |
88
+ | `billing_period_mark_invoiced` | `tasqmate clients invoice` | `workspace`, `client`, `month`, `invoiceRef` (admins) |
89
+ | `billing_period_reopen` | `tasqmate clients reopen` | `workspace`, `client`, `month` (admins) |
90
+ | `comment_add` | `tasqmate comment add` | `workspace`, `body`, `task`, `project`, `doc`, `propose`, `replyTo`, `thread`, `mentions`, `attach` (absolute paths) |
91
+ | `file_add` | `tasqmate file add` | `workspace`, `task`, `paths` (absolute paths, up to 100 MB each) |
92
+ | `file_list` | `tasqmate file list` | `workspace`, `task`: the task's files, then each comment's |
93
+ | `file_get` | `tasqmate file get` | `workspace`, `id`, `out` (absolute path), `force`, `link`; with neither, a five-minute link plus the text of a text file up to 256 KB |
94
+ | `file_remove` | `tasqmate file remove` | `workspace`, `id` |
95
+ | `thread_view` | `tasqmate thread view` | `workspace`, `threadId` |
96
+ | `thread_context` | `tasqmate thread context` | `workspace`, `threadId`, `format` (`markdown` by default) |
97
+ | `project_list` | `tasqmate project list` | `workspace` |
98
+ | `initiative_list` | `tasqmate initiative list` | `workspace` |
99
+ | `activity_list` | `tasqmate activity` | `workspace`, `limit` |
100
+ | `project_update_list` | `tasqmate update list` | `workspace`, `project`, `limit` |
101
+ | `project_update_draft` | `tasqmate update draft` | `workspace`, `project`, `health`, `body` |
102
+ | `cycle_current` | `tasqmate cycle current` | `workspace`, `team` |
103
+ | `events_listen` | `tasqmate events listen` | `workspace`, `wait` (seconds, 0–25) |
104
+ | `events_ack` | `tasqmate events ack` | `workspace`, `ids` |
105
+ | `doc_list` | `tasqmate doc list` | `workspace`, `filter` (`all`, `workspace`, `projects`, `teams`, `mine`, `archived`), `project`, `q` |
106
+ | `doc_view` | `tasqmate doc view` | `workspace`, `id` (doc id, link or exact title) |
107
+ | `doc_create` | `tasqmate doc create` | `workspace`, `title`, `body` (Markdown), `project`, `team` |
108
+ | `doc_update` | `tasqmate doc update` | `workspace`, `id`, `title`, `body` (Markdown, the whole body), `baseVersion` |
109
+ | `doc_link` | `tasqmate doc link` | `workspace`, `id`, one of `task`, `project`, `team` |
110
+ | `doc_archive` | `tasqmate doc archive` | `workspace`, `id`, `restore` |
111
+ | `whoami` | `tasqmate auth whoami` | — |
112
+
113
+ ### Custom fields
114
+
115
+ `field_list` returns each field compactly — `id`, `key`, `name`, `type`, `appliesTo`, live `options` by name, `archived` — rather than the full library `tasqmate field list --json` prints; archived fields only with `all`. `fields` on `task_create` and `task_update` is one object of field key to value, the CLI's repeated `--field key=value`: `{"budget": 1200, "tier": "Gold", "areas": ["Web", "API"], "owner": "ana@example.com"}`. Options and people go by name (a person also by email), a list field also takes `"a,b"`, and `null` clears. Each field is set after the task is written, one `task.setField` per key, and the result leads with a `Name: value.` line per field as the server read it. An unknown key is a usage error naming the task fields, before anything is written.
116
+
117
+ ### Docs and mentions in Markdown
118
+
119
+ Doc bodies and task descriptions go in and out as Markdown. A mention is a link
120
+ with a `tasq:` address: `[ENG-12](tasq:task/<id>)` for a task and
121
+ `[Launch plan](tasq:doc/<id>)` for a doc. `doc_view` returns `bodyMarkdown`
122
+ written that way (and leaves out the editor JSON), so read, edit and send the
123
+ whole body back with `doc_update` and every mention survives. A bare `@ENG-12`
124
+ also becomes a mention when it names a task you can see; inside code it stays
125
+ text. A task link's text must be the key; a mention of something you cannot
126
+ see is saved as plain `@text`. The server relabels each mention with the
127
+ task's current key and the doc's current title.
128
+
129
+ `doc_update` saves over the version you name in `baseVersion` (from
130
+ `doc_view`); if someone saved since, it is refused with a conflict, so read
131
+ again and merge. Without `baseVersion` it reads the latest version first.
132
+ Writing docs needs `doc.*` in the agent's policy: Full has them, Triage does
133
+ not.
134
+
135
+ ### The event loop
136
+
137
+ `events_listen` is one poll, not a stream: an MCP tool call has to return, so
138
+ the harness calls it again rather than the server holding the connection open.
139
+ The loop is the CLI's — listen, act, then `events_ack` last. An unacknowledged
140
+ event is offered again ten minutes after delivery, so a crash between acting
141
+ and acking costs nothing; an event acked up front is gone.
142
+
143
+ ### Errors
144
+
145
+ A failed call comes back as a tool error whose first line carries the category
146
+ from the CLI's exit-code table, so the two read as one.
147
+
148
+ | Prefix | CLI exit code | Meaning |
149
+ | --------------------- | ------------- | ---------------------------------------------------------- |
150
+ | `Error (1):` | 1 | Something failed; the message says what. |
151
+ | `Usage error (2):` | 2 | A bad input, or a mention name matching no agent or several. |
152
+ | `Rate limited (3):` | 3 | The message says how many seconds to wait. The tool returns rather than sleeping — retry when it says. |
153
+ | `Policy denied (4):` | 4 | Your policy refused the action. Do not retry it; say what was refused. |
154
+
155
+ ## License
156
+
157
+ MIT