@starasia/task-management-mcp 1.0.0 → 1.0.2

package/README.md

@@ -1,148 +1,99 @@
 # Task Management MCP
 
-MCP server for Star Perkasa Technology Task Management API.
+MCP server for Star Perkasa Technology Task Management.
 
-The server exposes read tools, dry-run-first write tools, and monitoring/reporting tools for spaces, projects, and tasks. It does **not** store a global user token in environment variables. Authorization is session-based: the AI agent must ask the active user for their bearer token, user id, and organization id, then call `set_auth_context` before using task tools.
+Package ini membantu AI agent membaca, membuat, memperbarui, memantau, dan merangkum task melalui Task Management API dengan permission sesuai user aktif.
+
+Server ini tidak menyimpan token global. Akses API memakai auth context runtime yang diberikan oleh user aktif melalui tool MCP.
 
 ## Requirements
 
 - Node.js 20+
-- Running `task-management-api`
-- A user-provided auth context at runtime:
-  - bearer token
-  - user id
-  - organization id
+- Access to a running Starasia Task Management API instance
 
-## Package
+## Features
 
-Published package name:
+- List spaces, projects, project members, workflow statuses, and tasks
+- Get project and task detail
+- Create single or bulk tasks
+- Update task fields, status, and assignees
+- Monitor overdue and stale tasks
+- Summarize project progress, workload, and work reports
+- Dry-run-first write tools for safer agent workflows
 
-```text
-@starasia/task-management-mcp
-```
+## Install
 
-Install from npm after a release lands on `main`:
+Install global:
 
 ```bash
 npm install -g @starasia/task-management-mcp
 ```
 
-## Install from source
+Run manually for smoke test:
 
 ```bash
-npm install
-npm run build
+task-management-mcp
 ```
 
-## Runtime configuration
+Or run without global install:
 
-Only non-user runtime settings should be configured as environment variables:
-
-```text
-TASK_MANAGEMENT_API_BASE_URL=http://localhost:3000
-TASK_MANAGEMENT_TIMEOUT_MS=30000
-TASK_MANAGEMENT_MAX_BULK_SIZE=50
-TASK_MANAGEMENT_AUTH_TTL_MS=28800000
+```bash
+npx -y @starasia/task-management-mcp
 ```
 
-Do **not** configure these as server env values:
+## Claude Code
+
+Install global lalu daftarkan ke Claude Code:
 
-```text
-TASK_MANAGEMENT_API_TOKEN
-TASK_MANAGEMENT_USER_ID
-TASK_MANAGEMENT_ORGANIZATION_ID
+```bash
+npm install -g @starasia/task-management-mcp
+claude mcp add --scope user task-management -- task-management-mcp
 ```
 
-Those values are user identity and permission context. The AI agent must request them from the user at runtime and call `set_auth_context`. `userId` is derived from the bearer token JWT `sub` claim, so it should not be configured as a server env value.
+Alternatif tanpa install global:
 
-## Hermes stdio config
+```bash
+claude mcp add --scope user task-management -- npx -y @starasia/task-management-mcp
+```
 
-```yaml
-mcp_servers:
-  task_management_dev:
-    command: "npx"
-    args: ["-y", "@starasia/task-management-mcp"]
-    env:
-      TASK_MANAGEMENT_API_BASE_URL: "https://dev-task-management-api.example.com"
+Verifikasi:
 
-  task_management_prod:
-    command: "npx"
-    args: ["-y", "@starasia/task-management-mcp"]
-    env:
-      TASK_MANAGEMENT_API_BASE_URL: "https://task-management-api.example.com"
+```bash
+claude mcp list
+claude mcp get task-management
 ```
 
-With two MCP instances, tools are clearly separated by environment. The exact rendered tool names depend on the host. Hermes usually prefixes them by server name; Claude Code and Codex use their own MCP tool naming conventions.
+## Codex CLI
 
-## Claude Code / Codex MCP config
+Quick command:
 
-Use the same stdio command shape. Example:
-
-```json
-{
-  "mcpServers": {
-    "task-management-dev": {
-      "command": "npx",
-      "args": ["-y", "@starasia/task-management-mcp"],
-      "env": {
-        "TASK_MANAGEMENT_API_BASE_URL": "https://dev-task-management-api.example.com"
-      }
-    },
-    "task-management-prod": {
-      "command": "npx",
-      "args": ["-y", "@starasia/task-management-mcp"],
-      "env": {
-        "TASK_MANAGEMENT_API_BASE_URL": "https://task-management-api.example.com"
-      }
-    }
-  }
-}
+```bash
+codex mcp add task-management --command npx --args -y --args @starasia/task-management-mcp
 ```
 
-## Auth flow for AI agents
-
-Before calling any task/space/project tool, the agent should:
+Fallback via `~/.codex/config.toml`:
 
