feedbackbasket-mcp-server 1.0.1 → 3.0.0

package/CHANGELOG.md

@@ -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

@@ -1,93 +1,82 @@
 # FeedbackBasket MCP Server
 
-Model Context Protocol (MCP) server for FeedbackBasket that allows AI assistants to query your project feedback and bug reports.
+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.
 
-## Features
+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`.
 
-- 🔍 **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
+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
 
-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)
+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
 
-Add the MCP server to your editor's configuration:
+#### Claude Code (CLI)
 
-#### Quick Setup (All Editors)
-```json
-{
-  "mcpServers": {
-    "feedbackbasket": {
-      "command": "npx",
-      "args": ["-y", "@feedbackbasket/mcp-server@latest", "--api-key", "fb_key_your_api_key_here"]
-    }
-  }
-}
+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
 ```
 
-#### Detailed Examples
+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@latest",
-        "--api-key",
-        "fb_key_your_api_key_here"
-      ]
+      "args": ["-y", "feedbackbasket-mcp-server@3.0.0"],
+      "env": { "FEEDBACKBASKET_API_KEY": "${FEEDBACKBASKET_API_KEY}" }
     }
   }
 }
 ```
 
-#### Cursor/Windsurf
+#### Cursor / Windsurf
+
+Add to your MCP config (`.cursor/mcp.json` or equivalent):
+
 ```json
 {
   "mcpServers": {
     "feedbackbasket": {
       "command": "npx",
-      "args": [
-        "-y",
-        "@feedbackbasket/mcp-server@latest",
-        "--api-key",
-        "fb_key_your_api_key_here"
-      ]
+      "args": ["-y", "feedbackbasket-mcp-server@3.0.0"],
+      "env": { "FEEDBACKBASKET_API_KEY": "${FEEDBACKBASKET_API_KEY}" }
     }
   }
 }
 ```
 
-#### Environment Variable (Alternative)
+#### 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"],
+      "args": ["-y", "feedbackbasket-mcp-server@latest"],
       "env": {
-        "FEEDBACKBASKET_API_KEY": "fb_key_your_api_key_here"
+        "FEEDBACKBASKET_API_KEY": "${FEEDBACKBASKET_API_KEY}"
       }
     }
   }
@@ -96,97 +85,107 @@ Add the MCP server to your editor's configuration:
 
 ## Usage Examples
 
-Once configured, you can ask your AI assistant:
+Once configured, ask your AI assistant:
 
 ### Project Overview
 - "Show me all my FeedbackBasket projects"
-- "What projects do I have and how much feedback do they have?"
+- "How much feedback does each project 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"
+- "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 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)
+- "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
 
-- ✅ **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
+- **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 API key is still active in your dashboard
-- Verify the API key has access to at least one project
+- 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
 
-### "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
+### Connection Issues
+- Ensure Node.js 18+ is installed
 - Try clearing npx cache: `npx clear-npx-cache`
-- Check your internet connection for package downloads
+- For local development, add `--base-url http://localhost:3000`
 
 ## API Key Management
 
