TaskHub MCP Server
# TaskHub MCP Server
MCP (Model Context Protocol) server for **TaskHub** — manage tasks, projects,
organizations, comments, notifications, and activity from an MCP host.
## Quick start
### 1. Install the package
Use a published package or a local checkout. The server command can be invoked
as `taskhub-mcp` after installation, or as `node /absolute/path/to/dist/index.js`.
### 2. Configure the MCP host
The preferred setup keeps credentials out of host configuration. The API URL is
optional for local development and should be HTTPS for remote servers.
#### Claude Code
For a project-scoped server, add this to the project's `.mcp.json`. For a
user/global Claude Code registration, put the same `mcpServers` entry in
`~/.claude.json` instead:
```json
{
"mcpServers": {
"taskhub": {
"command": "taskhub-mcp",
"env": {
"TASKHUB_API_URL": "https://api.taskhub.example/api"
}
}
}
}
```
For a local checkout, replace the command with `node` and use
`["/absolute/path/to/taskhub-mcp/dist/index.js"]` as `args`.
#### OpenCode
Use OpenCode's local MCP `environment` field; do not put project keys in the
configuration:
```json
{
"mcp": {
"taskhub": {
"type": "local",
"command": ["taskhub-mcp"],
"environment": {
"TASKHUB_API_URL": "https://api.taskhub.example/api"
},
"enabled": true
}
}
}
```
If the executable is not on PATH, use a portable launcher script that only
selects the executable and forwards arguments:
```sh
#!/bin/sh
exec /usr/bin/node /absolute/path/to/taskhub-mcp/dist/index.js "$@"
```
Point the host's local MCP command at that launcher. This repository does not
modify Claude Code, OpenCode, or any global host configuration automatically.
### 3. Register project-bound credentials
The non-MCP credential CLI reads the key from hidden stdin; never pass a key as
a model/tool argument, command-line argument, or configuration value:
```bash
taskhub-mcp credentials add --project-id <project-uuid> --label Work
taskhub-mcp credentials list
taskhub-mcp credentials update --project-id <project-uuid>
taskhub-mcp credentials remove --project-id <project-uuid>
```
The `list` command shows only project UUIDs, optional labels, and update times.
`--token` is rejected. CLI output is separate from MCP stdio; when the server
is running, stdout remains reserved for MCP protocol frames.
The default store is outside repositories:
- Linux: `$XDG_CONFIG_HOME/taskhub/credentials.json`, or `~/.config/taskhub/credentials.json`
- macOS: `~/Library/Application Support/TaskHub/credentials.json`
- Windows: `%APPDATA%/TaskHub/credentials.json`
`TASKHUB_CONFIG_DIR` or `TASKHUB_CREDENTIALS_FILE` may select an absolute
portable location. On POSIX, the store is written as `0600` and its directory
as `0700` where supported.
### 4. Link the working directory
With a known UUID, use the profile directly and avoid discovery ambiguity:
```text
Use taskhub_connect with projectId "<project-uuid>"
```
If no context exists and the UUID is not known, temporarily configure the
backward-compatible `TASKHUB_API_TOKEN`, then call `taskhub_context` or
`taskhub_projects_list`. They can list the projects visible to that key. Connect
by `systemCode` or `slug`, or register the UUID profile and connect by
`projectId`.
The server writes only project metadata to `.taskhub.json`:
```json
{
"projectId": "project-uuid",
"projectName": "My Project",
"projectSlug": "my-project",
"systemCode": "PRJ-260219-A3K7",
"organizationId": null,
"organizationName": null
}
```
It never writes a token to that file.
## Multi-project behavior
TaskHub still authorizes each API key for one backend project. This feature does
not weaken that binding or create a multi-project server key. It adds a local
mapping from stable project UUID to project-bound key.
For every request, the MCP server re-reads the effective project from
`.taskhub.json` (including an active sub-project) and selects only that UUID's
profile. A profile takes precedence over `TASKHUB_API_TOKEN`; when no profile
exists, the environment variable remains the compatibility fallback. The
server never tries every profile against an endpoint.
`projectId`-first connection can select a profile before a context exists.
Slug/systemCode discovery cannot identify a profile until the UUID is known, so
it uses the current context profile or `TASKHUB_API_TOKEN`. If neither is
available, the error explains the safe next step without exposing a key.
`taskhub_whoami`, project operations, and advisory scope checks use the same
effective profile. Scope caches are separated by credential context, so
switching projects cannot reuse another project's cached scopes.
## Backward compatibility and restart semantics
Existing installations may continue using:
```text
TASKHUB_API_TOKEN=<project-bound-api-key>
```
To migrate, register a profile for the linked project's UUID, validate with
`taskhub_whoami`, then remove the environment key only after the profile works.
The old variable remains a fallback for contexts without a registered profile.
Changing `.taskhub.json` or adding/updating/removing a credential profile does
not require an MCP restart: selection occurs on each request. Changing the MCP
command, `TASKHUB_API_URL`, host environment, or installed package does require
the MCP host to restart its process. Restart after the initial host setup so it
loads the new registration.
## Security contract
- Credentials are opaque project-bound API keys; there is no password, JWT, or refresh-token migration.
- Tokens are not rendered by tools, diagnostics, metadata listing, errors, README files, tests, or `.taskhub.json`.
- The CLI is explicit and non-MCP; it accepts secrets only through hidden stdin.
- Remote API URLs must use HTTPS. HTTP is reserved for localhost development.
- The backend remains authoritative for key validity, scopes, revocation, and project access.
- No normal MCP tool mutates Claude Code, OpenCode, host configuration, or credential files.
## Tools
### Auth and context
| Tool | Description |
|------|-------------|
| `taskhub_whoami` | Current user, server scopes, and linked/effective context |
| `taskhub_context` | Show the linked project or safe discovery guidance |
| `taskhub_connect` | Link by project UUID, slug, or system code; never accepts a token |
The remaining tools manage organizations, projects, tasks, comments,
notifications, statuses, and activity. See `GUIA.md` for extension and request
lifecycle details.
## Development and verification
```bash
pnpm install
pnpm test
pnpm run test:package
pnpm run build
```
Live tests are opt-in and require explicitly authorized test credentials:
`pnpm run test:live`.
## License
MIT
TDQS
Scored across 31 tools
Most tools map clearly to a distinct entity+action, but there are a few close boundaries: search vs. task_get both resolve by systemCode, whoami vs. context both expose linked project context, and task_complete is a specialized task_update. Detailed descriptions mitigate most confusion.
A general noun_verb pattern is visible (task_create, project_invite), but list endpoints are inconsistent: some use _list (orgs_list, tasks_list) while others use bare plurals (comments, notifications, statuses). Irregular names like whoami, connect, tasks_my, and daily_summary break the pattern further, though the naming remains readable.
With 31 tools, the server exceeds the 25-tool threshold for 'too many' in the calibration. The broad domain justifies some surface area, but utilities like whoami, search, and daily_summary could be consolidated with existing list/context tools to reduce redundancy.
Core task operations are well covered: list, get, create, update, complete, delete, and subtasks. However, org and project management lack update/delete operations, comments only support list/add with no edit/delete, and there is no member removal—leaving notable gaps for project administration workflows.