-1. Call `get_auth_context_status`.
-2. If `configured` is false, ask the active user for:
-   - bearer token
-   - organization id
-3. Call `set_auth_context`:
-
-```json
-{
-  "bearerToken": "user-supplied-jwt-access-token",
-  "organizationId": "organization-id",
-  "environment": "dev",
-  "validate": true
-}
+```toml
+[mcp_servers.task_management]
+command = "npx"
+args = ["-y", "@starasia/task-management-mcp"]
 ```
 
-`set_auth_context` decodes the bearer token JWT payload and uses the `sub` claim as `userId`. If the token is not a JWT or does not contain a string `sub`, pass `userId` explicitly as an override:
+## JSON MCP Config
+
+Untuk client lain yang memakai format JSON `mcpServers`:
 
 ```json
 {
-  "bearerToken": "user-supplied-token",
-  "userId": "explicit-user-id",
-  "organizationId": "organization-id",
-  "validate": true
+  "mcpServers": {
+    "task-management": {
+      "command": "npx",
+      "args": ["-y", "@starasia/task-management-mcp"]
+    }
+  }
 }
 ```
 
-`set_auth_context` validates the token with `GET /spaces` by default, stores the context only in the MCP process memory, and returns a masked status. It never returns the token. The context expires after `TASK_MANAGEMENT_AUTH_TTL_MS` milliseconds, default 8 hours.
-
-Important security note: for broad Claude Code / Codex compatibility, the bearer token is passed as a tool argument. That means it may transit the host application's conversation or debug surface before it reaches the MCP. Users should only provide tokens in trusted local agent sessions, prefer short-lived tokens, and call `clear_auth_context` when done.
-
-For separate dev/prod MCP instances, call `set_auth_context` separately on each instance because each process has its own in-memory session.
-
-When the user is done, call:
-
-```text
-clear_auth_context
-```
-
-If a tool is called before auth is configured, the MCP returns an error instructing the agent to ask the user for bearer token and organization id, then call `set_auth_context`. `userId` is derived from the token JWT `sub` claim unless an explicit override is provided.
-
 ## Tools
 
 ### Auth/session
@@ -165,17 +116,17 @@ If a tool is called before auth is configured, the MCP returns an error instruct
 
 ### Write tools
 
-Write tools default to `dryRun: true`. Set `dryRun: false` to execute.
+Write tools default to `dryRun: true`. Set `dryRun: false` only when the user has approved the action.
 
 - `create_task`
 - `bulk_create_tasks`
 - `update_task`
 - `change_task_status`
-- `assign_task` — add assignees using numeric `ProjectMember.id` values
-- `unassign_task` — remove one assignee using numeric `ProjectMember.id`
-- `replace_task_assignees` — make the assignee set exactly match the provided `projectMemberIds`
+- `assign_task`
+- `unassign_task`
+- `replace_task_assignees`
 
-`create_task.createdBy`, `assign_task.assignedBy`, and `replace_task_assignees.assignedBy` default to the active auth `userId` when omitted.
+Assignee tools use project member ids from `list_project_members`.
 
 ### Monitoring/reporting
 
@@ -184,47 +135,28 @@ Write tools default to `dryRun: true`. Set `dryRun: false` to execute.
 - `workload_by_user`
 - `generate_work_report`
 
-## API assumptions found from `task-management-api`
+## Auth model
 
-- Spaces are exposed at `GET /spaces`.
-- Projects are scoped by space: `/spaces/:spaceId/projects`.
-- Tasks are scoped by project: `/projects/:projectId/tasks`.
-- Cross-project task list is `GET /my-tasks` with `scope=me|all`.
-- The MCP forwards `Authorization`, `X-User-Id`, and `X-Organization-Id` from the active auth context.
-- Task creation currently requires `createdBy`; assignment uses numeric `ProjectMember.id` values.
+Before using task tools, the agent should check whether an auth context is configured. If not, it should ask the active user for the required runtime credentials and call `set_auth_context`.
 
-## Safety model
+The MCP keeps auth context in process memory only, returns masked auth status, and never returns the bearer token from any tool.
 
-- User identity and bearer token are supplied at runtime, not baked into env.
-- Auth context is held in process memory only and expires by `TASK_MANAGEMENT_AUTH_TTL_MS`.
-- `get_auth_context_status` masks the token and only returns `hasToken: true/false`.
-- The API URL cannot be overridden by `set_auth_context`; it comes from the MCP instance env to avoid bearer-token exfiltration to arbitrary hosts.
-- For compatibility with Claude Code and Codex, the token is passed through the MCP tool call surface. Use trusted local sessions and short-lived tokens where possible.
-- Read tools require an active auth context.
-- Write tools are dry-run by default.
-- Bulk create has a configurable limit (`TASK_MANAGEMENT_MAX_BULK_SIZE`, default 50).
-- `bulk_create_tasks` can skip existing tasks by exact normalized title (`idempotency: "title"`).
-- The MCP does not bypass application permissions; it only calls HTTP endpoints with the active user's auth context.
+Call `clear_auth_context` when the session is done.
+
+## Safety notes
+
+- The MCP does not bypass application permissions.
+- All API actions are performed using the active user's permission context.
+- Write tools use dry-run mode by default.
+- Bulk task creation supports idempotency by normalized title.
+- Use this MCP only in trusted local agent sessions.
 
 ## Development
 
 ```bash
