AI导哈

统一AI编码代理接口服务

提供统一接口封装多种AI编码代理SDK，实现工作区管理、会话和聊天的标准化交互。

  • by hongw
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 hongw/unicoda-mcp

使用说明

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.js

MCP配置

添加到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 了解内部设计细节和实施说明。

相关 MCP