@ign8t/mcp 0.1.2 → 0.3.0

package/README.md

@@ -7,11 +7,14 @@ Seamlessly integrate ign8t project management into your AI-powered development w
 Model Context Protocol (MCP) is an open standard that enables AI assistants to securely access external tools and data sources. With the ign8t MCP server, your AI assistant can:
 
 - 📋 Access all your ign8t projects without switching contexts
-- 📄 Read BRD, PRD, and TRD documents to understand requirements
+- 📄 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
 - ✅ Update task statuses as you complete work
 - 🔍 Search across all tasks and projects
-- 🎯 Get AI-powered task recommendations
+- 🎯 Review, accept, or reject AI/backlog recommendations
+- ➕ Add newly discovered tasks or feature requests from your IDE
+- 📥 Import your local codebase into the project context
 - 🧠 Access full context including related requirements and documentation
 
 ## Quick Start
@@ -24,7 +27,7 @@ pnpm install -g @ign8t/mcp
 
 ### 2. Get Your API Key
 
-1. Log in to [ign8t.com](https://ign8t.com)
+1. Log in to [ign8t.com](https://www.ign8t.com)
 2. Navigate to **Settings → API Keys**
 3. Click **"Create New API Key"**
 4. Give it a descriptive name (e.g., "Cursor Integration")
@@ -35,7 +38,7 @@ pnpm install -g @ign8t/mcp
 <details>
 <summary><strong>Cursor IDE (Recommended - using npx)</strong></summary>
 
-Add to `~/.cursor/mcp/settings.json`:
+Add to `~/.cursor/mcp.json`:
 
 ```json
 {
@@ -140,8 +143,18 @@ Once configured, you can interact with ign8t naturally through your AI assistant
 ```
 "Show me all my active projects"
 "Get details about the [project name] project"
-"Show me the BRD for [project name]"
+"Show me the master spec for [project name]"
 "Display all documents for my current project"
+"Import this codebase into project [id]"
+```
+
+### Specs Workflow
+
+```
+"What specs are left for this project?"
+"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]"
 ```
 
 ### Task Workflow
@@ -153,6 +166,16 @@ Once configured, you can interact with ign8t naturally through your AI assistant
 "Update task [id] to in_progress"
 "Mark task [id] as done with note: 'Implemented OAuth2'"
 "Get full context for task [id]"
+"Add a task for rate limiting the public API"
+```
+
+### Recommendation Workflow
+
+```
+"I want to add Stripe billing next"
+"List pending recommendations"
+"Accept recommendation [id] and create a task"
+"Reject recommendation [id]"
 ```
 
 ### Resources
@@ -164,26 +187,57 @@ The MCP server also provides quick access to resources:
 
 ## Available Tools Reference
 
-| Tool                 | Description                                   | Example Use                                 |
-| -------------------- | --------------------------------------------- | ------------------------------------------- |
-| `list_projects`      | List all projects with optional status filter | "Show my archived projects"                 |
-| `get_project`        | Get detailed project information              | "Get details for project abc123"            |
-| `get_documents`      | Retrieve BRD, PRD, TRD documents              | "Show me the PRD for project xyz"           |
-| `get_backlog`        | View epics, stories, and tasks                | "Display backlog including completed items" |
-| `get_next_task`      | AI-recommended next task                      | "What should I work on next?"               |
-| `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"                 |
+| Tool                     | Description                                      | Example Use                                  |
+| ------------------------ | ------------------------------------------------ | -------------------------------------------- |
+| `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_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?"                |
+| `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"                  |
+| `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"         |
+| `reject_recommendations` | Reject recommendations                           | "Reject this duplicate recommendation"       |
+| `add_user_persona`       | Add or replace a user persona in context         | "Add admin operator persona"                 |
+| `update_success_criteria`| Add or update measurable success criteria        | "Add activation-rate target"                 |
+| `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.
+
+### Updating the implementation context
+
+`update_context` lets the project owner's AI change what ign8t knows about the implementation: the tech stack's platform and framework (set or unset), its databases and AI models, and the project constraints (add or remove items: added values are trimmed, removed values must match the stored text exactly). Vision, features, users and success criteria are not writable through it.
+
+- The AI reads the project with `get_project` first, shows you the exact change, and applies it only after you agree. The change is saved immediately and costs no Sparks.
+- All previously generated documents (BRD/PRD/TRD, delivery brief, master spec, task specs) may be marked stale. They are not regenerated automatically, and regenerating them costs Sparks.
+- If the context changed since the AI read it, nothing is saved: the AI reads it again and asks you again.
+
+### Importing a local codebase
+
+`import_project` takes the project ID and the **absolute** path of your project folder, and fills the project's context (vision, users, features, tech stack) using ign8t's AI extraction. Results are written in Korean by default; pass `locale: "en"` for English.
+
+- **Cost:** 28 Sparks per new import. Re-importing the same content (README, package.json name, description, script and dependency names, notable paths, primary language) is free as long as nothing else has changed the project context since that import; after an edit in ign8t or another import, it runs (and is charged) again so the context is restored. When the import reports a failure, nothing is saved and the Sparks are refunded; the error's `refund_status` says when a refund needs manual follow-up. If the connection drops before any answer arrives, check the project in ign8t before retrying: a retry of an import that was already saved is free, but one whose charge went through without a save is charged again.
+- **What is uploaded:** the README (first 6,000 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 (for example `src/`, `app/`, `supabase/`), the file count and the primary language guessed from file extensions. Nothing else: no other file contents and no environment values.
+- **What is skipped:** hidden folders (`.git`, `.next`, `.venv`, ...), `node_modules`, build output (`dist`, `build`, `out`, ...), `vendor`, `Pods`, Python virtual environments (any folder with `pyvenv.cfg`), folders nested more than 12 levels deep, and folders you cannot read (listed in the result). The walk stops after 20,000 files and says so. Symbolic links inside the folder are not followed.
 
 ## Workflow Integration
 
 The ign8t MCP server is designed to fit seamlessly into your development workflow:
 
 1. **Start your day**: "What are my current tasks?"
-2. **Get context**: "Show me the requirements for this task"
-3. **Update progress**: "Mark this task as in progress"
-4. **Search when stuck**: "Find similar tasks I've completed"
-5. **Complete work**: "Mark task as done and get my next task"
+2. **Find the next build unit**: "What task should I work on next?"
+3. **Check spec coverage**: "What specs are left?"
+4. **Get context**: "Show me the task context and master spec"
+5. **Add discovered work**: "Queue a recommendation for webhook retry support"
+6. **Accept planned work**: "Accept that recommendation and create a task"
+7. **Update progress**: "Mark this task as in progress"
+8. **Complete work**: "Mark task as done and get my next task"
 
 ## Troubleshooting
 
@@ -218,22 +272,20 @@ The ign8t MCP server is designed to fit seamlessly into your development workflo
 
 ### Custom API Endpoint (Optional)
 
-The MCP server connects to `https://ign8t.com` by default. For enterprise deployments, self-hosted instances, or local development, you can override the API endpoint:
-
-**Using npx (Recommended):**
+The MCP server connects to `https://www.ign8t.com` by default. For enterprise deployments, self-hosted instances, or local development, you can override the API endpoint with `--api-url`:
 
 ```json
 {
   "mcpServers": {
     "ign8t": {
       "command": "npx",
-      "args": ["-y", "@ign8t/mcp@latest", "--api-key", "your-api-key"]
+      "args": ["-y", "@ign8t/mcp@latest", "--api-key", "your-api-key", "--api-url", "http://localhost:3000"]
     }
   }
 }
 ```
 
-````
+Or set `IGN8T_API_URL` in the `env` block of the same IDE configuration. A `.env` file in your workspace is not read.
 
 **Note**: Most users don't need to set a custom API URL. It's only required if you're:
 
@@ -250,32 +302,8 @@ For contributors working on the MCP server itself:
 3. Build the project: `pnpm build`
 4. Test locally: `pnpm dev --api-key your-key`
 
-## Contributing
-
-We welcome contributions! If you'd like to contribute to the ign8t MCP server:
-
-### Development Setup
-
-```bash
-# Clone the repository
-git clone https://github.com/ign8t/mcp-server.git
-cd mcp-server
-
-# Install dependencies
-pnpm install
-
-# Run tests
-pnpm test
-
-# Build
-pnpm build
-````
-
 ## Support
 
-- 📚 **Documentation**: [docs.ign8t.com/mcp](https://docs.ign8t.com/mcp)
-- 🐛 **Issues**: [GitHub Issues](https://github.com/ign8t/mcp-server/issues)
-- 💬 **Community**: [Discord](https://discord.gg/ign8t)
 - 📧 **Email**: support@ign8t.com
 
 ## License

package/dist/index.js

@@ -2,9 +2,8 @@
 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 * as dotenv from "dotenv";
-// Load environment variables
-dotenv.config();
+import { buildWorkspaceSnapshot } from "./workspace-snapshot.js";
+const VERSION = "0.3.0";
 // Parse command line arguments
 function parseArgs() {
     const args = process.argv.slice(2);
@@ -28,10 +27,10 @@ Usage: ign8t-mcp --api-key <key> [--api-url <url>]
 
 Options:
   --api-key <key>    Your ign8t API key (required)
-  --api-url <url>    Custom API URL (optional, defaults to https://ign8t.com)
+  --api-url <url>    Custom API URL (optional, defaults to https://www.ign8t.com)
   --help, -h         Show this help message
 
-Get your API key from: https://ign8t.com/settings/api-keys
+Get your API key from: https://www.ign8t.com/settings/api-keys
         `);
                 process.exit(0);
                 break;
@@ -41,19 +40,19 @@ Get your API key from: https://ign8t.com/settings/api-keys
 }
 // Configuration
 const config = parseArgs();
