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

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_projects`, `get_amp_item_with_test_cases`, `submit_amp_progress_update`, `add_amp_test_case_references`, `get_auth_status`, `audit_tdd_amp` are forwarded to AMP with `Authorization: Bearer <token>`.
+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>`.
 
 ## Prerequisites
 
@@ -64,8 +64,17 @@ In `.cursor/mcp.json` (project or global), use the **local server** via npx (no
 ## Tools
 
 - **get_auth_status** – Returns `Authenticated: YES` or `Authenticated: NO` (no browser).
-- **get_projects** – List AMP projects (optional `searchTerm`, `limit`).
-- **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).
+- **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.
+- **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`.
+- **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).
+- **submit_pen_test_review** – Record a completed Cursor AI pen test review: required `ampReference` and `scope` (branch, commits, files, or PR reviewed); optional `findings` (one per line, or `"None"`), `falsePositives` (`"N/A"` if none), `knownRisks` (`"N/A"` if none), `summary`. Posts a team comment with `[#PENTEST:COMPLETE#]` and sets review metadata on the work item.
 - **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.
+
+## 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

@@ -8,6 +8,69 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { ensureAccessToken, getAuthStatus } from "./auth.js";
 import { callAmpTool } from "./tools.js";
+const teamProgressValues = [
+    "Not started",
+    "TDD",
+    "Developing",
+    "Testing",
+    "Done",
+    "Blocked",
+];
+const stageValues = ["Test", "Local", "UAT", "Live", "Pre-Live"];
+const createAmpSchema = z.object({
+    project: z
+        .string()
+        .min(1)
+        .describe("Project key (preferred) or GUID from get_user_projects"),
+    subject: z.string().min(1).describe("Work item subject/title"),
+    type: z.string().min(1).describe("Work item type (AMP-defined value)"),
+    priority: z.string().min(1).describe("Priority (AMP-defined value)"),
+    description: z.string().optional().describe("Optional description"),
+    url: z.string().optional().describe("Optional URL"),
+    note: z.string().optional().describe("Optional note"),
+    visualSpecLink: z.string().optional().describe("Optional visual spec link"),
+    linkedWorkItems: z
+        .array(z.string().min(1))
+        .optional()
+        .describe("Optional linked AMP references"),
+    parentAmpReference: z
+        .string()
+        .optional()
+        .describe("Optional parent AMP reference, e.g. '12345' or 'AMP-12345'"),
+});
+const addAmpUpdateSchema = z
+    .object({
+    ampReference: z.string().min(1).describe("e.g. '12345' or 'AMP-12345'"),
+    message: z.string().optional().describe("Team comment text"),
+    teamPercentageDone: z
+        .number()
+        .int()
+        .min(0)
+        .max(100)
+        .refine((n) => n % 10 === 0, "Must be a multiple of 10 (0, 10, …, 100)")
+        .optional()
+        .describe("Team % done (0–100, step 10)"),
+    teamProgress: z
+        .enum(teamProgressValues)
+        .optional()
+        .describe("Team progress: Not started, TDD, Developing, Testing, Done, Blocked"),
+    stage: z
+        .enum(stageValues)
+        .optional()
+        .describe('Workflow stage; posts separate "Done on: {stage}" comment when changed'),
+})
+    .superRefine((val, ctx) => {
+    const hasUpdate = (val.message !== undefined && val.message.trim().length > 0) ||
+        val.teamPercentageDone !== undefined ||
+        val.teamProgress !== undefined ||
+        val.stage !== undefined;
+    if (!hasUpdate) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "Provide at least one of message, teamPercentageDone, teamProgress, or stage.",
+        });
+    }
+});
 const submitAmpProgressUpdateSchema = z
     .object({
     ampReference: z.string().min(1).describe("e.g. '12345' or 'AMP-12345'"),
@@ -51,8 +114,8 @@ async function main() {
             ],
         };
     });
