Unicoda MCP服务器
统一的AI编码代理MCP服务器——将多个编码代理SDK封装在一致的 模型上下文协议(MCP) 界面。
概述
Unicoda允许MCP客户端通过一个标准化的抽象层与不同的AI编码代理进行交互。您无需单独集成每个SDK,而是可以获得一个用于工作区管理、会话和聊天的一致接口。
核心概念
| 概念 | 描述 |
|---|---|
| 提供者 | 后端SDK(副产品、codex、claude代码) |
| 工作区 | 绑定到项目目录的代理实例。读取指令文件,如 AGENTS.md 为了上下文。 |
| 会话 | 工作空间内的对话。支持带上下文的多回合对话。 |
| 请求 | 单个消息发送,由以下人员跟踪 requestId. |
建筑```
┌─────────────────┐
│ MCP Client │
└────────┬────────┘
│ MCP Protocol
▼
┌─────────────────────────────────────────┐
│ Unicoda MCP Server │
│ ┌─────────────────────────────────┐ │
│ │ Unified Tool Interface │ │
│ └─────────────┬───────────────────┘ │
│ ┌─────────────┴───────────────────┐ │
│ │ Provider Abstraction │ │
│ │ ┌─────────┐ ┌───────┐ ┌─────┐ │ │
│ │ │ Copilot │ │ Codex │ │ ... │ │ │
│ │ └─────────┘ └───────┘ └─────┘ │ │
│ └─────────────────────────────────┘ │
└─────────────────────────────────────────┘
## 支持的提供商
|提供者|SDK|状态|
|----------|-----|--------|
| **GitHub Copilot** | `@github/copilot-sdk` | ✅ 已执行|
| **OpenAI 代码专家** | `@openai/codex-sdk` | 🔜 计划中|
| **克劳德代码** |TBD |🔜 计划中|
## 安装```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配置
添加到MCP客户端配置中:```json
{
"mcpServers": {
"unicoda": {
"command": "node",
"args": ["/path/to/unicoda-mcp/dist/index.js"],
"env": {
"UNICODA_PROVIDER": "copilot"
}
}
}
}
## 配置选项
|参数|环境变量|默认值|说明|
|-----------|---------------------|---------|-------------|
| `--provider` | `UNICODA_PROVIDER` | `copilot` |默认提供程序|
| `--auto-start-workspace` | `UNICODA_AUTO_START_WORKSPACE` | `true` |需要时自动启动工作区|
| `--max-workspaces` | `UNICODA_MAX_WORKSPACES` | `10` |最大并发工作空间|
| `--workspace-ttl` | `UNICODA_WORKSPACE_TTL` | `1800000` |工作区空闲超时(ms)|
| `--port-range-start` | `UNICODA_PORT_RANGE_START` | `40000` |CLI端口分配开始|
## 可用工具
### 工作空间管理
|工具|说明|
|------|-------------|
| `workspace_start` |为项目目录启动工作区|
| `workspace_stop` |停止工作区|
| `workspace_list` |列出所有正在运行的工作区|
### 会话管理
|工具|说明|
|------|-------------|
| `session_create` |创建新的对话会话|
| `session_list` |列出工作区中的会话|
| `session_delete` |删除会话|
| `session_history` |获取完整的聊天记录|
### 聊天
|工具|说明|
|------|-------------|
| `send` |发送消息(立即返回 `requestId`) |
| `send_and_wait` |发送消息并等待完成|
| `poll` |使用可选的长轮询检查请求状态|
| `abort` |中止正在进行的请求|
### 效用
|工具|说明|
|------|-------------|
| `models_list` |列出可用型号|
## 快速开始```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 该工具支持长轮询和响应过滤:
| 参数 | 说明 |
|---|---|
timeout |
轮询超时时间过长(毫秒)。等待此时间完成。 |
detail |
响应详细级别: |
status --只有 requestId 和 status |
|
message --状态+助理短信 |
|
brief --状态+消息+工具调用摘要(截断) |
|
full --全部(默认) |
消息格式
答复包括a messages 包含对话事件的数组:```typescript
interface Message {
type: 'user' | 'assistant' | 'tool_call' | 'tool_result' | 'system' | 'error';
content: string;
timestamp: string; // ISO8601
metadata?: {
toolName?: string;
toolArgs?: unknown;
toolResult?: unknown;
// ...
};
}
## 请求状态
所有请求都遵循统一的状态机:```
queued → running → completed
→ error
→ timeout
↓
aborted
错误处理
错误包括结构化信息:```json
{
"error": {
"code": "WORKSPACE_NOT_FOUND",
"message": "Workspace ws-xyz not found",
"retryable": false
}
}
常见错误代码: `WORKSPACE_NOT_FOUND`, `SESSION_NOT_FOUND`, `REQUEST_NOT_FOUND`, `TIMEOUT`, `CLI_START_FAILED`
## 发展```bash
pnpm install
pnpm build
pnpm test
pnpm lint
贡献
欢迎投稿!看 建筑.md 了解内部设计细节和实施说明。