-const API_KEY = config.apiKey;
-const API_URL = config.apiUrl || "https://ign8t.com";
+const API_KEY = config.apiKey || process.env.IGN8T_API_KEY;
+const API_URL = config.apiUrl || process.env.IGN8T_API_URL || "https://www.ign8t.com";
 if (!API_KEY) {
     console.error("Error: API key is required");
     console.error("Usage: ign8t-mcp --api-key <your-api-key>");
     console.error("Or set IGN8T_API_KEY environment variable");
-    console.error("Get your API key from https://ign8t.com/settings/api-keys");
+    console.error("Get your API key from https://www.ign8t.com/settings/api-keys");
     process.exit(1);
 }
 // Create MCP server instance
 const server = new Server({
     name: "ign8t-mcp",
-    version: "1.0.0",
+    version: VERSION,
     description: "ign8t project management integration for AI IDEs",
     author: "nocodecat",
     homepage: "https://www.ign8t.com",
@@ -69,30 +68,37 @@ const server = new Server({
         logging: {},
     },
 });
+// Turn a non-2xx response into a message the calling AI can act on: the
+// server's `error` plus its structured fields (error_code, refund_status, ...).
+async function describeApiError(response) {
+    if (!response.headers.get("content-type")?.includes("application/json")) {
+        return `${(await response.text()) || "API error"} (HTTP ${response.status})`;
+    }
+    const { success: _success, error, ...details } = await response.json();
+    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
 async function callIgn8tAPI(endpoint, data = {}) {
-    try {
-        const response = await fetch(`${API_URL}/api/mcp${endpoint}`, {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                "X-API-Key": API_KEY,
-            },
-            body: JSON.stringify(data),
-        });
-        if (!response.ok) {
-            const error = await response.text();
-            throw new Error(error || `API error: ${response.status}`);
-        }
-        return response.json();
-    }
-    catch (error) {
-        if (error instanceof Error) {
-            throw error;
-        }
-        throw new Error("Failed to connect to ign8t API");
+    const response = await fetch(`${API_URL}/api/mcp${endpoint}`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "X-API-Key": API_KEY,
+        },
+        body: JSON.stringify(data),
+    });
+    if (!response.ok) {
+        throw new Error(await describeApiError(response));
     }
+    return response.json();
 }
