@geeks.ltd/geeks-amp-mcp 1.0.5 → 1.0.6

package/README.md

@@ -1,12 +1,14 @@
 # Geeks AMP MCP Server
 
-Local MCP server for Cursor that authenticates to your AMP backend via OAuth 2.0 (Authorization Code + PKCE) and proxies tool calls to AMP’s `MCPServer.ashx`.
+Local MCP server for Cursor and Claude that authenticates to your AMP backend via OAuth 2.0 (Authorization Code + PKCE) and proxies tool calls to AMP’s `MCPServer.ashx`.
+
+**Using this as a developer?** See **[DEVELOPER.md](DEVELOPER.md)** for Cursor and Claude setup, example prompts, and how AMP MCP can help in day-to-day work.
 
 ## Flow
 
 1. **First use** – When you call an AMP tool, the server opens your browser to AMP’s login. After you sign in, AMP redirects to `http://127.0.0.1:5005/callback`. The server exchanges the code for access and refresh tokens and stores them (e.g. in `~/.amp-mcp/credentials.json`).
 2. **Later uses** – The server reuses the stored access token. When it expires, it uses the refresh token; if refresh fails, it runs the browser flow again.
-3. **Tools** – `get_user_projects`, `get_projects`, `get_amp_item`, `get_amp_comments`, `get_amp_item_with_test_cases`, `create_amp`, `add_amp_update`, `submit_amp_progress_update`, `add_amp_test_case_references`, `submit_pen_test_review`, `audit_tdd_amp`, and `audit_pen_test_amp` are forwarded to AMP with `Authorization: Bearer <token>`. `get_auth_status` reports the local authentication state without calling AMP.
+3. **Tools** – `get_user_projects`, `get_projects`, `get_amp_item`, `get_active_workplans`, `get_workplan_items`, `get_amp_comments`, `get_amp_item_with_test_cases`, `create_amp`, `add_amp_update`, `submit_amp_progress_update`, `add_amp_test_case_references`, `submit_pen_test_review`, `audit_tdd_amp`, and `audit_pen_test_amp` are forwarded to AMP with `Authorization: Bearer <token>`. `get_auth_status` reports the local authentication state without calling AMP.
 
 ## Prerequisites
 
@@ -67,6 +69,8 @@ In `.cursor/mcp.json` (project or global), use the **local server** via npx (no
 - **get_user_projects** – Non-archived projects the authenticated user belongs to: `{ projects: [{ id, key, name }] }`, ordered by key. Use this before `create_amp`.
 - **get_projects** – Legacy global project search (optional `searchTerm`, `limit`); returns id + name only, not user-scoped. Do not use for create flows.
 - **get_amp_item** – Rich details for an authorized AMP by `ampReference` (`12345` or `AMP-12345`): metadata, project, type, priority, status/progress/stage, completion, assignees, workplans, tags, URLs, linked AMPs, extension relationships (`extendedFrom`, `extensions`), pen-test review fields, and test case references. It does not return full comment history; use `get_amp_comments` for the conversation.
+- **get_active_workplans** – Active workplans for a project (there may be several). Required: `project` (key or GUID). Returns dates, teams, estimate/duration, completion %, and item counts. Use `get_workplan_items` with a workplan name or GUID to load that plan's AMPs.
+- **get_workplan_items** – All items in a workplan, assigned to any user. Required: `project`. Optional: `workplan` (name or GUID from `get_active_workplans`; omit for the newest active plan), `assignee` (name, email, or user GUID), `progress` (`Not started`, `TDD`, `Developing`, `Testing`, `Done`, `Blocked`). Returns workplan metadata, applied filters, and items in workplan order.
 - **get_amp_comments** – Authorized AMP comment history, newest first. Required: `ampReference`. Optional: `column` (`Team`, `Client`, `Director`, or `all`) and `limit` (1–500). With no column, AMP returns every column visible to the authenticated user's role; with no limit, it returns all visible comments. The response reports visible/returned counts and truncation, and includes decoded text, author, column, status/progress changes, assignees, and attachment URLs.
 - **create_amp** – Create a new work item (status New). Required: `project` (key or GUID from `get_user_projects`), `subject`, `type`, `priority`. Optional: `description`, `url`, `note`, `visualSpecLink`, `linkedWorkItems`, `parentAmpReference`. Response includes `reference`, `projectId`, `projectKey`, `projectName`, `url`, etc.
 - **get_amp_item_with_test_cases** – Existing TDD/pen-test-focused subset by `ampReference`. It requires authenticated access. Prefer `get_amp_item` plus `get_amp_comments` for general agent workflows.

package/dist/index.js

@@ -149,6 +149,45 @@ async function main() {
         const token = await ensureAccessToken();
         return callAmpTool("get_amp_item", { ampReference }, token);
     });
