@ign8t/mcp 0.3.1 → 0.4.0

package/README.md

@@ -9,7 +9,7 @@ Model Context Protocol (MCP) is an open standard that enables AI assistants to s
 - 📋 Access all your ign8t projects without switching contexts
 - 📄 Read master specs, feature specs, legacy PRP/BRD/PRD/TRD documents, and task specs
 - 📊 View and manage your backlog in real-time
-- 🧩 See which feature specs exist and which tasks still need specs
+- 🧩 See which feature specs exist and which tasks still need specs, and create a missing one after you approve its price
 - ✅ Update task statuses as you complete work
 - 🔍 Search across all tasks and projects
 - 🎯 Review, accept, or reject AI/backlog recommendations
@@ -155,6 +155,7 @@ Once configured, you can interact with ign8t naturally through your AI assistant
 "List the master spec, generated task specs, and missing specs"
 "Show me the feature spec for the authentication task"
 "Get all task specs for project [id]"
+"Create the missing spec for task [id]"
 ```
 
 ### Task Workflow
@@ -191,14 +192,15 @@ The MCP server also provides quick access to resources:
 | ------------------------ | ------------------------------------------------ | -------------------------------------------- |
 | `list_projects`          | List all projects with optional status filter    | "Show my active projects"                    |
 | `get_project`            | Get detailed project information                 | "Get details for project abc123"             |
-| `get_documents`          | Retrieve master spec, task specs, and legacy documents | "Show me the master spec for project xyz"    |
+| `get_documents`          | One document in full (`master_spec`, `brd`, `prd`, `trd`, `prp`, `task_spec:<task id>`); `all` or `task_spec` lists documents without text | "Show me the master spec for project xyz"    |
 | `get_backlog`            | View epics, stories, and tasks                   | "Display backlog including completed items"  |
 | `get_specs`              | List master, generated, and missing task specs   | "What specs are left?"                       |
-| `get_next_task`          | Next todo task (highest priority, then oldest) plus task spec preview | "What should I work on next?"                |
+| `get_next_task`          | The task to work on next (unfinished setup task, then the in-progress task to resume, then the next todo) with its full task spec and the project's rules | "What should I work on next?"                |
 | `create_task`            | Add a concrete task directly to backlog          | "Add a task for OAuth callback handling"     |
 | `update_task_status`     | Change task status with notes                    | "Set task 123 to blocked: waiting on API"    |
 | `search_tasks`           | Search across tasks                              | "Find all tasks mentioning 'payment'"        |
-| `get_task_context`       | Full task context with requirements              | "Show context for task 456"                  |
+| `get_task_context`       | One task with its full spec, the master spec and the project's rules | "Show context for task 456"                  |
+| `create_task_spec`       | Create a task's missing spec after you approve its price (Sparks) | "Create the spec for task 456"              |
 | `add_feature_request`    | Queue a feature idea as a backlog recommendation | "I want to add team invites next"            |
 | `list_recommendations`   | List queued backlog recommendations              | "Show pending feature recommendations"       |
 | `accept_recommendations` | Convert recommendations into tasks               | "Accept recommendations abc and def"         |
@@ -208,7 +210,22 @@ The MCP server also provides quick access to resources:
 | `update_context`         | Change the tech stack and constraints after you confirm the exact change | "We moved from Firebase to Supabase" |
 | `import_project`         | Import the local codebase into project context (28 Sparks) | "Import this codebase into project abc123" |
 
-The write tools (`create_task`, `update_task_status`, `accept_recommendations`, `reject_recommendations`, `add_feature_request`, `add_user_persona`, `update_success_criteria`, `update_context`) are free. Only `import_project` costs Sparks.
+The write tools (`create_task`, `update_task_status`, `accept_recommendations`, `reject_recommendations`, `add_feature_request`, `add_user_persona`, `update_success_criteria`, `update_context`) are free. Only `import_project` and `create_task_spec` cost Sparks. A change made with `add_user_persona`, `update_success_criteria` or `update_context` marks the project's previously generated documents out of date, and regenerating them costs Sparks, so the AI asks you before making one.
+
+### Working from the task spec
+
+`get_next_task` hands the AI the task to work on next: the project's setup task while it is unfinished, then the in-progress task updated most recently (so interrupted work resumes), then the next todo task. With it come the task's full spec and the project's rules (`implementation_guidance`). `get_task_context` returns the same for one task; the AI calls it before resuming a task after a pause.
+
+Each task spec has a state. A current spec is implemented as is. For an out-of-date one, the AI asks whether to regenerate it on the task board (costs Sparks) or go on with it. When a task's spec is missing or incomplete, the AI writes no production code for it until the spec exists or you tell it to go on without one. The same holds for a spec read with `get_documents` (the master spec or one task's spec).
+
+### Creating a missing task spec
+
+`create_task_spec` creates the spec of a task that has none, from your IDE.
+
+- **Cost:** the same Sparks as creating it on the task board. The AI first asks ign8t for the price (nothing is charged), tells you, and creates the spec only after you agree.
+- **Never charged twice:** if the answer is lost or the AI calls again, the spec already created is returned for free. While a spec is still being generated, another call is told to wait and is not charged. After a failed attempt has been refunded, retrying starts a new paid attempt. Follow the response for charge or recovery exceptions.
+- **Time:** usually about 45 seconds.
+- **An existing spec is never replaced:** it is returned for free. To regenerate an out-of-date or incomplete spec, use the task board.
 
 ### Updating the implementation context
 
@@ -304,6 +321,17 @@ For contributors working on the MCP server itself:
 2. Install dependencies: `pnpm install`
 3. Build the project: `pnpm build`
 4. Test locally: `pnpm dev --api-key your-key`
+5. Run the tests: `pnpm test` (builds, then runs `test/` against `dist/`)
+
+## Changelog
+
+### 0.4.0
+
+- New `create_task_spec`: create a task's missing spec from your IDE after you approve its price.
+- `get_next_task` and `get_task_context` describe the full hand-over: setup task first, then the in-progress task to resume, the full task spec with its state and what to do when it is not ready, and the project's rules.
+- `get_documents` no longer suggests `all` as its default: one document type returns the full text (including `task_spec:<task id>`); `all`, `task_spec` or no type returns a list without text.
+- `add_user_persona` and `update_success_criteria` tell the AI to ask you first, since a change marks generated documents out of date.
+- Requests identify the client as `ign8t-mcp/<version>`.
 
 ## Support
 

package/dist/index.js

@@ -3,7 +3,7 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { buildWorkspaceSnapshot } from "./workspace-snapshot.js";
-const VERSION = "0.3.1";
+const VERSION = "0.4.0";
 // Parse command line arguments
 function parseArgs() {
     const args = process.argv.slice(2);
@@ -78,12 +78,14 @@ async function describeApiError(response) {
     const message = `${typeof error === "string" ? error : "API error"} (HTTP ${response.status})`;
     return Object.keys(details).length ? `${message}\n${JSON.stringify(details, null, 2)}` : message;
 }
-// Helper function to call ign8t API
+// Helper function to call ign8t API. No timeout of its own: Node's fetch waits up to
+// 300 s for a response, and create_task_spec can take the server about 250 s.
 async function callIgn8tAPI(endpoint, data = {}) {
     const response = await fetch(`${API_URL}/api/mcp${endpoint}`, {
         method: "POST",
         headers: {
             "Content-Type": "application/json",
+            "User-Agent": `ign8t-mcp/${VERSION}`,
             "X-API-Key": API_KEY,
         },
         body: JSON.stringify(data),
@@ -135,7 +137,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: "get_documents",
-                description: "Get master specs, task specs, and legacy BRD/PRD/TRD documents for a project",
+                description: "Get a project's documents. One document type returns that document in full text: master_spec, brd, prd, trd, prp (legacy), or task_spec:<task id> for one task's spec; it comes with the project's rules (implementation_guidance, rules). A spec document (master_spec, task_spec:<id>) carries readiness.status: for draft, write no production code; for stale, ask the user whether to regenerate it (costs Sparks) or proceed. To implement a task, read it with get_task_context instead. all, task_spec, or no document_type returns only a list of documents (no text) with a hint on how to read one.",
                 inputSchema: {
                     type: "object",
                     properties: {
@@ -146,9 +148,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         },
                         document_type: {
                             type: "string",
-                            enum: ["master_spec", "prp", "brd", "prd", "trd", "task_spec", "all"],
-                            description: "Type of document to retrieve",
-                            default: "all",
+                            // A pattern, not an enum, so one task's spec (task_spec:<task id>) can be named.
+                            pattern: "^(master_spec|brd|prd|trd|prp|all|task_spec(:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})?)$",
+                            description: "master_spec, brd, prd, trd, prp or task_spec:<task id> for one document in full; all or task_spec for a list only",
                         },
                     },
                     required: ["project_id"],
@@ -315,7 +317,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: "get_next_task",
-                description: "Get the next todo task to work on (highest priority, then oldest), including its generated task spec when available.",
+                description: "Get the task to work on next, with what is needed to implement it. While the project's setup task is unfinished it comes first, since every other task depends on it; otherwise the most recently updated in-progress task is resumed (resume: true, other in-progress tasks in other_in_progress); otherwise the next todo task (highest priority, then oldest). Returns the task, its full spec in task_spec.content_text with task_spec.state (ready, stale, draft or missing), task_spec.instruction when the spec is not ready, and the project's rules (implementation_guidance, rules) to implement under. Follow task_spec.instruction exactly: for missing or draft, write no production code for the task; for stale, ask the user whether to regenerate the spec or proceed. A missing spec can also be created with create_task_spec once the user agrees to its price. later_decisions, when present, are accepted decisions the spec does not reflect yet: follow them where they differ. With no task, message says why and what to do next.",
                 inputSchema: {
                     type: "object",
                     properties: {
@@ -380,7 +382,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: "get_task_context",
-                description: "Get a task with its story, epic, its own task spec and the project's master spec",
+                description: "Get one task with what is needed to implement it: the task with its story and epic, its full spec and the project's master spec (documents), spec_state (ready, stale, draft or missing), a warning to follow when a spec is missing, a draft or out of date (the same rules as get_next_task's instruction), board_url, and the project's rules (implementation_guidance, rules). Call it before resuming work on a task after a pause, so you work from its current spec and rules. later_decisions, when present, are accepted decisions the spec does not reflect yet: follow them where they differ.",
                 inputSchema: {
                     type: "object",
                     properties: {
@@ -393,6 +395,31 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     required: ["task_id"],
                 },
             },
+            {
+                name: "create_task_spec",
+                description: "Create the spec for a task that has none (task_spec.state missing). It costs Sparks: call first with confirmed_with_user false, which charges nothing and answers with the price (error_code CONFIRMATION_REQUIRED, sparks_cost); tell the user the price, ask, and call again with confirmed_with_user true only after they agree. Calling again is safe: while the spec is being generated the answer is IN_PROGRESS and once it is saved EXISTS, both free; after a failed attempt was refunded, a new call starts a new paid attempt. It usually takes about 45 seconds, at most about 5 minutes. outcome says what happened: CREATED — the new spec is in content_text and the Sparks were charged; EXISTS — the task already has a spec, returned without a charge (this tool never replaces a spec; follow instruction: the user regenerates a draft one on the task board, and decides whether to regenerate a stale one there or proceed with it); IN_PROGRESS — the spec is being generated (by the board or an earlier call), nothing charged: call again with the same arguments in a minute or two, for up to 10 minutes if an earlier call was cut off; INSUFFICIENT_SPARKS — nothing charged, the user adds Sparks (billing_url) first; RECOVERY_PENDING — an earlier attempt's result is not confirmed yet, nothing new is charged: call again in a few minutes; FAILED — no spec was created and any charge was refunded unless the message says otherwise. Follow any returned instruction first, then implement from content_text under implementation_guidance; later_decisions, when present, are accepted decisions the spec does not reflect yet: follow them where they differ.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        project_id: {
+                            type: "string",
+                            format: "uuid",
+                            description: "The project ID",
+                        },
+                        task_id: {
+                            type: "string",
+                            format: "uuid",
+                            description: "The task whose spec is missing",
+                        },
+                        confirmed_with_user: {
+                            type: "boolean",
+                            description: "true only after the user was told the price and agreed to it; false returns the price without creating or charging anything",
+                        },
+                    },
+                    required: ["project_id", "task_id", "confirmed_with_user"],
+                    additionalProperties: false,
+                },
+            },
             {
                 name: "import_project",
                 description: "Import the local codebase into the ign8t project's context (AI extraction of product vision, users, features and tech stack). Costs 28 Sparks per new import; re-importing the same content (README, package.json name/description/script/dependency names, notable paths, primary language) is free while nothing else has changed the project context since the last import. Uploads only: the README (first 6000 characters), the package.json name (or the folder name when it has none), description, script names and dependency names, up to 120 notable file paths, the file count and the primary language guessed from file extensions — never other file contents or environment values.",
@@ -474,7 +501,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: "add_user_persona",
-                description: "Add a new user persona discovered during development. Enriches the project context with detailed user information. Adding a persona with an existing name replaces that persona.",
+                description: "Add a new user persona discovered during development. Enriches the project context with detailed user information. Adding a persona with an existing name replaces that persona. Changing the project context marks the previously generated documents (BRD/PRD/TRD, delivery brief, master spec, task specs) as out of date, and regenerating them costs Sparks: before calling, show the user the exact persona and tell them this, and call only after the user agreed. Resending a saved persona unchanged changes nothing.",
                 inputSchema: {
                     type: "object",
                     properties: {
@@ -536,7 +563,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: "update_success_criteria",
-                description: "Add or update success criteria and metrics for the project. Helps define how success will be measured. A criterion with an existing metric name replaces that criterion.",
+                description: "Add or update success criteria and metrics for the project. Helps define how success will be measured. A criterion with an existing metric name replaces that criterion. Changing the project context marks the previously generated documents (BRD/PRD/TRD, delivery brief, master spec, task specs) as out of date, and regenerating them costs Sparks: before calling, show the user the exact criteria and tell them this, and call only after the user agreed. Resending saved criteria unchanged changes nothing.",
                 inputSchema: {
                     type: "object",
                     properties: {
@@ -683,6 +710,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
             case "get_task_context":
                 result = await callIgn8tAPI("/tasks/context", args);
                 break;
+            case "create_task_spec":
+                result = await callIgn8tAPI("/tasks/spec/create", args);
+                break;
             case "import_project": {
                 const { snapshot, unreadableDirectories, fileLimitReached } = await buildWorkspaceSnapshot(args?.workspace_path);
                 // The upload is what charges Sparks: a call the user cancelled while the folder

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ign8t/mcp",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "MCP server for ign8t project management - AI IDE integration",
   "type": "module",
   "main": "dist/index.js",
@@ -18,7 +18,7 @@
     "dev": "tsx src/index.ts",
     "dev:help": "tsx src/index.ts --help",
     "clean": "rm -rf dist",
-    "test": "node debug-mcp.js",
+    "test": "pnpm build && node --test test/index.test.mjs",
     "test:local": "node dist/index.js --help",
     "link:local": "npm link",
     "unlink:local": "npm unlink -g @ign8t/mcp",
@@ -38,7 +38,7 @@
   "mcp": {
     "name": "ign8t-mcp",
     "description": "MCP server for ign8t project management - AI IDE integration",
-    "version": "0.3.1"
+    "version": "0.4.0"
   },
   "author": "nocodecat",
   "license": "MIT",