targetprocess-mcp-server 2.3.1 → 2.4.1

package/README.md

@@ -61,6 +61,8 @@ Cards — Read
 - `get_bug_comments` — Get comments on a bug (id, optional results)
 - `get_user_story_comments` — Get comments on a user story (id, optional results)
 - `get_user_story_test_cases` — Fetch the linked test plan and all its test cases (with steps) for a user story (resourceId)
+- `get_card_relations` — Get all relations (Dependency, Blocker, Relation, Link, Duplicate) for a card, with direction and the related card (id)
+- `get_relation_types` — List the relation types available in this instance (id + name); use to find the `relationType` name for `create_card_relation` (no params)
 - `search_tp_cards` — Search TP cards by keyword or phrase in description (keyword, optional entityType: UserStories | Bugs, default: UserStories)
 
 Cards — Write
@@ -70,6 +72,11 @@ Cards — Write
   > Resolve state name → ID via `get_bug_workflows` before passing `entityStateId`
 - `update_user_story` — Update an existing user story (id, optional title, optional description, optional projectId, optional teamId, optional entityStateId)
   > Resolve state name → ID via `get_user_story_workflows` before passing `entityStateId`
+- `create_card_relation` — Create a relation between two cards (masterId, slaveId, optional relationType name, default: "Depends on")
+  > The Slave depends on the Master — the Master must be done first
+  > `relationType` is matched by name against this instance's types; resolve exact names via `get_relation_types` (it's resolved to an ID before the API call, since TP rejects relation types passed by name)
+- `delete_card_relation` — Remove a relation by its relation ID (relationId)
+  > Get the `relationId` from `get_card_relations` first — it's the relation's own ID, not a card ID
 - `update_user_story_state` — Update the sub-state (team assignment entity state) for a user story (id, optional entityStateId, optional teamId, optional teamAssignmentId)
   > 1. Call `get_user_story_content` first to find the assigned team and `teamAssignmentId`
   > 2. Call `get_user_story_workflows` to resolve the target state name → `entityStateId`
@@ -84,6 +91,9 @@ Cards — Write
 - `create_user_story` — Create a new user story (title, optional description, optional featureId, optional releaseId, optional projectId, optional teamId)  
 > [!NOTE]  
 > `projectId` and `teamId` are optional — fall back to `TP_PROJECT_ID` and `TP_TEAM_ID` from config  
+- `create_formatted_user_story` — Create a new user story with a structured template description (title, header object with asA/iWant/soThat, acceptanceCriteria array, scenarios array with Gherkin steps, optional definitions, examplesTable, edgeCases, references, notes, optional featureId, releaseId, projectId, teamId)  
+> [!NOTE]  
+> `projectId` and `teamId` are optional — fall back to `TP_PROJECT_ID` and `TP_TEAM_ID` from config  
 - `create_feature` — Create a new feature (title, optional description, optional epicId, optional releaseId, optional projectId, optional teamId)  
 > [!NOTE]  
 > `projectId` and `teamId` are optional — fall back to `TP_PROJECT_ID` and `TP_TEAM_ID` from config  

package/build/handlers/create_card_relation.js

@@ -0,0 +1,35 @@
+export async function handleCreateCardRelation(tp, params) {
+    const wanted = params.relationType || 'Depends on';
+    // Resolve the relation type name → Id. TP rejects relations whose RelationType
+    // is passed by Name (405 Method Not Allowed), so we look up the existing type.
+    const typesResponse = await tp.getRelationTypes();
+    const types = typesResponse?.Items || [];
+    const match = types.find((t) => t.Name.toLowerCase() === wanted.toLowerCase());
+    if (!match) {
+        const available = types.map((t) => `${t.Name} (id: ${t.Id})`).join(', ');
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Unknown relation type "${wanted}". Available relation types in this instance: ${available || '(none returned)'}`
+                }],
+        };
+    }
+    const result = await tp.createRelation({
+        masterId: params.masterId,
+        slaveId: params.slaveId,
+        relationTypeId: String(match.Id),
+    });
+    if (!result.ok) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Failed to create "${match.Name}" relation between master id: ${params.masterId} and slave id: ${params.slaveId}\n` +
+                        `HTTP status: ${result.status}\n` +
+                        `Response body: ${result.body}`
+                }],
+        };
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify(result.data) }],
+    };
+}

package/build/handlers/delete_card_relation.js