+    // get_active_workplans – list a project's active workplans (there may be several)
+    server.tool("get_active_workplans", "List a project's active workplans (there may be more than one) with dates, teams, estimates, completion, and item counts. Use get_workplan_items with a workplan name or GUID to load that plan's AMPs. Use get_user_projects for a project key.", {
+        project: z
+            .string()
+            .min(1)
+            .describe("Project key (preferred) or GUID from get_user_projects"),
+    }, async ({ project }) => {
+        const token = await ensureAccessToken();
+        return callAmpTool("get_active_workplans", { project }, token);
+    });
+    // get_workplan_items – all items in the project's active workplan (optional assignee/progress filters)
+    server.tool("get_workplan_items", "List all AMP items in a workplan, assigned to any user, in workplan order. Optional filters: assignee (name, email, or GUID) and progress (Not started, TDD, Developing, Testing, Done, Blocked). Pass workplan name or GUID from get_active_workplans when the project has several active plans; omit workplan to use the newest active one. Use get_user_projects for a project key.", {
+        project: z
+            .string()
+            .min(1)
+            .describe("Project key (preferred) or GUID from get_user_projects"),
+        workplan: z
+            .string()
+            .optional()
+            .describe("Optional workplan name or GUID. Omit to use the project's current active workplan."),
+        assignee: z
+            .string()
+            .optional()
+            .describe("Optional team assignee filter (name, email, or user GUID). Omit to include items assigned to any user."),
+        progress: z
+            .enum(teamProgressValues)
+            .optional()
+            .describe("Optional team progress filter: Not started, TDD, Developing, Testing, Done, Blocked"),
+    }, async ({ project, workplan, assignee, progress, }) => {
+        const token = await ensureAccessToken();
+        const args = { project };
+        if (workplan !== undefined && workplan.trim() !== "")
+            args.workplan = workplan.trim();
+        if (assignee !== undefined && assignee.trim() !== "")
+            args.assignee = assignee.trim();
+        if (progress !== undefined)
+            args.progress = progress;
+        return callAmpTool("get_workplan_items", args, token);
+    });
     // get_amp_comments – authorized, role-filtered AMP conversation history
     server.tool("get_amp_comments", "Get comments on an AMP that the authenticated user is allowed to view, ordered newest first. Returns all visible comments by default. Optionally filter to Team, Client, or Director and/or limit the result.", {
         ampReference: z

package/dist/tools.js

@@ -49,6 +49,46 @@ export const TOOL_DEFINITIONS = [
             required: ["ampReference"],
         },
     },
+    {
+        name: "get_active_workplans",
+        description: "List a project's active workplans (there may be more than one) with dates, teams, estimates, completion, and item counts. Use get_workplan_items with a workplan name or GUID to load that plan's AMPs. Use get_user_projects for a project key.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project: {
+                    type: "string",
+                    description: "Project key (preferred) or GUID from get_user_projects",
+                },
+            },
+            required: ["project"],
+        },
+    },
+    {
+        name: "get_workplan_items",
+        description: "List all AMP items in a workplan, assigned to any user, in workplan order. Optional filters: assignee (name, email, or GUID) and progress (Not started, TDD, Developing, Testing, Done, Blocked). Pass workplan name or GUID from get_active_workplans when the project has several active plans; omit workplan to use the newest active one. Use get_user_projects for a project key.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project: {
+                    type: "string",
+                    description: "Project key (preferred) or GUID from get_user_projects",
+                },
+                workplan: {
+                    type: "string",
+                    description: "Optional workplan name or GUID. Omit to use the project's current active workplan.",
+                },
+                assignee: {
+                    type: "string",
+                    description: "Optional team assignee filter (name, email, or user GUID). Omit to include items assigned to any user.",
+                },
+                progress: {
+                    type: "string",
+                    description: "Optional team progress filter: Not started, TDD, Developing, Testing, Done, or Blocked",
+                },
+            },
+            required: ["project"],
+        },
+    },
     {
         name: "get_amp_comments",
         description: "Get comments on an AMP that the authenticated user is allowed to view, ordered newest first. Returns all visible comments by default. Optionally filter to Team, Client, or Director and/or limit the result.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geeks.ltd/geeks-amp-mcp",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "Local MCP server for AMP (OAuth 2.0 PKCE, token storage, proxy to AMP MCPServer.ashx)",
   "type": "module",
   "main": "dist/index.js",