testchimp-mcp-client 0.0.1 → 0.0.2

package/README.md

@@ -13,11 +13,24 @@ MCP (Model Context Protocol) server for [TestChimp](https://testchimp.io). Expos
 
 - **`get_requirement_coverage`** — POST `/api/mcp/list_requirement_coverage` (scenario / requirement coverage scoped by platform-rooted `scope.folderPath` under **`tests/...`** or **`plans/...`**).
 - **`get_execution_history`** — POST `/api/mcp/list_execution_history`.
-- **`get_test_advice`** — POST `/api/mcp/get_test_advice` (stub until PR analysis ships).
+- **`create_user_story`** — POST `/api/mcp/create_user_story` (`platformFilePath` under `plans/stories/...`, `title`).
+- **`create_test_scenario`** — POST `/api/mcp/create_test_scenario` (`platformFilePath` under `plans/scenarios/...`, `title`, `userStoryOrdinalId`).
+- **`update_user_story`** — POST `/api/mcp/update_user_story` (full markdown `content` with `id: US-...` in frontmatter).
+- **`update_test_scenario`** — POST `/api/mcp/update_test_scenario` (full markdown `content` with `id: TS-...` and `story: US-...` in frontmatter).
 
 ## Cursor
 
-Add to MCP config (e.g. `~/.cursor/mcp.json`):
+**Install only at project level.** TestChimp API keys are **scoped to a TestChimp project**; the MCP server must use the key for **the repo you have open**. Do **not** add this server to **IDE-wide** MCP config (`~/.cursor/mcp.json` or global Cursor MCP settings): you risk using the wrong key when switching workspaces, and agents may target the wrong backend project.
+
+**For humans and AI agents:** create or edit **`<project-root>/.cursor/mcp.json`** in the repository you are working in (the folder Cursor has open as the workspace root). That path is **`.cursor/mcp.json` relative to the project root**, not under your home directory.
+
+The MCP server reads **`TESTCHIMP_API_KEY`** and **`TESTCHIMP_BACKEND_URL`** from **`process.env`** — it does not read `mcp.json` directly. Cursor starts the server as a **child process**; variables must be present in **that** process’s environment.
+
+**Why `mcp.json` uses an `env` block:** If you open Cursor from the Dock, Spotlight, or similar, it usually does **not** load your shell profile (`.zshrc`, etc.), so values you only `export` in a terminal may **not** reach the MCP server. The `env` object next to `command` / `args` is the reliable way Cursor injects variables into the MCP process. (Cursor’s `mcp.json` does **not** expand `$VAR` / `${VAR}` from your shell; use literal values in `env`, or a wrapper that loads a `.env` file before starting the server.)
+
+### Project `mcp.json` example
+
+`<project-root>/.cursor/mcp.json`:
 
 ```json
 {
@@ -34,6 +47,9 @@ Add to MCP config (e.g. `~/.cursor/mcp.json`):
 }
 ```
 
+- **Do not commit secrets:** Add `.cursor/mcp.json` to **`.gitignore`** if it contains real keys, or keep only a committed `.cursor/mcp.json.example` with placeholders and document that each developer maintains a local ignored file.
+- **After changing env or config:** Restart the MCP server or reload MCP / restart Cursor so the new environment is picked up.
+
 For a published npm package name, adjust `args` to your scope (e.g. `@testchimp/mcp-client`) after publish.
 
 ## Scope path format

package/dist/index.js

@@ -16,7 +16,7 @@ function getBackendUrl() {
 function requireApiKey() {
     const k = process.env.TESTCHIMP_API_KEY?.trim();
     if (!k) {
-        throw new Error("TESTCHIMP_API_KEY is required. Set it in the MCP server env (e.g. Cursor mcp.json).");
+        throw new Error("TESTCHIMP_API_KEY is required. Set it in <project>/.cursor/mcp.json env (project-level MCP config), not IDE-wide config.");
     }
     return k;
 }
@@ -59,11 +59,20 @@ const listExecutionInput = z.object({
     scope: scopeSchema,
     branchName: z.string().optional(),
 });
-const testAdviceInput = z.object({
-    branchName: z.string().optional(),
-    prUrl: z.string().optional(),
-    baseSha: z.string().optional(),
-    headSha: z.string().optional(),
+/** Platform path to the new markdown file, e.g. plans/stories/auth/login-flow.md */
+const createUserStoryInput = z.object({
+    platformFilePath: z.string().min(1),
+    title: z.string().min(1),
+});
+const createTestScenarioInput = z.object({
+    platformFilePath: z.string().min(1),
+    title: z.string().min(1),
+    /** Parent story ordinal (the number n in US-n). */
+    userStoryOrdinalId: z.coerce.number().int().positive(),
+});
+const updatePlanMarkdownInput = z.object({
+    /** Full markdown including YAML frontmatter and body (as written under the repo plans root). */
+    content: z.string().min(1),
 });
 function textResult(json) {
     return {
@@ -133,21 +142,45 @@ async function main() {
         const json = await postMcp("/api/mcp/list_execution_history", body);
         return textResult(json);
     });
-    server.registerTool("get_test_advice", {
-        description: "Placeholder for PR-scoped test advice. Returns not_implemented until the backend provides analysis.",
-        inputSchema: testAdviceInput,
+    server.registerTool("create_user_story", {
+        description: "Create a user story on the TestChimp project and its plan file stub. " +
+            "Always call this before writing a new story markdown file; use the returned ordinalId as US-<ordinalId> in frontmatter. " +
+            "platformFilePath must be under plans/stories/ and end with .md.",
+        inputSchema: createUserStoryInput,
     }, async (args) => {
-        const body = {};
-        if (args.branchName != null && args.branchName.trim() !== "") {
-            body.branchName = args.branchName.trim();
-        }
-        if (args.prUrl != null)
-            body.pr_url = args.prUrl;
-        if (args.baseSha != null)
-            body.base_sha = args.baseSha;
-        if (args.headSha != null)
-            body.head_sha = args.headSha;
-        const json = await postMcp("/api/mcp/get_test_advice", body);
+        const json = await postMcp("/api/mcp/create_user_story", {
+            platformFilePath: args.platformFilePath,
+            title: args.title,
+        });
+        return textResult(json);
+    });
+    server.registerTool("create_test_scenario", {
+        description: "Create a test scenario linked to a user story. Call after the parent story exists. " +
+            "platformFilePath must be under plans/scenarios/ and end with .md. " +
+            "userStoryOrdinalId is the numeric part of the parent US-<n> id.",
+        inputSchema: createTestScenarioInput,
+    }, async (args) => {
+        const json = await postMcp("/api/mcp/create_test_scenario", {
+            platformFilePath: args.platformFilePath,
+            title: args.title,
+            userStoryOrdinalId: args.userStoryOrdinalId,
+        });
+        return textResult(json);
+    });
+    server.registerTool("update_user_story", {
+        description: "Sync a user story markdown file to the platform after local edits. " +
+            "Parses frontmatter (id: US-..., title, priority, status) and updates the linked support file and entity.",
+        inputSchema: updatePlanMarkdownInput,
+    }, async (args) => {
+        const json = await postMcp("/api/mcp/update_user_story", { content: args.content });
+        return textResult(json);
+    });
+    server.registerTool("update_test_scenario", {
+        description: "Sync a test scenario markdown file to the platform after local edits. " +
+            "Parses frontmatter (id: TS-..., story: US-..., title, priority, status) and updates linking if story changes.",
+        inputSchema: updatePlanMarkdownInput,
+    }, async (args) => {
+        const json = await postMcp("/api/mcp/update_test_scenario", { content: args.content });
         return textResult(json);
     });
     const transport = new StdioServerTransport();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "testchimp-mcp-client",
-  "version": "0.0.1",
-  "description": "MCP server for TestChimp — requirement coverage, execution history, and test advice (stub)",
+  "version": "0.0.2",
+  "description": "MCP server for TestChimp — coverage, execution history, and plan authoring",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",