+npm test
 npm run typecheck
 npm run lint
-npm test
 npm run build
 npm run pack:check
 ```
-
-## CI/CD
-
-- `CI` runs on pull requests to `main`/`dev`, pushes to `dev`, and manual dispatch.
-- `CI` uses GitHub Environment `development` for Discord notification only.
-- `Release and Notify` runs on pushes to `main` and manual dispatch.
-- Release workflow validates typecheck, lint, test, build, and `npm pack --dry-run` before publishing.
-- Publish is skipped when the package version already exists on npm.
-- Required development secrets:
-  - `DISCORD_WEBHOOK_URL`
-- Required production secrets:
-  - `NPM_TOKEN`
-  - `DISCORD_WEBHOOK_URL` (notification)

package/dist/config.js

@@ -1,9 +1,11 @@
 import { z } from "zod";
+import { BUILD_TASK_MANAGEMENT_API_BASE_URL } from "./generated-config.js";
+const DEFAULT_TASK_MANAGEMENT_API_BASE_URL = BUILD_TASK_MANAGEMENT_API_BASE_URL || "http://localhost:3000";
 const envSchema = z.object({
     TASK_MANAGEMENT_API_BASE_URL: z
         .string()
         .url()
-        .default("http://localhost:3000"),
+        .default(DEFAULT_TASK_MANAGEMENT_API_BASE_URL),
     TASK_MANAGEMENT_TIMEOUT_MS: z.coerce
         .number()
         .int()

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC;IACzB,4BAA4B,EAAE,CAAC;SAC5B,MAAM,EAAE;SACR,GAAG,EAAE;SACL,OAAO,CAAC,uBAAuB,CAAC;IACnC,0BAA0B,EAAE,CAAC,CAAC,MAAM;SACjC,MAAM,EAAE;SACR,GAAG,EAAE;SACL,QAAQ,EAAE;SACV,OAAO,CAAC,MAAM,CAAC;IAClB,6BAA6B,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;IAC7E,2BAA2B,EAAE,CAAC,CAAC,MAAM;SAClC,MAAM,EAAE;SACR,GAAG,EAAE;SACL,QAAQ,EAAE;SACV,OAAO,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;CAC/B,CAAC,CAAC;AAIH,MAAM,UAAU,UAAU,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG;IAC1C,OAAO,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,kCAAkC,EAAE,MAAM,uBAAuB,CAAC;AAE3E,MAAM,oCAAoC,GACxC,kCAAkC,IAAI,uBAAuB,CAAC;AAEhE,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC;IACzB,4BAA4B,EAAE,CAAC;SAC5B,MAAM,EAAE;SACR,GAAG,EAAE;SACL,OAAO,CAAC,oCAAoC,CAAC;IAChD,0BAA0B,EAAE,CAAC,CAAC,MAAM;SACjC,MAAM,EAAE;SACR,GAAG,EAAE;SACL,QAAQ,EAAE;SACV,OAAO,CAAC,MAAM,CAAC;IAClB,6BAA6B,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;IAC7E,2BAA2B,EAAE,CAAC,CAAC,MAAM;SAClC,MAAM,EAAE;SACR,GAAG,EAAE;SACL,QAAQ,EAAE;SACV,OAAO,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;CAC/B,CAAC,CAAC;AAIH,MAAM,UAAU,UAAU,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG;IAC1C,OAAO,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AAC9B,CAAC"}

package/dist/generated-config.d.ts

@@ -0,0 +1 @@
+export declare const BUILD_TASK_MANAGEMENT_API_BASE_URL = "https://task-management-api-323393867185.asia-southeast2.run.app";

package/dist/generated-config.js

@@ -0,0 +1,4 @@
+// This file is generated by scripts/generate-build-config.mjs.
+// BUILD_TASK_MANAGEMENT_API_BASE_URL is injected by CI for published builds.
+export const BUILD_TASK_MANAGEMENT_API_BASE_URL = "https://task-management-api-323393867185.asia-southeast2.run.app";
+//# sourceMappingURL=generated-config.js.map

package/dist/generated-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated-config.js","sourceRoot":"","sources":["../src/generated-config.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,6EAA6E;AAC7E,MAAM,CAAC,MAAM,kCAAkC,GAAG,kEAAkE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starasia/task-management-mcp",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "private": false,
   "type": "module",
   "description": "MCP server for Star Perkasa Technology Task Management API",
@@ -34,7 +34,7 @@
   },
   "scripts": {
     "test": "vitest run",
-    "build": "tsc",
+    "build": "node scripts/generate-build-config.mjs && tsc",
     "dev": "tsx src/index.ts",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src --ext .ts",