-Visit your [FeedbackBasket dashboard](https://feedbackbasket.com/dashboard/settings) to:
+Visit [feedbackbasket.com/dashboard/settings](https://feedbackbasket.com/dashboard/settings) to:
 - Generate new API keys
-- Manage project access for existing keys
+- Manage project access
 - View usage statistics
-- Deactivate or delete keys
-- Monitor key activity
+- Activate/deactivate keys
+- Delete keys
 
-## Support
+## Links
 
-- 🐛 Issues: [GitHub Issues](https://github.com/deifos/feedbackbasket-mcp/issues)
-- 📖 Docs: [FeedbackBasket Documentation](https://feedbackbasket.com/docs)
+- [FeedbackBasket](https://feedbackbasket.com)
+- [GitHub Issues](https://github.com/deifos/feedbackbasket-mcp/issues)

package/dist/client.d.ts

@@ -1,60 +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);
-    /**
-     * List all projects accessible by the API key
-     */
-    listProjects(): Promise<{
-        content: Array<{
-            type: string;
-            text: string;
-        }>;
-    }>;
-    /**
-     * Get feedback for projects
-     */
-    getFeedback(params?: {
-        projectId?: string;
-        category?: 'BUG' | 'FEATURE' | 'REVIEW';
-        status?: 'PENDING' | 'REVIEWED' | 'DONE';
-        sentiment?: 'POSITIVE' | 'NEGATIVE' | 'NEUTRAL';
-        limit?: number;
-        search?: string;
-        includeNotes?: boolean;
-    }): Promise<{
-        content: Array<{
-            type: string;
-            text: string;
-        }>;
-    }>;
-    /**
-     * Get bug reports specifically
-     */
-    getBugReports(params?: {
-        projectId?: string;
-        status?: 'PENDING' | 'REVIEWED' | 'DONE';
-        severity?: 'high' | 'medium' | 'low';
-        limit?: number;
-        search?: string;
-        includeNotes?: boolean;
-    }): Promise<{
-        content: Array<{
-            type: string;
-            text: string;
-        }>;
-    }>;
-    /**
-     * Search feedback across all accessible projects
-     */
-    searchFeedback(query: string, options?: {
-        projectId?: string;
-        category?: 'BUG' | 'FEATURE' | 'REVIEW';
-        limit?: number;
-    }): Promise<{
-        content: Array<{
-            type: string;
-            text: string;
-        }>;
-    }>;
+    execute(operationId: ProductOperationId, rawArgs: Record<string, unknown>): Promise<McpOperationResult>;
     private handleError;
 }

package/dist/client.js

@@ -1,207 +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/1.0.0',
+                'User-Agent': `FeedbackBasket-MCP/${AGENT_SURFACE_VERSION}`,
             },
-            timeout: 30000, // 30 second timeout
+            timeout: 30_000,
         });
     }
-    /**
-     * List all projects accessible by the API key
-     */
-    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 totalFeedback = project.stats.totalFeedback;
-                const pendingCount = project.stats.byStatus.PENDING;
-                const bugCount = project.stats.byCategory.BUG;
-                return [
-                    `**${project.name}**`,
-                    `  URL: ${project.url}`,
-                    `  Total Feedback: ${totalFeedback}`,
-                    `  Pending: ${pendingCount} | Bugs: ${bugCount}`,
-                    `  Created: ${new Date(project.createdAt).toLocaleDateString()}`,
-                    ''
-                ].join('\n');
-            }).join('\n');
-            const summary = [
-                `# FeedbackBasket Projects (${projects.length} total)\n`,
-                projectList,
-                `\n*API Key: ${response.data.apiKeyInfo.name} (${response.data.apiKeyInfo.usageCount} uses)*`
-            ].join('\n');
-            return {
-                content: [{
-                        type: 'text',
-                        text: summary
-                    }]
-            };
-        }
-        catch (error) {
-            throw this.handleError('Failed to fetch projects', error);
-        }
-    }
-    /**
-     * Get feedback for projects
-     */
-    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 confidenceText = item.categoryConfidence
-                    ? ` (${Math.round(item.categoryConfidence * 100)}% confidence)`
-                    : '';
-                return [
-                    `**${category}${confidenceText} | ${sentiment} | ${item.status}**`,
-                    `Project: ${item.project.name}`,
-                    `Content: ${item.content.length > 100 ? item.content.substring(0, 100) + '...' : item.content}`,
-                    item.email ? `Email: ${item.email}` : '',
-                    item.notes && params.includeNotes ? `Notes: ${item.notes}` : '',
-                    `Created: ${new Date(item.createdAt).toLocaleDateString()}`,
-                    ''
-                ].filter(Boolean).join('\n');
-            }).join('\n');
-            const summary = [
-                `# Feedback Results (${feedback.length} of ${response.data.pagination.totalCount})\n`,
-                feedbackList,
-                response.data.pagination.hasMore ? `\n*Showing first ${feedback.length} results. Use offset parameter to get more.*` : '',
-                `\n*API Key: ${response.data.apiKeyInfo.name}*`
-            ].join('\n');
+            const structuredContent = response.data && typeof response.data === 'object' && !Array.isArray(response.data)
+                ? response.data
+                : { value: response.data };
             return {
-                content: [{
-                        type: 'text',
-                        text: summary
-                    }]
+                structuredContent,
+                content: [{ type: 'text', text: JSON.stringify(structuredContent) }],
             };
         }
         catch (error) {
-            throw this.handleError('Failed to fetch feedback', error);
+            throw this.handleError(error);
         }
     }