+// update_context's add/remove of list items, each at most maxLength characters; the
+// 20-operation cap is on the whole patch (see its description).
+const listOps = (maxLength) => {
+    const items = { type: "array", items: { type: "string", minLength: 1, maxLength } };
+    return { type: "object", properties: { add: items, remove: items }, additionalProperties: false };
+};
 // Define available tools
 server.setRequestHandler(ListToolsRequestSchema, async () => {
     return {
@@ -120,6 +126,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     properties: {
                         project_id: {
                             type: "string",
+                            format: "uuid",
                             description: "The project ID",
                         },
                     },
@@ -128,17 +135,18 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: "get_documents",
-                description: "Get BRD, PRD, and TRD documents for a project",
+                description: "Get master specs, task specs, and legacy BRD/PRD/TRD documents for a project",
                 inputSchema: {
                     type: "object",
                     properties: {
                         project_id: {
                             type: "string",
+                            format: "uuid",
                             description: "The project ID",
                         },
                         document_type: {
                             type: "string",
-                            enum: ["brd", "prd", "trd", "all"],
+                            enum: ["master_spec", "prp", "brd", "prd", "trd", "task_spec", "all"],
                             description: "Type of document to retrieve",
                             default: "all",
                         },
@@ -154,6 +162,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     properties: {
                         project_id: {
                             type: "string",
+                            format: "uuid",
                             description: "The project ID",
                         },
                         include_completed: {
@@ -166,18 +175,154 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 },
             },
             {
-                name: "get_next_task",
-                description: "Get the next recommended task to work on",
+                name: "get_specs",
+                description: "List the master spec, generated feature specs, and tasks that still need specs for a project. Use this to answer what specs are left.",
                 inputSchema: {
                     type: "object",
                     properties: {
                         project_id: {
                             type: "string",
+                            format: "uuid",
                             description: "The project ID",
                         },
-                        context: {
+                        include_generated: {
+                            type: "boolean",
+                            description: "Include specs that already exist",
+                            default: true,
+                        },
+                        include_missing: {
+                            type: "boolean",
+                            description: "Include backlog tasks without generated specs",
+                            default: true,
+                        },
+                    },
+                    required: ["project_id"],
+                },
+            },
+            {
+                name: "create_task",
+                description: "Add a new implementation task to a project's backlog from the IDE. Use this when you discover missing work or the user asks to add a feature/task.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        project_id: {
+                            type: "string",
+                            format: "uuid",
+                            description: "The project ID",
+                        },
+                        title: {
+                            type: "string",
+                            minLength: 3,
+                            maxLength: 200,
+                            description: "Short task title",
+                        },
+                        description: {
                             type: "string",
-                            description: "Optional context about what you want to work on",
+                            maxLength: 10000,
+                            description: "Detailed task description",
+                        },
+                        priority: {
+                            type: "string",
+                            enum: ["critical", "high", "medium", "low"],
+                            description: "Task priority",
+                            default: "medium",
+                        },
+                        status: {
+                            type: "string",
+                            enum: ["todo", "in_progress", "review", "done", "blocked"],
+                            description: "Initial task status",
+                            default: "todo",
+                        },
+                        acceptance_criteria: {
+                            type: "array",
+                            items: { type: "string", minLength: 1, maxLength: 500 },
+                            maxItems: 30,
+                            description: "Acceptance criteria for the task",
+                        },
+                        technical_details: {
+                            type: "string",
+                            maxLength: 10000,
+                            description: "Implementation notes or technical requirements",
+                        },
+                    },
+                    required: ["project_id", "title"],
+                },
+            },
+            {
+                name: "list_recommendations",
+                description: "List backlog recommendations queued for review. Use this after adding feature requests or when deciding what to build next.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        project_id: {
+                            type: "string",
+                            format: "uuid",
+                            description: "The project ID",
+                        },
+                        status: {
+                            type: "string",
+                            enum: ["pending", "accepted", "rejected", "expired", "all"],
+                            description: "Recommendation status to list",
+                            default: "pending",
+                        },
+                    },
+                    required: ["project_id"],
+                },
+            },
+            {
+                name: "accept_recommendations",
+                description: "Accept pending backlog recommendations and create concrete tasks from them.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        project_id: {
+                            type: "string",
+                            format: "uuid",
+                            description: "The project ID",
+                        },
+                        recommendation_ids: {
+                            type: "array",
+                            items: { type: "string", format: "uuid" },
+                            minItems: 1,
+                            maxItems: 50,
+                            description: "Recommendation IDs to accept",
+                        },
+                    },
+                    required: ["project_id", "recommendation_ids"],
+                },
+            },
+            {
+                name: "reject_recommendations",
+                description: "Reject pending backlog recommendations so they no longer appear as work candidates.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        project_id: {
+                            type: "string",
+                            format: "uuid",
+                            description: "The project ID",
+                        },
+                        recommendation_ids: {
+                            type: "array",
+                            items: { type: "string", format: "uuid" },
+                            minItems: 1,
+                            maxItems: 50,
+                            description: "Recommendation IDs to reject",
+                        },
+                    },
+                    required: ["project_id", "recommendation_ids"],
+                },
+            },
+            {
+                name: "get_next_task",
+                description: "Get the next todo task to work on (highest priority, then oldest), including its generated task spec when available.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        project_id: {
+                            type: "string",
+                            format: "uuid",
+                            description: "The project ID",
                         },
                     },
                     required: ["project_id"],
