ikuncode-aimcp

<div align="center">

# ikuncode-aimcp

**一个二进制，三套 AI 引擎 — Gemini · Codex · Grok**

[![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](LICENSE)
[![Rust](https://img.shields.io/badge/Built_with-Rust-dea584.svg)](https://www.rust-lang.org/)

[English](README-en.md)

</div>

用 Rust 编写的统一 MCP 服务器，将 [Gemini CLI](https://github.com/google-gemini/gemini-cli)、[Codex CLI](https://github.com/openai/codex) 和 [Grok Search](https://x.ai/) 整合到单个进程中。配置一次，即可在 Cursor / Windsurf / Claude Desktop 等任意 MCP 客户端中使用全部工具。

### 相关项目

| 项目 | 类型 | 适用场景 |
|:-----|:-----|:---------|
| **ikuncode-aimcp**（本项目） | MCP Server | 所有 MCP 客户端通用，含 `gemini_image` 图像生成 |
| [**IKunImage**](https://github.com/deijing/IKunImage) | Claude Code Skill | Claude Code 专用 — 文生图 / 图生图 / 并发批量生成 |




</details>


| | |
|:---:|:---|
| [![api.ikuncode.cc](https://i.mij.rip/2026/02/13/89608547b83c501429c0b258de08257b.jpeg)](https://api.ikuncode.cc) |  [api.ikuncode.cc](https://api.ikuncode.cc) 提供稳定高效的 API 聚合中转服务，支持 Claude Code、Codex、Gemini 等主流模型。 |

## 特性

- **一个二进制，全部工具** — 只需配置一个 MCP 服务器，取代三个
- **运行时检测** — 启动时自动检测可用工具；不可用的工具在被调用时返回清晰的错误信息
- **AdaptiveStdio 传输** — 自动检测 JSONL 和 LSP 帧格式，最大化客户端兼容性
- **纯 Rust 的 GrokSearch** — 零 Python 依赖；通过 Grok API 实现 Web 搜索和内容抓取，支持 SSE 流式传输和重试

## 工具列表

| 工具 | 来源 | 描述 |
|------|------|------|
| `gemini` | Gemini CLI | AI 驱动的任务执行，支持会话连续性 |
| `gemini_image` | Gemini CLI | AI 图像生成，使用专用生图模型 |
| `codex` | Codex CLI | AI 辅助编码，支持沙箱策略 |
| `web_search` | Grok API | Web 搜索，返回结构化 JSON 结果 |
| `web_fetch` | Grok API | 抓取网页内容并转为 Markdown |
| `get_config_info` | Grok API | 显示配置信息并测试 API 连接 |

## 工具使用说明

### `gemini` — 执行 Gemini CLI

| 参数 | 必填 | 类型 | 默认值 | 描述 |
|------|------|------|--------|------|
| `PROMPT` | **是** | string | — | 发送给 Gemini 的任务指令 |
| `sandbox` | 否 | bool | `false` | 在沙箱模式下运行（隔离执行） |
| `SESSION_ID` | 否 | string | — | 恢复已有会话，用于多轮对话 |
| `return_all_messages` | 否 | bool | `false` | 返回所有消息（含推理过程和工具调用） |
| `model` | 否 | string | — | 模型覆盖。回退到 `GEMINI_FORCE_MODEL` 环境变量或 Gemini CLI 默认值 |
| `timeout_secs` | 否 | int | 600 | 超时时间，单位秒（1–3600） |

**返回结构：**
- `success` — 执行状态（布尔值）
- `SESSION_ID` — 用于恢复对话的唯一标识符
- `agent_messages` — 拼接的助手回复文本
- `all_messages` — （可选）`return_all_messages=true` 时返回完整的 JSON 事件
- `error` — `success=false` 时的错误描述

### `gemini_image` — Gemini 图像生成

通过 Gemini API 直接生成图像（非 CLI），支持宽高比和分辨率控制，生成后自动保存到指定目录。

| 参数 | 必填 | 类型 | 默认值 | 描述 |
|------|------|------|--------|------|
| `PROMPT` | **是** | string | — | 发送给 Gemini 的图像生成指令 |
| `model` | 否 | string | — | 模型覆盖。回退到 `GEMINI_IMAGE_MODEL` 环境变量 |
| `output_dir` | 否 | string | — | 图片保存目录。回退到 MCP workspace root → 当前工作目录 |
| `aspect_ratio` | 否 | string | — | 宽高比：`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9` |
| `image_size` | 否 | string | — | 分辨率：`1K`、`2K`、`4K`（4K 仅部分模型支持，如 `gemini-3-pro-image-preview`） |
| `timeout_secs` | 否 | int | 600 | 超时时间，单位秒（1–3600） |
| `sandbox` | 否 | bool | `false` | 在沙箱模式下运行 |
| `SESSION_ID` | 否 | string | — | 恢复已有会话 |
| `return_all_messages` | 否 | bool | `false` | 返回所有消息 |

**返回结构：**
- 生成的图像（base64 内联数据）
- 模型文本回复（如有）
- 保存路径信息（文件名格式：`gemini_image_YYYYMMDD_HHMMSS.{ext}`）

### `codex` — 执行 Codex CLI

| 参数 | 必填 | 类型 | 默认值 | 描述 |
|------|------|------|--------|------|
| `PROMPT` | **是** | string | — | 发送给 Codex 的任务指令 |
| `cd` | **是** | string | — | 工作目录路径 |
| `sandbox` | 否 | string | `"read-only"` | 沙箱策略：`"read-only"`、`"workspace-write"` 或 `"danger-full-access"` |
| `SESSION_ID` | 否 | string | — | 恢复之前的会话 |
| `skip_git_repo_check` | 否 | bool | `false` | 允许在 Git 仓库外运行 |
| `return_all_messages` | 否 | bool | `false` | 返回完整的推理轨迹 |
| `return_all_messages_limit` | 否 | int | 10000 | `return_all_messages` 为 true 时的最大消息数 |
| `image` | 否 | array | `[]` | 要附加的图片文件路径 |
| `model` | 否 | string | — | 覆盖 Codex 模型 |
| `yolo` | 否 | bool | `false` | 无需确认直接运行，跳过所有沙箱限制 |
| `profile` | 否 | string | — | `~/.codex/config.toml` 中的配置文件名 |
| `timeout_secs` | 否 | int | 600 | 超时时间，单位秒（最大 3600） |
| `force_stdin` | 否 | bool | `false` | 强制通过 stdin 传递 prompt。对于超过 800 字符或包含特殊字符的 prompt 会自动触发 |

### `web_search` — Grok Web 搜索

| 参数 | 必填 | 类型 | 默认值 | 描述 |
|------|------|------|--------|------|
| `query` | **是** | string | — | 自然语言搜索查询。可包含主题、时间范围、语言或域名等约束 |
| `platform` | 否 | string | — | 聚焦特定平台（如 `"Twitter"`、`"GitHub"`、`"Reddit"`） |
| `min_results` | 否 | int | 3 | 最少返回结果数 |
| `max_results` | 否 | int | 10 | 最多返回结果数 |
| `model` | 否 | string | — | 覆盖 Grok 模型。回退到 `GROK_MODEL` 环境变量或默认值 `grok-4.20-beta` |

### `web_fetch` — 抓取网页内容

| 参数 | 必填 | 类型 | 默认值 | 描述 |
|------|------|------|--------|------|
| `url` | **是** | string | — | 有效的 HTTP/HTTPS 网址 |
| `model` | 否 | string | — | 覆盖 Grok 模型。回退到 `GROK_MODEL` 环境变量或默认值 `grok-4.20-beta` |

### `get_config_info` — 显示 Grok 配置

无参数。返回当前 Grok 配置（API URL、模型、重试设置）并测试 API 连接。API Key 仅从环境变量读取，不会写入配置文件。

## 安装

### 方式一：下载预编译二进制（推荐）

从 [GitHub Releases](https://github.com/xuxu777xu/ikuncode-aimcp/releases) 下载对应平台的二进制文件：

| 平台 | 文件 |
|------|------|
| Windows x64 | `ikuncode-aimcp-x86_64-pc-windows-msvc.exe` |
| macOS Apple

... (truncated)