Devrel/roles, workflows #58

pokornyd · 2025-12-09T12:49:22Z

Motivation

Adds support for available roles and workflow MAPI endpoints

Checklist

Code follows coding conventions held in this repo
Automated tests have been added
Tests are passing
Docs have been updated (if applicable)
Temporary settings (e.g. variables used during development and testing) have been reverted to defaults

How to test

If manual testing is required, what are the steps?

huluvu21 · 2025-12-15T10:42:39Z

src/tools/upsert-asset-mapi.ts

+
+export const registerTool = (server: McpServer): void => {
+  server.tool(
+    "upsert-asset-mapi",


Honestly, the MAPI contract for assets is kinda weird. Should the MCP client "craft" the internal ID when creating the asset? Just look at the docs...

I would simplify things for the MCP server: one tool for creating and one tool for updating.

huluvu21 · 2025-12-15T10:44:54Z

src/schemas/patchSchemas/assetPatchSchemas.ts

+  reference: referenceObjectSchema,
+});
+
+export const upsertAssetDataSchema = z.object({


I don't think it should belong to "patch" schemas. Move it under the "schemas" folder and name it simply assetSchemas.ts.

huluvu21 · 2025-12-15T11:16:55Z

src/tools/list-roles-mapi.ts

+export const registerTool = (server: McpServer): void => {
+  server.tool(
+    "list-roles-mapi",
+    "Get all Kontent.ai roles from Management API",


IMHO we don't need to say that we use management API all the time. Actually, most tools don't talk about it at all :)

I agree we don't, but it's mentioned in kontent-tool-descriptions.mdc:

API source: Always specify the API being used:

"from Management API"

"via Management API"

"from Delivery API"

I mainly used variant endpoints for reference -- coincidentally, all of them state the API :) might be worth updating the doc and unifying this across the codebase

huluvu21 · 2025-12-15T11:19:50Z

src/tools/get-role-mapi.ts

+export const registerTool = (server: McpServer): void => {
+  server.tool(
+    "get-role-mapi",
+    "Get Kontent.ai role by ID from Management API",


Again, remove "from Management API".

decided to ditch getRole altogether -- list roles is sufficient and we save a bit of context

huluvu21 · 2025-12-15T11:20:18Z

src/tools/get-role-mapi.ts

+    "get-role-mapi",
+    "Get Kontent.ai role by ID from Management API",
+    {
+      identifier: z.string().describe("Role ID (UUID)"),


IMHO "(UUID)" can be removed.

endpoint removed

huluvu21 · 2025-12-15T19:47:10Z

src/tools/delete-workflow-mapi.ts

+    "delete-workflow-mapi",
+    "Delete Kontent.ai workflow",
+    {
+      identifier: z.string().describe("Workflow ID (UUID) to delete"),


I would remove "(UUID) to delete". Also, use z.uuid() instead of z.string() and get rid of the description because it's self-explanatory. Also, rename the pro from identifier to id.

huluvu21 · 2025-12-15T19:49:39Z

src/schemas/workflowSchemas.ts

 });

 // Schema for the list workflows response
 export const listWorkflowsResponseSchema = z


The "listWorkflowsResponseSchema" is unused. I know that this is not your doing but removing it (and all the related code) would simplify this file. Boy scout rule.

huluvu21 · 2025-12-15T20:00:50Z

src/schemas/workflowSchemas.ts

+});
+
+// Workflow scope input schema
+export const workflowScopeInputSchema = z.object({


This (and not just this) should not be needed to export.

removed exports and also removed previous impls of workflows and its subschemas (scopes were outdated and the schemas were not used)

huluvu21 · 2025-12-15T20:05:19Z

src/schemas/workflowSchemas.ts

+    .string()
+    .uuid()
+    .optional()
+    .describe("Step ID (required when updating existing steps)"),


Just a suggestion: I think we should make the schemas as easy to understand as possible. What about splitting create and update schema?

I don't think it adds any value, but feel free to challenge that. unless I'm missing something, the only difference is ID and scheduled_step, both of which are readonly. we're not using response schemas anywhere, are we?

wait a sec, I might actually rethink that, once I figure out the API reference.

alright, thought about it some more. API reference is a bit confusing, mentioning IDs in POST/PUT request body for workflows, even though you cannot set them. anyway, even though update workflow is a PUT request, pretty much all of the fields are required, so the bodies are identical IMO. I don't see value in splitting them.

huluvu21 · 2025-12-15T20:09:24Z

src/schemas/workflowSchemas.ts

+    .describe("Codename for API operations (auto-generated if omitted)"),
+  scopes: z
+    .array(workflowScopeInputSchema)
+    .describe("Array of scopes defining which content types use this workflow"),


Scopes are currently content type and collection. You mention content types only here. Also, this might change in the future. Please simplify the description. It might be worth it to mention what empty array means?

I adjusted the description to mention collections too and also mention the behavior of setting both to empty. can't say I simplified anything, I mostly copied the description from the api reference

huluvu21 · 2025-12-15T20:30:12Z

src/tools/delete-workflow-mapi.ts

+
+        return createMcpToolSuccessResponse({
+          message: `Workflow '${identifier}' deleted successfully`,
+          deletedWorkflow: response.rawData,


According to our docs, the response is empty :/

pokornyd · 2025-12-18T13:05:52Z

Simplified the schemas by removing redundant fields. This includes removal of ID from workflow step schema, which effectively means the MCP will not have an option to change codename of an existing workflow step (=> nothing to reference the step with). whether or not we want to have this feature in the MCP is for consideration.

pokornyd · 2025-12-18T13:18:07Z

Simplified the schemas by removing redundant fields. This includes removal of ID from workflow step schema, which effectively means the MCP will not have an option to change codename of an existing workflow step (=> nothing to reference the step with). whether or not we want to have this feature in the MCP is for consideration.

never mind, I added the ID as a readonly optional field for referencing -> codename update now possible

huluvu21

I have one final note but the PR can be merged as is :)

src/schemas/workflowSchemas.ts

pokornyd requested review from a team and JiriLojda as code owners December 9, 2025 12:49

pokornyd force-pushed the devrel/increment-3 branch 2 times, most recently from 4bb8a33 to 742376a Compare December 15, 2025 14:29

huluvu21 requested changes Dec 15, 2025

View reviewed changes

pokornyd force-pushed the devrel/increment-3 branch 2 times, most recently from be0edc2 to d764466 Compare December 18, 2025 12:55

pokornyd requested a review from huluvu21 December 18, 2025 13:06

huluvu21 approved these changes Dec 19, 2025

View reviewed changes

src/schemas/workflowSchemas.ts Outdated Show resolved Hide resolved

pokornyd added 5 commits January 5, 2026 13:30

add roles tools

90eb70c

add workflow tools

8cd3e32

remove get-role-mapi, cleanup comments

294c358

adjust workflow schemas, align naming conventions

dd81767

add id to workflowstep schema

6f9a22b

pokornyd force-pushed the devrel/increment-3 branch from d04762c to 8a27ee2 Compare January 5, 2026 12:31

remove redundant descriptions for workflows

db4fc9f

pokornyd force-pushed the devrel/increment-3 branch from 8a27ee2 to db4fc9f Compare January 5, 2026 12:33

huluvu21 approved these changes Jan 5, 2026

View reviewed changes

pokornyd merged commit 732a5ed into master Jan 5, 2026
3 checks passed

Devrel/roles, workflows #58

Devrel/roles, workflows #58

Uh oh!

Conversation

pokornyd commented Dec 9, 2025

Motivation

Checklist

How to test

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

huluvu21 Dec 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pokornyd commented Dec 18, 2025

Uh oh!

pokornyd commented Dec 18, 2025

Uh oh!

huluvu21 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

huluvu21 Dec 15, 2025 •

edited

Loading