@@ -191,6 +336,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     properties: {
                         task_id: {
                             type: "string",
+                            format: "uuid",
                             description: "The task ID",
                         },
                         status: {
@@ -200,6 +346,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         },
                         notes: {
                             type: "string",
+                            maxLength: 10000,
                             description: "Optional notes about the status change",
                         },
                     },
@@ -218,6 +365,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         },
                         project_id: {
                             type: "string",
+                            format: "uuid",
                             description: "Optional: limit search to specific project",
                         },
                         status: {
@@ -232,23 +380,268 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: "get_task_context",
-                description: "Get full context for a task including related BRD/PRD/TRD sections",
+                description: "Get a task with its story, epic, its own task spec and the project's master spec",
                 inputSchema: {
                     type: "object",
                     properties: {
                         task_id: {
                             type: "string",
+                            format: "uuid",
                             description: "The task ID",
                         },
                     },
                     required: ["task_id"],
                 },
             },
+            {
+                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.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        project_id: {
+                            type: "string",
+                            format: "uuid",
+                            description: "The ign8t project ID to import into",
+                        },
+                        workspace_path: {
+                            type: "string",
+                            description: "Absolute path to the project root directory",
+                        },
+                        locale: {
+                            type: "string",
+                            enum: ["ko", "en"],
+                            description: "Language of the extracted context",
+                            default: "ko",
+                        },
+                    },
+                    required: ["project_id", "workspace_path"],
+                },
+            },
+            // ===== BIDIRECTIONAL CONTEXT UPDATE TOOLS =====
+            {
+                name: "add_feature_request",
+                description: "Request a new feature spec candidate discovered during development. This queues the idea for product-owner review before implementation.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        project_id: {
+                            type: "string",
+                            format: "uuid",
+                            description: "The project ID",
+                        },
+                        feature: {
+                            type: "object",
+                            properties: {
+                                name: {
+                                    type: "string",
+                                    minLength: 1,
+                                    maxLength: 200,
+                                    description: "Feature name (e.g., 'OAuth Social Login')",
+                                },
+                                description: {
+                                    type: "string",
+                                    minLength: 1,
+                                    maxLength: 5000,
+                                    description: "Detailed feature description",
+                                },
+                                user_story: {
+                                    type: "string",
+                                    minLength: 1,
+                                    maxLength: 2000,
+                                    description: "User story (As a... I want... So that...)",
+                                },
+                                priority: {
+                                    type: "string",
+                                    enum: ["critical", "high", "medium", "low"],
+                                    description: "Feature priority",
+                                },
+                                estimated_complexity: {
+                                    type: "string",
+                                    enum: ["simple", "moderate", "complex"],
+                                    description: "Estimated implementation complexity",
+                                },
+                            },
+                            required: ["name", "description", "user_story"],
+                        },
+                        related_context: {
+                            type: "object",
+                            description: "Additional context for spec definition (optional, at most 10000 characters as JSON)",
+                        },
+                    },
+                    required: ["project_id", "feature"],
+                },
+            },
+            {
+                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.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        project_id: {
+                            type: "string",
+                            format: "uuid",
+                            description: "The project ID",
+                        },
+                        persona: {
+                            type: "object",
+                            properties: {
+                                name: {
+                                    type: "string",
+                                    minLength: 1,
+                                    maxLength: 100,
+                                    description: "Persona name (e.g., 'Sarah - Operations Manager')",
+                                },
+                                role: {
+                                    type: "string",
+                                    minLength: 1,
+                                    maxLength: 200,
+                                    description: "User role or job title",
+                                },
+                                demographics: {
+                                    type: "object",
+                                    properties: {
+                                        age: { type: "string", maxLength: 100 },
+                                        tech_savviness: {
+                                            type: "string",
+                                            enum: ["beginner", "intermediate", "advanced"],
+                                        },
+                                        industry: { type: "string", maxLength: 100 },
+                                    },
+                                },
+                                goals: {
+                                    type: "array",
+                                    items: { type: "string", minLength: 1, maxLength: 500 },
+                                    maxItems: 20,
+                                    description: "User goals and objectives",
+                                },
+                                pain_points: {
+                                    type: "array",
+                                    items: { type: "string", minLength: 1, maxLength: 500 },
+                                    maxItems: 20,
+                                    description: "User pain points and frustrations",
+                                },
+                                use_cases: {
+                                    type: "array",
+                                    items: { type: "string", minLength: 1, maxLength: 500 },
+                                    maxItems: 20,
+                                    description: "Specific use cases for this persona",
+                                },
+                            },
+                            required: ["name", "role", "goals", "pain_points"],
+                        },
+                    },
+                    required: ["project_id", "persona"],
+                },
+            },
+            {
+                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.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        project_id: {
+                            type: "string",
+                            format: "uuid",
+                            description: "The project ID",
+                        },
+                        criteria: {
+                            type: "array",
+                            minItems: 1,
+                            maxItems: 20,
+                            items: {
+                                type: "object",
+                                properties: {
+                                    metric: {
+                                        type: "string",
+                                        minLength: 1,
+                                        maxLength: 200,
+                                        pattern: "^[^:]*$",
+                                        description: "What to measure, without ':' (e.g., 'User sign-up rate')",
+                                    },
+                                    target: {
+                                        type: "string",
+                                        minLength: 1,
+                                        maxLength: 200,
+                                        description: "Target value (e.g., '80% of visitors')",
+                                    },
+                                    priority: {
+                                        type: "string",
+                                        enum: ["must-have", "nice-to-have"],
+                                        description: "Metric priority",
+                                    },
+                                    measurement_method: {
+                                        type: "string",
+                                        maxLength: 500,
+                                        description: "How this will be measured (optional)",
+                                    },
+                                },
+                                required: ["metric", "target", "priority"],
+                            },
+                        },
+                    },
+                    required: ["project_id", "criteria"],
+                },
+            },
+            {
+                name: "update_context",
+                description: "Change the project's implementation context: tech_stack platform/framework (set, or list them in tech_stack.unset to clear), tech_stack database/ai_models and constraints (add/remove items: add values are trimmed; remove values must match the stored text exactly). Writes immediately and costs zero Sparks. Call get_project first and pass its context.context_version as expected_context_version. Before calling, show the user the exact change and tell them that all previously generated documents (BRD/PRD/TRD, delivery brief, master spec, task specs) may be marked stale, and that regenerating them costs Sparks; set confirmed_with_user to true only after the user agreed. A CONTEXT_CHANGED error means the context changed since you read it: read it again, reconcile, and ask the user again. Vision, features, users and success criteria are not writable here: use add_user_persona, update_success_criteria or add_feature_request.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        project_id: {
+                            type: "string",
+                            format: "uuid",
+                            description: "The project ID",
+                        },
+                        expected_context_version: {
+                            type: "integer",
+                            minimum: 1,
+                            description: "context.context_version from the get_project call the user's confirmation was based on",
+                        },
+                        reason: {
+                            type: "string",
+                            minLength: 10,
+                            maxLength: 500,
+                            description: "Why this change is needed (e.g., what was discovered while implementing)",
+                        },
+                        confirmed_with_user: {
+                            type: "boolean",
+                            description: "Must be true, set only after the user saw the exact change and agreed to it; anything else is rejected",
+                        },
+                        patch: {
+                            type: "object",
+                            description: "At most 20 operations in total (each set, unset, added or removed item counts). A list can grow to at most 50 items, and the tech stack and constraints to at most 12000 characters together.",
+                            properties: {
+                                tech_stack: {
+                                    type: "object",
+                                    properties: {
+                                        platform: { type: "string", minLength: 1, maxLength: 200 },
+                                        framework: { type: "string", minLength: 1, maxLength: 200 },
+                                        unset: {
+                                            type: "array",
+                                            items: { type: "string", enum: ["platform", "framework"] },
+                                            description: "Keys to clear; a key cannot be both set and unset",
+                                        },
+                                        database: listOps(200),
+                                        ai_models: listOps(200),
+                                    },
+                                    additionalProperties: false,
+                                },
+                                constraints: listOps(500),
+                            },
+                            additionalProperties: false,
+                        },
+                    },
+                    required: ["project_id", "expected_context_version", "reason", "confirmed_with_user", "patch"],
+                    additionalProperties: false,
+                },
+            },
         ],
     };
 });
 // Handle tool calls
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
+server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
     const { name, arguments: args } = request.params;
     try {
         let result;
@@ -265,6 +658,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "get_backlog":
                 result = await callIgn8tAPI("/backlog/get", args);
                 break;
+            case "get_specs":
+                result = await callIgn8tAPI("/specs/list", args);
+                break;
+            case "create_task":
+                result = await callIgn8tAPI("/tasks/create", args);
+                break;
+            case "list_recommendations":
+                result = await callIgn8tAPI("/recommendations/list", args);
+                break;
+            case "accept_recommendations":
+                result = await callIgn8tAPI("/recommendations/accept", args);
+                break;
+            case "reject_recommendations":
+                result = await callIgn8tAPI("/recommendations/reject", args);
+                break;
             case "get_next_task":
                 result = await callIgn8tAPI("/tasks/next", args);
                 break;
@@ -277,6 +685,72 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "get_task_context":
                 result = await callIgn8tAPI("/tasks/context", 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
+                // was being read must not go on to charge.
+                extra.signal.throwIfAborted();
+                // The server's reply states what happened: sparks_charged, already_imported, warning.
+                result = await callIgn8tAPI("/projects/import", {
+                    project_id: args?.project_id,
+                    locale: args?.locale,
+                    workspace: snapshot,
+                });
+                if (unreadableDirectories.length) {
+                    result = { ...result, skipped_unreadable_directories: unreadableDirectories };
+                }
+                if (fileLimitReached) {
+                    result = {
+                        ...result,
+                        file_limit_reached: "The folder has more than 20000 files; the count and notable paths cover the first 20000 reached (folders walked depth-first, each sorted by name).",
+                    };
+                }
+                break;
+            }
+            // ===== BIDIRECTIONAL CONTEXT UPDATE HANDLERS =====
+            case "add_feature_request": {
+                console.error(`Adding feature request for project: ${args.project_id}`);
+                result = await callIgn8tAPI("/features/add", {
+                    project_id: args.project_id,
+                    feature: args.feature,
+                    related_context: args.related_context,
+                    mcp_metadata: {
+                        ide: "MCP Client",
+                        timestamp: new Date().toISOString(),
+                    },
+                });
+                console.error("Feature request submitted successfully");
+                break;
+            }
+            case "add_user_persona": {
+                console.error(`Adding user persona for project: ${args.project_id}`);
+                result = await callIgn8tAPI("/personas/add", {
+                    project_id: args.project_id,
+                    persona: args.persona,
+                    mcp_metadata: {
+                        ide: "MCP Client",
+                        timestamp: new Date().toISOString(),
+                    },
+                });
+                console.error("User persona added successfully");
+                break;
+            }
+            case "update_success_criteria": {
+                console.error(`Updating success criteria for project: ${args.project_id}`);
+                result = await callIgn8tAPI("/criteria/update", {
+                    project_id: args.project_id,
+                    criteria: args.criteria,
+                    mcp_metadata: {
+                        ide: "MCP Client",
+                        timestamp: new Date().toISOString(),
+                    },
+                });
+                console.error("Success criteria updated successfully");
+                break;
+            }
+            case "update_context":
+                result = await callIgn8tAPI("/context/update", args);
+                break;
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }
@@ -368,7 +842,7 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error("ign8t MCP server v1.0.0");
+    console.error(`ign8t MCP server v${VERSION}`);
     console.error(`Connected to: ${API_URL}`);
     console.error("Ready to serve requests...");
 }