-    /**
-     * Get bug reports specifically
-     */
-    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 statusEmoji = bug.status === 'PENDING' ? '⏳' : bug.status === 'REVIEWED' ? '👁️' : '✅';
-                return [
-                    `${severityEmoji} **${bug.severity.toUpperCase()} SEVERITY** ${statusEmoji} ${bug.status}`,
-                    `Project: ${bug.project.name}`,
-                    `Bug: ${bug.content.length > 150 ? bug.content.substring(0, 150) + '...' : bug.content}`,
-                    bug.email ? `Reported by: ${bug.email}` : '',
-                    bug.notes && params.includeNotes ? `Notes: ${bug.notes}` : '',
-                    `Reported: ${new Date(bug.createdAt).toLocaleDateString()}`,
-                    ''
-                ].filter(Boolean).join('\n');
-            }).join('\n');
-            const stats = response.data.stats;
-            const statsText = [
-                `## Bug Statistics`,
-                `Total Bugs: ${stats.totalBugs}`,
-                `🔴 High: ${stats.bySeverity.high} | 🟡 Medium: ${stats.bySeverity.medium} | 🟢 Low: ${stats.bySeverity.low}`,
-                `⏳ Pending: ${stats.byStatus.pending} | 👁️ Reviewed: ${stats.byStatus.reviewed} | ✅ Done: ${stats.byStatus.done}`,
-                ''
-            ].join('\n');
-            const summary = [
-                `# Bug Reports (${bugReports.length} of ${response.data.pagination.totalCount})\n`,
-                statsText,
-                bugList,
-                response.data.pagination.hasMore ? `\n*Showing first ${bugReports.length} results. Use offset parameter to get more.*` : '',
-                `\n*API Key: ${response.data.apiKeyInfo.name}*`
-            ].join('\n');
-            return {
-                content: [{
-                        type: 'text',
-                        text: summary
-                    }]
-            };
-        }
-        catch (error) {
-            throw this.handleError('Failed to fetch bug reports', error);
-        }
-    }
-    /**
-     * Search feedback across all accessible projects
-     */
-    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?.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: ${responseMessage}. 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

@@ -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

@@ -1,241 +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';
-// Parse command line arguments manually (like Stripe does)
-function parseArgs(args) {
-    const options = {};
-    args.forEach((arg) => {
-        if (arg.startsWith('--')) {
-            const [key, value] = arg.slice(2).split('=');
-            if (key === 'api-key' && value) {
-                options.apiKey = value;
-            }
-            else if (key === 'base-url' && value) {
-                options.baseUrl = value;
-            }
+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;
         }
-    });
-    return options;
-}
-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: Use --api-key option or set FEEDBACKBASKET_API_KEY environment variable');
-    process.exit(1);
-}
-// Validate API key format
-if (!apiKey.startsWith('fb_key_')) {
-    console.error('Error: Invalid API key format. API keys should start with "fb_key_".');
-    process.exit(1);
+        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 result;
 }
