npm package: @keeborg/mcp
Description: MCP server for Keeborg - Generate technical specs for AI coding agents
Author: Keeborg
Latest version: 0.3.0

# @keeborg/mcp

[![npm version](https://img.shields.io/npm/v/@keeborg/mcp.svg?style=flat-square)](https://www.npmjs.com/package/@keeborg/mcp)
[![npm downloads](https://img.shields.io/npm/dm/@keeborg/mcp.svg?style=flat-square)](https://www.npmjs.com/package/@keeborg/mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)

MCP (Model Context Protocol) server for [Keeborg](https://www.keeborg.com) - Generate complete technical specifications for AI coding agents in under 60 seconds.

## What is Keeborg?

Keeborg generates an 8-document specification suite from a simple app idea:

- **PRD** - Product Requirements Document with features and user stories
- **Architecture** - System design, tech stack, and component diagrams
- **API Spec** - Complete endpoint definitions with request/response schemas
- **DB Schema** - Database tables, relationships, and indexes
- **UX Spec** - User flows, states, and navigation maps
- **UI Spec** - Screen layouts, components, and design tokens
- **Implementation Guide** - Security, deployment, and testing requirements
- **Agent Workflow** - Phased development plan optimized for AI agents

## Quick Start

### 1. Install

```bash
npm install -g @keeborg/mcp
```

### 2. Get Your API Key

1. Sign up at [keeborg.com](https://www.keeborg.com)
2. Go to [Settings > API Keys](https://www.keeborg.com/settings)
3. Create a new key (starts with `kb_live_`)

### 3. Configure Your AI Agent

#### Claude Code

Add to `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "keeborg": {
      "command": "keeborg-mcp",
      "env": {
        "KEEBORG_API_KEY": "kb_live_your_key_here"
      }
    }
  }
}
```

#### Cursor

Add to your Cursor MCP settings:

```json
{
  "keeborg": {
    "command": "keeborg-mcp",
    "env": {
      "KEEBORG_API_KEY": "kb_live_your_key_here"
    }
  }
}
```

## Available Tools

| Tool | Description |
|------|-------------|
| `create_project` | Create a new project and generate specs |
| `get_project_status` | Check generation progress |
| `get_document` | Retrieve a specific spec document |
| `list_projects` | List all your projects |
| `get_prompts` | Get AI-optimized prompts from specs |
| `regenerate_document` | Refresh a single document |

### create_project

Create a new project and generate technical specifications.

```
Arguments:
  name (required)        Short project name
  description (required) Detailed description of what to build
  tech_stack (optional)  Tech preferences object:
    - frontend_framework: "Next.js", "React", "Vue", etc.
    - css_styling: "Tailwind CSS", "CSS Modules", etc.
    - backend_framework: "FastAPI", "Express", "Django", etc.
    - database: "PostgreSQL", "MongoDB", "Supabase", etc.
    - auth_provider: "Supabase Auth", "Auth0", "Clerk", etc.
    - deployment: "Vercel", "AWS", "Coolify", etc.
```

### get_project_status

Check generation progress. Poll until status is `COMPLETED`.

```
Arguments:
  project_id (required)  Project ID from create_project
```

### get_document

Retrieve a specific specification document.

```
Arguments:
  project_id (required)  Project ID
  doc_type (required)    One of:
    - PRD
    - ARCHITECTURE
    - API_SPEC
    - DB_SCHEMA
    - UX_SPEC
    - UI_SPEC
    - IMPLEMENTATION_GUIDE
    - AGENT_WORKFLOW
```

### list_projects

List all your projects with their status.

### get_prompts

Get AI agent prompts generated from the specs.

```
Arguments:
  project_id (required)  Project ID
  prompt_type (optional) "primary", "backend", "frontend",
                         "fullstack", "devops", or "testing"
```

### regenerate_document

Regenerate a single document using current project context.

```
Arguments:
  project_id (required)  Project ID
  doc_type (required)    Document type to regenerate
```

## Example Workflow

```
You: "I want to build a habit tracking app with React Native and Supabase"

Claude: [Uses create_project]
        "Project created! Generating specifications...
         This typically completes in 30-60 seconds."

        [Polls get_project_status]
        "All 8 documents ready!"

        [Uses get_document with DB_SCHEMA]
        "Based on the database schema, I'll create these tables:
         - users, habits, habit_logs, streaks..."

        [Uses get_document with API_SPEC]
        "The API defines these endpoints:
         - POST /habits, GET /habits, POST /habits/:id/log..."

        [Proceeds to implement using the complete specs]
```

## Error Handling

The MCP server handles API errors gracefully:

| Status | Meaning | Action |
|--------|---------|--------|
| `504` | LLM generation timed out | Auto-retries up to 2 times with backoff |
| `429` | Rate limit exceeded | Wait and retry (5 generates/min, 10 regenerates/min) |
| `500` | Server error | Reported to agent with error details |

## Requirements

- Node.js 18+
- [Keeborg Pro subscription](https://www.keeborg.com/pricing) (for API access)

## Development

```bash
# Clone the repo
git clone https://github.com/keeborg/mcp-server.git
cd mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run locally
KEEBORG_API_KEY=kb_live_xxx npm start
```

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## Links

- [Keeborg Website](https://www.keeborg.com)
- [API Documentation](https://www.keeborg.com/docs/api)
- [Interactive Demo](https://www.keeborg.com/demo) - See example specs without signing up
- [Changelog](CHANGELOG.md)

## License

MIT - see [LICENSE](LICENSE) for details.