bottlenecks-mcp-server/README.md

Model Context Protocol server for Bottlenecks database - enables AI agents like Claude to interact with bottleneck data

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

```bash
npm install -g bottlenecks-mcp-server
```

### Basic Usage

```bash
# 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:

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

## 🛠️ Available Tools (19)

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

### Feedback

- **`submit_bug_report`** - File a bug report or feature request as a GitHub
  issue (requires a write-scoped API key)

## 🔒 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

```javascript
// 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

```bash
# 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

```bash
# 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

```typescript
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

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

### Testing

```bash
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](https://github.com/bottlenecks-institute/mcp-server/issues)
- **Documentation**: [Full Documentation](https://bottlenecksinstitute.com/docs/mcp)
- **Community**: [Discord](https://discord.gg/bottlenecks)

---

**Made with ❤️ by the Bottlenecks Institute**