package/dist/workspace-snapshot.js

@@ -0,0 +1,197 @@
+/**
+ * Workspace Snapshot
+ *
+ * Builds the bounded, deterministic summary of a local codebase that
+ * import_project uploads. Only the README excerpt, package.json metadata,
+ * notable file paths and counts leave the machine — never other file contents.
+ */
+import { readdir, readFile, stat } from "node:fs/promises";
+import * as path from "node:path";
+// Hidden directories (.git, .next, .venv, .tox, ...) are skipped too: caches there
+// would otherwise fill the file cap before the real code is reached.
+const SKIPPED_DIRECTORIES = new Set([
+    "node_modules",
+    "dist",
+    "build",
+    "out",
+    "coverage",
+    "vendor",
+    "target",
+    "__pycache__",
+    "venv",
+    "Pods",
+]);
+// Same selection the web GitHub import uses (import-github.ts).
+const NOTABLE_FILE = /(^|\/)(package\.json|pnpm-lock\.yaml|yarn\.lock|next\.config|vite\.config|src\/|app\/|pages\/|components\/|supabase\/|prisma\/|drizzle|README|Dockerfile)/i;
+const LANGUAGE_BY_EXTENSION = {
+    ".ts": "TypeScript",
+    ".tsx": "TypeScript",
+    ".js": "JavaScript",
+    ".jsx": "JavaScript",
+    ".mjs": "JavaScript",
+    ".cjs": "JavaScript",
+    ".py": "Python",
+    ".go": "Go",
+    ".rs": "Rust",
+    ".java": "Java",
+    ".kt": "Kotlin",
+    ".swift": "Swift",
+    ".rb": "Ruby",
+    ".php": "PHP",
+    ".cs": "C#",
+    ".cpp": "C++",
+    ".c": "C",
+    ".dart": "Dart",
+    ".vue": "Vue",
+    ".svelte": "Svelte",
+    ".html": "HTML",
+    ".css": "CSS",
+};
+const MAX_DEPTH = 12;
+const MAX_FILES = 20_000;
+/**
+ * Clip to `max` UTF-16 units without leaving half of a surrogate pair. Unpaired
+ * surrogates (possible through package.json escapes) become U+FFFD: the server
+ * rejects them, since Postgres cannot store them.
+ */
+function clip(value, max) {
+    // NUL (possible through "\u0000" escapes) is dropped for the same reason.
+    const wellFormed = Buffer.from(value, "utf8").toString("utf8").replace(/\u0000/g, "");
+    const clipped = wellFormed.slice(0, max);
+    return /[\uD800-\uDBFF]$/.test(clipped) ? clipped.slice(0, -1) : clipped;
+}
+function objectKeys(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? Object.keys(value) : [];
+}
+function byName(a, b) {
+    return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+}
+/**
+ * Relative POSIX paths of regular files, in sorted depth-first order.
+ * Symlinks are never followed and the walk stops at MAX_FILES. Subdirectories the
+ * user cannot read (e.g. a root-owned database volume) are skipped and returned.
+ */
+async function listFiles(root) {
+    // Collects one file past the cap, so "more than MAX_FILES" is a fact, not a guess.
+    const files = [];
+    const unreadable = [];
+    async function visit(directory, prefix, depth) {
+        let entries;
+        try {
+            entries = (await readdir(directory, { withFileTypes: true })).sort(byName);
+        }
+        catch (error) {
+            const code = error.code;
+            // ENOENT/ENOTDIR: removed or replaced while the walk ran, or a name the OS cannot reopen.
+            if (prefix && (code === "EACCES" || code === "EPERM" || code === "ENOENT" || code === "ENOTDIR")) {
+                unreadable.push(prefix.slice(0, -1));
+                return;
+            }
+            throw error;
+        }
+        // A Python virtual environment, whatever its folder is called (PEP 405 marker).
+        if (prefix && entries.some((entry) => entry.isFile() && entry.name === "pyvenv.cfg"))
+            return;
+        for (const entry of entries) {
+            if (files.length > MAX_FILES)
+                return;
+            const relativePath = prefix + entry.name;
+            if (entry.isFile()) {
+                files.push(relativePath);
+            }
+            else if (entry.isDirectory() &&
+                depth < MAX_DEPTH &&
+                !entry.name.startsWith(".") &&
+                !SKIPPED_DIRECTORIES.has(entry.name)) {
+                await visit(path.join(directory, entry.name), `${relativePath}/`, depth + 1);
+            }
+        }
+    }
+    await visit(root, "", 0);
+    return { files: files.slice(0, MAX_FILES), unreadable, fileLimitReached: files.length > MAX_FILES };
+}
+function primaryLanguage(files) {
+    const counts = new Map();
+    for (const file of files) {
+        const language = LANGUAGE_BY_EXTENSION[path.posix.extname(file).toLowerCase()];
+        if (language)
+            counts.set(language, (counts.get(language) ?? 0) + 1);
+    }
+    return [...counts].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1))[0]?.[0];
+}
+/**
+ * The snapshot to upload, plus what it left out (reported to the caller, never sent):
+ * unreadable subdirectories and whether the file cap stopped the walk.
+ */
+export async function buildWorkspaceSnapshot(root) {
+    if (typeof root !== "string" || !path.isAbsolute(root)) {
+        throw new Error(`workspace_path must be an absolute directory path, got: ${String(root)}`);
+    }
+    if (!(await stat(root)).isDirectory()) {
+        throw new Error(`workspace_path is not a directory: ${root}`);
+    }
+    const rootFiles = (await readdir(root, { withFileTypes: true }))
+        .filter((entry) => entry.isFile())
+        .map((entry) => entry.name)
+        .sort();
+    let packageJson = {};
+    if (rootFiles.includes("package.json")) {
+        const packageJsonPath = path.join(root, "package.json");
+        const text = await readFile(packageJsonPath, "utf8");
+        try {
+            // A leading byte-order mark is valid for npm and Node, but not for JSON.parse.
+            packageJson = JSON.parse(text.replace(/^\uFEFF/, ""));
+        }
+        catch {
+            // The parser's message quotes the file, which may hold script values; only
+            // names leave the machine, so the error must not repeat its contents.
+            throw new Error(`Cannot parse ${packageJsonPath}: it is not valid JSON`);
+        }
+        if (!packageJson || typeof packageJson !== "object" || Array.isArray(packageJson)) {
+            throw new Error(`${packageJsonPath} is not a JSON object`);
+        }
+    }
+    const readmeName = ["readme.md", "readme"]
+        .map((wanted) => rootFiles.find((name) => name.toLowerCase() === wanted))
+        .find(Boolean);
+    // NULs (a UTF-16 README read as UTF-8) are dropped by clip(): the server rejects them.
+    const readme = readmeName ? await readFile(path.join(root, readmeName), "utf8") : "";
+    const { files, unreadable, fileLimitReached } = await listFiles(root);
+    // Every value is clipped before the empty checks: a value made only of dropped
+    // characters (e.g. NUL) must count as empty, not be sent as "".
+    const packageName = clip(typeof packageJson.name === "string" ? packageJson.name : "", 214);
+    const description = clip(typeof packageJson.description === "string" ? packageJson.description : "", 1000);
+    const readmeExcerpt = clip(readme, 6000);
+    const language = primaryLanguage(files);
+    const snapshot = {
+        name: packageName || clip(path.basename(root), 214),
+        ...(description ? { description } : {}),
+        ...(language ? { primary_language: language } : {}),
+        total_files: files.length,
+        scripts: objectKeys(packageJson.scripts)
+            .map((script) => clip(script, 100))
+            .filter(Boolean)
+            .slice(0, 50),
+        // Runtime dependencies win the 60 slots over dev tooling (same order as the
+        // GitHub import), then the list is sorted so key order cannot change it.
+        dependencies: [
+            ...new Set([
+                ...objectKeys(packageJson.dependencies).sort(),
+                ...objectKeys(packageJson.devDependencies).sort(),
+            ]),
+        ]
+            .filter((dependency) => dependency.length <= 214)
+            .map((dependency) => clip(dependency, 214))
+            .filter(Boolean)
+            .slice(0, 60)
+            .sort(),
+        ...(readmeExcerpt ? { readme_excerpt: readmeExcerpt } : {}),
+        // Paths the server would reject (backslash, drive prefix, over 300 chars) are left out.
+        notable_files: files
+            .filter((file) => file.length <= 300 && !file.includes("\\") && !/^[A-Za-z]:/.test(file))
+            .filter((file) => NOTABLE_FILE.test(file))
+            .sort()
+            .slice(0, 120),
+    };
+    return { snapshot, unreadableDirectories: unreadable, fileLimitReached };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ign8t/mcp",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "MCP server for ign8t project management - AI IDE integration",
   "type": "module",
   "main": "dist/index.js",
@@ -11,6 +11,19 @@
     "dist/",
     "README.md"
   ],
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js",
+    "build:watch": "tsc --watch",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "dev:help": "tsx src/index.ts --help",
+    "clean": "rm -rf dist",
+    "test": "node debug-mcp.js",
+    "test:local": "node dist/index.js --help",
+    "link:local": "npm link",
+    "unlink:local": "npm unlink -g @ign8t/mcp",
+    "prepublishOnly": "pnpm clean && pnpm build"
+  },
   "keywords": [
     "mcp",
     "model-context-protocol",
@@ -25,34 +38,17 @@
   "mcp": {
     "name": "ign8t-mcp",
     "description": "MCP server for ign8t project management - AI IDE integration",
-    "version": "1.0.0"
+    "version": "0.3.0"
   },
   "author": "nocodecat",
   "license": "MIT",
   "homepage": "https://www.ign8t.com",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/ign8t/mcp-server.git"
-  },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^0.5.0",
-    "dotenv": "^16.3.1"
+    "@modelcontextprotocol/sdk": "^0.5.0"
   },
   "devDependencies": {
     "@types/node": "^20.10.5",
     "tsx": "^4.7.0",
     "typescript": "^5.3.3"
-  },
-  "scripts": {
-    "build": "tsc && chmod +x dist/index.js",
-    "build:watch": "tsc --watch",
-    "start": "node dist/index.js",
-    "dev": "tsx src/index.ts",
-    "dev:help": "tsx src/index.ts --help",
-    "clean": "rm -rf dist",
-    "test": "node debug-mcp.js",
-    "test:local": "node dist/index.js --help",
-    "link:local": "npm link",
-    "unlink:local": "npm unlink -g @ign8t/mcp"
   }
-}
+}