wolfpack-mcp 1.0.0

package/README.md

@@ -0,0 +1,369 @@
+# 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.
+
+## Installation
+
+```bash
+npm install -g wolfpack-mcp
+```
+
+Or use directly with npx (no installation required):
+
+```bash
+npx wolfpack-mcp
+```
+
+## 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**
+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!
+
+### 2. Configure Claude Desktop
+
+Add the MCP server to your Claude Desktop configuration:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "wolfpack": {
+      "command": "npx",
+      "args": ["-y", "wolfpack-mcp"],
+      "env": {
+        "WOLFPACK_API_KEY": "wfp_sk_your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+Replace `wfp_sk_your_api_key_here` with your actual API key.
+
+**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.
+
+**Optional**: To pre-select a specific team, add `WOLFPACK_TEAM_SLUG` to the env:
+
+```json
+"env": {
+  "WOLFPACK_API_KEY": "wfp_sk_your_api_key_here",
+  "WOLFPACK_TEAM_SLUG": "your-team-slug"
+}
+```
+
+### 3. Restart Claude Desktop
+
+After updating the configuration, restart Claude Desktop to load the MCP server.
+
+## API Key Permissions
+
+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
+
+### Teams
+
+#### `list_teams`
+
+List all teams you have access to. Use this to discover available teams and get team IDs.
+
+- **Parameters:** None
+- **Returns:** Array of team objects 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.
+
+- **Parameters:**
+  - `team_id` (number, optional): Team ID (use `list_teams` to get IDs)
+  - `status` (string, optional): Filter by status (new, doing, review, completed, blocked)
+  - `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
+
+#### `get_work_item`
+
+Gets a specific work item by ID or reference number.
+
+- **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
+
+#### `create_work_item`
+
+Creates a new work item. Requires `mcp:work_items:create` permission.
+
+- **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
+
+#### `update_work_progress`
+
+Updates the description/notes on a work item. Requires `mcp:work_items:update` permission.
+
+- **Parameters:**
+  - `work_item_id` (string, required): The work item ID
+  - `description` (string, required): Complete updated description (markdown)
+- **Returns:** The updated work item object
+
+#### `update_work_item_status`
+
+Changes work item status. Requires `mcp:work_items:update` permission.
+
+- **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
+
+### Issues
+
+Issues track bugs, feature requests, and other items in the issue tracker.
+
+#### `list_issues`
+
+Lists issues from the team issue tracker.
+
+- **Parameters:**
+  - `team_id` (number, optional): Team ID to filter issues
+  - `status` (string, optional): Filter by status (open, in-progress, resolved, closed)
+  - `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
+
+#### `get_issue`
+
+Gets a specific issue by ID or reference number.
+
+- **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
+
+#### `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
+
+#### `update_issue`
+
+Updates an existing issue. Requires `mcp:issues:update` permission.
+
+- **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
+
+### Wiki Pages
+
+Wiki pages store team documentation and knowledge base articles.
+
+#### `list_wiki_pages`
+
+Lists wiki pages from your accessible teams.
+
+- **Parameters:**
+  - `limit` (number, optional): Maximum pages to return
+  - `offset` (number, optional): Pages to skip
+- **Returns:** Array of wiki page objects
+
+#### `get_wiki_page`
+
+Gets a specific 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
+
+#### `create_wiki_page`
+
+Creates a new wiki page. Requires `mcp:wiki:create` permission.
+
+- **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
+
+#### `update_wiki_page`
+
+Updates an existing wiki page. Requires `mcp:wiki:update` permission.
+
+- **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
+
+### Journal Entries
+
+Journal entries are daily logs, standup notes, or progress updates.
+
+#### `list_journal_entries`
+
+Lists journal entries from your accessible teams.
+
+- **Parameters:**
+  - `limit` (number, optional): Maximum entries to return
+  - `offset` (number, optional): Entries to skip
+- **Returns:** Array of journal entry objects
+
+#### `get_journal_entry`
+
+Gets a specific journal entry by ID or reference number.
+
+- **Parameters:**
+  - `entry_id` (string, required): The entry UUID or refId
+  - `team_id` (number, optional): Team ID (required when using refId)
+- **Returns:** Journal entry object
+
+#### `create_journal_entry`
+
+Creates a new journal entry. Requires `mcp:journal:create` permission.
+
+- **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
+
+#### `update_journal_entry`
+
+Updates an existing journal entry. Requires `mcp:journal:update` permission.
+
+- **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
+
+### Comments
+
+#### `create_work_item_comment`
+
+Adds a comment to a work item. Requires `mcp:comments:create` permission.
+
+- **Parameters:**
+  - `work_item_id` (string, required): The work item UUID
+  - `content` (string, required): Comment content (markdown)
+- **Returns:** The created comment object
+
+#### `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
+
+### Radar Items (Initiatives)
+
+Radar items are strategic initiatives or roadmap items that group related work.
+
+#### `list_radar_items`
+
+Lists radar items from the team.
+
+- **Parameters:**
+  - `team_id` (number, optional): Team ID to filter
+  - `stage` (string, optional): Filter by stage (pending, now, next, later, completed)
+  - `limit` (number, optional): Maximum items to return
+  - `offset` (number, optional): Items to skip
+- **Returns:** Array of radar item objects
+
+#### `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
+
+## 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
+
+Ensure:
+
+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

package/dist/apiClient.js

@@ -0,0 +1,118 @@
+import fetch from 'node-fetch';
+import { config } from './config.js';
+export class ApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'ApiError';
+    }
+}
+export class ApiClient {
+    headers = {
+        Authorization: `Bearer ${config.apiKey}`,
+        'Content-Type': 'application/json',
+    };
+    async get(path) {
+        const url = `${config.apiUrl}${path}`;
+        try {
+            const response = await fetch(url, {
+                method: 'GET',
+                headers: this.headers,
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new ApiError(response.status, `API error: ${response.statusText} - ${errorText}`);
+            }
+            return (await response.json());
+        }
+        catch (error) {
+            if (error instanceof ApiError) {
+                throw error;
+            }
+            throw new Error(`Failed to GET ${path}: ${error}`);
+        }
+    }
+    async post(path, body) {
+        const url = `${config.apiUrl}${path}`;
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: this.headers,
+                body: JSON.stringify(body),
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new ApiError(response.status, `API error: ${response.statusText} - ${errorText}`);
+            }
+            return (await response.json());
+        }
+        catch (error) {
+            if (error instanceof ApiError) {
+                throw error;
+            }
+            throw new Error(`Failed to POST ${path}: ${error}`);
+        }
+    }
+    async put(path, body) {
+        const url = `${config.apiUrl}${path}`;
+        try {
+            const response = await fetch(url, {
+                method: 'PUT',
+                headers: this.headers,
+                body: JSON.stringify(body),
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new ApiError(response.status, `API error: ${response.statusText} - ${errorText}`);
+            }
+            return (await response.json());
+        }
+        catch (error) {
+            if (error instanceof ApiError) {
+                throw error;
+            }
+            throw new Error(`Failed to PUT ${path}: ${error}`);
+        }
+    }
+    async patch(path, body) {
+        const url = `${config.apiUrl}${path}`;
+        try {
+            const response = await fetch(url, {
+                method: 'PATCH',
+                headers: this.headers,
+                body: JSON.stringify(body),
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new ApiError(response.status, `API error: ${response.statusText} - ${errorText}`);
+            }
+            return (await response.json());
+        }
+        catch (error) {
+            if (error instanceof ApiError) {
+                throw error;
+            }
+            throw new Error(`Failed to PATCH ${path}: ${error}`);
+        }
+    }
+    async delete(path) {
+        const url = `${config.apiUrl}${path}`;
+        try {
+            const response = await fetch(url, {
+                method: 'DELETE',
+                headers: this.headers,
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new ApiError(response.status, `API error: ${response.statusText} - ${errorText}`);
+            }
+        }
+        catch (error) {
+            if (error instanceof ApiError) {
+                throw error;
+            }
+            throw new Error(`Failed to DELETE ${path}: ${error}`);
+        }
+    }
+}