@@ -0,0 +1,19 @@
+export async function handleDeleteCardRelation(tp, relationId) {
+    const result = await tp.deleteRelation(relationId);
+    if (!result.ok) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Failed to delete relation id: ${relationId}\n` +
+                        `HTTP status: ${result.status}\n` +
+                        `Response body: ${result.body}`
+                }],
+        };
+    }
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({ deleted: true, relationId: Number(relationId), relation: result.data })
+            }],
+    };
+}

package/build/handlers/get_card_relations.js

@@ -0,0 +1,38 @@
+export async function handleGetCardRelations(tp, id) {
+    const response = await tp.getCardRelations(id);
+    if (!response) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Failed to get relations for card id: ${id}`
+                }],
+        };
+    }
+    const items = response.Items || [];
+    if (items.length === 0) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `No relations found for card id: ${id}`,
+                }],
+        };
+    }
+    const cardId = Number(id);
+    const relations = items.map((relation) => {
+        const isMaster = relation.Master.Id === cardId;
+        const other = isMaster ? relation.Slave : relation.Master;
+        return {
+            relationId: relation.Id,
+            relationType: relation.RelationType.Name,
+            direction: isMaster ? 'outbound' : 'inbound',
+            relatedCard: {
+                id: other.Id,
+                name: other.Name,
+                entityType: other.EntityType?.Name,
+            },
+        };
+    });
+    return {
+        content: [{ type: 'text', text: JSON.stringify(relations) }],
+    };
+}

package/build/index.js

@@ -23,7 +23,7 @@ import { handleAddComment } from "./handlers/add_comment.js";
 import { handleGetUserStoryComments } from "./handlers/get_user_story_comments.js";
 import { handleGetBugComments } from "./handlers/get_bug_comments.js";
 import { handleCreateBug } from "./handlers/create_bug.js";
-import { handleCreateUserStory } from "./handlers/create_user_story.js";
+// import { handleCreateUserStory } from "./handlers/create_user_story.js";
 import { handleCreateFeature } from "./handlers/create_feature.js";
 import { handleCreateTask } from "./handlers/create_task.js";
 import { handleUpdateBug } from "./handlers/update_bug.js";
@@ -36,6 +36,9 @@ import { handleGetFeatureUserStories } from "./handlers/get_feature_user_stories
 import { handleGetUserStoryBugs } from "./handlers/get_user_story_bugs.js";
 import { handleGetCardCurrentStatus } from "./handlers/get_card_current_status.js";
 import { handleUpdateUserStorySubState } from "./handlers/update_user_story_sub_state.js";
