npm package: @hongw/unicoda-mcp
Description: Unified AI Coding Agent MCP Server — wraps multiple coding agent SDKs (GitHub Copilot, OpenAI Codex, Claude Code) behind a consistent MCP interface
Author: Hong Wang
Latest version: 0.1.2

# Unicoda MCP Server

[![CI](https://github.com/hongw/unicoda-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/hongw/unicoda-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Unified AI Coding Agent MCP Server — wraps multiple coding agent SDKs behind a consistent [Model Context Protocol (MCP)](https://modelcontextprotocol.io) interface.

## Overview

Unicoda lets MCP clients interact with different AI coding agents through a single, standardized abstraction layer. Instead of integrating each SDK separately, you get one consistent interface for workspace management, sessions, and chat.

### Core Concepts

| Concept | Description |
|---------|-------------|
| **Provider** | Backend SDK (copilot, codex, claude-code) |
| **Workspace** | An agent instance bound to a project directory. Reads instruction files like `AGENTS.md` for context. |
| **Session** | A conversation within a workspace. Supports multi-turn dialogue with context. |
| **Request** | A single message send, tracked by `requestId`. |

### Architecture

```
┌─────────────────┐
│   MCP Client    │
└────────┬────────┘
         │ MCP Protocol
         ▼
┌─────────────────────────────────────────┐
│            Unicoda MCP Server           │
│  ┌─────────────────────────────────┐    │
│  │      Unified Tool Interface     │    │
│  └─────────────┬───────────────────┘    │
│  ┌─────────────┴───────────────────┐    │
│  │       Provider Abstraction      │    │
│  │  ┌─────────┐ ┌───────┐ ┌─────┐  │    │
│  │  │ Copilot │ │ Codex │ │ ... │  │    │
│  │  └─────────┘ └───────┘ └─────┘  │    │
│  └─────────────────────────────────┘    │
└─────────────────────────────────────────┘
```

## Supported Providers

| Provider | SDK | Status |
|----------|-----|--------|
| **GitHub Copilot** | `@github/copilot-sdk` | ✅ Implemented |
| **OpenAI Codex** | `@openai/codex-sdk` | 🔜 Planned |
| **Claude Code** | TBD | 🔜 Planned |

## Installation

```bash
# Run directly from npm
npx @hongw/unicoda-mcp

# Or install globally
npm install -g @hongw/unicoda-mcp

# Or clone and build from source
git clone https://github.com/hongw/unicoda-mcp
cd unicoda-mcp
pnpm install
pnpm build
node dist/index.js
```

## MCP Configuration

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "unicoda": {
      "command": "node",
      "args": ["/path/to/unicoda-mcp/dist/index.js"],
      "env": {
        "UNICODA_PROVIDER": "copilot"
      }
    }
  }
}
```

## Configuration Options

| Parameter | Environment Variable | Default | Description |
|-----------|---------------------|---------|-------------|
| `--provider` | `UNICODA_PROVIDER` | `copilot` | Default provider |
| `--auto-start-workspace` | `UNICODA_AUTO_START_WORKSPACE` | `true` | Auto-start workspace when needed |
| `--max-workspaces` | `UNICODA_MAX_WORKSPACES` | `10` | Maximum concurrent workspaces |
| `--workspace-ttl` | `UNICODA_WORKSPACE_TTL` | `1800000` | Workspace idle timeout (ms) |
| `--port-range-start` | `UNICODA_PORT_RANGE_START` | `40000` | CLI port allocation start |

## Available Tools

### Workspace Management

| Tool | Description |
|------|-------------|
| `workspace_start` | Start a workspace for a project directory |
| `workspace_stop` | Stop a workspace |
| `workspace_list` | List all running workspaces |

### Session Management

| Tool | Description |
|------|-------------|
| `session_create` | Create a new conversation session |
| `session_list` | List sessions in a workspace |
| `session_delete` | Delete a session |
| `session_history` | Get full chat history |

### Chat

| Tool | Description |
|------|-------------|
| `send` | Send a message (returns immediately with `requestId`) |
| `send_and_wait` | Send a message and wait for completion |
| `poll` | Check request status with optional long-polling |
| `abort` | Abort an in-progress request |

### Utility

| Tool | Description |
|------|-------------|
| `models_list` | List available models |

## Quick Start

```javascript
// 1. Create session (auto-starts workspace)
session_create({ workspace: "/path/to/project" })
// → { sessionId: "sess-xyz", workspaceId: "ws-abc", autoStarted: true }

// 2. Send task and wait for completion
send_and_wait({
  workspace: "ws-abc",
  sessionId: "sess-xyz",
  prompt: "Add error handling to src/api.ts"
})
// → { requestId: "req-123", status: "completed", messages: [...] }
```

## Poll Options

The `poll` tool supports long-polling and response filtering:

| Parameter | Description |
|-----------|-------------|
| `timeout` | Long-poll timeout (ms). Waits up to this duration for completion. |
| `detail` | Response detail level: |
| | `status` — Only `requestId` and `status` |
| | `message` — Status + assistant text messages |
| | `brief` — Status + messages + tool call summaries (truncated) |
| | `full` — Everything (default) |

## Message Format

Responses include a `messages` array with conversation events:

```typescript
interface Message {
  type: 'user' | 'assistant' | 'tool_call' | 'tool_result' | 'system' | 'error';
  content: string;
  timestamp: string;  // ISO8601
  metadata?: {
    toolName?: string;
    toolArgs?: unknown;
    toolResult?: unknown;
    // ...
  };
}
```

## Request Status

All requests follow a unified state machine:

```
queued → running → completed
                 → error
                 → timeout
         ↓
       aborted
```

## Error Handling

Errors include structured information:

```json
{
  "error": {
    "code": "WORKSPACE_NOT_FOUND",
    "message": "Workspace ws-xyz not found",
    "retryable": false
  }
}
```

Common error codes: `WORKSPACE_NOT_FOUND`, `SESSION_NOT_FOUND`, `REQUEST_NOT_FOUND`, `TIMEOUT`, `CLI_START_FAILED`

## Development

```bash
pnpm install
pnpm build
pnpm test
pnpm lint
```

## Contributing

Contributions welcome! See [ARCHITECTURE.md](docs/ARCHITECTURE.md) for internal design details and implementation notes.