-console.log('API key format accepted:', apiKey.substring(0, 20) + '...');
-const client = new FeedbackBasketClient(apiKey, baseUrl);
-// Create MCP server
-const server = new Server({
-    name: 'feedbackbasket-mcp',
-    version: '1.0.0',
-    capabilities: {
-        tools: {},
-    },
-});
-// List available tools
-server.setRequestHandler(ListToolsRequestSchema, async (_request) => {
-    return {
-        tools: [
-            {
-                name: 'list_projects',
-                description: 'List all FeedbackBasket projects accessible by your API key with summary statistics',
-                inputSchema: {
-                    type: 'object',
-                    properties: {},
-                    additionalProperties: false,
-                },
-            },
-            {
-                name: 'get_feedback',
-                description: 'Get feedback from your FeedbackBasket projects with filtering options',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        projectId: {
-                            type: 'string',
-                            description: 'Filter by specific project ID',
-                        },
-                        category: {
-                            type: 'string',
-                            enum: ['BUG', 'FEATURE', 'REVIEW'],
-                            description: 'Filter by feedback category',
-                        },
-                        status: {
-                            type: 'string',
-                            enum: ['PENDING', 'REVIEWED', 'DONE'],
-                            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 to return (default: 20, max: 100)',
-                            minimum: 1,
-                            maximum: 100,
-                        },
-                        includeNotes: {
-                            type: 'boolean',
-                            description: 'Include internal notes in the response (default: false)',
-                        },
-                    },
-                    additionalProperties: false,
-                },
-            },
-            {
-                name: 'get_bug_reports',
-                description: 'Get bug reports specifically from your FeedbackBasket projects',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        projectId: {
-                            type: 'string',
-                            description: 'Filter by specific project ID',
-                        },
-                        status: {
-                            type: 'string',
-                            enum: ['PENDING', 'REVIEWED', 'DONE'],
-                            description: 'Filter by bug status',
-                        },
-                        severity: {
-                            type: 'string',
-                            enum: ['high', 'medium', 'low'],
-                            description: 'Filter by computed severity (based on sentiment: negative=high, neutral=medium, positive=low)',
-                        },
-                        search: {
-                            type: 'string',
-                            description: 'Search bug report content for specific text',
-                        },
-                        limit: {
-                            type: 'number',
-                            description: 'Maximum number of results to return (default: 20, max: 100)',
-                            minimum: 1,
-                            maximum: 100,
-                        },
-                        includeNotes: {
-                            type: 'boolean',
-                            description: 'Include internal notes in the response (default: false)',
-                        },
-                    },
-                    additionalProperties: false,
-                },
-            },
-            {
-                name: 'search_feedback',
-                description: 'Search for feedback across all accessible projects using text search',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        query: {
-                            type: 'string',
-                            description: 'Search query to find in feedback content',
-                        },
-                        projectId: {
-                            type: 'string',
-                            description: 'Limit search to specific project',
-                        },
-                        category: {
-                            type: 'string',
-                            enum: ['BUG', 'FEATURE', 'REVIEW'],
-                            description: 'Filter search results by category',
-                        },
-                        limit: {
-                            type: 'number',
-                            description: 'Maximum number of results (default: 10)',
-                            minimum: 1,
-                            maximum: 50,
-                        },
-                    },
-                    required: ['query'],
-                    additionalProperties: false,
-                },
-            },
-        ],
-    };
-});
-// Handle tool calls
-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 searchOptions = {};
-                if (typeof args.projectId === 'string') {
-                    searchOptions.projectId = args.projectId;
-                }
-                if (typeof args.category === 'string' && ['BUG', 'FEATURE', 'REVIEW'].includes(args.category)) {
-                    searchOptions.category = args.category;
-                }
-                if (typeof args.limit === 'number') {
-                    searchOptions.limit = args.limit;
-                }
-                return await client.searchFeedback(args.query, searchOptions);
-            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.');
     }
-});
-// Start the server
+}
+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);
-        // We use console.error instead of console.log since console.log will output to stdio, which will confuse the MCP server
-        console.error('✅ FeedbackBasket MCP server started successfully');
-    }
-    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);
-    }
+    });
 }
-// Handle graceful shutdown
-process.on('SIGINT', () => {
-    console.error('Received SIGINT, shutting down gracefully...');
-    process.exit(0);
-});
-process.on('SIGTERM', () => {
-    console.error('Received SIGTERM, shutting down gracefully...');
-    process.exit(0);
-});
-// Only run if this file is the main module
-main().catch((error) => {
-    console.error('🚨 Fatal error:', error);
-    process.exit(1);
-});

package/dist/types.d.ts

@@ -4,62 +4,45 @@ export interface Project {
     url: string;
     description?: string;
     createdAt: string;
-    updatedAt: string;
-    stats: {
-        totalFeedback: number;
-        byCategory: {
-            BUG: number;
-            FEATURE: number;
-            REVIEW: number;
-            UNKNOWN: number;
-        };
-        byStatus: {
-            PENDING: number;
-            REVIEWED: number;
-            DONE: number;
-        };
-    };
+    totalFeedback: number;
+    byStatus: Record<string, number>;
+    byCategory: Record<string, number>;
 }
 export interface Feedback {
     id: string;
     content: string;
-    email?: string;
-    status: 'PENDING' | 'REVIEWED' | 'DONE';
-    notes?: string;
-    category?: 'BUG' | 'FEATURE' | 'REVIEW';
-    categorySource: 'manual' | 'ai';
-    categoryConfidence?: number;
-    sentiment?: 'POSITIVE' | 'NEGATIVE' | 'NEUTRAL';
-    sentimentSource: 'manual' | 'ai';
-    sentimentConfidence?: number;
-    isAiAnalyzed: boolean;
-    aiAnalyzedAt?: string;
-    aiReasoning?: string;
+    email?: string | null;
+    status: 'OPEN' | 'UNDER_REVIEW' | 'PLANNED' | 'IN_PROGRESS' | 'COMPLETE' | 'CLOSED';
+    category?: 'BUG' | 'FEATURE_REQUEST' | 'IMPROVEMENT' | 'QUESTION' | null;
+    sentiment?: 'POSITIVE' | 'NEGATIVE' | 'NEUTRAL' | null;
+    aiSummary?: string | null;
+    aiPriorityScore?: number | null;
+    reasoning?: string | null;
+    pageUrl?: string | null;
+    browser?: string | null;
+    os?: string | null;
+    device?: string | null;
+    language?: string | null;
     project: {
         id: string;
         name: string;
-        url: string;
     };
+    notes?: Array<{
+        id: string;
+        content: string;
+        createdAt: string;
+        author: {
+            name: string;
+        };
+    }>;
     createdAt: string;
-    updatedAt: string;
 }
 export interface BugReport extends Feedback {
     severity: 'high' | 'medium' | 'low';
 }