+import { handleGetCardRelations } from "./handlers/get_card_relations.js";
+import { handleCreateCardRelation } from "./handlers/create_card_relation.js";
+import { handleDeleteCardRelation } from "./handlers/delete_card_relation.js";
 const server = new McpServer({
     name: "tp",
     version: "1.0.0"
@@ -527,15 +530,98 @@ server.registerTool('create_bug', {
             .describe('Optional Entity State ID — if user gave a state name, resolve it via "get_bug_workflows" first; defaults to "Done"'),
     },
 }, async ({ title, bugContent, origin, projectId, teamId, entityStateId }) => handleCreateBug(tp, { title, bugContent, origin, projectId, teamId, entityStateId }));
+// server.registerTool(
+//   'create_user_story',
+//   {
+//     title: 'Create a new user story',
+//     description: `Create a new user story in Targetprocess.`,
+//     inputSchema: {
+//       title: z.string()
+//         .describe('User story title'),
+//       description: z.string()
+//         .optional()
+//         .describe('Optional user story description (when provided, format as HTML)'),
+//       featureId: z.string()
+//         .min(5)
+//         .max(6)
+//         .optional()
+//         .describe('Optional Feature ID to link this user story to (e.g. 145636)'),
+//       releaseId: z.string()
+//         .min(5)
+//         .max(6)
+//         .optional()
+//         .describe('Optional Release ID to link this user story to (e.g. 145200)'),
+//       projectId: z.string()
+//         .optional()
+//         .describe('Optional Project ID — defaults to TP_PROJECT_ID from config'),
+//       teamId: z.string()
+//         .optional()
+//         .describe('Optional Team ID — defaults to TP_TEAM_ID from config'),
+//     },
+//   },
+//   async ({ title, description, featureId, releaseId, projectId, teamId }) =>
+//     handleCreateUserStory(tp, { title, description, featureId, releaseId, projectId, teamId })
+// )
 server.registerTool('create_user_story', {
-    title: 'Create a new user story',
-    description: `Create a new user story in Targetprocess.`,
+    title: 'Create a formatted user story',
+    description: `Create a new user story in Targetprocess with a structured, template-driven description.
+      The description is assembled from discrete sections (header, definitions, acceptance criteria, Gherkin scenarios, edge cases, references, notes) and stored as HTML.
+      CRITICAL WORKFLOW: Before calling this tool, you MUST follow these steps:
+        1) IF the user specified a feature by name (not ID), call "get_feature_user_stories" or "search_tp_cards" to resolve the feature ID;
+        2) IF the user specified a release by name (not ID), call "get_current_releases" to resolve the release ID;
+        3) IF the user specified a team by name (not ID), call "get_teams" to find the matching team and use its ID as teamId;
+        4) IF the user specified a project by name (not ID), call "get_projects" to find the matching project and use its ID as projectId;`,
     inputSchema: {
         title: z.string()
             .describe('User story title'),
-        description: z.string()
+        header: z.object({
+            storyId: z.string()
+                .optional()
+                .describe('Story ID if already known (e.g. US-12345), omit for new stories'),
+            asA: z.string()
+                .describe('Role or persona — the "As a ..." part'),
+            iWant: z.string()
+                .describe('Goal — the "I want ..." part'),
+            soThat: z.string()
+                .describe('Benefit — the "so that ..." part'),
+        })
+            .describe('Story header following the As a / I want / so that format'),
+        definitions: z.array(z.object({
+            term: z.string()
+                .describe('The term, module name, or feature flag being defined'),
+            description: z.string()
+                .describe('Explanation of the term'),
+        })),
+        acceptanceCriteria: z.array(z.string())
+            .min(1)
+            .describe('Bullet checklist items for quick review sign-off — each string is one criterion'),
+        scenarios: z.array(z.object({
+            name: z.string()
+                .describe('Scenario name'),
+            steps: z.array(z.string())
+                .min(1)
+                .describe('Gherkin steps — each string is a full step line, e.g. "Given I am on the login page"'),
+        }))
+            .min(1)
+            .describe('Gherkin scenario blocks, one per behavior branch'),
+        examplesTable: z.string()
+            .optional()
+            .describe('Examples table for parameterized or matrix behavior (plain text or Gherkin Examples: table format)'),
+        edgeCases: z.array(z.object({
+            name: z.string()
+                .describe('Edge case scenario name'),
+            steps: z.array(z.string())
+                .min(1)
+                .describe('Gherkin steps for this edge case'),
+        }))
+            .optional()
+            .describe('Explicit edge case or boundary condition scenarios'),
+        references: z.string()
             .optional()
-            .describe('Optional user story description (when provided, format as HTML)'),
+            .describe('Links to Axure mockups or other external references (not inline in prose)'),
+        notes: z.string()
+            .optional()
+            .describe('Anything that helps understand the story context but does not fit other sections'),
         featureId: z.string()
             .min(5)
             .max(6)
@@ -553,7 +639,63 @@ server.registerTool('create_user_story', {
             .optional()
             .describe('Optional Team ID — defaults to TP_TEAM_ID from config'),
     },
-}, async ({ title, description, featureId, releaseId, projectId, teamId }) => handleCreateUserStory(tp, { title, description, featureId, releaseId, projectId, teamId }));
+}, async ({ title, header, definitions, acceptanceCriteria, scenarios, examplesTable, edgeCases, references, notes, featureId, releaseId, projectId, teamId }) => {
+    const gherkinBlock = (items) => items.map((s, indx) => `<div><strong>Scenario ${indx + 1} - ${s.name}:</strong></div><div>${s.steps.map(step => `<div>\t${step}</div>`).join('\n')}</div>`).join('\n');
+    const parts = ['<div>'];
+    parts.push('<h3>Header</h3>');
+    if (header.storyId)
+        parts.push(`<p><strong>Story ID:</strong> ${header.storyId}</p>`);
+    parts.push(`<p>As a ${header.asA} / I want ${header.iWant} / so that ${header.soThat}</p>`);
+    if (definitions) {
+        parts.push('<h3>Definitions</h3>');
+        parts.push(`<div>`);
+        for (const def of definitions) {
+            parts.push(`<p><strong>${def.term}</strong> — ${def.description}</p>`);
+        }
+        parts.push(`</div>`);
+    }
+    parts.push('<h3>Acceptance Criteria</h3>');
+    parts.push('<ol>');
+    for (const criterion of acceptanceCriteria) {
+        parts.push(`<li>${criterion}</li>`);
+    }
+    parts.push('</ol>');
+    parts.push('<h3>Scenarios</h3>');
+    parts.push(gherkinBlock(scenarios));
+    if (examplesTable) {
+        parts.push('<h3>Examples</h3>');
+        parts.push(`<pre>${examplesTable}</pre>`);
+    }
+    if (edgeCases && edgeCases.length > 0) {
+        parts.push('<h3>Edge Cases</h3>');
+        parts.push(gherkinBlock(edgeCases));
+    }
+    if (references) {
+        parts.push('<h3>References</h3>');
+        parts.push(`<p>${references}</p>`);
+    }
+    if (notes) {
+        parts.push('<h3>Notes</h3>');
+        parts.push(`<p>${notes}</p>`);
+    }
+    parts.push('</div>');
+    const description = parts.join('\n');
+    const userStoryResponse = await tp.createUserStory({ title, description, featureId, releaseId, projectId, teamId });
+    if (!userStoryResponse) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Failed to create formatted user story "${title}"\n JSON: ${JSON.stringify(userStoryResponse, null, 2)}`
+                }]
+        };
+    }
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify(userStoryResponse)
+            }],
+    };
+});
 server.registerTool('create_feature', {
     title: 'Create a new feature',
     description: `Create a new Feature in Targetprocess.`,
@@ -1086,6 +1228,62 @@ server.registerTool('get_card_current_status', {
             .describe('Type of the TP card — UserStory, Bug, or Feature (default: UserStory)'),
     },
 }, async ({ id, resourceType = 'UserStory' }) => handleGetCardCurrentStatus(tp, id, resourceType));
+server.registerTool('get_card_relations', {
+    title: 'Get card relations',
+    description: `Get all relations (Dependency, Blocker, Relation, Link, Duplicate) for a TP card (UserStory, Bug, Feature, etc.) by its ID.
+      Each relation shows the related card and the direction:
+      - "outbound" — this card is the Master (e.g. for Dependency, the related card depends on this card)
+      - "inbound" — this card is the Slave (e.g. for Dependency, this card depends on the related card)`,
+    inputSchema: {
+        id: z.string()
+            .min(5)
+            .max(6)
+            .describe('TP card ID (e.g. 145789)'),
+    },
+}, async ({ id }) => handleGetCardRelations(tp, id));
+server.registerTool('get_relation_types', {
+    title: 'Get relation types',
+    description: 'Get all relation types available in this Targetprocess instance (id + name). Use this to find the correct relationType name for "create_card_relation".',
+}, async () => {
+    const response = await tp.getRelationTypes();
+    if (!response) {
+        return {
+            content: [{ type: 'text', text: `Failed to get relation types` }],
+        };
+    }
+    const items = (response.Items || []).map((t) => ({ id: t.Id, name: t.Name }));
+    return {
+        content: [{ type: 'text', text: JSON.stringify(items) }],
+    };
+});
+server.registerTool('create_card_relation', {
+    title: 'Create a relation between two cards',
+    description: `Create a relation between two TP cards (UserStory, Bug, Feature, etc.).
+      The Master is the source of the relation and the Slave is the target — e.g. for a "Depends on" relation, the Slave depends on the Master (Master must be done first).
+      NOTE: relationType is matched by name against this instance's relation types. If unsure of the exact name, call "get_relation_types" first. The handler resolves the name to its ID before creating the relation.`,
+    inputSchema: {
+        masterId: z.string()
+            .min(5)
+            .max(6)
+            .describe('Master card ID — the source of the relation (e.g. 145789)'),
+        slaveId: z.string()
+            .min(5)
+            .max(6)
+            .describe('Slave card ID — the target of the relation (e.g. 145790)'),
+        relationType: z.string()
+            .optional()
+            .describe('Relation type name as defined in this instance (e.g. "Depends on", "Relate to"). Resolve exact names via "get_relation_types". Defaults to "Depends on".'),
+    },
+}, async ({ masterId, slaveId, relationType }) => handleCreateCardRelation(tp, { masterId, slaveId, relationType }));
+server.registerTool('delete_card_relation', {
+    title: 'Delete a relation between two cards',
+    description: `Delete (remove) a relation between two TP cards by the relation's own ID — not the card IDs.
+      To find the relationId, call "get_card_relations" for one of the cards; each entry includes a "relationId" field.`,
+    inputSchema: {
+        relationId: z.string()
+            .describe('The relation ID to delete (the "relationId" field from "get_card_relations", e.g. 20748)'),
+    },
+}, async ({ relationId }) => handleDeleteCardRelation(tp, relationId));
 server.registerTool('get_in_progress_tasks_and_bugs', {
     title: 'Get in-progress tasks and bugs for a user',
     description: 'Get all Tasks and Bugs currently in "In Progress" state assigned to a given user ID',

package/build/tp.js

@@ -82,6 +82,54 @@ export class TpClient {
             return null;
         }
     }
+    // Like post(), but on failure returns the HTTP status and raw response body
+    // instead of null, so callers can surface TP's error detail to the user.
+    async postRaw(params, data) {
+        params.param["access_token"] = this.token;
+        let _url = this.params(params);
+        console.error(JSON.stringify({ "TP_POST_URL": _url }));
+        console.error(JSON.stringify({ "TP_POST_BODY": data }));
+        try {
+            const response = await fetch(_url, {
+                method: "POST",
+                headers: this.headers,
+                body: JSON.stringify(data),
+            });
+            const text = await response.text();
+            if (!response.ok) {
+                console.error(JSON.stringify({ "TP_POST_ERROR_STATUS": response.status, "TP_POST_ERROR_BODY": text }));
+                return { ok: false, status: response.status, body: text };
+            }
+            return { ok: true, data: (text ? JSON.parse(text) : null) };
+        }
+        catch (error) {
+            console.error("Error making TP request:", error);
+            return { ok: false, status: 0, body: String(error) };
+        }
+    }
+    // DELETE request that, like postRaw(), surfaces the HTTP status and raw
+    // response body on failure so callers can report TP's error detail.
+    async del(params) {
+        params.param["access_token"] = this.token;
+        let _url = this.params(params);
+        console.error(JSON.stringify({ "TP_DELETE_URL": _url }));
+        try {
+            const response = await fetch(_url, {
+                method: "DELETE",
+                headers: this.headers,
+            });
+            const text = await response.text();
+            if (!response.ok) {
+                console.error(JSON.stringify({ "TP_DELETE_ERROR_STATUS": response.status, "TP_DELETE_ERROR_BODY": text }));
+                return { ok: false, status: response.status, body: text };
+            }
+            return { ok: true, data: (text ? JSON.parse(text) : null) };
+        }
+        catch (error) {
+            console.error("Error making TP request:", error);
+            return { ok: false, status: 0, body: String(error) };
+        }
+    }
     async getUserStory(userStoryId) {
         const response = await this.get({
             pathParam: ["userStories", userStoryId],
@@ -768,6 +816,52 @@ export class TpClient {
             },
         });
     }
+    // TP's Relations endpoint silently returns nothing for an OR across
+    // Master.Id/Slave.Id, so we query each side separately and merge the results.
+    async getCardRelations(cardId) {
+        const include = "[Id,RelationType[Name],Master[Id,Name,EntityType],Slave[Id,Name,EntityType]]";
+        const query = (side) => this.get({
+            pathParam: ["Relations"],
+            param: {
+                "format": "json",
+                "where": `${side}.Id eq ${cardId}`,
+                "include": include,
+                "take": 100,
+            },
+        });
+        const [asMaster, asSlave] = await Promise.all([query("Master"), query("Slave")]);
+        const items = [...(asMaster?.Items ?? []), ...(asSlave?.Items ?? [])];
+        return { Next: "", Items: items };
+    }
+    async getRelationTypes() {
+        return this.get({
+            pathParam: ["RelationTypes"],
+            param: {
+                "format": "json",
+                "include": "[Id,Name]",
+                "take": 100,
+            },
+        });
+    }
+    // RelationType must be referenced by Id — passing it by Name makes TP try to
+    // create a new RelationType resource, which returns 405 Method Not Allowed.
+    async createRelation({ masterId, slaveId, relationTypeId }) {
+        const relation = {
+            "Master": { "Id": masterId },
+            "Slave": { "Id": slaveId },
+            "RelationType": { "Id": relationTypeId },
+        };
+        return this.postRaw({
+            pathParam: ["Relations"],
+            param: { "format": "json" },
+        }, relation);
+    }
+    async deleteRelation(relationId) {
+        return this.del({
+            pathParam: ["Relations", relationId],
+            param: { "format": "json" },
+        });
+    }
     async addAttachedFile(generalId, source) {
         let blob;
         let fileName;

package/package.json

@@ -27,7 +27,7 @@
   "engines": {
     "node": ">=20.x"
   },
-  "version": "2.3.1",
+  "version": "2.4.1",
   "description": "MCP server for Tartget Process",
   "main": "build/index.js",
   "keywords": [