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

package/README.md

@@ -6,7 +6,7 @@ Local MCP server for Cursor that authenticates to your AMP backend via OAuth 2.0
 
 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`, `create_amp`, `get_amp_item_with_test_cases`, `add_amp_update`, `submit_amp_progress_update`, `add_amp_test_case_references`, `submit_pen_test_review`, `get_auth_status`, `audit_tdd_amp`, `audit_pen_test_amp` are forwarded to AMP with `Authorization: Bearer <token>`.
+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.
 
 ## Prerequisites
 
@@ -66,8 +66,10 @@ In `.cursor/mcp.json` (project or global), use the **local server** via npx (no
 - **get_auth_status** – Returns `Authenticated: YES` or `Authenticated: NO` (no browser).
 - **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_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** – AMP item + test case refs by `ampReference` (e.g. `12345` or `AMP-12345`). Response JSON includes `ampItem.teamPercentageDone` (team board % done) alongside `progress` (workflow stage), and pen test review fields: `hasPenTestReview`, `penTestReviewCompleted`, `penTestReviewCompletedBy`, `penTestReviewCommentId`.
+- **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.
 - **add_amp_update** – Team-column update (mirrors Form_EnterComment team fields except assignees/attachments). Required: `ampReference` plus at least one of `message`, `teamPercentageDone` (0–100, step 10), `teamProgress` (Not started, TDD, Developing, Testing, Done, Blocked), or `stage` (Test, Local, UAT, Live, Pre-Live). Stage changes post a separate `"Done on: {stage}"` comment.
 - **submit_amp_progress_update** – Team board: optional `teamPercentageDone` (0, 10, …, 100) and/or `message`; at least one required. Omits `message` when only updating % so AMP can default the comment to `"{n}% completed"`.
 - **add_amp_test_case_references** – `ampReference`, required `testCaseReferences` (array of strings), optional `message` after refs; same as AMP “Update test cases” (`[#+REF#]` markers).
@@ -75,6 +77,8 @@ In `.cursor/mcp.json` (project or global), use the **local server** via npx (no
 - **audit_tdd_amp** – Same as above plus auth status message for `/audit-tdd-amp` flows.
 - **audit_pen_test_amp** – AMP item + pen test review status + test cases, plus auth status message for `/run-pen-test` flows.
 
+For general agent workflows, call `get_amp_item` to understand the work item, then `get_amp_comments` for acceptance details, blockers, and conversation history before using write tools such as `add_amp_update`.
+
 ## Cursor command: `/run-pen-test`
 
 Copy `.cursor/commands/run-pen-test.md` into your project (or use it from a repo that includes it). The command loads AMP context via MCP, runs a security review, and after human confirmation calls `submit_pen_test_review` to persist the outcome on AMP.

package/dist/index.js

@@ -139,6 +139,42 @@ async function main() {
         const token = await ensureAccessToken();
         return callAmpTool("get_amp_item_with_test_cases", { ampReference }, token);
     });
+    // get_amp_item – rich authorized work-item details without comment history
+    server.tool("get_amp_item", "Get rich details for an AMP work item, including project, type, priority, status, progress, stage, assignees, workplans, tags, links, extension relationships (extendedFrom / extensions), URLs, completion, and test case references. Use get_amp_comments separately for its conversation history.", {
+        ampReference: z
+            .string()
+            .min(1)
+            .describe("AMP item reference number, e.g. '12345' or 'AMP-12345'"),
+    }, async ({ ampReference }) => {
+        const token = await ensureAccessToken();
+        return callAmpTool("get_amp_item", { ampReference }, 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
+            .string()
+            .min(1)
+            .describe("AMP item reference number, e.g. '12345' or 'AMP-12345'"),
+        column: z
+            .string()
+            .optional()
+            .describe("Optional comment column: 'Team', 'Client', 'Director', or 'all'. Defaults to all columns visible to the user."),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(500)
+            .optional()
+            .describe("Optional maximum number of newest comments to return (1-500). Omit to return all visible comments."),
+    }, async ({ ampReference, column, limit, }) => {
+        const token = await ensureAccessToken();
+        const args = { ampReference };
+        if (column !== undefined)
+            args.column = column;
+        if (limit !== undefined)
+            args.limit = limit;
+        return callAmpTool("get_amp_comments", args, token);
+    });
     // create_amp – new work item (status New)
     server.tool("create_amp", "Create a new AMP work item with status New. Required project is a project key (preferred) or GUID from get_user_projects. User must belong to the project. Extension items add Team + Client column comments automatically.", {
         project: z

package/dist/tools.js

@@ -35,6 +35,42 @@ export const TOOL_DEFINITIONS = [
             required: ["ampReference"],
         },
     },
+    {
+        name: "get_amp_item",
+        description: "Get rich details for an AMP work item, including project, type, priority, status, progress, stage, assignees, workplans, tags, links, extension relationships (extendedFrom / extensions), URLs, completion, and test case references. Use get_amp_comments separately for its conversation history.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ampReference: {
+                    type: "string",
+                    description: "AMP item reference number, e.g. '12345' or 'AMP-12345'",
+                },
+            },
+            required: ["ampReference"],
+        },
+    },
+    {
+        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.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ampReference: {
+                    type: "string",
+                    description: "AMP item reference number, e.g. '12345' or 'AMP-12345'",
+                },
+                column: {
+                    type: "string",
+                    description: "Optional comment column: 'Team', 'Client', 'Director', or 'all'. Defaults to all columns visible to the user.",
+                },
+                limit: {
+                    type: "number",
+                    description: "Optional maximum number of newest comments to return (1-500). Omit to return all visible comments.",
+                },
+            },
+            required: ["ampReference"],
+        },
+    },
     {
         name: "get_user_projects",
         description: "List non-archived projects the authenticated user belongs to (id, key, name), ordered by key. Use before create_amp to pick a valid project key or GUID.",

package/package.json

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