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

package/README.md

@@ -8,7 +8,7 @@ Local MCP server for Cursor and Claude that authenticates to your AMP backend vi
 
 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_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.
+3. **Tools** – `get_user_projects`, `list_project_tags`, `create_project_tag`, `update_project_tag`, `delete_project_tag`, `get_amp_item_tags`, `add_amp_item_tags`, `remove_amp_item_tags`, `get_projects`, `get_amp_item`, `get_workplans`, `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
 
@@ -66,15 +66,20 @@ 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_user_projects** – Non-archived projects the authenticated user belongs to: `{ projects: [{ id, key, name }] }`, ordered by key. Use this before `create_amp`.
+- **get_user_projects** – Non-archived projects the authenticated user belongs to: `{ projects: [{ id, key, name }] }`, ordered by key. Use this before `create_amp` or `list_project_tags`.
+- **list_project_tags** – List or search project tags (`project`, optional `search`, optional `includeArchived`). Returns tag id, name, description, visibility, and archived state.
+- **create_project_tag** / **update_project_tag** / **delete_project_tag** – Manage project tags (project manager only). Delete is blocked when a tag is still on work items; archive instead.
+- **get_amp_item_tags** – Read an item's current tags without changing it.
+- **add_amp_item_tags** / **remove_amp_item_tags** – Add or remove specific tags while leaving other tags unchanged (project manager only).
 - **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_workplans** – All workplans in a project (active and inactive), including Backlog. Required: `project` (key or GUID). Returns name, dates, teams, and `isActive`. Use `get_workplan_items` with a workplan name or GUID to load that plan's AMPs.
 - **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_workplan_items** – All items in a workplan, assigned to any user. Required: `project`. Optional: `workplan` (name or GUID from `get_workplans` / `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.