-export interface FeedbackBasketResponse<T> {
-    data?: T;
-    error?: {
-        message: string;
-        code?: string;
-    };
-}
 export interface ProjectsResponse {
     projects: Project[];
     totalProjects: number;
-    apiKeyInfo: {
-        name: string;
-        usageCount: number;
-    };
 }
 export interface FeedbackResponse {
     feedback: Feedback[];
@@ -68,50 +51,23 @@ export interface FeedbackResponse {
         limit: number;
         offset: number;
         hasMore: boolean;
-        nextOffset: number | null;
-    };
-    filters: {
-        projectId?: string;
-        category?: string;
-        status?: string;
-        sentiment?: string;
-        search?: string;
-    };
-    apiKeyInfo: {
-        name: string;
-        usageCount: number;
     };
 }
 export interface BugReportsResponse {
     bugReports: BugReport[];
     stats: {
-        totalBugs: number;
+        total: number;
         bySeverity: {
             high: number;
             medium: number;
             low: number;
         };
-        byStatus: {
-            pending: number;
-            reviewed: number;
-            done: number;
-        };
+        byStatus: Record<string, number>;
     };
     pagination: {
         totalCount: number;
         limit: number;
         offset: number;
         hasMore: boolean;
-        nextOffset: number | null;
-    };
-    filters: {
-        projectId?: string;
-        status?: string;
-        severity?: string;
-        search?: string;
-    };
-    apiKeyInfo: {
-        name: string;
-        usageCount: number;
     };
 }

package/dist/types.js

@@ -1,2 +1,2 @@
-// Shared types for the MCP server based on actual database schema
+// Shared types for the MCP server — aligned with FeedbackBasket v3
 export {};

package/package.json

@@ -1,48 +1,54 @@
-{
-  "name": "feedbackbasket-mcp-server",
-  "version": "1.0.1",
-  "description": "MCP server for FeedbackBasket project data access",
-  "type": "module",
-  "main": "dist/index.js",
-  "bin": {
-    "feedbackbasket-mcp-server": "dist/index.js"
-  },
-  "scripts": {
-    "build": "tsc",
-    "start": "node dist/index.js",
-    "dev": "tsx src/index.ts",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "mcp",
-    "feedbackbasket",
-    "feedback",
-    "projects",
-    "ai-assistant",
-    "claude-desktop",
-    "cursor"
-  ],
-  "author": "deifosv",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/deifos/feedbackbasket-mcp.git"
-  },
-  "homepage": "https://feedbackbasket.com",
-  "bugs": {
-    "url": "https://github.com/deifos/feedbackbasket-mcp/issues"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^0.4.0",
-    "axios": "^1.6.0"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "typescript": "^5.0.0",
-    "tsx": "^4.0.0"
-  },
-  "files": [
-    "dist/**/*",
-    "README.md"
-  ]
-}
+{
+  "name": "feedbackbasket-mcp-server",
+  "version": "3.0.0",
+  "description": "MCP server for FeedbackBasket project data access",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "feedbackbasket-mcp-server": "dist/index.js"
+  },
+  "scripts": {
+    "build": "node node_modules/typescript/bin/tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "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",
+    "feedbackbasket",
+    "feedback",
+    "projects",
+    "ai-assistant",
+    "claude-desktop",
+    "cursor"
+  ],
+  "author": "deifosv",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/deifos/feedbackbasket-mcp.git"
+  },
+  "homepage": "https://feedbackbasket.com",
+  "bugs": {
+    "url": "https://github.com/deifos/feedbackbasket-mcp/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "axios": "^1.19.0",
+    "feedbackbasket-agent-contract": "3.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "CHANGELOG.md"
+  ]
+}