@vibeplanner/mcp-server/README.md

MCP server for VibePlanner AI - Integrate project management and collaborative memory into Claude Desktop

# @vibeplanner/mcp-server

MCP (Model Context Protocol) server for VibePlanner AI. Integrate project management, task tracking, and collaborative memory directly into Claude Code or Claude Desktop.

[![npm version](https://img.shields.io/npm/v/@vibeplanner/mcp-server.svg)](https://www.npmjs.com/package/@vibeplanner/mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- **Project Management**: Create and manage projects with tags and descriptions
- **Task Tracking**: Full task hierarchy support (epics, stories, tasks, bugs)
- **Document Storage**: Store and search project documentation with vector search
- **Collaborative Comments**: Thread-based discussions on tasks
- **Smart Search**: Hybrid text and vector search across all content

## Quick Start

### For Claude Code Users (Recommended)

```bash
# Install globally for all projects (user scope)
claude mcp add --scope user vibeplanner \
  --env CLAUDE_COLLAB_API_URL=https://api.vibeplanner.ai \
  --env API_KEY=your-api-key-here \
  -- npx -y @vibeplanner/mcp-server@latest
```

This installs the MCP server at the user level, making it available in all your Claude Code projects.

**Note:** Get your API key from [vibe.vibeplanner.ai/profile](https://vibe.vibeplanner.ai/profile)

To verify installation:
```bash
claude mcp list
```

To remove:
```bash
claude mcp remove --scope user vibeplanner
```

### For Claude Desktop Users

Claude Desktop requires manual configuration. Edit your configuration file:

**Location:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

**Configuration:**

```json
{
  "mcpServers": {
    "vibeplanner": {
      "command": "npx",
      "args": ["@vibeplanner/mcp-server@latest"],
      "env": {
        "CLAUDE_COLLAB_API_URL": "https://api.vibeplanner.ai",
        "API_KEY": "your-vibeplanner-api-key"
      }
    }
  }
}
```

Remember to restart Claude Desktop after making configuration changes.

## Getting Your API Key

1. **Sign up** at [vibe.vibeplanner.ai](https://vibe.vibeplanner.ai)
2. **Navigate** to your [Profile page](https://vibe.vibeplanner.ai/profile) 
3. **Generate** or copy your API key
4. **Use** it in the configuration commands above

## Alternative Installation Methods

### Project-Specific Installation (Claude Code)

For a single project only:
```bash
claude mcp add --scope local vibeplanner \
  --env CLAUDE_COLLAB_API_URL=https://api.vibeplanner.ai \
  --env API_KEY=your-api-key-here \
  -- npx -y @vibeplanner/mcp-server@latest
```

### Team Shared Installation (Claude Code)

For team collaboration:
```bash
claude mcp add --scope project vibeplanner \
  --env CLAUDE_COLLAB_API_URL=https://api.vibeplanner.ai \
  --env API_KEY=your-api-key-here \
  -- npx -y @vibeplanner/mcp-server@latest
```

### NPM Global Install

For development or custom setups:
```bash
npm install -g @vibeplanner/mcp-server
```

## Available Tools

Once configured, Claude will have access to these tools:

### Project Management
- `list_projects` - List all projects in the system
- `get_project` - Get detailed information about a specific project
- `create_project` - Create a new project with name, description, and tags

### Task Management
- `list_tasks` - List tasks with optional filtering by project, status, or assignee
- `list_epics` - List all epics (for creating child tasks)
- `get_task` - Get detailed information about a specific task
- `create_task` - Create new tasks (epic, story, task, bug, component)
- `update_task` - Update task status, priority, assignment, etc.

### Document Management
- `search_documents` - Search documents using text, vector, or hybrid search
- `get_document` - Retrieve a specific document by ID
- `create_document` - Create new documents (plan, specification, notes, code)
- `update_document` - Update existing document content

### Collaboration
- `list_task_comments` - List all comments for a task
- `create_task_comment` - Add comments or replies to tasks
- `get_comment` - Get specific comment details
- `update_comment` - Edit existing comments
- `delete_comment` - Remove comments

## Usage Examples

After configuration, you can interact with the tools naturally in Claude:

```
"Create a new project called 'Website Redesign' with tags for frontend and ux"

"List all tasks assigned to me that are in progress"

"Search for documents about authentication implementation"

"Add a comment to task [task-id] saying the API integration is complete"
```

## API Information

- **API Endpoint**: `https://api.vibeplanner.ai`
- **API Key**: Available from [your profile](https://vibe.vibeplanner.ai/profile)
- **Documentation**: [vibe.vibeplanner.ai](https://vibe.vibeplanner.ai)

## Security

- API keys must be at least 32 characters long
- Never commit API keys to version control
- Use environment variables for sensitive configuration
- The server validates all inputs and sanitizes API responses

## Troubleshooting

### Connection Issues

1. Verify API server is running:
   ```bash
   curl https://api.vibeplanner.ai/api/health
   ```

2. Check Claude Desktop logs:
   - macOS: `~/Library/Logs/Claude/`
   - Windows: `%APPDATA%\Claude\logs\`

3. Test MCP server directly:
   ```bash
   CLAUDE_COLLAB_API_URL=https://api.vibeplanner.ai \
   API_KEY=your-api-key \
   npx @vibeplanner/mcp-server@latest
   ```

4. Check your configuration in Claude Code:
   ```bash
   claude mcp list
   ```

### Common Errors

- **"API_KEY environment variable is required"**: Set the API_KEY environment variable when adding the MCP server
- **"API Error (401)"**: Your API key is invalid or expired. Get a new one from [your profile](https://vibe.vibeplanner.ai/profile)
- **"Circuit breaker activated"**: Too many consecutive errors. Wait 30 seconds and try again
- **"Failed to connect"** in Claude Code: Run `claude mcp list` to check status, then remove and re-add the server
- **"MCP server not found"**: Make sure you've added it with `claude mcp add --scope user` command

## Development

### Building from Source

```bash
npm install
npm run build
npm test
```

### Running in Development Mode

```bash
npm run dev
```

## Contributing

Contributions are welcome! Please read our [Contributing Guide](../../CONTRIBUTING.md) for details.

## License

MIT - See [LICENSE](../../LICENSE) for details.

## Version History

- **1.0.2** - Fixed bin executable issue for npx compatibility
- **1.0.1** - Updated API endpoints and documentation
- **1.0.0** - Initial release

## Support

- **Website**: [VibePlanner AI](https://vibe.vibeplanner.ai)
- **API Status**: [api.vibeplanner.ai/api/health](https://api.vibeplanner.ai/api/health)
- **GitHub Issues**: [Report bugs or request features](https://github.com/yourusername/ai-agent-coordinator/issues)
- **NPM Package**: [@vibeplanner/mcp-server](https://www.npmjs.com/package/@vibeplanner/mcp-server)