@elixium.ai/mcp-server 0.1.1 → 0.1.3

package/README.md

@@ -5,80 +5,125 @@ This server implements the [Model Context Protocol (MCP)](https://modelcontextpr
 ## Features
 - **List Stories**: See the current backlog and icebox.
 - **Create Story**: Add new stories directly from your editor.
+- **Update Story**: Move stories between lanes and update fields.
 - **Iteration Context**: Provide the AI with the full context of your Current and Backlog lanes for better planning.
 
-## Setup
+## Quick Start
 
-### 1. Install
-If you do not have the Elixium codebase, install the MCP server package:
+### 1. Install (Optional)
+If you want to install the package locally:
 ```bash
-npm install -g @elixium.ai/mcp-server
+npm install -D @elixium.ai/mcp-server@latest
 ```
 
-Air-gapped/offline install (download the `.tgz` from GitHub Releases first):
+Or install globally:
 ```bash
-npm install -g /path/to/elixium.ai-mcp-server-0.1.0.tgz
+npm install -g @elixium.ai/mcp-server@latest
 ```
 
-If you are developing from source:
-```bash
-cd mcp-server
-npm install
-npm run build
-```
+> [!TIP]
+> You can also use `npx` to run the server without installing it (recommended for IDE configurations).
 
-### 2. Authentication (API Key)
-Elixium uses a secure, tenant-scoped API key system for external integrations.
+### 2. Get Your API Key
+Contact your Elixium workspace administrator to obtain an API key for your tenant.
 
-1.  **Request a Key**: Ask your Elixium administrator to create an API key in the `sys_api_keys` collection.
-2.  **Scope**: Each key is hardcoded to a specific `tenantId` in the database, ensuring your AI agent only has access to your workspace.
-3.  **Board Selection**: Optionally scope the MCP server to a single board by setting `ELIXIUM_BOARD_SLUG`.
+### 3. Configure Your IDE
+Add the following to your IDE's MCP configuration file (e.g., `mcp_config.json`):
 
-### 3. Configuration
-Add the following to your IDE's MCP configuration (e.g., `mcp_config.json`):
+```json
+{
+  "mcpServers": {
+    "elixium": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@elixium.ai/mcp-server@latest"
+      ],
+      "env": {
+        "ELIXIUM_API_KEY": "<YOUR_API_KEY>",
+        "ELIXIUM_API_URL": "https://<YOUR_TENANT>.elixium.ai/api",
+        "ELIXIUM_BOARD_SLUG": "main"
+      }
+    }
+  }
+}
+```
+
+Replace:
+- `<YOUR_API_KEY>` with the API key from your administrator
+- `<YOUR_TENANT>` with your workspace subdomain (e.g., `acme` for `acme.elixium.ai`)
+
+### Multi-MCP Example (Stripe + Elixium)
+If you're using multiple MCP servers, combine them in the same config:
 
 ```json
 {
   "mcpServers": {
+    "stripe": {
+      "command": "npx",
+      "args": ["-y", "@stripe/mcp", "--tools=all", "--api-key=<STRIPE_KEY>"],
+      "env": {}
+    },
     "elixium": {
-      "command": "elixium-mcp-server",
-      "args": [],
+      "command": "npx",
+      "args": ["-y", "@elixium.ai/mcp-server@latest"],
       "env": {
-        "ELIXIUM_API_KEY": "your_api_key_here",
-        "ELIXIUM_API_URL": "https://your-tenant-slug.elixium.ai/api",
-        "ELIXIUM_BOARD_SLUG": "main",
-        "ELIXIUM_LANE_STYLE": "upper"
+        "ELIXIUM_API_KEY": "<YOUR_API_KEY>",
+        "ELIXIUM_API_URL": "https://<YOUR_TENANT>.elixium.ai/api",
+        "ELIXIUM_BOARD_SLUG": "main"
       }
     }
   }
 }
 ```
 
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `ELIXIUM_API_KEY` | ✅ Yes | Your tenant-scoped API key |
+| `ELIXIUM_API_URL` | ✅ Yes | Your tenant's API endpoint (e.g., `https://acme.elixium.ai/api`) |
+| `ELIXIUM_BOARD_SLUG` | ⚠️ Recommended | Board slug to scope operations (e.g., `main`) |
+| `ELIXIUM_LANE_STYLE` | Optional | `upper` for `BACKLOG/CURRENT` or `title` for `Backlog/Current` (auto-detected) |
+
 > [!IMPORTANT]
-> Always use your **Tenant Subdomain** in the `ELIXIUM_API_URL` (e.g., `https://indirecttek.elixium.ai/api`) to ensure the server correctly resolves your workspace context.
->
 > If you set `ELIXIUM_BOARD_SLUG`, the MCP server will only read/write stories for that board.
 > The server resolves the board slug to a boardId on startup, so the slug must match an existing board.
->
-> `ELIXIUM_LANE_STYLE` is optional. Use `upper` for APIs that store lanes as `CURRENT/BACKLOG`, or `title` for `Current/Backlog`. The server auto-detects when possible.
->
-> If you built the MCP server from source, set `command` to `node` and `args`
-> to the absolute path of `dist/index.js`.
 
 ## Usage
-Once configured, your AI agent will have access to tools like `list_stories` and `create_story`. You can use these to groom your backlog or generate implementation plans based on real-time board data.
+Once configured, your AI agent will have access to tools like:
+- `list_stories` - View all stories on the board
+- `create_story` - Add new stories with title, description, lane, and points
+- `update_story` - Move stories between lanes or update fields
+- `list_epics` - View epics on the board
+- `get_iteration_context` - Get current iteration and backlog for planning
 
-## Maintainers: build a clean release tarball (gh CLI)
-This package uses the `files` list in `package.json` to keep the tarball small.
+## Development (Source Build)
+If you're contributing or developing from source:
 
 ```bash
 cd mcp-server
 npm install
 npm run build
-npm pack
 ```
 
+To use the local build, update your config:
+```json
+{
+  "elixium": {
+    "command": "node",
+    "args": ["/path/to/mcp-server/dist/index.js"],
+    "env": { ... }
+  }
+}
+```
+
+## Maintainers: Release Process
+
 ```bash
-gh release create mcp-server-v0.1.0 elixium.ai-mcp-server-0.1.0.tgz \
-  -t "MCP Server v0.1.0" -n "Air-gapped install artifact"
+cd mcp-server
+npm install
+npm run build
+npm version patch  # or minor/major
+npm publish --access public
 ```

package/dist/index.js

@@ -332,6 +332,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             type: "string",
                             description: "Learning outcome summary",
                         },
