npm package: @kenkaiiii/queen-mcp
Description: Queen Claude MCP server - streamlined with 14 essential tools for Next.js development
Author: kenkaiiii
Latest version: 3.29.0

# Queen MCP Server

MCP server for Queen Claude autonomous development system. Provides AI agents with structured database access for project management, task coordination, and knowledge storage.

## What is Queen MCP?

Queen MCP server gives Claude Code (and other AI agents) direct access to the Queen Claude database through the Model Context Protocol. This enables autonomous development where AI agents can manage tasks, store knowledge, and coordinate work without human intervention.

## Features

### Project Context Management
- **`get_project_context`** - Get complete project overview, critical docs, and important memories

### Task Management  
- **`get_available_tasks`** - Find tasks ready to work on
- **`create_task`** - Create new development tasks with requirements and expected results
- **`update_task_progress`** - Update task status, progress, and time spent  
- **`get_task_details`** - Get complete task information including dependencies

### Knowledge Management
- **`search_memory`** - Search stored patterns, decisions, and knowledge
- **`store_memory`** - Store important knowledge for future reference

### Problem Tracking
- **`report_problem`** - Log issues encountered during development
- **`get_similar_problems`** - Find previously solved similar issues
- **`solve_problem`** - Mark problems as solved with solution details

### Utilities
- **`query_database`** - Execute raw SQL queries (SELECT only for safety)
- **`get_agent_status`** - Get current agent session status
- **`update_agent_activity`** - Update current agent activity and progress

## Installation

```bash
npm install -g queen-mcp
```

Or for local development:
```bash
git clone <repository>
cd queen-mcp
npm install
npm run build
npm link
```

## Usage

### Prerequisites

1. Project must be initialized with Queen Claude:
```bash
cd your-project
npx queen-claude-init
```

2. MCP server automatically discovers `.queen/database.db` in current working directory

### Claude Code Integration

The MCP server is automatically available in Claude Code when installed. No manual setup required.

Example usage in Claude Code:
```typescript
// Get project context when joining a project
const context = await mcp.call('get_project_context');

// Find work to do
const tasks = await mcp.call('get_available_tasks');

// Start working on a task
await mcp.call('update_agent_activity', {
  activity: 'Implementing user authentication',
  current_file: 'src/components/auth/LoginForm.tsx'
});

// Store important knowledge
await mcp.call('store_memory', {
  title: 'React Hook Pattern',
  content: 'Always include dependencies in useEffect array',
  tags: ['react', 'hooks'],
  importance: 'critical',
  memory_type: 'important_pattern'
});
```

## Database Auto-Discovery

The MCP server automatically finds the Queen database:

1. **Looks for**: `<current-working-directory>/.queen/database.db`
2. **Validates**: Database exists and has required tables
3. **Returns helpful errors**: If not initialized or corrupted

## Error Handling

All tools return helpful error messages:

```json
{
  "error": "Queen Claude not found. Run 'npx queen-claude-init' to initialize this project."
}
```

Common errors:
- **Not initialized**: `.queen` directory doesn't exist
- **Corrupted database**: Missing required tables
- **Invalid task ID**: Task not found
- **SQL errors**: Query execution failures

## Real-Time Updates

When database changes occur, the MCP server:
1. **Updates** `.queen/last-update` file with timestamp  
2. **Dashboard** (separate web app) watches this file for real-time updates
3. **Perfect isolation** - each project has its own change file

## Development

```bash
# Build TypeScript
npm run build

# Development mode (watch)
npm run dev

# Test the server
npm test
```

## Tool Reference

### Project Context
```typescript
get_project_context()
// Returns: { project: {...}, critical_docs: [...], important_memories: [...] }
```

### Task Management
```typescript
get_available_tasks(status_filter?)
// Returns: Array<TaskSummary>

create_task(name, requirements, files, expected_results, estimated_hours?)
// Returns: { task_id: number }

update_task_progress(task_id, status, progress_percentage?, actual_hours?, notes?)
// Returns: { success: boolean }

get_task_details(task_id)
// Returns: TaskSummary with full details
```

### Knowledge
```typescript
search_memory(query, tags?, importance_level?)
// Returns: Array<MemorySearchResult>

store_memory(title, content, tags, importance, memory_type, context?)
// Returns: { memory_id: number }
```

### Problem Tracking
```typescript
report_problem(description, related_files?, severity?)
// Returns: { problem_id: number }

get_similar_problems(description)
// Returns: Array<SimilarProblemResult>

solve_problem(problem_id, solution)
// Returns: { success: boolean }
```

### Utilities
```typescript
query_database(sql, params?)
// Returns: Array<any> (SELECT queries only)

get_agent_status()
// Returns: AgentStatusResponse

update_agent_activity(activity, current_file?, progress_detail?, task_id?)
// Returns: { success: boolean }
```

## Philosophy

Queen MCP server enables **autonomous development** by giving AI agents:
- **Complete project context** when joining a project
- **Structured task management** with clear requirements and expected results
- **Knowledge continuity** through memory and problem-solution tracking
- **Coordination capabilities** for multi-agent parallel development

**"Human sets prompt → goes to bed → LLM handles everything"** ✨

## Requirements

- Node.js 18.0 or later
- Queen Claude initialized project (`.queen` directory with database)
- Compatible with Claude Code MCP integration

## License

MIT

---

**Part of the Queen Claude ecosystem** - transforming development through autonomous AI collaboration.