feat(mcp): bulk case creation and template selection/listing (#454)

Add two MCP case-authoring capabilities, reusing the existing transactional
import service rather than duplicating case-creation logic:

- testplanit_cases_create_many creates many cases in one call via a new
  app/api/projects/[projectId]/cases/bulk-create route that reuses
  persistGeneratedTestCases (one transaction per folder/state group) and
  reports per-case success/failure so partial failures are visible. The route
  authenticates by session or API token with read-only-token enforcement,
  mirroring the ZenStack RPC handler the MCP server already calls.
- testplanit_templates_list returns a project's enabled templates with the
  case fields each defines.
- cases_create and cases_create_many accept an optional templateId (default:
  the project's first enabled template). Custom fields are resolved and
  validated against the chosen template — and the case's own template on
  update — so an out-of-template field returns a clear error instead of being
  silently dropped.

Consolidate to a single bulk-create path by removing the orphaned legacy
app/api/repository/import-generated-test-cases route (no product callers;
session-only, non-transactional). Its e2e is repointed at the new endpoint and
its audit-coverage and OpenAPI references are dropped.

Update the MCP docs (overview, configuration, prompts) and the package README
for the new tools and the 44-tool count.

Author: therealbrad

docs/docs/sdk/mcp-configuration.md

@@ -86,7 +86,7 @@ Tokens with both scopes set show a **Read-only** badge and an **Agent token** ba
 
 ## Tool catalog
 
-The full tool catalog — 28 tools across cases, folders, tags, projects, test runs, results, sessions, findings, code repositories, issues, and repository case links — lives in the [npm package README](https://www.npmjs.com/package/@testplanit/mcp-server). Each tool entry shows its input parameters, output shape, and (where applicable) which killer-app composition it participates in.
+The full tool catalog — 44 tools across cases, templates, folders, tags, projects, test runs, results, sessions, findings, milestones, code repositories, issues, and repository case links — lives in the [npm package README](https://www.npmjs.com/package/@testplanit/mcp-server). Each tool entry shows its input parameters, output shape, and (where applicable) which killer-app composition it participates in.
 
 ## Troubleshooting
 

docs/docs/sdk/mcp-overview.md

@@ -10,7 +10,8 @@ The TestPlanIt MCP server lets AI agents — Claude Desktop, Cursor, custom MCP-
 
 ## What an agent can ask
 
-- List, fetch, create, update, and soft-delete test cases (with steps, custom fields, tags, folder breadcrumb, linked issues, and linked automated tests inline)
+- List, fetch, create (one at a time or many in a single bulk call), update, and soft-delete test cases (with steps, custom fields, tags, folder breadcrumb, linked issues, and linked automated tests inline)
+- List a project's templates and the case fields each defines, and choose which template a new case uses — custom fields are validated against that template
 - List and create test runs, add cases to existing runs, submit test results, and update run state
 - List sessions, session results, and session findings — the exploratory testing surface — and create or update sessions
 - Create and update milestones, mark them started or complete, and list milestone progress with pooled status rollups inline
@@ -19,7 +20,7 @@ The TestPlanIt MCP server lets AI agents — Claude Desktop, Cursor, custom MCP-
 - List code repositories configured in a project (with credentials never returned)
 - List folders and tags scoped to a project, with usage counts and tree relationships preserved
 
-See the [npm package README](https://www.npmjs.com/package/@testplanit/mcp-server) for the full tool reference, including request/response schemas for all 42 tools.
+See the [npm package README](https://www.npmjs.com/package/@testplanit/mcp-server) for the full tool reference, including request/response schemas for all 44 tools.
 
 ## Installation
 

docs/docs/sdk/mcp-prompts.md

@@ -165,6 +165,33 @@ Mark the login test case as passed in run 5.
 }
 ```
 
+## "Create these test cases from our checkout spec"
+
+```text
+Create these 20 test cases in project Acme under the "Checkout" folder using the
+"Regression" template — each has steps and a Priority.
+```
+
+**Tool calls (2–3):**
+
+1. (Optional) `testplanit_templates_list({ projectId: <P> })` → lists the project's enabled templates, each with the case fields it defines. The agent picks the right `templateId` and sees which custom fields (e.g. `Priority`) that template accepts.
+2. (Optional) `testplanit_folders_list({ projectId: <P> })` → resolves the "Checkout" folder id.
+3. `testplanit_cases_create_many({ projectId: <P>, folderId: <id>, templateId: <id>, cases: [ { name, steps, tags, customFields }, ... ] })` → creates all of them in one call. Each case may override `folderId`/`stateName`; `templateId` defaults to the project's first enabled template when omitted.
+
+**What comes back:** a per-case results array so partial failures are visible — each entry is either a success (with the new `caseId`) or an error (with a message). A custom field that isn't part of the chosen template is reported as a per-case error rather than silently dropped.
+
+```json
+{
+  "importedCount": 19,
+  "failedCount": 1,
+  "results": [
+    { "id": "0", "name": "Guest checkout — valid card", "status": "success", "caseId": 1201 },
+    { "id": "1", "name": "Checkout — expired card", "status": "error",
+      "error": "Custom field(s) not part of template \"Regression\": Severity." }
+  ]
+}
+```
+
 ## See also
 
 - [Overview](./mcp-overview.md) — what the MCP server does

packages/mcp-server/README.md

@@ -92,10 +92,17 @@ Your MCP client discovers each tool's full parameters automatically, so the list
 | --- | --- |
 | `testplanit_cases_list` | List and filter test cases in a project (by folder, tag, name, state, custom field, linked issue, automation, and more). |
 | `testplanit_cases_get` | Get a single test case with its fields and steps. |
-| `testplanit_cases_create` | Create a test case. |
-| `testplanit_cases_update` | Update a test case. |
+| `testplanit_cases_create` | Create a test case. Optionally pass `templateId` to choose a template (defaults to the project's first enabled template); custom fields are validated against the chosen template. |
+| `testplanit_cases_create_many` | Create many test cases in one call — far faster than per-case creates. Each case takes the same fields as a single create plus optional per-case `folderId`/`stateName`; returns a per-case success/failure result so partial failures are visible. |
+| `testplanit_cases_update` | Update a test case. Custom fields are validated against the case's template. |
 | `testplanit_cases_delete` | Delete a test case. |
 
+### Templates
+
+| Tool | Description |
+| --- | --- |
+| `testplanit_templates_list` | List a project's enabled templates, each with the case fields it defines (display name, system name, type, required) — use it to pick a `templateId` for case creation and to learn which custom fields a template accepts. |
+
 ### Folders
 
 | Tool | Description |

packages/mcp-server/src/api.ts

@@ -291,6 +291,48 @@ export async function resolveDefaultTemplate(
   return templates[0].id;
 }
 
+/**
+ * Resolve the template to use for a case create.
+ *
+ * When `templateId` is provided, verify it is an enabled, non-deleted template
+ * assigned to the project — throwing a 422 with a human-readable message when
+ * it is not, so the agent gets a clear "that template isn't available here"
+ * instead of a downstream foreign-key / policy error. When `templateId` is
+ * omitted, this falls back to `resolveDefaultTemplate` (first enabled template
+ * assigned to the project).
+ */
+export async function resolveTemplateForProject(
+  projectId: number,
+  env: EnvConfig,
+  templateId?: number,
+): Promise<number> {
+  if (templateId == null) {
+    return resolveDefaultTemplate(projectId, env);
+  }
+  const templates = await zenstack<{ id: number }[]>(
+    "templates",
+    "findMany",
+    {
+      where: {
+        id: templateId,
+        isDeleted: false,
+        isEnabled: true,
+        projects: { some: { projectId } },
+      },
+      select: { id: true },
+      take: 1,
+    },
+    env,
+  );
+  if (!templates || templates.length === 0) {
+    throw new TestPlanItHttpError(
+      `Template ${templateId} is not an enabled template assigned to project ${projectId}. Use testplanit_templates_list to see available templates.`,
+      { statusCode: 422 },
+    );
+  }
+  return templates[0].id;
+}
+
 /**
  * Resolve a workflow state for the CASES scope (NOT runs). Pass `name` to
  * select by name; omit to take the first by `order asc`.

packages/mcp-server/src/tools/cases/create.test.ts

@@ -10,7 +10,7 @@ vi.mock("../../api.js", () => ({
   zenstack: vi.fn(),
   lookup: vi.fn(),
   resolveActiveRepository: vi.fn(),
-  resolveDefaultTemplate: vi.fn(),
+  resolveTemplateForProject: vi.fn(),
   resolveCaseWorkflowState: vi.fn(),
 }));
 
@@ -38,7 +38,7 @@ import { registerCasesCreate } from "./create.js";
 const zenstackMock = vi.mocked(apiModule.zenstack);
 const lookupMock = vi.mocked(apiModule.lookup);
 const resolveActiveRepositoryMock = vi.mocked(apiModule.resolveActiveRepository);
-const resolveDefaultTemplateMock = vi.mocked(apiModule.resolveDefaultTemplate);
+const resolveTemplateForProjectMock = vi.mocked(apiModule.resolveTemplateForProject);
 const resolveCaseWorkflowStateMock = vi.mocked(apiModule.resolveCaseWorkflowState);
 const resolveCustomFieldsMock = vi.mocked(customFieldsModule.resolveCustomFields);
 const writeCustomFieldValuesMock = vi.mocked(customFieldsModule.writeCustomFieldValues);
@@ -90,7 +90,7 @@ beforeEach(() => {
 
   // Default happy-path mocks
   resolveActiveRepositoryMock.mockResolvedValue(11);
-  resolveDefaultTemplateMock.mockResolvedValue(22);
+  resolveTemplateForProjectMock.mockResolvedValue(22);
   resolveCaseWorkflowStateMock.mockResolvedValue({ id: 3, name: "Draft" });
   resolveCustomFieldsMock.mockResolvedValue([]);
   writeCustomFieldValuesMock.mockResolvedValue(undefined);
@@ -181,6 +181,7 @@ describe("testplanit_cases_create", () => {
 
     expect(resolveCustomFieldsMock).toHaveBeenCalledWith(
       { Priority: "High" },
+      22,
       env,
     );
     expect(writeCustomFieldValuesMock).toHaveBeenCalledWith(
@@ -203,6 +204,104 @@ describe("testplanit_cases_create", () => {
     expect(resolveCaseWorkflowStateMock).toHaveBeenCalledWith(7, env, "Active");
   });
 
+  it("default template: resolveTemplateForProject called with undefined templateId when omitted", async () => {
+    await callTool({ projectId: 7, folderId: 12, name: "Default template" });
+
+    expect(resolveTemplateForProjectMock).toHaveBeenCalledWith(7, env, undefined);
+    // The create body connects the resolved (default) template id 22.
+    const createCall = zenstackMock.mock.calls.find((c) => c[1] === "create");
+    const data = (createCall![2] as { data: Record<string, unknown> }).data;
+    expect(data.template).toEqual({ connect: { id: 22 } });
+  });
+
+  it("honors an explicit templateId by passing it to resolveTemplateForProject", async () => {
+    resolveTemplateForProjectMock.mockResolvedValueOnce(55);
+
+    await callTool({
+      projectId: 7,
+      folderId: 12,
+      name: "Pick template",
+      templateId: 55,
+    });
+
+    expect(resolveTemplateForProjectMock).toHaveBeenCalledWith(7, env, 55);
+    const createCall = zenstackMock.mock.calls.find((c) => c[1] === "create");
+    const data = (createCall![2] as { data: Record<string, unknown> }).data;
+    expect(data.template).toEqual({ connect: { id: 55 } });
+  });
+
+  it("surfaces 422 when an explicit templateId is not assigned/enabled for the project", async () => {
+    resolveTemplateForProjectMock.mockRejectedValueOnce(
+      new TestPlanItHttpError(
+        "Template 99 is not an enabled template assigned to project 7.",
+        { statusCode: 422 },
+      ),
+    );
+
+    const result = await callTool({
+      projectId: 7,
+      folderId: 12,
+      name: "bad template",
+      templateId: 99,
+    });
+
+    expect(result.isError).toBe(true);
+    const text = (result.content as Array<{ type: string; text: string }>)[0]!.text;
+    expect(text).toContain("Template 99");
+  });
+
+  it("rejects a custom field not on the chosen template (template-scoped resolver throws 422, pre-write)", async () => {
+    // The template-scoped resolver rejects an out-of-template field.
+    resolveCustomFieldsMock.mockRejectedValueOnce(
+      new TestPlanItHttpError(
+        "Custom field 'Component' is not part of the selected template.",
+        { statusCode: 422 },
+      ),
+    );
+
+    const result = await callTool({
+      projectId: 7,
+      folderId: 12,
+      name: "cf not in template",
+      customFields: { Component: "x" },
+    });
+
+    expect(result.isError).toBe(true);
+    const text = (result.content as Array<{ type: string; text: string }>)[0]!.text;
+    expect(text).toContain("Component");
+    expect(text).toContain("template");
+    // The case row must NOT have been created — resolution fires pre-write.
+    expect(zenstackMock.mock.calls.find((c) => c[1] === "create")).toBeUndefined();
+  });
+
+  it("resolves custom fields against the chosen template id, then writes them", async () => {
+    resolveTemplateForProjectMock.mockResolvedValueOnce(55);
+    resolveCustomFieldsMock.mockResolvedValueOnce([
+      { fieldId: 2, value: "High", name: "Priority" },
+    ]);
+
+    const result = await callTool({
+      projectId: 7,
+      folderId: 12,
+      name: "cf in template",
+      templateId: 55,
+      customFields: { Priority: "High" },
+    });
+
+    expect(result.isError).toBeFalsy();
+    // Custom-field resolution is scoped to the resolved template id (55).
+    expect(resolveCustomFieldsMock).toHaveBeenCalledWith(
+      { Priority: "High" },
+      55,
+      env,
+    );
+    expect(writeCustomFieldValuesMock).toHaveBeenCalledWith(
+      99,
+      [{ fieldId: 2, value: "High", name: "Priority" }],
+      env,
+    );
+  });
+
   it("surfaces 422 when no active repository found", async () => {
     resolveActiveRepositoryMock.mockRejectedValueOnce(
       new TestPlanItHttpError(

packages/mcp-server/src/tools/cases/create.ts

@@ -3,7 +3,7 @@ import * as z from "zod/v4";
 import {
   zenstack,
   resolveActiveRepository,
-  resolveDefaultTemplate,
+  resolveTemplateForProject,
   resolveCaseWorkflowState,
 } from "../../api.js";
 import type { EnvConfig } from "../../env.js";
@@ -31,6 +31,14 @@ export function registerCasesCreate(
         projectId: z.number().int().positive().describe("Project to create the case in."),
         folderId: z.number().int().positive().describe("Folder to place the case in."),
         name: z.string().min(1).max(2000).describe("Test case name."),
+        templateId: z
+          .number()
+          .int()
+          .positive()
+          .optional()
+          .describe(
+            "Template to use. Defaults to the project's first enabled template. Use testplanit_templates_list to see available templates and their fields.",
+          ),
         stateName: z
           .string()
           .min(1)
@@ -60,16 +68,25 @@ export function registerCasesCreate(
       try {
         // Pre-resolution: fail fast if project is misconfigured.
         const repositoryId = await resolveActiveRepository(input.projectId, deps.env);
-        const templateId = await resolveDefaultTemplate(input.projectId, deps.env);
+        // Honor an explicit templateId (validated against the project) or fall
+        // back to the project's default template when omitted.
+        const templateId = await resolveTemplateForProject(
+          input.projectId,
+          deps.env,
+          input.templateId,
+        );
         const state = await resolveCaseWorkflowState(
           input.projectId,
           deps.env,
           input.stateName,
         );
 
-        // Resolve tags and custom fields before the create write.
+        // Resolve custom fields against the chosen template — a field that
+        // isn't on the template is rejected (not silently dropped), and the
+        // template scope removes any global display-name ambiguity.
         const resolvedCustomFields = await resolveCustomFields(
           input.customFields,
+          templateId,
           deps.env,
         );
         const tagIds = await resolveTagIds(input.tags, deps.env);