+                        acceptanceCriteria: {
+                            type: "string",
+                            description: "Acceptance criteria in Given/When/Then format",
+                        },
                     },
                     required: ["storyId"],
                 },
@@ -437,13 +441,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
             case "update_story": {
                 const args = request.params.arguments;
-                const { storyId, lane, ...rest } = args;
+                const { storyId, lane, state, ...rest } = args;
                 if (!storyId) {
                     throw new Error("storyId is required");
                 }
+                // Guardrail: Block AI from setting accepted/rejected states (human-in-the-loop)
+                const blockedStates = ["accepted", "rejected"];
+                if (state && blockedStates.includes(state.toLowerCase())) {
+                    throw new Error(`Cannot set state to "${state}". Acceptance decisions require human review.`);
+                }
                 const normalizedLane = await normalizeLane(lane);
                 const payload = Object.fromEntries(Object.entries({
                     ...rest,
+                    ...(state ? { state } : {}),
                     ...(normalizedLane ? { lane: normalizedLane } : {}),
                 }).filter(([, value]) => value !== undefined));
                 const response = await client.patch(`/stories/${storyId}`, payload);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elixium.ai/mcp-server",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "description": "MCP Server for Elixium.ai",
   "publishConfig": {
@@ -13,7 +13,7 @@
   ],
   "main": "dist/index.js",
   "bin": {
-    "elixium-mcp-server": "./dist/index.js"
+    "elixium-mcp-server": "dist/index.js"
   },
   "scripts": {
     "build": "tsc",