+- **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`, `tags` (project manager only). 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.
-- **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.
+- **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), `stage` (Test, Local, UAT, Live, Pre-Live), or `tags`. Optional `tags` replaces the complete tag set (project manager only); omit `tags` to keep current tags, `[]` clears all. Use `add_amp_item_tags` / `remove_amp_item_tags` to change some tags without replacing the rest. 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.

package/dist/ampToolArgs.d.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+/** Copy tags onto a tool payload only when the caller set the field. Undefined must not clear tags. */
+export declare function includeTags(args: Record<string, unknown>, tags: string[] | undefined): Record<string, unknown>;
+/** Copy assignees onto a tool payload only when the caller set the field. Undefined must not clear assignees. */
+export declare function includeAssignees(args: Record<string, unknown>, assignees: string[] | undefined): Record<string, unknown>;
+export declare function hasAddAmpUpdatePayload(input: {
+    message?: string;
+    teamPercentageDone?: number;
+    teamProgress?: string;
+    stage?: string;
+    tags?: string[];
+    assignees?: string[];
+}): boolean;
+export declare const projectKeySchema: z.ZodString;
+export declare const ampReferenceSchema: z.ZodString;
+export declare const tagNameSchema: z.ZodString;
+export declare const listProjectTagsSchema: {
+    project: z.ZodString;
+    search: z.ZodOptional<z.ZodString>;
+    includeArchived: z.ZodOptional<z.ZodBoolean>;
+};
+export declare const itemTagChangeSchema: {
+    ampReference: z.ZodString;
+    tags: z.ZodArray<z.ZodString, "many">;
+};
+export declare const optionalTagsSchema: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+export declare const assigneeNameSchema: z.ZodString;
+export declare const optionalAssigneesSchema: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+export declare const listAssignableUsersSchema: {
+    project: z.ZodString;
+    column: z.ZodOptional<z.ZodString>;
+};

package/dist/ampToolArgs.js

@@ -0,0 +1,71 @@
+import { z } from "zod";
+/** Copy tags onto a tool payload only when the caller set the field. Undefined must not clear tags. */
+export function includeTags(args, tags) {
+    if (tags !== undefined)
+        args.tags = tags;
+    return args;
+}
+/** Copy assignees onto a tool payload only when the caller set the field. Undefined must not clear assignees. */
+export function includeAssignees(args, assignees) {
+    if (assignees !== undefined)
+        args.assignees = assignees;
+    return args;
+}
+export function hasAddAmpUpdatePayload(input) {
+    const hasMessage = input.message !== undefined && input.message.trim().length > 0;
+    return (hasMessage ||
+        input.teamPercentageDone !== undefined ||
+        input.teamProgress !== undefined ||
+        input.stage !== undefined ||
+        input.tags !== undefined ||
+        input.assignees !== undefined);
+}
+export const projectKeySchema = z
+    .string()
+    .min(1)
+    .describe("Project key (preferred) or GUID from get_user_projects");
+export const ampReferenceSchema = z
+    .string()
+    .min(1)
+    .describe("AMP reference, e.g. '12345' or 'AMP-12345'");
+export const tagNameSchema = z
+    .string()
+    .min(1)
+    .describe("Project tag GUID or name from list_project_tags");
+export const listProjectTagsSchema = {
+    project: projectKeySchema,
+    search: z
+        .string()
+        .optional()
+        .describe("Optional text matched against tag name or description"),
+    includeArchived: z
+        .boolean()
+        .optional()
+        .describe("Include archived tags (default false)"),
+};
+export const itemTagChangeSchema = {
+    ampReference: ampReferenceSchema,
+    tags: z
+        .array(tagNameSchema)
+        .min(1)
+        .describe("One or more project tags. Unlisted tags on the item are left unchanged."),
+};
+export const optionalTagsSchema = z
+    .array(tagNameSchema)
+    .optional()
+    .describe("Project tags (GUID or name from list_project_tags). Omit to leave tags unchanged.");
+export const assigneeNameSchema = z
+    .string()
+    .min(1)
+    .describe("Team assignee name, email, or user GUID from list_assignable_users");
+export const optionalAssigneesSchema = z
+    .array(assigneeNameSchema)
+    .optional()
+    .describe("Team assignees. Omit to leave assignees unchanged; [] unassigns.");
+export const listAssignableUsersSchema = {
+    project: projectKeySchema,
+    column: z
+        .string()
+        .optional()
+        .describe("Team (default) or Director. Client column does not use this assignee list."),
+};

package/dist/ampToolArgs.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ampToolArgs.test.js

@@ -0,0 +1,58 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { z } from "zod";
+import { hasAddAmpUpdatePayload, includeAssignees, includeTags, itemTagChangeSchema, listAssignableUsersSchema, listProjectTagsSchema, } from "./ampToolArgs.js";
+describe("includeTags", () => {
+    it("omits tags when the caller did not set them", () => {
+        const args = includeTags({ project: "GTech", subject: "Fix" }, undefined);
+        assert.equal("tags" in args, false);
+    });
+    it("sends an empty list when the caller clears tags", () => {
+        const args = includeTags({ ampReference: "181526" }, []);
+        assert.deepEqual(args.tags, []);
+    });
+    it("sends the supplied tag names", () => {
+        const args = includeTags({}, ["Bug", "UI"]);
+        assert.deepEqual(args.tags, ["Bug", "UI"]);
+    });
+});
+describe("includeAssignees", () => {
+    it("omits assignees when the caller did not set them", () => {
+        const args = includeAssignees({ ampReference: "181526" }, undefined);
+        assert.equal("assignees" in args, false);
+    });
+    it("sends an empty list when the caller unassigns everyone", () => {
+        const args = includeAssignees({ ampReference: "181526" }, []);
+        assert.deepEqual(args.assignees, []);
+    });
+});
+describe("hasAddAmpUpdatePayload", () => {
+    it("accepts a tags-only replace and rejects a completely empty update", () => {
+        assert.equal(hasAddAmpUpdatePayload({ tags: ["Bug"] }), true);
+        assert.equal(hasAddAmpUpdatePayload({ tags: [] }), true);
+        assert.equal(hasAddAmpUpdatePayload({ assignees: ["jane@example.com"] }), true);
+        assert.equal(hasAddAmpUpdatePayload({ assignees: [] }), true);
+        assert.equal(hasAddAmpUpdatePayload({ message: "   " }), false);
+        assert.equal(hasAddAmpUpdatePayload({}), false);
+    });
+});
+describe("tag tool schemas", () => {
+    it("requires a project for list and at least one tag to add or remove", () => {
+        const list = z.object(listProjectTagsSchema);
+        assert.equal(list.safeParse({}).success, false);
+        assert.equal(list.safeParse({ project: "GTech", search: "bug" }).success, true);
+        const change = z.object(itemTagChangeSchema);
+        assert.equal(change.safeParse({ ampReference: "AMP-181526", tags: ["Bug"] }).success, true);
+        assert.equal(change.safeParse({ ampReference: "181526", tags: [] }).success, false);
+        assert.equal(change.safeParse({ ampReference: "", tags: ["Bug"] }).success, false);
+        assert.equal(change.safeParse({ ampReference: "nope" }).success, false);
+    });
+});
+describe("listAssignableUsersSchema", () => {
+    it("requires a project and accepts an optional column", () => {
+        const schema = z.object(listAssignableUsersSchema);
+        assert.equal(schema.safeParse({}).success, false);
+        assert.equal(schema.safeParse({ project: "GTech" }).success, true);
+        assert.equal(schema.safeParse({ project: "GTech", column: "Director" }).success, true);
+    });
+});

package/dist/index.js

@@ -6,6 +6,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
+import { hasAddAmpUpdatePayload, includeAssignees, includeTags, itemTagChangeSchema, listAssignableUsersSchema, listProjectTagsSchema, optionalAssigneesSchema, optionalTagsSchema, } from "./ampToolArgs.js";
 import { ensureAccessToken, getAuthStatus } from "./auth.js";
 import { callAmpTool } from "./tools.js";
 const teamProgressValues = [
@@ -37,11 +38,18 @@ const createAmpSchema = z.object({
         .string()
         .optional()
         .describe("Optional parent AMP reference, e.g. '12345' or 'AMP-12345'"),
+    tags: optionalTagsSchema,
+    assignees: optionalAssigneesSchema.describe("Optional team assignees. Posts a Team comment so the item shows as assigned."),
 });
+const teamProgressFieldDescription = "Team workflow stage. ONLY set when the user explicitly asked to move team progress — omit for comment-only updates. Advance one step: Not started → TDD → Developing → Testing → Done (never skip; from Developing use Testing, not Done).";
+const addAmpUpdateToolDescription = 'Post a team-column update on an AMP item, matching the AMP UI team comment form. Default to message-only comments. Do NOT set teamProgress, teamPercentageDone, or stage unless the user explicitly asked to move the board — reporting finished work or posting an update is not the same as advancing progress. When teamProgress is requested, advance one step only along Not started → TDD → Developing → Testing → Done (never skip steps; from Developing go to Testing, not Done). Changing stage posts a separate "Done on: {stage}" comment.';
 const addAmpUpdateSchema = z
     .object({
     ampReference: z.string().min(1).describe("e.g. '12345' or 'AMP-12345'"),
-    message: z.string().optional().describe("Team comment text"),
+    message: z
+        .string()
+        .optional()
+        .describe("Team comment text. Safe default when the user only asked for a comment or progress note."),
     teamPercentageDone: z
         .number()
         .int()
@@ -49,25 +57,23 @@ const addAmpUpdateSchema = z
         .max(100)
         .refine((n) => n % 10 === 0, "Must be a multiple of 10 (0, 10, …, 100)")
         .optional()
-        .describe("Team % done (0–100, step 10)"),
+        .describe("Team board % done (0–100, step 10). ONLY set when the user explicitly asked to change % done — omit for comment-only updates."),
     teamProgress: z
         .enum(teamProgressValues)
         .optional()
-        .describe("Team progress: Not started, TDD, Developing, Testing, Done, Blocked"),
+        .describe(teamProgressFieldDescription),
     stage: z
         .enum(stageValues)
         .optional()
-        .describe('Workflow stage; posts separate "Done on: {stage}" comment when changed'),
+        .describe('Deployment stage. ONLY set when the user explicitly asked to record a stage change — omit for comment-only updates. Posts separate "Done on: {stage}" comment when changed.'),
+    tags: optionalTagsSchema.describe("Replace the complete tag set (project manager only). Omit to keep current tags; [] clears all. Use add_amp_item_tags or remove_amp_item_tags to change some tags without replacing the rest."),
+    assignees: optionalAssigneesSchema.describe("Replace team assignees. Omit to keep current assignees; [] unassigns. Defaults message to 'Assigning' if nothing else is posted."),
 })
     .superRefine((val, ctx) => {
-    const hasUpdate = (val.message !== undefined && val.message.trim().length > 0) ||
-        val.teamPercentageDone !== undefined ||
-        val.teamProgress !== undefined ||
-        val.stage !== undefined;
-    if (!hasUpdate) {
+    if (!hasAddAmpUpdatePayload(val)) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
-            message: "Provide at least one of message, teamPercentageDone, teamProgress, or stage.",
+            message: "Provide at least one of message, teamPercentageDone, teamProgress, stage, tags, or assignees.",
         });
     }
 });
@@ -128,10 +134,88 @@ async function main() {
         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 () => {
+    server.tool("get_user_projects", "List non-archived projects the authenticated user belongs to (id, key, name), ordered by key. Use before create_amp or list_project_tags to pick a valid project key or GUID.", {}, async () => {
         const token = await ensureAccessToken();
         return callAmpTool("get_user_projects", {}, token);
     });
+    server.tool("list_assignable_users", "List people who can be assigned on a project's Team (or Director) column. Use before create_amp or add_amp_update when setting assignees.", listAssignableUsersSchema, async (args) => {
+        const token = await ensureAccessToken();
+        const payload = { project: args.project };
+        if (args.column !== undefined && args.column.trim() !== "")
+            payload.column = args.column.trim();
+        return callAmpTool("list_assignable_users", payload, token);
+    });
+    server.tool("list_project_tags", "List or search tags defined on an AMP project (id, name, description, visibility, archived state). Any project member can list tags; creating or changing tags requires a project manager.", listProjectTagsSchema, async (args) => {
+        const token = await ensureAccessToken();
+        const payload = { project: args.project };
+        if (args.search !== undefined && args.search.trim() !== "")
+            payload.search = args.search.trim();
+        if (args.includeArchived !== undefined)
+            payload.includeArchived = args.includeArchived;
+        return callAmpTool("list_project_tags", payload, token);
+    });
+    server.tool("create_project_tag", "Create a new tag on an AMP project. Requires project manager. Returns tag id and name.", {
+        project: listProjectTagsSchema.project,
+        value: z.string().min(1).describe("Tag label (unique within the project)"),
+        description: z
+            .string()
+            .optional()
+            .describe("Optional tooltip description"),
+        isVisibleToClient: z
+            .boolean()
+            .optional()
+            .describe("Whether clients can see this tag (default false)"),
+        color: z.string().optional().describe("Optional CSS colour"),
+    }, async (args) => {
+        const token = await ensureAccessToken();
+        return callAmpTool("create_project_tag", args, token);
+    });
+    server.tool("update_project_tag", "Update a project tag's name, description, client visibility, colour, or archived state. Requires project manager. Identify the tag by GUID or name within the project.", {
+        project: listProjectTagsSchema.project,
+        tag: z
+            .string()
+            .min(1)
+            .describe("Tag GUID or name from list_project_tags"),
+        value: z.string().optional().describe("New tag label"),
+        description: z
+            .string()
+            .optional()
+            .describe("New description (empty string clears)"),
+        isVisibleToClient: z
+            .boolean()
+            .optional()
+            .describe("Whether clients can see this tag"),
+        isArchived: z
+            .boolean()
+            .optional()
+            .describe("Archive (true) or restore (false) the tag"),
+        color: z.string().optional().describe("CSS colour for the tag"),
+    }, async (args) => {
+        const token = await ensureAccessToken();
+        return callAmpTool("update_project_tag", args, token);
+    });
+    server.tool("delete_project_tag", "Delete a project tag that is not assigned to any work items. Requires project manager. Use update_project_tag with isArchived=true to retire tags still in use.", {
+        project: listProjectTagsSchema.project,
+        tag: z
+            .string()
+            .min(1)
+            .describe("Tag GUID or name from list_project_tags"),
+    }, async (args) => {
+        const token = await ensureAccessToken();
+        return callAmpTool("delete_project_tag", args, token);
+    });
+    server.tool("get_amp_item_tags", "Get the tags on an AMP item (id and name) that the authenticated user can see. Does not change the item.", { ampReference: itemTagChangeSchema.ampReference }, async ({ ampReference }) => {
+        const token = await ensureAccessToken();
+        return callAmpTool("get_amp_item_tags", { ampReference }, token);
+    });
+    server.tool("add_amp_item_tags", "Add existing project tags to an AMP item. Other tags and item fields stay unchanged. Already-assigned tags are left as-is. Requires project manager.", itemTagChangeSchema, async (args) => {
+        const token = await ensureAccessToken();
+        return callAmpTool("add_amp_item_tags", args, token);
+    });
+    server.tool("remove_amp_item_tags", "Remove selected project tags from an AMP item. Tags not listed, and other item fields, stay unchanged. Tags that are not assigned are left as-is. Requires project manager.", itemTagChangeSchema, async (args) => {
+        const token = await ensureAccessToken();
+        return callAmpTool("remove_amp_item_tags", args, 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, 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'"),
@@ -149,6 +233,51 @@ async function main() {
         const token = await ensureAccessToken();
         return callAmpTool("get_amp_item", { ampReference }, token);
     });
+    server.tool("get_my_amp_items", "List open AMP work items assigned to the authenticated user across their projects, in the same order as the AMP home 'My Assigned AMPs' list. Use when the user asks to list their AMPs or see what is assigned to them. Optional project filter and keyword search. Paginated.", {
+        project: z
+            .string()
+            .optional()
+            .describe("Optional project key (preferred) or GUID from get_user_projects. Omit for all assigned projects."),
+        keyword: z
+            .string()
+            .optional()
+            .describe("Optional search text or AMP reference (e.g. 12345 or #12345)"),
+        skip: z
+            .number()
+            .int()
+            .min(0)
+            .optional()
+            .describe("Rows to skip (default 0)"),
+        take: z
+            .number()
+            .int()
+            .min(1)
+            .max(200)
+            .optional()
+            .describe("Page size (default 50, max 200)"),
+    }, async (args) => {
+        const token = await ensureAccessToken();
+        const payload = {};
+        if (args.project !== undefined && args.project.trim() !== "")
+            payload.project = args.project.trim();
+        if (args.keyword !== undefined && args.keyword.trim() !== "")
+            payload.keyword = args.keyword.trim();
+        if (args.skip !== undefined)
+            payload.skip = args.skip;
+        if (args.take !== undefined)
+            payload.take = args.take;
+        return callAmpTool("get_my_amp_items", payload, token);
+    });
+    // get_workplans – list all workplans in a project (active and inactive)
+    server.tool("get_workplans", "List all workplans in a project (active and inactive) with name, dates, teams, and active flag. Use get_workplan_items with a workplan name or GUID to load that plan's AMPs. Prefer get_active_workplans when you only need current active plans. 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_workplans", { project }, 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
@@ -160,7 +289,7 @@ async function main() {
         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.", {
+    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_workplans or get_active_workplans; omit workplan to use the newest active one. Use get_user_projects for a project key.", {
         project: z
             .string()
             .min(1)
@@ -215,7 +344,7 @@ async function main() {
         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.", {
+    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. Optional tags (project manager only). Optional assignees assigns the item to those team members (use list_assignable_users). Extension items add Team + Client column comments automatically.", {
         project: z
             .string()
             .min(1)
@@ -238,6 +367,7 @@ async function main() {
             .string()
             .optional()
             .describe("Optional parent AMP reference, e.g. '12345' or 'AMP-12345'"),
+        assignees: optionalAssigneesSchema.describe("Optional team assignees. Posts a Team comment so the item shows as assigned."),
     }, async (raw) => {
         const parsed = createAmpSchema.parse(raw);
         const token = await ensureAccessToken();
@@ -259,31 +389,41 @@ async function main() {
             args.linkedWorkItems = parsed.linkedWorkItems;
         if (parsed.parentAmpReference !== undefined)
             args.parentAmpReference = parsed.parentAmpReference;
+        if (parsed.tags !== undefined)
+            args.tags = parsed.tags;
+        if (parsed.assignees !== undefined)
+            args.assignees = parsed.assignees;
         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.', {
+    server.tool("add_amp_update", addAmpUpdateToolDescription, {
         ampReference: z.string().min(1).describe("e.g. '12345' or 'AMP-12345'"),
-        message: z.string().optional().describe("Team comment text"),
+        message: z
+            .string()
+            .optional()
+            .describe("Team comment text. Safe default when the user only asked for a comment or progress note."),
         teamPercentageDone: z
             .number()
             .int()
             .min(0)
             .max(100)
             .optional()
-            .describe("Team % done (0–100, step 10)"),
+            .describe("Team board % done (0–100, step 10). ONLY set when the user explicitly asked to change % done — omit for comment-only updates."),
         teamProgress: z
             .enum(teamProgressValues)
             .optional()
-            .describe("Team progress: Not started, TDD, Developing, Testing, Done, Blocked"),
+            .describe(teamProgressFieldDescription),
         stage: z
             .enum(stageValues)
             .optional()
-            .describe('Workflow stage; posts separate "Done on: {stage}" comment when changed'),
+            .describe('Deployment stage. ONLY set when the user explicitly asked to record a stage change — omit for comment-only updates. Posts separate "Done on: {stage}" comment when changed.'),
+        tags: optionalTagsSchema.describe("Replace the complete tag set (project manager only). Omit to keep current tags; [] clears all."),
+        assignees: optionalAssigneesSchema.describe("Replace team assignees. Omit to keep current assignees; [] unassigns. Defaults message to 'Assigning' if nothing else is posted."),
     }, async (raw) => {
         const parsed = addAmpUpdateSchema.parse(raw);
         const token = await ensureAccessToken();
-        const args = { ampReference: parsed.ampReference };
+        let args = includeTags({ ampReference: parsed.ampReference }, parsed.tags);
+        args = includeAssignees(args, parsed.assignees);
         if (parsed.message !== undefined && parsed.message.trim() !== "")
             args.message = parsed.message.trim();
         if (parsed.teamPercentageDone !== undefined)
@@ -295,7 +435,7 @@ async function main() {
         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.", {
+    server.tool("submit_amp_progress_update", "Update the AMP team board % done (0, 10, …, 100) and/or append a team-column comment. Does NOT change teamProgress (workflow stage). Do NOT set teamPercentageDone unless the user explicitly asked — omit for comment-only updates. At least one of teamPercentageDone or a non-empty message is required.", {
         ampReference: z.string().min(1).describe("e.g. '12345' or 'AMP-12345'"),
         teamPercentageDone: z
             .number()
@@ -303,7 +443,7 @@ async function main() {
             .min(0)
             .max(100)
             .optional()
-            .describe("Team % done (multiple of 10); omit if only posting a comment"),
+            .describe("Team board % done (multiple of 10). ONLY set when the user explicitly asked — omit for comment-only updates."),
         message: z.string().optional().describe("Team comment text"),
     }, async (raw) => {
         const parsed = submitAmpProgressUpdateSchema.parse(raw);

package/dist/tools.js

@@ -49,6 +49,45 @@ export const TOOL_DEFINITIONS = [
             required: ["ampReference"],
         },
     },
+    {
+        name: "get_my_amp_items",
+        description: "List open AMP work items assigned to the authenticated user across their projects, in the same order as the AMP home 'My Assigned AMPs' list. Use when the user asks to list their AMPs or see what is assigned to them. Optional project filter and keyword search. Paginated.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project: {
+                    type: "string",
+                    description: "Optional project key (preferred) or GUID from get_user_projects. Omit for all assigned projects.",
+                },
+                keyword: {
+                    type: "string",
+                    description: "Optional search text or AMP reference (e.g. 12345 or #12345)",
+                },
+                skip: {
+                    type: "number",
+                    description: "Rows to skip (default 0)",
+                },
+                take: {
+                    type: "number",
+                    description: "Page size (default 50, max 200)",
+                },
+            },
+        },
+    },
+    {
+        name: "get_workplans",
+        description: "List all workplans in a project (active and inactive) with name, dates, teams, and active flag. Use get_workplan_items with a workplan name or GUID to load that plan's AMPs. Prefer get_active_workplans when you only need current active plans. 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_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.",
@@ -65,7 +104,7 @@ export const TOOL_DEFINITIONS = [
     },
     {
         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.",
+        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_workplans or get_active_workplans; omit workplan to use the newest active one. Use get_user_projects for a project key.",
         inputSchema: {
             type: "object",
             properties: {
@@ -113,15 +152,160 @@ export const TOOL_DEFINITIONS = [
     },
     {
         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.",
+        description: "List non-archived projects the authenticated user belongs to (id, key, name), ordered by key. Use before create_amp or list_project_tags to pick a valid project key or GUID.",
         inputSchema: {
             type: "object",
             properties: {},
         },
     },
+    {
+        name: "list_assignable_users",
+        description: "List people who can be assigned on a project's Team (or Director) column. Use before create_amp or add_amp_update when setting assignees.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project: {
+                    type: "string",
+                    description: "Project key (preferred) or GUID from get_user_projects",
+                },
+                column: {
+                    type: "string",
+                    description: "Team (default) or Director. Client column does not use this assignee list.",
+                },
+            },
+            required: ["project"],
+        },
+    },
+    {
+        name: "list_project_tags",
+        description: "List or search tags defined on an AMP project (id, name, description, visibility, archived state). Any project member can list tags; creating or changing tags requires a project manager.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project: {
+                    type: "string",
+                    description: "Project key (preferred) or GUID from get_user_projects",
+                },
+                search: {
+                    type: "string",
+                    description: "Optional text matched against tag name or description",
+                },
+                includeArchived: {
+                    type: "boolean",
+                    description: "Include archived tags (default false)",
+                },
+            },
+            required: ["project"],
+        },
+    },
+    {
+        name: "create_project_tag",
+        description: "Create a new tag on an AMP project. Requires project manager. Returns tag id and name.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project: { type: "string", description: "Project key (preferred) or GUID" },
+                value: { type: "string", description: "Tag label (unique within the project)" },
+                description: { type: "string", description: "Optional tooltip description" },
+                isVisibleToClient: {
+                    type: "boolean",
+                    description: "Whether clients can see this tag (default false)",
+                },
+                color: { type: "string", description: "Optional CSS colour" },
+            },
+            required: ["project", "value"],
+        },
+    },
+    {
+        name: "update_project_tag",
+        description: "Update a project tag (name, description, client visibility, colour, archived). Requires project manager. Tag is GUID or name within the project.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project: { type: "string", description: "Project key (preferred) or GUID" },
+                tag: { type: "string", description: "Tag GUID or name from list_project_tags" },
+                value: { type: "string", description: "New tag label" },
+                description: { type: "string", description: "New description (empty string clears)" },
+                isVisibleToClient: {
+                    type: "boolean",
+                    description: "Whether clients can see this tag",
+                },
+                isArchived: {
+                    type: "boolean",
+                    description: "Archive (true) or restore (false) the tag",
+                },
+                color: { type: "string", description: "CSS colour for the tag" },
+            },
+            required: ["project", "tag"],
+        },
+    },
+    {
+        name: "delete_project_tag",
+        description: "Delete a project tag not assigned to any work items. Requires project manager.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project: { type: "string", description: "Project key (preferred) or GUID" },
+                tag: { type: "string", description: "Tag GUID or name from list_project_tags" },
+            },
+            required: ["project", "tag"],
+        },
+    },
+    {
+        name: "get_amp_item_tags",
+        description: "Get the tags on an AMP item (id and name) that the authenticated user can see. Does not change the item.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ampReference: {
+                    type: "string",
+                    description: "AMP reference, e.g. '12345' or 'AMP-12345'",
+                },
+            },
+            required: ["ampReference"],
+        },
+    },
+    {
+        name: "add_amp_item_tags",
+        description: "Add existing project tags to an AMP item without changing other tags. Requires project manager.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ampReference: {
+                    type: "string",
+                    description: "AMP reference, e.g. '12345' or 'AMP-12345'",
+                },
+                tags: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "One or more project tags to add (GUID or name)",
+                },
+            },
+            required: ["ampReference", "tags"],
+        },
+    },
+    {
+        name: "remove_amp_item_tags",
+        description: "Remove selected project tags from an AMP item without changing other tags. Requires project manager.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ampReference: {
+                    type: "string",
+                    description: "AMP reference, e.g. '12345' or 'AMP-12345'",
+                },
+                tags: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "One or more project tags to remove (GUID or name)",
+                },
+            },
+            required: ["ampReference", "tags"],
+        },
+    },
     {
         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.",
+        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. Optional assignees assigns the item to those team members (use list_assignable_users). Extension items add Team + Client column comments automatically.",
         inputSchema: {
             type: "object",
             properties: {
@@ -166,13 +350,23 @@ export const TOOL_DEFINITIONS = [
                     type: "string",
                     description: "Optional parent AMP reference, e.g. '12345' or 'AMP-12345'",
                 },
+                tags: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional project tags (GUID or name from list_project_tags). Project manager only. Omit for no tags.",
+                },
+                assignees: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional team assignees (name, email, or user GUID from list_assignable_users). Posts a Team comment so the item shows as assigned.",
+                },
             },
             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.",
+        description: "Post a team-column update on an AMP item, matching the AMP UI team comment form. Default to message-only comments. Do NOT set teamProgress, teamPercentageDone, or stage unless the user explicitly asked to move the board — reporting finished work or posting an update is not the same as advancing progress. When teamProgress is requested, advance one step only along Not started → TDD → Developing → Testing → Done (never skip steps; from Developing go to Testing, not Done).",
         inputSchema: {
             type: "object",
             properties: {
@@ -182,19 +376,29 @@ export const TOOL_DEFINITIONS = [
                 },
                 message: {
                     type: "string",
-                    description: "Team comment text",
+                    description: "Team comment text. Safe default when the user only asked for a comment or progress note.",
                 },
                 teamPercentageDone: {
                     type: "number",
-                    description: "Team % done; integer 0–100, multiple of 10",
+                    description: "Team board % done; integer 0–100, multiple of 10. ONLY set when the user explicitly asked to change % done — omit for comment-only updates.",
                 },
                 teamProgress: {
                     type: "string",
-                    description: "Team progress: Not started, TDD, Developing, Testing, Done, or Blocked",
+                    description: "Team workflow stage. ONLY set when the user explicitly asked to move team progress — omit for comment-only updates. Advance one step: Not started → TDD → Developing → Testing → Done (never skip; from Developing use Testing, not Done).",
                 },
                 stage: {
                     type: "string",
-                    description: "Workflow stage: Test, Local, UAT, Live, or Pre-Live",
+                    description: "Deployment stage. ONLY set when the user explicitly asked to record a stage change — omit for comment-only updates.",
+                },
+                tags: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Replace all tags on the item. Project manager only. Omit to keep current tags; [] clears all.",
+                },
+                assignees: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Replace team assignees. Omit to keep current assignees; [] unassigns. Defaults message to 'Assigning' if nothing else is posted.",
                 },
             },
             required: ["ampReference"],
@@ -202,7 +406,7 @@ export const TOOL_DEFINITIONS = [
     },
     {
         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\".",
+        description: "Update the AMP team board % done (0–100, multiple of 10) and/or append a team-column comment. Does NOT change teamProgress (workflow stage). Do NOT set teamPercentageDone unless the user explicitly asked — omit for comment-only updates. At least one of teamPercentageDone or non-empty message required.",
         inputSchema: {
             type: "object",
             properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geeks.ltd/geeks-amp-mcp",
-  "version": "1.0.6",
+  "version": "1.0.9",
   "description": "Local MCP server for AMP (OAuth 2.0 PKCE, token storage, proxy to AMP MCPServer.ashx)",
   "type": "module",
   "main": "dist/index.js",
@@ -17,6 +17,7 @@
   ],
   "scripts": {
     "build": "tsc",
+    "test": "node --import tsx --test src/**/*.test.ts",
     "start": "node dist/index.js",
     "dev": "node --import tsx src/index.ts"
   },