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 | 🔜 计划中 |
安装
# 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.jsMCP配置
添加到MCP客户端配置中：
{
"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 | 列出可用型号 |
快速开始
// 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 包含对话事件的数组：
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错误处理
错误包括结构化信息：
{
"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
发展
pnpm install
pnpm build
pnpm test
pnpm lint贡献
欢迎投稿！看 建筑.md 了解内部设计细节和实施说明。