@bottlenecks/mcp-server

Model Context Protocol server for Bottlenecks database - Enables AI agents like Claude to interact with your bottleneck data through a comprehensive set of tools.

🚀 Quick Start

Installation

npm install -g bottlenecks-mcp-server

Basic Usage

# Test the server (using npx - no installation needed)
npx bottlenecks-mcp-server test

# Start with configuration
npx bottlenecks-mcp-server start

# Or install globally first
npm install -g bottlenecks-mcp-server
bottlenecks-mcp-server start

Claude Desktop Integration

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "bottlenecks": {
      "command": "npx",
      "args": ["bottlenecks-mcp-server", "start"],
      "env": {
        "BOTTLENECKS_API_KEY": "your-api-key-here"
      }
    }
  }
}

🛠️ Available Tools (18)

Discovery & Schema

• agents_start_here - Comprehensive workflow guide for AI agents
• get_capabilities - Server capabilities and status
• get_bottleneck_schema - Complete data schema with validation
• get_taxonomy - Tag taxonomy and categorization
• get_bottleneck_template - Content templates (5 types)
• get_mdx_guide - MDX formatting guide

Read Operations

• search_bottlenecks - Advanced search with filters (supports admin access)
• get_bottleneck - Individual bottleneck details
• list_bottlenecks - Paginated listing (supports admin access)
• list_unapproved_bottlenecks - 🔒 Admin tool to review pending/draft cards

Write Operations

• create_bottleneck - Create new bottlenecks
• update_bottleneck - Update existing bottlenecks
• validate_bottleneck_data - Validate without saving

File Operations

• upload_file - Attach files to bottlenecks
• get_file_attachments - List attached files
• get_file_content - Access processed content (OCR, text)
• download_file - Download original files
• delete_file - Remove attachments

🔒 Admin Features (New in v1.0.22)

Access unapproved cards for review and improvement!

Admin-Enhanced Tools

search_bottlenecks now supports:

• include_unapproved: true - Include pending/draft cards in search
• approval_status: "pending" - Filter by specific approval status

list_bottlenecks now supports:

• include_unapproved: true - Include unapproved cards in listing
• approval_status: "draft" - Show only draft cards

New Admin Tool

list_unapproved_bottlenecks - Dedicated admin review tool:

• status: "pending" - Show pending cards (default)
• status: "draft" - Show draft cards
• status: "rejected" - Show rejected cards
• Includes admin edit links and detailed summaries

Usage Examples

// Search including unapproved cards
search_bottlenecks({
  query: 'AI safety',
  include_unapproved: true,
});

// List only pending cards for review
list_unapproved_bottlenecks({
  status: 'pending',
  limit: 10,
});

// Find all draft cards
search_bottlenecks({
  approval_status: 'draft',
});

Note: Admin features require admin API key authentication.

🔧 Configuration

Environment Variables

# Required
BOTTLENECKS_API_URL=https://your-app.vercel.app
BOTTLENECKS_API_KEY=your-oauth-api-key

# Optional (for direct database access)
NEXT_PUBLIC_SUPABASE_URL=your-supabase-url
SUPABASE_SERVICE_ROLE_KEY=your-service-key

Getting an API Key

1. Visit your Bottlenecks deployment: https://your-app.vercel.app/api/auth/mcp/authorize
2. Complete the OAuth flow
3. Copy the generated API key
4. Set it as BOTTLENECKS_API_KEY

📖 CLI Commands

# Start the MCP server
bottlenecks-mcp start

# Test with mock configuration
bottlenecks-mcp test

# Show configuration help
bottlenecks-mcp config

# List available tools
bottlenecks-mcp tools

# Show version and help
bottlenecks-mcp --version
bottlenecks-mcp --help

🤖 AI Agent Workflow

1. Discovery: Agent calls agents_start_here for comprehensive guidance
2. Authentication: Uses your OAuth-generated API key
3. Schema Learning: Calls get_bottleneck_schema and get_taxonomy
4. Content Creation: Uses templates from get_bottleneck_template
5. CRUD Operations: Creates, reads, updates bottlenecks
6. File Support: Uploads and analyzes supporting documents

💡 Example Usage

Programmatic Usage

import { createBottlenecksMCPServer } from '@bottlenecks/mcp-server';

const server = createBottlenecksMCPServer({
  apiBaseUrl: 'https://your-app.vercel.app',
  supabaseUrl: process.env.NEXT_PUBLIC_SUPABASE_URL,
  supabaseKey: process.env.SUPABASE_SERVICE_ROLE_KEY,
});

server.setApiKey('your-oauth-key');
await server.start();

Claude Integration

Once configured, Claude can:

• Search your bottlenecks: "Find all performance-related bottlenecks"
• Create new entries: "Create a bottleneck about database query performance"
• Upload supporting files: "Attach this performance report to the bottleneck"
• Analyze content: "What insights can you extract from the attached data?"

🔒 Security

• OAuth Authentication: Secure API key generation and management
• Scoped Permissions: Read, write, and admin access levels
• Rate Limiting: Configurable request limits
• Row Level Security: Database-level access control

🏗️ Architecture

The MCP server acts as a bridge between AI agents and your Bottlenecks deployment:

AI Agent (Claude) ↔ MCP Server ↔ Bottlenecks API ↔ Supabase Database

• Stateless: No local data storage
• API-First: Uses your existing REST APIs
• Secure: OAuth-based authentication
• Scalable: Leverages your Vercel deployment

🛠️ Development

Building from Source

git clone https://github.com/bottlenecks-institute/mcp-server.git
cd mcp-server
npm install
npm run build
npm test

Testing

npm test                    # Unit tests
npm run test:integration    # Integration tests
npm run lint               # Code linting

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📞 Support

• Issues: GitHub Issues
• Documentation: Full Documentation
• Community: Discord

Made with ❤️ by the Bottlenecks Institute