-    // get_projects – ensure token, then call AMP
-    server.tool("get_projects", "Get a list of projects with their ID and Name from AMP.", {
+    // get_projects – legacy global project search (not user-scoped)
+    server.tool("get_projects", "Legacy: global search of non-archived AMP projects (id + name only, not scoped to the current user). Prefer get_user_projects for create_amp flows.", {
         searchTerm: z.string().optional().describe("Optional search term to filter projects by name or ID"),
         limit: z.number().optional().describe("Maximum number of projects to return (default: 100)"),
     }, async ({ searchTerm, limit, }) => {
@@ -64,13 +127,98 @@ async function main() {
             args.limit = limit;
         return callAmpTool("get_projects", args, token);
     });
+    // get_user_projects – projects the authenticated user can use
+    server.tool("get_user_projects", "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.", {}, async () => {
+        const token = await ensureAccessToken();
+        return callAmpTool("get_user_projects", {}, token);
+    });
     // get_amp_item_with_test_cases – ensure token, then call AMP
-    server.tool("get_amp_item_with_test_cases", "Get AMP (work item) details and all its test case references for a given AMP item. Use the reference number (e.g. 12345) or AMP-12345 format. Returns subject, note, status, progress (workflow stage), teamPercentageDone (team board % done, 0–100 in steps of 10), project, and a list of test case references (e.g. +AVFD) with the comment they appear in.", {
+    server.tool("get_amp_item_with_test_cases", "Get AMP (work item) details and all its test case references for a given AMP item. Use the reference number (e.g. 12345) or AMP-12345 format. Returns subject, note, status, progress (workflow stage), teamPercentageDone (team board % done, 0–100 in steps of 10), project, pen test review status (hasPenTestReview, penTestReviewCompleted, penTestReviewCompletedBy, penTestReviewCommentId), and a list of test case references (e.g. +AVFD) with the comment they appear in.", {
         ampReference: z.string().describe("AMP item reference number, e.g. '12345' or 'AMP-12345'"),
     }, async ({ ampReference }) => {
         const token = await ensureAccessToken();
         return callAmpTool("get_amp_item_with_test_cases", { ampReference }, 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
+            .string()
+            .min(1)
+            .describe("Project key (preferred) or GUID from get_user_projects"),
+        subject: z.string().min(1).describe("Work item subject/title"),
+        type: z.string().min(1).describe("Work item type (AMP-defined value)"),
+        priority: z.string().min(1).describe("Priority (AMP-defined value)"),
+        description: z.string().optional().describe("Optional description"),
+        url: z.string().optional().describe("Optional URL"),
+        note: z.string().optional().describe("Optional note"),
+        visualSpecLink: z
+            .string()
+            .optional()
+            .describe("Optional visual spec link"),
+        linkedWorkItems: z
+            .array(z.string().min(1))
+            .optional()
+            .describe("Optional linked AMP references"),
+        parentAmpReference: z
+            .string()
+            .optional()
+            .describe("Optional parent AMP reference, e.g. '12345' or 'AMP-12345'"),
+    }, async (raw) => {
+        const parsed = createAmpSchema.parse(raw);
+        const token = await ensureAccessToken();
+        const args = {
+            project: parsed.project,
+            subject: parsed.subject,
+            type: parsed.type,
+            priority: parsed.priority,
+        };
+        if (parsed.description !== undefined)
+            args.description = parsed.description;
+        if (parsed.url !== undefined)
+            args.url = parsed.url;
+        if (parsed.note !== undefined)
+            args.note = parsed.note;
+        if (parsed.visualSpecLink !== undefined)
+            args.visualSpecLink = parsed.visualSpecLink;
+        if (parsed.linkedWorkItems !== undefined)
+            args.linkedWorkItems = parsed.linkedWorkItems;
+        if (parsed.parentAmpReference !== undefined)
+            args.parentAmpReference = parsed.parentAmpReference;
+        return callAmpTool("create_amp", args, token);
+    });
+    // add_amp_update – team-column update (Form_EnterComment team fields)
+    server.tool("add_amp_update", 'Post a team-column update on an AMP item (mirrors Form_EnterComment team fields except assignees and attachments). At least one of message, teamPercentageDone, teamProgress, or stage required. Changing stage posts a separate "Done on: {stage}" comment.', {
+        ampReference: z.string().min(1).describe("e.g. '12345' or 'AMP-12345'"),
+        message: z.string().optional().describe("Team comment text"),
+        teamPercentageDone: z
+            .number()
+            .int()
+            .min(0)
+            .max(100)
+            .optional()
+            .describe("Team % done (0–100, step 10)"),
+        teamProgress: z
+            .enum(teamProgressValues)
+            .optional()
+            .describe("Team progress: Not started, TDD, Developing, Testing, Done, Blocked"),
+        stage: z
+            .enum(stageValues)
+            .optional()
+            .describe('Workflow stage; posts separate "Done on: {stage}" comment when changed'),
+    }, async (raw) => {
+        const parsed = addAmpUpdateSchema.parse(raw);
+        const token = await ensureAccessToken();
+        const args = { ampReference: parsed.ampReference };
+        if (parsed.message !== undefined && parsed.message.trim() !== "")
+            args.message = parsed.message.trim();
+        if (parsed.teamPercentageDone !== undefined)
+            args.teamPercentageDone = parsed.teamPercentageDone;
+        if (parsed.teamProgress !== undefined)
+            args.teamProgress = parsed.teamProgress;
+        if (parsed.stage !== undefined)
+            args.stage = parsed.stage;
+        return callAmpTool("add_amp_update", args, token);
+    });
     // submit_amp_progress_update – team board % done and/or team comment (AMP MCPServer parity)
     server.tool("submit_amp_progress_update", "Update the AMP team board: set team % done (0, 10, …, 100) and/or append a team-column comment. Not the same as workflow progress. At least one of teamPercentageDone or a non-empty message is required.", {
         ampReference: z.string().min(1).describe("e.g. '12345' or 'AMP-12345'"),
@@ -113,6 +261,31 @@ async function main() {
             args.message = message.trim();
         return callAmpTool("add_amp_test_case_references", args, token);
     });
+    // submit_pen_test_review – record completed Cursor AI pen test review on AMP
+    server.tool("submit_pen_test_review", "Record a completed Cursor AI pen test review on an AMP work item. Posts a structured team comment and sets review metadata. Use after run-pen-test and human confirmation.", {
+        ampReference: z
+            .string()
+            .describe("AMP reference, e.g. '12345' or 'AMP-12345'"),
+        scope: z
+            .string()
+            .describe("Branch, commits, files, or PR reviewed"),
+        findings: z
+            .string()
+            .optional()
+            .describe("Findings, one per line; 'None' if none"),
+        falsePositives: z
+            .string()
+            .optional()
+            .describe("False positives explained; 'N/A' if none"),
+        knownRisks: z
+            .string()
+            .optional()
+            .describe("Accepted known risks; 'N/A' if none"),
+        summary: z.string().optional().describe("Short overall outcome"),
+    }, async (args) => {
+        const token = await ensureAccessToken();
+        return callAmpTool("submit_pen_test_review", args, token);
+    });
     // Optional: audit-tdd-amp – get AMP item + test cases and report auth status (for /audit-tdd-amp in Cursor)
     server.tool("audit_tdd_amp", "Get AMP item and its test case references, and report auth status. Use for /audit-tdd-amp flows in Cursor.", {
         ampReference: z.string().describe("AMP item reference number, e.g. '12345' or 'AMP-12345'"),
@@ -132,6 +305,27 @@ async function main() {
             ],
         };
     });
+    // Optional: audit-pen-test-amp – get AMP item + pen test review status and report auth (for /run-pen-test in Cursor)
+    server.tool("audit_pen_test_amp", "Get AMP item, pen test review status, and test case references, plus auth status. Use for /run-pen-test flows in Cursor.", {
+        ampReference: z
+            .string()
+            .describe("AMP item reference number, e.g. '12345' or 'AMP-12345'"),
+    }, async ({ ampReference }) => {
+        const token = await ensureAccessToken();
+        const result = await callAmpTool("get_amp_item_with_test_cases", { ampReference }, token);
+        const status = getAuthStatus();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        message: status.message,
+                        ampItemAndPenTestReview: result.content[0]?.text,
+                    }),
+                },
+            ],
+        };
+    });
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/dist/tools.js

@@ -6,7 +6,7 @@ import { getAmpBaseUrl } from "./auth.js";
 export const TOOL_DEFINITIONS = [
     {
         name: "get_projects",
-        description: "Get a list of projects with their ID and Name from AMP.",
+        description: "Legacy: global search of non-archived AMP projects (id + name only, not scoped to the current user). Prefer get_user_projects for create_amp flows.",
         inputSchema: {
             type: "object",
             properties: {
@@ -23,7 +23,7 @@ export const TOOL_DEFINITIONS = [
     },
     {
         name: "get_amp_item_with_test_cases",
-        description: "Get AMP (work item) details and all its test case references for a given AMP item. Use the reference number (e.g. 12345) or AMP-12345 format. Returns subject, note, status, progress (workflow stage), teamPercentageDone (team board % done), project, and a list of test case references (e.g. +AVFD) with the comment they appear in.",
+        description: "Get AMP (work item) details and all its test case references for a given AMP item. Use the reference number (e.g. 12345) or AMP-12345 format. Returns subject, note, status, progress (workflow stage), teamPercentageDone (team board % done), project, pen test review status (hasPenTestReview, penTestReviewCompleted, penTestReviewCompletedBy, penTestReviewCommentId), and a list of test case references (e.g. +AVFD) with the comment they appear in.",
         inputSchema: {
             type: "object",
             properties: {
@@ -35,6 +35,95 @@ export const TOOL_DEFINITIONS = [
             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.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    {
+        name: "create_amp",
+        description: "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.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project: {
+                    type: "string",
+                    description: "Project key (preferred) or GUID from get_user_projects",
+                },
+                subject: {
+                    type: "string",
+                    description: "Work item subject/title",
+                },
+                type: {
+                    type: "string",
+                    description: "Work item type (AMP-defined value)",
+                },
+                priority: {
+                    type: "string",
+                    description: "Priority (AMP-defined value)",
+                },
+                description: {
+                    type: "string",
+                    description: "Optional description",
+                },
+                url: {
+                    type: "string",
+                    description: "Optional URL",
+                },
+                note: {
+                    type: "string",
+                    description: "Optional note",
+                },
+                visualSpecLink: {
+                    type: "string",
+                    description: "Optional visual spec link",
+                },
+                linkedWorkItems: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional linked AMP references",
+                },
+                parentAmpReference: {
+                    type: "string",
+                    description: "Optional parent AMP reference, e.g. '12345' or 'AMP-12345'",
+                },
+            },
+            required: ["project", "subject", "type", "priority"],
+        },
+    },
+    {
+        name: "add_amp_update",
+        description: "Post a team-column update on an AMP item (mirrors Form_EnterComment team fields except assignees and attachments). At least one of message, teamPercentageDone, teamProgress, or stage required. Changing stage posts a separate \"Done on: {stage}\" comment.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ampReference: {
+                    type: "string",
+                    description: "e.g. '12345' or 'AMP-12345'",
+                },
+                message: {
+                    type: "string",
+                    description: "Team comment text",
+                },
+                teamPercentageDone: {
+                    type: "number",
+                    description: "Team % done; integer 0–100, multiple of 10",
+                },
+                teamProgress: {
+                    type: "string",
+                    description: "Team progress: Not started, TDD, Developing, Testing, Done, or Blocked",
+                },
+                stage: {
+                    type: "string",
+                    description: "Workflow stage: Test, Local, UAT, Live, or Pre-Live",
+                },
+            },
+            required: ["ampReference"],
+        },
+    },
     {
         name: "submit_amp_progress_update",
         description: "Set team board % done (0–100, multiple of 10) and/or append a team-column comment. At least one of teamPercentageDone or non-empty message required. If only teamPercentageDone is sent, AMP sets comment text to \"{n}% completed\".",
@@ -80,6 +169,40 @@ export const TOOL_DEFINITIONS = [
             required: ["ampReference", "testCaseReferences"],
         },
     },
+    {
+        name: "submit_pen_test_review",
+        description: "Record a completed Cursor AI pen test review on an AMP work item. Posts a structured team comment and sets review metadata. Use after run-pen-test and human confirmation.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ampReference: {
+                    type: "string",
+                    description: "AMP reference, e.g. '12345' or 'AMP-12345'",
+                },
+                scope: {
+                    type: "string",
+                    description: "Branch, commits, files, or PR reviewed",
+                },
+                findings: {
+                    type: "string",
+                    description: "Findings, one per line; 'None' if none",
+                },
+                falsePositives: {
+                    type: "string",
+                    description: "False positives explained; 'N/A' if none",
+                },
+                knownRisks: {
+                    type: "string",
+                    description: "Accepted known risks; 'N/A' if none",
+                },
+                summary: {
+                    type: "string",
+                    description: "Short overall outcome",
+                },
+            },
+            required: ["ampReference", "scope"],
+        },
+    },
     {
         name: "get_auth_status",
         description: "Report whether the MCP server is authenticated to AMP. Returns 'Authenticated: YES' or 'Authenticated: NO' without opening the browser.",

package/package.json

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