wolfpack-mcp 1.0.2 → 1.0.4

package/README.md

@@ -1,6 +1,9 @@
 # Wolfpack MCP Server
 
-The Wolfpack MCP (Model Context Protocol) server enables AI assistants to interact with Wolfpack team projects, providing full CRUD operations for work items, issues, wiki pages, journal entries, and more.
+[![npm](https://img.shields.io/npm/v/wolfpack-mcp)](https://www.npmjs.com/package/wolfpack-mcp)
+
+Connect your AI assistant to Wolfpack to manage work items, track issues, update documentation, and log progress—all
+through natural conversation.
 
 ## Installation
 
@@ -14,22 +17,34 @@ Or use directly with npx (no installation required):
 npx wolfpack-mcp
 ```
 
+## Quick Start
+
+1. Generate an API key at [wolfpacks.work](https://wolfpacks.work) → Account Settings → API Keys
+2. Add the server to Claude Desktop (see [Setup](#setup) below)
+3. Restart Claude Desktop
+4. Start asking Claude about your work!
+
+**Try these prompts:**
+
+- "What work items are assigned to me?"
+- "Show me open bugs"
+- "Create a work item to refactor the auth module"
+- "Update issue #42 status to in-progress"
+- "Add a journal entry about today's progress"
+
 ## Setup
 
 ### 1. Generate an API Key
 
-1. Log in to your Wolfpack application at [wolfpacks.work](https://wolfpacks.work)
-2. Navigate to **Account Settings** → **API Keys**
+1. Log in to [wolfpacks.work](https://wolfpacks.work)
+2. Go to **Account Settings** → **API Keys**
 3. Click **Create New Key**
-4. Give your key a descriptive name (e.g., "Claude MCP Server")
-5. Select the MCP permissions you want to grant (e.g., work items, issues, wiki)
-6. Choose an expiration period (or "Never expires" for permanent keys)
-7. Click **Create Key**
-8. **Important**: Copy your API key immediately - you won't be able to see it again!
+4. Select the permissions you need (work items, issues, wiki, etc.)
+5. Copy your API key immediately—you won't see it again
 
 ### 2. Configure Claude Desktop
 
-Add the MCP server to your Claude Desktop configuration:
+Add to your Claude Desktop config file:
 
 **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
 **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
@@ -48,333 +63,253 @@ Add the MCP server to your Claude Desktop configuration:
 }
 ```
 
-Replace `wfp_sk_your_api_key_here` with your actual API key.
+### 3. Restart Claude Desktop
+
+After saving the configuration, restart Claude Desktop to connect.
+
+## What You Can Do
+
+| Feature        | Example Prompts                                                                       |
+| -------------- | ------------------------------------------------------------------------------------- |
+| **Work Items** | "What's on my plate?" / "Create a task for API updates" / "Mark task #15 as done"     |
+| **Issues**     | "Show critical bugs" / "File a bug about the login timeout" / "Assign issue #8 to me" |
+| **Wiki**       | "Find docs about deployment" / "Create a page for onboarding steps"                   |
+| **Journal**    | "Log my standup notes" / "What did I work on last week?"                              |
+| **Radar**      | "What initiatives are in progress?" / "Show the roadmap"                              |
 
-**Team Selection**: If you belong to only one team, it will be selected automatically. If you have multiple teams, use the `list_teams` tool to see them, then specify `team_id` in your tool calls.
+## Multi-Team Users
 
-**Optional**: To pre-select a specific team, add `WOLFPACK_TEAM_SLUG` to the env:
+If you belong to multiple teams, Claude will ask which team you mean, or you can specify:
+
+- "Show my work items for the Platform team"
+- Use `list_teams` to see all your teams
+
+To pre-select a default team, add to your config:
 
 ```json
 "env": {
-  "WOLFPACK_API_KEY": "wfp_sk_your_api_key_here",
-  "WOLFPACK_TEAM_SLUG": "your-team-slug"
+"WOLFPACK_API_KEY": "wfp_sk_your_api_key_here",
+"WOLFPACK_TEAM_SLUG": "your-team-slug"
 }
 ```
 
-### 3. Restart Claude Desktop
+## API Key Permissions
 
-After updating the configuration, restart Claude Desktop to load the MCP server.
+When creating your API key, select the permissions you need:
+
+| Permission              | What It Enables                 |
+| ----------------------- | ------------------------------- |
+| `mcp:work_items:read`   | View your tasks                 |
+| `mcp:work_items:create` | Create new tasks                |
+| `mcp:work_items:update` | Update task status and notes    |
+| `mcp:issues:read`       | View issues                     |
+| `mcp:issues:create`     | File new issues                 |
+| `mcp:issues:update`     | Update issue status and details |
+| `mcp:wiki:read`         | Read documentation              |
+| `mcp:wiki:create`       | Create new pages                |
+| `mcp:wiki:update`       | Edit existing pages             |
+| `mcp:journal:read`      | View journal entries            |
+| `mcp:journal:create`    | Create journal entries          |
+| `mcp:journal:update`    | Edit journal entries            |
+| `mcp:comments:create`   | Add comments to items           |
+| `mcp:radar:read`        | View initiatives and roadmap    |
 
-## API Key Permissions
+## Troubleshooting
+
+**"WOLFPACK_API_KEY environment variable is required"**
+Check that your Claude Desktop config has the API key set correctly.
+
+**"Invalid API key format"**
+API keys must start with `wfp_sk_` (user keys) or `wfp_ak_` (org-managed agent keys).
+
+**"Invalid API key"**
+Your key may be incorrect or revoked. Generate a new one from Account Settings.
+
+**"API key does not have permission: mcp:..."**
+Create a new key with the required permission enabled.
+
+**Connection errors**
+Verify [wolfpacks.work](https://wolfpacks.work) is accessible from your network.
+
+## Security
+
+- API keys are scoped to your account and team memberships
+- Permissions are configurable per key—grant only what you need
+- Revoke keys anytime from Account Settings
+
+## Available Tools Reference
 
-Each API key has granular permissions that control which MCP tools are available:
-
-| Permission              | Tools Enabled                                      |
-| ----------------------- | -------------------------------------------------- |
-| `mcp:work_items:read`   | `list_work_items`, `get_work_item`                 |
-| `mcp:work_items:create` | `create_work_item`                                 |
-| `mcp:work_items:update` | `update_work_progress`, `update_work_item_status`  |
-| `mcp:issues:read`       | `list_issues`, `get_issue`                         |
-| `mcp:issues:create`     | `create_issue`                                     |
-| `mcp:issues:update`     | `update_issue`                                     |
-| `mcp:wiki:read`         | `list_wiki_pages`, `get_wiki_page`                 |
-| `mcp:wiki:create`       | `create_wiki_page`                                 |
-| `mcp:wiki:update`       | `update_wiki_page`                                 |
-| `mcp:journal:read`      | `list_journal_entries`, `get_journal_entry`        |
-| `mcp:journal:create`    | `create_journal_entry`                             |
-| `mcp:journal:update`    | `update_journal_entry`                             |
-| `mcp:comments:create`   | `create_work_item_comment`, `create_issue_comment` |
-| `mcp:radar:read`        | `list_radar_items`, `get_radar_item`               |
-
-## Available Tools
+<details>
+<summary>Click to expand full tool documentation</summary>
 
 ### Teams
 
 #### `list_teams`
 
-List all teams you have access to. Use this to discover available teams and get team IDs.
+List all teams you have access to.
 
 - **Parameters:** None
-- **Returns:** Array of team objects with `id`, `slug`, and `name`
+- **Returns:** Array of teams with `id`, `slug`, and `name`
 
 ### Work Items
 
-Work items are tasks or tickets assigned to team members.
-
 #### `list_work_items`
 
-Lists work items assigned to you. By default, excludes completed and closed items to show active work.
+Lists work items assigned to you (excludes completed by default).
 
-- **Parameters:**
-  - `team_id` (number, optional): Team ID (use `list_teams` to get IDs)
-  - `status` (string, optional): Filter by status (new, doing, review, completed, blocked). Use `completed` or `closed` to see those items.
-  - `limit` (number, optional): Maximum number of items to return
-  - `offset` (number, optional): Number of items to skip for pagination
-- **Returns:** Array of work item objects
-- **Note:** Results are automatically paginated. If there are more than 200 items, you'll receive a truncation warning with the first 50 items.
+- `team_id` (optional): Filter by team
+- `status` (optional): Filter by status (new, doing, review, completed, blocked)
+- `limit`, `offset` (optional): Pagination
 
 #### `get_work_item`
 
-Gets a specific work item by ID or reference number.
+Get a specific work item.
 
-- **Parameters:**
-  - `work_item_id` (string, required): The work item ID (UUID) or refId (number)
-  - `team_id` (number, optional): Team ID (required when using refId)
-- **Returns:** Work item object with full description
+- `work_item_id` (required): UUID or reference number
+- `team_id` (optional): Required when using reference number
 
 #### `create_work_item`
 
-Creates a new work item. Requires `mcp:work_items:create` permission.
+Create a new work item.
 
-- **Parameters:**
-  - `title` (string, required): Title of the work item
-  - `description` (string, optional): Description/notes (markdown)
-  - `status` (string, optional): Initial status (new, doing, review, completed, blocked - defaults to 'new')
-  - `priority` (number, optional): Priority level (0-4, higher is more important)
-  - `leading_user_id` (string, optional): User ID to assign
-- **Returns:** The created work item object
+- `title` (required): Task title
+- `description`, `status`, `priority`, `leading_user_id` (optional)
 
 #### `update_work_progress`
 
-Updates the description/notes on a work item. Requires `mcp:work_items:update` permission.
+Update work item description/notes.
 
-- **Parameters:**
-  - `work_item_id` (string, required): The work item ID
-  - `description` (string, required): Complete updated description (markdown)
-- **Returns:** The updated work item object
+- `work_item_id` (required): The work item ID
+- `description` (required): Updated description (markdown)
 
 #### `update_work_item_status`
 
-Changes work item status. Requires `mcp:work_items:update` permission.
+Change work item status.
 
-- **Parameters:**
-  - `work_item_id` (string, required): The work item ID
-  - `status` (string, required): New status (new, doing, review, completed, blocked)
-- **Returns:** The updated work item object
+- `work_item_id` (required): The work item ID
+- `status` (required): New status
 
 ### Issues
 
-Issues track bugs, feature requests, and other items in the issue tracker.
-
 #### `list_issues`
 
-Lists issues from the team issue tracker. By default, excludes closed issues.
+List issues (excludes closed by default).
 
-- **Parameters:**
-  - `team_id` (number, optional): Team ID to filter issues
-  - `status` (string, optional): Filter by status (open, in-progress, resolved, closed). Use `closed` to see closed items.
-  - `severity` (string, optional): Filter by severity (low, medium, high, critical)
-  - `type` (string, optional): Filter by type (bug, feature-request, task, improvement, question)
-  - `assigned_to_id` (string, optional): Filter by assignee ('unassigned' or 'me' for special cases)
-  - `limit` (number, optional): Maximum number of items
-  - `offset` (number, optional): Items to skip
-- **Returns:** Array of issue objects
-- **Note:** Results are automatically paginated. If there are more than 200 items, you'll receive a truncation warning.
+- `team_id`, `status`, `severity`, `type`, `assigned_to_id` (optional): Filters
+- `limit`, `offset` (optional): Pagination
 
 #### `get_issue`
 
-Gets a specific issue by ID or reference number.
+Get a specific issue.
 
-- **Parameters:**
-  - `issue_id` (string, required): The issue ID (UUID) or refId (number)
-  - `team_id` (number, optional): Team ID (required when using refId)
-- **Returns:** Issue object with comment and attachment counts
+- `issue_id` (required): UUID or reference number
+- `team_id` (optional): Required when using reference number
 
 #### `create_issue`
 
-Creates a new issue. Requires `mcp:issues:create` permission.
-
-- **Parameters:**
-  - `title` (string, required): Issue title
-  - `description` (string, optional): Issue description
-  - `severity` (string, optional): Severity level (low, medium, high, critical)
-  - `type` (string, optional): Issue type (bug, feature-request, task, improvement, question)
-  - `assigned_to_id` (string, optional): User ID to assign
-  - `environment` (string, optional): Environment where issue occurred
-  - `affected_version` (string, optional): Version affected
-  - `reproducible` (boolean, optional): Whether reproducible
-  - `steps_to_reproduce` (string, optional): Steps to reproduce
-  - `expected_behavior` (string, optional): Expected behavior
-  - `actual_behavior` (string, optional): Actual behavior observed
-- **Returns:** The created issue object
+Create a new issue.
+
+- `title` (required): Issue title
+- `description`, `severity`, `type`, `assigned_to_id`, `environment`, `affected_version`, `reproducible`,
+  `steps_to_reproduce`, `expected_behavior`, `actual_behavior` (optional)
 
 #### `update_issue`
 
-Updates an existing issue. Requires `mcp:issues:update` permission.
+Update an existing issue.
 
-- **Parameters:**
-  - `issue_id` (string, required): The issue UUID
-  - `title` (string, optional): Updated title
-  - `description` (string, optional): Updated description
-  - `status` (string, optional): Updated status (open, in-progress, resolved, closed)
-  - `severity` (string, optional): Updated severity
-  - `assigned_to_id` (string, optional): Updated assignee
-  - `closing_note` (string, optional): Note when closing
-- **Returns:** The updated issue object
+- `issue_id` (required): The issue UUID
+- `title`, `description`, `status`, `severity`, `assigned_to_id`, `closing_note` (optional)
 
 ### Wiki Pages
 
-Wiki pages store team documentation and knowledge base articles.
-
 #### `list_wiki_pages`
 
-Lists wiki pages from your accessible teams.
+List wiki pages.
 
-- **Parameters:**
-  - `limit` (number, optional): Maximum pages to return
-  - `offset` (number, optional): Pages to skip
-- **Returns:** Array of wiki page objects
+- `limit`, `offset` (optional): Pagination
 
 #### `get_wiki_page`
 
-Gets a specific wiki page by ID or slug.
+Get a wiki page by ID or slug.
 
-- **Parameters:**
-  - `page_id` (string, required): The page UUID or slug (URL path like "getting-started")
-- **Returns:** Wiki page object with content
+- `page_id` (required): UUID or slug (e.g., "getting-started")
 
 #### `create_wiki_page`
 
-Creates a new wiki page. Requires `mcp:wiki:create` permission.
+Create a new wiki page.
 
-- **Parameters:**
-  - `slug` (string, required): URL slug for the page (without team prefix)
-  - `title` (string, required): Page title
-  - `content` (string, required): Page content (markdown)
-- **Returns:** The created wiki page object
+- `slug` (required): URL path
+- `title` (required): Page title
+- `content` (required): Markdown content
 
 #### `update_wiki_page`
 
-Updates an existing wiki page. Requires `mcp:wiki:update` permission.
+Update an existing wiki page.
 
-- **Parameters:**
-  - `page_id` (string, required): The page UUID
-  - `title` (string, optional): Updated title
-  - `content` (string, optional): Updated content (markdown)
-- **Returns:** The updated wiki page object
+- `page_id` (required): The page UUID
+- `title`, `content` (optional)
 
 ### Journal Entries
 
-Journal entries are daily logs, standup notes, or progress updates.
-
 #### `list_journal_entries`
 
-Lists journal entries from your accessible teams.
+List journal entries.
 
-- **Parameters:**
-  - `limit` (number, optional): Maximum entries to return
-  - `offset` (number, optional): Entries to skip
-- **Returns:** Array of journal entry objects
+- `limit`, `offset` (optional): Pagination
 
 #### `get_journal_entry`
 
-Gets a specific journal entry by ID or reference number.
+Get a specific journal entry.
 
-- **Parameters:**
-  - `entry_id` (string, required): The entry UUID or refId
-  - `team_id` (number, optional): Team ID (required when using refId)
-- **Returns:** Journal entry object
+- `entry_id` (required): UUID or reference number
+- `team_id` (optional): Required when using reference number
 
 #### `create_journal_entry`
 
-Creates a new journal entry. Requires `mcp:journal:create` permission.
+Create a new journal entry.
 
-- **Parameters:**
-  - `title` (string, required): Entry title
-  - `content` (string, required): Entry content (markdown)
-  - `date` (string, optional): Entry date (ISO format, defaults to now)
-- **Returns:** The created journal entry object
+- `title` (required): Entry title
+- `content` (required): Markdown content
+- `date` (optional): ISO date string
 
 #### `update_journal_entry`
 
-Updates an existing journal entry. Requires `mcp:journal:update` permission.
+Update an existing journal entry.
 
-- **Parameters:**
-  - `entry_id` (string, required): The entry UUID
-  - `title` (string, optional): Updated title
-  - `content` (string, optional): Updated content (markdown)
-- **Returns:** The updated journal entry object
+- `entry_id` (required): The entry UUID
+- `title`, `content` (optional)
 
 ### Comments
 
 #### `create_work_item_comment`
 
-Adds a comment to a work item. Requires `mcp:comments:create` permission.
+Add a comment to a work item.
 
-- **Parameters:**
-  - `work_item_id` (string, required): The work item UUID
-  - `content` (string, required): Comment content (markdown)
-- **Returns:** The created comment object
+- `work_item_id` (required): The work item UUID
+- `content` (required): Markdown content
 
 #### `create_issue_comment`
 
-Adds a comment to an issue. Requires `mcp:comments:create` permission.
-
-- **Parameters:**
-  - `issue_id` (string, required): The issue UUID
-  - `content` (string, required): Comment content (markdown)
-- **Returns:** The created comment object
+Add a comment to an issue.
 
-### Radar Items (Initiatives)
+- `issue_id` (required): The issue UUID
+- `content` (required): Markdown content
 
-Radar items are strategic initiatives or roadmap items that group related work.
+### Radar Items
 
 #### `list_radar_items`
 
-Lists radar items from the team. By default, excludes completed items.
+List radar items/initiatives (excludes completed by default).
 
-- **Parameters:**
-  - `team_id` (number, optional): Team ID to filter
-  - `stage` (string, optional): Filter by stage (pending, now, next, later, completed). Use `completed` to see completed items.
-  - `limit` (number, optional): Maximum items to return
-  - `offset` (number, optional): Items to skip
-- **Returns:** Array of radar item objects
-- **Note:** Results are automatically paginated. If there are more than 200 items, you'll receive a truncation warning.
+- `team_id` (optional): Filter by team
+- `stage` (optional): Filter by stage (pending, now, next, later, completed)
+- `limit`, `offset` (optional): Pagination
 
 #### `get_radar_item`
 
-Gets a specific radar item by ID or reference number.
-
-- **Parameters:**
-  - `item_id` (string, required): The radar item ID (UUID) or refId (number)
-  - `team_id` (number, optional): Team ID (required when using refId)
-- **Returns:** Radar item object with work items and participants
-
-## Automatic Updates
-
-The MCP server checks for updates on startup. If a newer version is available, you'll see a notification in the server logs with instructions to update:
-
-```
-npm install -g wolfpack-mcp@latest
-```
-
-## Security
-
-- API keys authenticate with your Wolfpack account
-- Each key has configurable permissions for granular access control
-- Two-layer permission system: API key permissions checked first, then team role permissions
-- All operations are scoped to teams you are a member of
-- API keys can be revoked at any time from the Wolfpack application
-- All changes are logged with `source: 'mcp'` for audit trails
-
-## Troubleshooting
-
-### "WOLFPACK_API_KEY environment variable is required"
-
-This error means the API key is not configured. Check your Claude Desktop configuration file and ensure the `WOLFPACK_API_KEY` is set correctly.
-
-### "Invalid API key"
-
-Your API key may be incorrect or has been revoked. Generate a new API key from the Wolfpack application.
-
-### "API key does not have permission: mcp:..."
-
-Your API key doesn't have the required MCP permission. Create a new key with the appropriate permissions enabled.
-
-### Connection errors
+Get a specific radar item.
 
-Ensure:
+- `item_id` (required): UUID or reference number
+- `team_id` (optional): Required when using reference number
 
-1. The Wolfpack service is available at [wolfpacks.work](https://wolfpacks.work)
-2. Your network allows connections to the backend
-3. If self-hosting, verify `WOLFPACK_API_URL` points to the correct backend URL
+</details>

package/dist/client.js

@@ -43,6 +43,10 @@ export class WolfpackClient {
         firstParams.set('offset', '0');
         const firstQuery = firstParams.toString();
         const firstPage = await this.api.get(`${endpoint}${firstQuery ? `?${firstQuery}` : ''}`);
+        // Validate response structure
+        if (!firstPage || !Array.isArray(firstPage.items)) {
+            throw new Error(`Invalid API response from ${endpoint}: expected { items: [], total: number } but got ${JSON.stringify(firstPage)}`);
+        }
         // If total exceeds threshold, return first page with truncation warning
         if (firstPage.total > MAX_ITEMS_THRESHOLD) {
             return {
@@ -92,6 +96,10 @@ export class WolfpackClient {
                 params.append('offset', options.offset.toString());
             const query = params.toString();
             const response = await this.api.get(`/work-items${query ? `?${query}` : ''}`);
+            // Validate response structure
+            if (!response || !Array.isArray(response.items)) {
+                throw new Error(`Invalid API response from /work-items: expected { items: [], total: number } but got ${JSON.stringify(response)}`);
+            }
             return {
                 items: response.items,
                 total: response.total,
@@ -155,6 +163,10 @@ export class WolfpackClient {
                 params.append('offset', options.offset.toString());
             const query = params.toString();
             const response = await this.api.get(`/radar-items${query ? `?${query}` : ''}`);
+            // Validate response structure
+            if (!response || !Array.isArray(response.items)) {
+                throw new Error(`Invalid API response from /radar-items: expected { items: [], total: number } but got ${JSON.stringify(response)}`);
+            }
             return {
                 items: response.items,
                 total: response.total,
@@ -199,6 +211,10 @@ export class WolfpackClient {
                 params.append('offset', options.offset.toString());
             const query = params.toString();
             const response = await this.api.get(`/issues${query ? `?${query}` : ''}`);
+            // Validate response structure
+            if (!response || !Array.isArray(response.items)) {
+                throw new Error(`Invalid API response from /issues: expected { items: [], total: number } but got ${JSON.stringify(response)}`);
+            }
             return {
                 items: response.items,
                 total: response.total,
@@ -243,6 +259,10 @@ export class WolfpackClient {
                 params.append('offset', options.offset.toString());
             const query = params.toString();
             const response = await this.api.get(`/wiki-pages${query ? `?${query}` : ''}`);
+            // Validate response structure
+            if (!response || !Array.isArray(response.items)) {
+                throw new Error(`Invalid API response from /wiki-pages: expected { items: [], total: number } but got ${JSON.stringify(response)}`);
+            }
             return {
                 items: response.items,
                 total: response.total,

package/dist/config.js

@@ -8,12 +8,12 @@ export function validateConfig() {
     if (!config.apiKey) {
         console.error('Error: WOLFPACK_API_KEY environment variable is required');
         console.error('Please set WOLFPACK_API_KEY to your API key from the Wolfpack application');
-        console.error('Example: WOLFPACK_API_KEY=wfp_sk_...');
+        console.error('Example: WOLFPACK_API_KEY=wfp_sk_... (user) or wfp_ak_... (agent)');
         process.exit(1);
     }
-    if (!config.apiKey.startsWith('wfp_sk_')) {
+    if (!config.apiKey.startsWith('wfp_sk_') && !config.apiKey.startsWith('wfp_ak_')) {
         console.error('Error: Invalid API key format');
-        console.error('API keys should start with "wfp_sk_"');
+        console.error('API keys should start with "wfp_sk_" (user) or "wfp_ak_" (agent)');
         process.exit(1);
     }
     console.error(`MCP Server connecting to: ${config.apiUrl}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wolfpack-mcp",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "MCP server for Wolfpack AI-enhanced software delivery tools",
   "main": "dist/index.js",
   "type": "module",