npm - feedbackbasket-mcp-server - Versions diffs - 2.0.0 → 3.0.0 - Mend

feedbackbasket-mcp-server 2.0.0 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,14 @@
+# Changelog
+## [3.0.0] - 2026-08-22
+### Added
+- Added the complete 31-tool FeedbackBasket product-operation contract.
+- Added structured MCP output, tool schemas, annotations, input checks, and confirmation checks.
+- Added parity, protocol, client-path, build, and package release checks.
+### Changed
+- Read and full keys now follow the same scopes and project restrictions as the live MCP server.
+- The package, server, and shared contract now use version `3.0.0`.

package/README.md CHANGED Viewed

@@ -1,192 +1,191 @@
-# FeedbackBasket MCP Server
-Model Context Protocol (MCP) server for FeedbackBasket that allows AI assistants to query your project feedback and bug reports.
-## Features
-- 🔍 **List Projects** - View all your FeedbackBasket projects with summary statistics
-- 📝 **Get Feedback** - Retrieve feedback with filtering by category, status, sentiment, and more
-- 🐛 **Get Bug Reports** - Specifically fetch bug reports with severity classification
-- 🔎 **Search Feedback** - Search across all feedback content using text queries
-- 🔐 **Secure Authentication** - Uses API keys with project-level access control
-- 📊 **Rich Statistics** - Get counts by category, status, sentiment, and severity
-## Installation & Setup
-### 1. Generate API Key
-First, you'll need to create an API key from your FeedbackBasket account:
-1. **Visit** [feedbackbasket.com](https://feedbackbasket.com) and log into your account
-2. **Navigate** to your Account Settings (click your profile → Account)
-3. **Find** the "MCP API Keys" section
-4. **Click** "New API Key"
-5. **Name your key** (e.g., "Claude Desktop", "Cursor IDE", "Windsurf")
-6. **Select projects** you want to grant access to (or leave empty for all projects)
-7. **Copy the generated API key** (starts with `fb_key_`) - you'll only see the full key once!
-> 💡 **Tip**: You can manage your API keys anytime from your account settings at [feedbackbasket.com/account](https://feedbackbasket.com/account)
-### 2. Configure Your Editor
-Add the MCP server to your editor's configuration:
-#### Quick Setup (All Editors)
-```json
-{
-  "mcpServers": {
-    "feedbackbasket": {
-      "command": "npx",
-      "args": ["-y", "@feedbackbasket/mcp-server@latest", "--api-key", "fb_key_your_api_key_here"]
-    }
-  }
-}
-```
-#### Detailed Examples
-#### Claude Desktop
-```json
-{
-  "mcpServers": {
-    "feedbackbasket": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@feedbackbasket/mcp-server@latest",
-        "--api-key",
-        "fb_key_your_api_key_here"
-      ]
-    }
-  }
-}
-```
-#### Cursor/Windsurf
-```json
-{
-  "mcpServers": {
-    "feedbackbasket": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@feedbackbasket/mcp-server@latest",
-        "--api-key",
-        "fb_key_your_api_key_here"
-      ]
-    }
-  }
-}
-```
-#### Environment Variable (Alternative)
-```json
-{
-  "mcpServers": {
-    "feedbackbasket": {
-      "command": "npx",
-      "args": ["-y", "@feedbackbasket/mcp-server@latest"],
-      "env": {
-        "FEEDBACKBASKET_API_KEY": "fb_key_your_api_key_here"
-      }
-    }
-  }
-}
-```
-## Usage Examples
-Once configured, you can ask your AI assistant:
-### Project Overview
-- "Show me all my FeedbackBasket projects"
-- "What projects do I have and how much feedback do they have?"
-### Bug Reports
-- "Show me all bug reports from my projects"
-- "Get high severity bug reports that are still pending"
-- "Find bug reports for my main website project"
-### Feedback Analysis
-- "Show me negative feedback from the last week"
-- "Get all feature requests from my mobile app project"
-- "Search for feedback containing 'login error'"
-### Filtering & Search
-- "Show me reviewed feedback with positive sentiment"
-- "Find all pending bug reports with high severity"
-- "Search for feedback about 'payment issues' in my e-commerce project"
-## Available Tools
-### `list_projects`
-Lists all projects accessible by your API key with summary statistics.
-### `get_feedback`
-Retrieves feedback with optional filtering:
-- `projectId` - Filter by specific project
-- `category` - Filter by BUG, FEATURE, or REVIEW
-- `status` - Filter by PENDING, REVIEWED, or DONE
-- `sentiment` - Filter by POSITIVE, NEGATIVE, or NEUTRAL
-- `search` - Text search in feedback content
-- `limit` - Number of results (max 100)
-- `includeNotes` - Include internal notes
-### `get_bug_reports`
-Specifically fetches bug reports with computed severity:
-- `projectId` - Filter by specific project
-- `status` - Filter by bug status
-- `severity` - Filter by high, medium, or low severity
-- `search` - Text search in bug reports
-- `limit` - Number of results (max 100)
-- `includeNotes` - Include internal notes
-### `search_feedback`
-Searches feedback content across all accessible projects:
-- `query` - Search text (required)
-- `projectId` - Limit to specific project
-- `category` - Filter by category
-- `limit` - Number of results (max 50)
-## Security & Privacy
-- ✅ **Read-only access** - MCP server can only read data, never modify
-- ✅ **Project-level permissions** - Grant access only to specific projects
-- ✅ **API key authentication** - Secure token-based authentication
-- ✅ **Usage tracking** - Monitor API key usage in your dashboard
-- ✅ **Revokable access** - Instantly deactivate API keys if needed
-- ✅ **Subscription limits respected** - Only returns feedback within your plan limits
-## Troubleshooting
-### "Invalid or missing API key"
-- Check that your API key starts with `fb_key_`
-- Ensure the API key is still active in your dashboard
-- Verify the API key has access to at least one project
-### "No projects found"
-- Make sure your API key has been granted access to projects
-- Check that you have projects in your FeedbackBasket account
-### "Authentication failed"
-- Verify your API key hasn't been revoked
-- Check that the API key format is correct (71 characters, starts with `fb_key_`)
-### Installation Issues
-- Ensure you have Node.js installed
-- Try clearing npx cache: `npx clear-npx-cache`
-- Check your internet connection for package downloads
-## API Key Management
-Visit your [FeedbackBasket dashboard](https://feedbackbasket.com/dashboard/settings) to:
-- Generate new API keys
-- Manage project access for existing keys
-- View usage statistics
-- Deactivate or delete keys
-- Monitor key activity
-## Support
-- 🐛 Issues: [GitHub Issues](https://github.com/deifos/feedbackbasket-mcp/issues)
-- 📖 Docs: [FeedbackBasket Documentation](https://feedbackbasket.com/docs)
+# FeedbackBasket MCP Server
+Model Context Protocol (MCP) server for [FeedbackBasket](https://feedbackbasket.com). Version `3.0.0` provides the same 31 product operations as the FeedbackBasket CLI and live Streamable HTTP server.
+Use a read key for queries. Use a full key for approved writes. A project-restricted key can access only its allowed projects. Project creation and team operations need an unrestricted full key. Each high-impact operation needs `confirm: true`.
+You can use this stdio package or connect directly to `https://feedbackbasket.com/.well-known/mcp` with Streamable HTTP. Both transports use the same MCP key and contract.
+## Installation & Setup
+### 1. Generate API Key
+1. Log into [feedbackbasket.com](https://feedbackbasket.com)
+2. Go to **Settings** (sidebar)
+3. Scroll to **MCP API Keys** section
+4. Click **New API Key**
+5. Name your key (e.g., "Claude Code", "Cursor", "Windsurf")
+6. Select projects to grant access to (or leave empty for all projects)
+7. Copy the generated key. It is shown only once. Keep it out of source, logs, prompts, and command history.
+### 2. Configure Your Editor
+#### Claude Code (CLI)
+Set `FEEDBACKBASKET_API_KEY` in the environment that starts Claude Code. Then
+add the server without putting the key in the command or shell history:
+```bash
+claude mcp add feedbackbasket -- npx -y feedbackbasket-mcp-server@3.0.0
+```
+On native Windows, use `cmd /c npx` as the command because Claude Code cannot
+start `npx` directly there.
+#### Claude Desktop
+Add to your Claude Desktop config (`claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "feedbackbasket": {
+      "command": "npx",
+      "args": ["-y", "feedbackbasket-mcp-server@3.0.0"],
+      "env": { "FEEDBACKBASKET_API_KEY": "${FEEDBACKBASKET_API_KEY}" }
+    }
+  }
+}
+```
+#### Cursor / Windsurf
+Add to your MCP config (`.cursor/mcp.json` or equivalent):
+```json
+{
+  "mcpServers": {
+    "feedbackbasket": {
+      "command": "npx",
+      "args": ["-y", "feedbackbasket-mcp-server@3.0.0"],
+      "env": { "FEEDBACKBASKET_API_KEY": "${FEEDBACKBASKET_API_KEY}" }
+    }
+  }
+}
+```
+#### Environment Variable
+Use an environment variable instead of the `--api-key` argument. This keeps
+the key out of process listings and saved command history.
+```json
+{
+  "mcpServers": {
+    "feedbackbasket": {
+      "command": "npx",
+      "args": ["-y", "feedbackbasket-mcp-server@latest"],
+      "env": {
+        "FEEDBACKBASKET_API_KEY": "${FEEDBACKBASKET_API_KEY}"
+      }
+    }
+  }
+}
+```
+## Usage Examples
+Once configured, ask your AI assistant:
+### Project Overview
+- "Show me all my FeedbackBasket projects"
+- "How much feedback does each project have?"
+### Bug Reports
+- "Show me all open bug reports"
+- "Get high severity bugs that haven't been addressed"
+- "Find bugs related to authentication"
+### Feedback Analysis
+- "Show me negative feedback from my project"
+- "Get all feature requests"
+- "What are users asking for the most?"
+- "Show me high priority feedback"
+### Search
+- "Search for feedback about 'payment issues'"
+- "Find feedback mentioning 'mobile'"
+### Agentic Workflows
+- "Look at my bug reports and suggest which ones to fix first"
+- "Summarize this week's feedback trends"
+- "Are users happy with the new checkout flow?"
+<!-- BEGIN GENERATED AGENT CAPABILITIES -->
+## Agent capability contract
+Agent surface version: `3.0.0`. The CLI and both MCP transports implement the same 31 product operations.
+| Product operation | CLI command | MCP tool | Required access | Confirm |
+| --- | --- | --- | --- | --- |
+| `projects.list` | `projects list` | `list_projects` | `read:projects` | No |
+| `projects.get` | `projects show` | `get_project` | `read:projects; allowed project` | No |
+| `projects.create` | `projects create` | `create_project` | `write:projects; unrestricted key` | No |
+| `projects.update` | `projects update` | `update_project` | `write:projects; allowed project` | No |
+| `projects.delete` | `projects delete` | `delete_project` | `write:projects; allowed project` | Yes |
+| `feedback.list` | `feedback list` | `get_feedback` | `read:feedback; allowed project` | No |
+| `feedback.get` | `feedback show` | `get_feedback_item` | `read:feedback; allowed project` | No |
+| `feedback.search` | `feedback search` | `search_feedback` | `read:feedback; allowed project` | No |
+| `feedback.create` | `feedback create` | `create_feedback` | `write:feedback; allowed project` | No |
+| `feedback.update` | `feedback update` | `update_feedback` | `write:feedback; allowed project` | No |
+| `feedback.delete` | `feedback delete` | `delete_feedback` | `write:feedback; allowed project` | Yes |
+| `feedback.bulkUpdate` | `feedback bulk-update` | `bulk_update_feedback` | `write:feedback; allowed project` | Yes |
+| `feedback.export` | `feedback export` | `export_feedback` | `read:feedback; allowed project` | No |
+| `bugs.list` | `bugs list` | `get_bug_reports` | `read:feedback; allowed project` | No |
+| `bugs.stats` | `bugs stats` | `get_bug_stats` | `read:feedback; allowed project` | No |
+| `notes.create` | `feedback note` | `create_feedback_note` | `write:notes; allowed project` | No |
+| `notes.update` | `feedback note update` | `update_feedback_note` | `write:notes; allowed project` | No |
+| `notes.delete` | `feedback note delete` | `delete_feedback_note` | `write:notes; allowed project` | Yes |
+| `replies.list` | `feedback replies` | `list_feedback_replies` | `read:feedback; allowed project` | No |
+| `replies.send` | `feedback reply` | `send_feedback_reply` | `write:replies; allowed project` | Yes |
+| `widget.getSettings` | `widget settings` | `get_widget_settings` | `read:projects; allowed project` | No |
+| `widget.updateSettings` | `widget update`<br>`widget flow` | `update_widget_settings` | `write:widget; allowed project` | No |
+| `widget.getScript` | `widget script` | `get_widget_script` | `read:projects; allowed project` | No |
+| `mobile.get` | `mobile status`<br>`mobile verify` | `get_mobile_integration` | `read:projects; allowed project` | No |
+| `mobile.update` | `mobile setup`<br>`mobile bundle`<br>`mobile conversations`<br>`mobile disable` | `update_mobile_integration` | `write:mobile; allowed project` | No |
+| `mobile.rotateKey` | `mobile rotate-key` | `rotate_mobile_project_key` | `write:mobile; allowed project` | Yes |
+| `waitlist.list` | `waitlist list` | `get_waitlist` | `read:feedback; allowed project` | No |
+| `waitlist.export` | `waitlist export` | `export_waitlist` | `read:feedback; allowed project` | No |
+| `team.list` | `team list` | `list_team_members` | `write:team; unrestricted key` | No |
+| `team.updateRole` | `team role` | `update_team_member_role` | `write:team; unrestricted key` | Yes |
+| `team.remove` | `team remove` | `remove_team_member` | `write:team; unrestricted key` | Yes |
+<!-- END GENERATED AGENT CAPABILITIES -->
+## Security & Privacy
+- **Explicit access** — Read keys query data. Full keys can use approved write operations.
+- **Project-level permissions** — Restricted keys can access only selected projects.
+- **Confirmation** — High-impact operations do not run without explicit confirmation.
+- **API key authentication** — Secure token-based authentication
+- **Usage tracking** — Monitor API key usage from your Settings page
+- **Revokable access** — Deactivate or delete API keys instantly
+## Troubleshooting
+### "Invalid or missing API key"
+- Check that your API key starts with `fb_key_`
+- Ensure the key is still active in Settings > MCP API Keys
+- Verify the key has access to at least one project
+### "No projects found"
+- Make sure your API key has been granted access to projects
+- Check that you have projects in your FeedbackBasket account
+### Connection Issues
+- Ensure Node.js 18+ is installed
+- Try clearing npx cache: `npx clear-npx-cache`
+- For local development, add `--base-url http://localhost:3000`
+## API Key Management
+Visit [feedbackbasket.com/dashboard/settings](https://feedbackbasket.com/dashboard/settings) to:
+- Generate new API keys
+- Manage project access
+- View usage statistics
+- Activate/deactivate keys
+- Delete keys
+## Links
+- [FeedbackBasket](https://feedbackbasket.com)
+- [GitHub Issues](https://github.com/deifos/feedbackbasket-mcp/issues)

package/dist/client.d.ts CHANGED Viewed

@@ -1,50 +1,22 @@
+import { type ProductOperationId } from 'feedbackbasket-agent-contract';
+export type McpOperationResult = {
+    structuredContent: Record<string, unknown>;
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+};
+export type OperationRequest = {
+    method: "GET" | "POST" | "PATCH" | "DELETE";
+    url: string;
+    params?: Record<string, unknown>;
+    data?: Record<string, unknown>;
+};
+export declare function createOperationRequest(operationId: ProductOperationId, rawArgs: Record<string, unknown>): OperationRequest;
 export declare class FeedbackBasketClient {
-    private api;
+    private readonly api;
     constructor(apiKey: string, baseUrl?: string);
-    listProjects(): Promise<{
-        content: Array<{
-            type: string;
-            text: string;
-        }>;
-    }>;
-    getFeedback(params?: {
-        projectId?: string;
-        category?: string;
-        status?: string;
-        sentiment?: string;
-        limit?: number;
-        offset?: number;
-        search?: string;
-        includeNotes?: boolean;
-    }): Promise<{
-        content: Array<{
-            type: string;
-            text: string;
-        }>;
-    }>;
-    getBugReports(params?: {
-        projectId?: string;
-        status?: string;
-        severity?: 'high' | 'medium' | 'low';
-        limit?: number;
-        offset?: number;
-        search?: string;
-        includeNotes?: boolean;
-    }): Promise<{
-        content: Array<{
-            type: string;
-            text: string;
-        }>;
-    }>;
-    searchFeedback(query: string, options?: {
-        projectId?: string;
-        category?: string;
-        limit?: number;
-    }): Promise<{
-        content: Array<{
-            type: string;
-            text: string;
-        }>;
-    }>;
+    execute(operationId: ProductOperationId, rawArgs: Record<string, unknown>): Promise<McpOperationResult>;
     private handleError;
 }

package/dist/client.js CHANGED Viewed

@@ -1,208 +1,98 @@
 import axios, { AxiosError } from 'axios';
+import { AGENT_SURFACE_VERSION, getProductOperation, } from 'feedbackbasket-agent-contract';
+export function createOperationRequest(operationId, rawArgs) {
+    const operation = getProductOperation(operationId);
+    if (!operation)
+        throw new Error(`Unknown operation: ${operationId}`);
+    const args = { ...rawArgs };
+    const requestPath = operation.http.path.replace(/\{([^}]+)\}/g, (_match, name) => {
+        const value = args[name];
+        if (typeof value !== 'string' || value.length === 0)
+            throw new Error(`${name} is required.`);
+        delete args[name];
+        return encodeURIComponent(value);
+    });
+    delete args.confirm;
+    if (operationId === 'feedback.search') {
+        args.search = args.query;
+        delete args.query;
+    }
+    if (operationId === 'widget.updateSettings' && args.settings && typeof args.settings === 'object') {
+        Object.assign(args, args.settings);
+        delete args.settings;
+    }
+    const params = {};
+    for (const name of operation.http.queryParameters) {
+        if (name in args) {
+            params[name] = args[name];
+            delete args[name];
+        }
+    }
+    if (operation.http.method === 'GET')
+        Object.assign(params, args);
+    return {
+        method: operation.http.method,
+        url: requestPath,
+        ...(Object.keys(params).length > 0 ? { params } : {}),
+        ...(operation.http.method === 'GET' ? {} : { data: args }),
+    };
+}
 export class FeedbackBasketClient {
     api;
     constructor(apiKey, baseUrl = 'https://feedbackbasket.com') {
         this.api = axios.create({
-            baseURL: `${baseUrl}/api/mcp`,
+            baseURL: baseUrl.replace(/\/$/, ''),
             headers: {
-                'Authorization': `Bearer ${apiKey}`,
+                Authorization: `Bearer ${apiKey}`,
                 'Content-Type': 'application/json',
-                'User-Agent': 'FeedbackBasket-MCP/2.0.0',
+                'User-Agent': `FeedbackBasket-MCP/${AGENT_SURFACE_VERSION}`,
             },
-            timeout: 30000,
+            timeout: 30_000,
         });
     }
-    async listProjects() {
-        try {
-            const response = await this.api.post('/projects', {});
-            const projects = response.data.projects;
-            if (projects.length === 0) {
-                return {
-                    content: [{
-                            type: 'text',
-                            text: 'No projects found. Make sure your API key has access to projects in your FeedbackBasket dashboard.'
-                        }]
-                };
-            }
-            const projectList = projects.map(project => {
-                const openCount = project.byStatus['OPEN'] || 0;
-                const bugCount = project.byCategory['BUG'] || 0;
-                return [
-                    `**${project.name}**`,
-                    `  ID: ${project.id}`,
-                    `  URL: ${project.url}`,
-                    `  Total Feedback: ${project.totalFeedback}`,
-                    `  Open: ${openCount} | Bugs: ${bugCount}`,
-                    ''
-                ].join('\n');
-            }).join('\n');
-            return {
-                content: [{
-                        type: 'text',
-                        text: `# FeedbackBasket Projects (${projects.length} total)\n\n${projectList}`
-                    }]
-            };
-        }
-        catch (error) {
-            throw this.handleError('Failed to fetch projects', error);
-        }
-    }
-    async getFeedback(params = {}) {
+    async execute(operationId, rawArgs) {
+        const request = createOperationRequest(operationId, rawArgs);
         try {
-            const response = await this.api.post('/feedback', {
-                limit: 20,
-                includeNotes: false,
-                ...params,
+            const response = await this.api.request({
+                ...request,
+                transformResponse: [(value) => {
+                        try {
+                            return JSON.parse(value);
+                        }
+                        catch {
+                            return value;
+                        }
+                    }],
             });
-            const feedback = response.data.feedback;
-            if (feedback.length === 0) {
-                const filters = Object.entries(params)
-                    .filter(([, value]) => value !== undefined)
-                    .map(([key, value]) => `${key}: ${value}`)
-                    .join(', ');
-                return {
-                    content: [{
-                            type: 'text',
-                            text: `No feedback found${filters ? ` with filters: ${filters}` : ''}.`
-                        }]
-                };
-            }
-            const feedbackList = feedback.map(item => {
-                const category = item.category || 'UNCATEGORIZED';
-                const sentiment = item.sentiment || 'UNKNOWN';
-                const priority = item.aiPriorityScore != null
-                    ? ` | Priority: ${item.aiPriorityScore >= 70 ? 'HIGH' : item.aiPriorityScore >= 40 ? 'MEDIUM' : 'LOW'} (${item.aiPriorityScore}/100)`
-                    : '';
-                const lines = [
-                    `**${category} | ${sentiment} | ${item.status}${priority}**`,
-                    `Project: ${item.project.name}`,
-                ];
-                if (item.aiSummary)
-                    lines.push(`Summary: ${item.aiSummary}`);
-                lines.push(`Content: ${item.content.length > 150 ? item.content.substring(0, 150) + '...' : item.content}`);
-                if (item.email)
-                    lines.push(`Email: ${item.email}`);
-                if (item.pageUrl)
-                    lines.push(`Page: ${item.pageUrl}`);
-                if (item.browser || item.os)
-                    lines.push(`Browser: ${[item.browser, item.os, item.device].filter(Boolean).join(' | ')}`);
-                if (item.notes && item.notes.length > 0) {
-                    lines.push(`Notes: ${item.notes.map(n => `[${n.author.name}] ${n.content}`).join('; ')}`);
-                }
-                lines.push(`Created: ${new Date(item.createdAt).toLocaleDateString()}`);
-                lines.push('');
-                return lines.join('\n');
-            }).join('\n');
-            const { pagination } = response.data;
+            const structuredContent = response.data && typeof response.data === 'object' && !Array.isArray(response.data)
+                ? response.data
+                : { value: response.data };
             return {
-                content: [{
-                        type: 'text',
-                        text: [
-                            `# Feedback Results (${feedback.length} of ${pagination.totalCount})\n`,
-                            feedbackList,
-                            pagination.hasMore ? `\n*Showing ${feedback.length} results. Use offset: ${pagination.offset + pagination.limit} to get more.*` : '',
-                        ].join('\n')
-                    }]
+                structuredContent,
+                content: [{ type: 'text', text: JSON.stringify(structuredContent) }],
             };
         }
         catch (error) {
-            throw this.handleError('Failed to fetch feedback', error);
+            throw this.handleError(error);
         }
     }
-    async getBugReports(params = {}) {
-        try {
-            const response = await this.api.post('/feedback/bugs', {
-                limit: 20,
-                includeNotes: false,
-                ...params,
-            });
-            const bugReports = response.data.bugReports;
-            if (bugReports.length === 0) {
-                const filters = Object.entries(params)
-                    .filter(([, value]) => value !== undefined)
-                    .map(([key, value]) => `${key}: ${value}`)
-                    .join(', ');
-                return {
-                    content: [{
-                            type: 'text',
-                            text: `No bug reports found${filters ? ` with filters: ${filters}` : ''}.`
-                        }]
-                };
-            }
-            const bugList = bugReports.map(bug => {
-                const severityEmoji = bug.severity === 'high' ? '🔴' : bug.severity === 'medium' ? '🟡' : '🟢';
-                const statusMap = {
-                    OPEN: '⏳', UNDER_REVIEW: '👁️', PLANNED: '📋',
-                    IN_PROGRESS: '🔨', COMPLETE: '✅', CLOSED: '🔒'
-                };
-                const statusEmoji = statusMap[bug.status] || '❓';
-                const lines = [
-                    `${severityEmoji} **${bug.severity.toUpperCase()} SEVERITY** ${statusEmoji} ${bug.status}`,
-                    `Project: ${bug.project.name}`,
-                ];
-                if (bug.aiSummary)
-                    lines.push(`Summary: ${bug.aiSummary}`);
-                lines.push(`Bug: ${bug.content.length > 150 ? bug.content.substring(0, 150) + '...' : bug.content}`);
-                if (bug.email)
-                    lines.push(`Reported by: ${bug.email}`);
-                if (bug.pageUrl)
-                    lines.push(`Page: ${bug.pageUrl}`);
-                if (bug.browser || bug.os)
-                    lines.push(`Browser: ${[bug.browser, bug.os, bug.device].filter(Boolean).join(' | ')}`);
-                lines.push(`Reported: ${new Date(bug.createdAt).toLocaleDateString()}`);
-                lines.push('');
-                return lines.join('\n');
-            }).join('\n');
-            const stats = response.data.stats;
-            const statsText = [
-                `## Bug Statistics`,
-                `Total Bugs: ${stats.total}`,
-                `🔴 High: ${stats.bySeverity.high} | 🟡 Medium: ${stats.bySeverity.medium} | 🟢 Low: ${stats.bySeverity.low}`,
-                `Open: ${stats.byStatus['OPEN'] || 0} | Under Review: ${stats.byStatus['UNDER_REVIEW'] || 0} | In Progress: ${stats.byStatus['IN_PROGRESS'] || 0} | Complete: ${stats.byStatus['COMPLETE'] || 0}`,
-                ''
-            ].join('\n');
-            const { pagination } = response.data;
-            return {
-                content: [{
-                        type: 'text',
-                        text: [
-                            `# Bug Reports (${bugReports.length} of ${pagination.totalCount})\n`,
-                            statsText,
-                            bugList,
-                            pagination.hasMore ? `\n*Showing ${bugReports.length} results. Use offset: ${pagination.offset + pagination.limit} to get more.*` : '',
-                        ].join('\n')
-                    }]
-            };
-        }
-        catch (error) {
-            throw this.handleError('Failed to fetch bug reports', error);
-        }
-    }
-    async searchFeedback(query, options = {}) {
-        return this.getFeedback({
-            search: query,
-            limit: options.limit || 10,
-            ...(options.projectId && { projectId: options.projectId }),
-            ...(options.category && { category: options.category }),
-        });
-    }
-    handleError(message, error) {
+    handleError(error) {
         if (error instanceof AxiosError) {
             const status = error.response?.status;
-            const responseMessage = error.response?.data?.error || error.response?.data?.message || error.message;
-            if (status === 401) {
-                return new Error(`Authentication failed: ${responseMessage}. Check your API key.`);
-            }
-            else if (status === 403) {
-                return new Error(`Access denied: ${responseMessage}. Check your API key permissions.`);
-            }
-            else if (status === 429) {
-                return new Error(`Rate limit exceeded. Please try again later.`);
-            }
-            else {
-                return new Error(`${message}: ${responseMessage} (HTTP ${status})`);
-            }
+            const data = error.response?.data;
+            const responseMessage = typeof data?.error === 'string'
+                ? data.error
+                : typeof data?.message === 'string'
+                    ? data.message
+                    : error.message;
+            if (status === 401)
+                return new Error(`Authentication failed: ${responseMessage}.`);
+            if (status === 403)
+                return new Error(`Access denied: ${responseMessage}.`);
+            if (status === 429)
+                return new Error('Rate limit exceeded. Try again later.');
+            return new Error(`FeedbackBasket request failed: ${responseMessage} (HTTP ${status ?? 'unknown'}).`);
         }
-        return new Error(`${message}: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        return new Error(error instanceof Error ? error.message : 'FeedbackBasket request failed.');
     }
 }

package/dist/index.d.ts CHANGED Viewed

@@ -1,2 +1,22 @@
 #!/usr/bin/env node
-export {};
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { FeedbackBasketClient, type McpOperationResult } from './client.js';
+export declare const MCP_TOOLS: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: Readonly<Record<string, unknown>>;
+    outputSchema: Readonly<Record<string, unknown>>;
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+}[];
+export declare function parseArgs(args: string[]): {
+    apiKey?: string;
+    baseUrl?: string;
+};
+export declare function dispatchTool(client: Pick<FeedbackBasketClient, 'execute'>, name: string, args: unknown): Promise<McpOperationResult>;
+export declare function createServer(client: FeedbackBasketClient): Server;

package/dist/index.js CHANGED Viewed

@@ -1,228 +1,90 @@
 #!/usr/bin/env node
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { AGENT_SURFACE_VERSION, PRODUCT_OPERATIONS, getProductOperationByTool, validateOperationInput, } from 'feedbackbasket-agent-contract';
 import { FeedbackBasketClient } from './client.js';
-function parseArgs(args) {
-    let apiKey;
-    let baseUrl;
-    for (let i = 0; i < args.length; i++) {
-        const arg = args[i] ?? '';
-        if (arg.startsWith('--api-key')) {
-            const eqIdx = arg.indexOf('=');
-            apiKey = eqIdx > 0 ? arg.slice(eqIdx + 1) : args[++i];
+export const MCP_TOOLS = PRODUCT_OPERATIONS.map((operation) => ({
+    name: operation.mcp.name,
+    title: operation.mcp.title,
+    description: operation.mcp.description,
+    inputSchema: operation.mcp.inputSchema,
+    outputSchema: operation.mcp.outputSchema,
+    annotations: {
+        readOnlyHint: operation.risk.readOnly,
+        destructiveHint: operation.risk.destructive,
+        idempotentHint: operation.risk.idempotent,
+        openWorldHint: operation.risk.openWorld,
+    },
+}));
+export function parseArgs(args) {
+    const result = {};
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index] ?? '';
+        if (arg === '--api-key') {
+            const value = args[++index];
+            if (value !== undefined)
+                result.apiKey = value;
         }
-        else if (arg.startsWith('--base-url')) {
-            const eqIdx = arg.indexOf('=');
-            baseUrl = eqIdx > 0 ? arg.slice(eqIdx + 1) : args[++i];
+        else if (arg.startsWith('--api-key='))
+            result.apiKey = arg.slice('--api-key='.length);
+        else if (arg === '--base-url') {
+            const value = args[++index];
+            if (value !== undefined)
+                result.baseUrl = value;
         }
+        else if (arg.startsWith('--base-url='))
+            result.baseUrl = arg.slice('--base-url='.length);
     }
-    return { apiKey, baseUrl };
-}
-const options = parseArgs(process.argv.slice(2));
-const apiKey = options.apiKey || process.env.FEEDBACKBASKET_API_KEY;
-const baseUrl = options.baseUrl || 'https://feedbackbasket.com';
-if (!apiKey) {
-    console.error('Error: API key required.');
-    console.error('Usage: --api-key <key> or set FEEDBACKBASKET_API_KEY env var');
-    process.exit(1);
-}
-if (!apiKey.startsWith('fb_key_')) {
-    console.error('Error: Invalid API key format. Keys should start with "fb_key_".');
-    process.exit(1);
+    return result;
 }
-const client = new FeedbackBasketClient(apiKey, baseUrl);
-const server = new Server({
-    name: 'feedbackbasket-mcp',
-    version: '2.0.0',
-    capabilities: {
-        tools: {},
-    },
-});
-server.setRequestHandler(ListToolsRequestSchema, async (_request) => {
-    return {
-        tools: [
-            {
-                name: 'list_projects',
-                description: 'List all FeedbackBasket projects accessible by your API key with summary statistics including feedback counts by status and category',
-                inputSchema: {
-                    type: 'object',
-                    properties: {},
-                    additionalProperties: false,
-                },
-            },
-            {
-                name: 'get_feedback',
-                description: 'Get feedback from your FeedbackBasket projects with filtering. Returns AI analysis (summary, priority, category, sentiment), page URL, browser info, and optional notes.',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        projectId: {
-                            type: 'string',
-                            description: 'Filter by specific project ID',
-                        },
-                        category: {
-                            type: 'string',
-                            enum: ['BUG', 'FEATURE_REQUEST', 'IMPROVEMENT', 'QUESTION'],
-                            description: 'Filter by feedback category',
-                        },
-                        status: {
-                            type: 'string',
-                            enum: ['OPEN', 'UNDER_REVIEW', 'PLANNED', 'IN_PROGRESS', 'COMPLETE', 'CLOSED'],
-                            description: 'Filter by feedback status',
-                        },
-                        sentiment: {
-                            type: 'string',
-                            enum: ['POSITIVE', 'NEGATIVE', 'NEUTRAL'],
-                            description: 'Filter by sentiment analysis result',
-                        },
-                        search: {
-                            type: 'string',
-                            description: 'Search feedback content for specific text',
-                        },
-                        limit: {
-                            type: 'number',
-                            description: 'Maximum number of results (default: 20, max: 100)',
-                            minimum: 1,
-                            maximum: 100,
-                        },
-                        offset: {
-                            type: 'number',
-                            description: 'Offset for pagination (default: 0)',
-                            minimum: 0,
-                        },
-                        includeNotes: {
-                            type: 'boolean',
-                            description: 'Include internal team notes (default: false)',
-                        },
-                    },
-                    additionalProperties: false,
-                },
-            },
-            {
-                name: 'get_bug_reports',
-                description: 'Get bug reports from your FeedbackBasket projects with severity classification (high/medium/low based on sentiment) and statistics',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        projectId: {
-                            type: 'string',
-                            description: 'Filter by specific project ID',
-                        },
-                        status: {
-                            type: 'string',
-                            enum: ['OPEN', 'UNDER_REVIEW', 'PLANNED', 'IN_PROGRESS', 'COMPLETE', 'CLOSED'],
-                            description: 'Filter by bug status',
-                        },
-                        severity: {
-                            type: 'string',
-                            enum: ['high', 'medium', 'low'],
-                            description: 'Filter by severity (high=negative sentiment, medium=neutral, low=positive)',
-                        },
-                        search: {
-                            type: 'string',
-                            description: 'Search bug report content',
-                        },
-                        limit: {
-                            type: 'number',
-                            description: 'Maximum number of results (default: 20, max: 100)',
-                            minimum: 1,
-                            maximum: 100,
-                        },
-                        offset: {
-                            type: 'number',
-                            description: 'Offset for pagination',
-                            minimum: 0,
-                        },
-                        includeNotes: {
-                            type: 'boolean',
-                            description: 'Include internal team notes (default: false)',
-                        },
-                    },
-                    additionalProperties: false,
-                },
-            },
-            {
-                name: 'search_feedback',
-                description: 'Search for feedback across all accessible projects using text search. Useful for finding specific issues or topics.',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        query: {
-                            type: 'string',
-                            description: 'Search text to find in feedback content',
-                        },
-                        projectId: {
-                            type: 'string',
-                            description: 'Limit search to a specific project',
-                        },
-                        category: {
-                            type: 'string',
-                            enum: ['BUG', 'FEATURE_REQUEST', 'IMPROVEMENT', 'QUESTION'],
-                            description: 'Filter search results by category',
-                        },
-                        limit: {
-                            type: 'number',
-                            description: 'Maximum number of results (default: 10)',
-                            minimum: 1,
-                            maximum: 50,
-                        },
-                    },
-                    required: ['query'],
-                    additionalProperties: false,
-                },
-            },
-        ],
-    };
-});
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const { name, arguments: args } = request.params;
+export async function dispatchTool(client, name, args) {
+    const operation = getProductOperationByTool(name);
+    if (!operation)
+        return errorResult(`Unknown tool: ${name}`);
+    const input = args && typeof args === 'object' && !Array.isArray(args)
+        ? args
+        : {};
+    const validation = validateOperationInput(operation, input);
+    if (!validation.valid)
+        return errorResult(validation.message);
     try {
-        switch (name) {
-            case 'list_projects':
-                return await client.listProjects();
-            case 'get_feedback':
-                return await client.getFeedback(args || {});
-            case 'get_bug_reports':
-                return await client.getBugReports(args || {});
-            case 'search_feedback':
-                if (!args || typeof args !== 'object' || !('query' in args) || typeof args.query !== 'string') {
-                    throw new Error('Search query is required');
-                }
-                const searchOpts = {};
-                if (typeof args.projectId === 'string')
-                    searchOpts.projectId = args.projectId;
-                if (typeof args.category === 'string')
-                    searchOpts.category = args.category;
-                if (typeof args.limit === 'number')
-                    searchOpts.limit = args.limit;
-                return await client.searchFeedback(args.query, searchOpts);
-            default:
-                throw new Error(`Unknown tool: ${name}`);
-        }
+        return await client.execute(operation.id, input);
     }
     catch (error) {
-        const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
-        return {
-            content: [{ type: 'text', text: `Error: ${errorMessage}` }],
-            isError: true,
-        };
+        return errorResult(error instanceof Error ? error.message : 'FeedbackBasket request failed.');
     }
-});
+}
+function errorResult(message) {
+    const structuredContent = { error: message };
+    return {
+        structuredContent,
+        content: [{ type: 'text', text: JSON.stringify(structuredContent) }],
+        isError: true,
+    };
+}
+export function createServer(client) {
+    const server = new Server({ name: 'feedbackbasket-mcp', version: AGENT_SURFACE_VERSION }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: MCP_TOOLS }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => dispatchTool(client, request.params.name, request.params.arguments));
+    return server;
+}
 async function main() {
-    try {
-        const transport = new StdioServerTransport();
-        await server.connect(transport);
-        console.error('FeedbackBasket MCP server v2.0.0 started');
-    }
-    catch (error) {
-        console.error('Failed to start MCP server:', error);
+    const options = parseArgs(process.argv.slice(2));
+    const apiKey = options.apiKey || process.env.FEEDBACKBASKET_API_KEY;
+    if (!apiKey)
+        throw new Error('API key required. Use --api-key or FEEDBACKBASKET_API_KEY.');
+    if (!/^fb_key_[a-f0-9]{64}$/.test(apiKey))
+        throw new Error('Invalid API key format.');
+    const server = createServer(new FeedbackBasketClient(apiKey, options.baseUrl));
+    await server.connect(new StdioServerTransport());
+    console.error(`FeedbackBasket MCP server v${AGENT_SURFACE_VERSION} started`);
+}
+if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
+    main().catch((error) => {
+        console.error(error instanceof Error ? error.message : 'MCP server failed.');
         process.exit(1);
-    }
+    });
 }
-process.on('SIGINT', () => process.exit(0));
-process.on('SIGTERM', () => process.exit(0));
-main().catch((error) => {
-    console.error('Fatal error:', error);
-    process.exit(1);
-});

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "feedbackbasket-mcp-server",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "MCP server for FeedbackBasket project data access",
   "type": "module",
   "main": "dist/index.js",
@@ -11,7 +11,11 @@
     "build": "node node_modules/typescript/bin/tsc",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts",
-    "prepublishOnly": "npm run build"
+    "test": "tsx --test tests/*.test.ts",
+    "check:parity": "tsx scripts/check-parity.ts",
+    "docs:generate": "tsx scripts/generate-capabilities.ts",
+    "docs:check": "tsx scripts/generate-capabilities.ts --check",
+    "prepublishOnly": "npm run check:parity && npm run docs:check && npm test && npm run build"
   },
   "keywords": [
     "mcp",
@@ -33,16 +37,18 @@
     "url": "https://github.com/deifos/feedbackbasket-mcp/issues"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^0.4.0",
-    "axios": "^1.6.0"
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "axios": "^1.19.0",
+    "feedbackbasket-agent-contract": "3.0.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
-    "typescript": "^5.0.0",
-    "tsx": "^4.0.0"
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
   },
   "files": [
     "dist/**/*",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ]
 }