# Universal Creativity MCP

简体中文 | [English](README.en.md)

一个供 AI agent 使用的通用创意发散 MCP 服务。它通过 Recoding-Decoding（RD）循环，为每个候选创意引入新的联想刺激，并把前面生成的候选继续带入后续生成过程，帮助 agent 探索更多不同方向。

服务负责生成和扩展候选方案；可行性判断、排序和最终选择仍由调用它的 agent 完成。

## 功能

| MCP 工具 | 用途 |
| --- | --- |
| `creative_generate` | 从一个问题或主题开始发散创意 |
| `creative_expand` | 扩展现有创意的含义、场景或实现形式 |
| `creative_mutate` | 改变创意，同时保留指定属性 |
| `creative_cross` | 融合两个概念的机制或含义 |

工具支持语言、数量、约束、随机种子、并行链和可选生成轨迹。每次调用无状态，不会把 prompt、创意或历史写入数据库。

## 工作方式

```mermaid
flowchart LR
  A[Agent / MCP Host] -->|stdio 或 Streamable HTTP| B[Universal Creativity MCP]
  B --> C[采样联想刺激并构造提示]
  C --> D[调用已配置的语言模型]
  D --> E[返回并去重的创意候选]
  E --> A
```

RD 是由程序控制的生成循环：每个候选都需要单独生成；一个链后续的生成会看到该链先前的候选。通常请求 8 个创意至少会产生 8 次模型请求，重复或无效输出可能触发额外请求。`CREATIVE_MAX_CALLS` 限制每次工具调用的请求总数。

## 环境要求

- Python 3.10 或更新版本。
- 一个可访问的 OpenAI-compatible 模型服务。此项目不会下载、启动或托管模型。
- 在 Codex 等 agent host 中使用时，将 MCP 配置为本地 stdio 服务；远程客户端可使用 Streamable HTTP 部署。

## 安装和配置

在项目目录执行：

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .
if (!(Test-Path .env)) { Copy-Item .env.example .env }
```

macOS / Linux 激活虚拟环境的命令为 `source .venv/bin/activate`；仅在尚无 `.env` 时复制配置文件：`test -f .env || cp .env.example .env`。

编辑 `.env`，填写模型服务信息：

```env
CREATIVE_LLM_PROVIDER=completion
CREATIVE_LLM_BASE_URL=http://localhost:8000/v1
CREATIVE_LLM_API_KEY=
CREATIVE_LLM_MODEL=YOUR_MODEL_NAME
```

`completion` 模式请求 `{CREATIVE_LLM_BASE_URL}/completions`，适用于提供 completion 接口的模型服务。若模型只提供 `/chat/completions`，将 provider 改为 `chat_simulated`。按模型服务要求填写 API key；本地服务可以不需要 key。

不要把真实 API key 写入 Git。`.env` 已列入 `.gitignore`；部署到云端时，把 key 放到云平台的 secrets / 环境变量设置中。

## 在 Codex 中连接

Codex 桌面版、CLI 和 IDE 扩展共用 MCP 配置。可运行 Codex CLI 命令：

```powershell
codex mcp add universal-creativity -- "D:\path\to\Ideaflect\.venv\Scripts\creativity-mcp.exe"
codex mcp list
```

将路径换成仓库的绝对路径。也可以在 `%USERPROFILE%\.codex\config.toml` 中添加以下配置：

```toml
[mcp_servers.universal-creativity]
command = 'D:\path\to\Ideaflect\.venv\Scripts\creativity-mcp.exe'
args = []
cwd = 'D:\path\to\Ideaflect'
```

macOS / Linux 的 `command` 应指向 `.venv/bin/creativity-mcp`。保存配置后，重载 Codex 的 MCP 配置；在 Codex CLI 中可用 `/mcp` 查看连接状态。由于模型参数存于项目的 `.env`，请保留正确的 `cwd`。

### GitHub Copilot CLI

本地运行时，可以将同一个 stdio 入口添加到 Copilot CLI：

```powershell
copilot mcp add universal-creativity -- "D:\path\to\Ideaflect\.venv\Scripts\creativity-mcp.exe"
copilot mcp list
```

在 VS Code 的 Copilot Chat 中，也可以在仓库的 `.vscode/mcp.json` 使用 workspace 相对路径：

```json
{
  "servers": {
    "universal-creativity": {
      "type": "stdio",
      "command": "${workspaceFolder}/.venv/Scripts/creativity-mcp.exe",
      "args": [],
      "cwd": "${workspaceFolder}"
    }
  }
}
```

该 executable 路径是 Windows 写法。macOS / Linux 请将 `command` 改为 `${workspaceFolder}/.venv/bin/creativity-mcp`。VS Code 可通过 MCP: List Servers 查看并启动服务；在 Copilot CLI 中用 `/mcp` 查看状态。GitHub Copilot CLI 和 VS Code 的 MCP 配置格式不同，请使用对应客户端的格式。

## 调用示例

可以直接告诉 agent 你的问题、数量和约束，例如：

> 用 `creative_generate` 为公交站候车体验生成 8 个中文创意。不要增加硬件或收集个人数据；尽量让方案的核心机制彼此不同。

也可以明确要求不同的探索方式：

- “用 `creative_expand` 将这个点子扩展为 6 种适用于校园的方案：共享雨伞。”
- “用 `creative_mutate` 改造这个方案，保留无需注册和保护隐私这两个特点：社区活动发现工具。”
- “用 `creative_cross` 融合社区图书馆与游戏化任务，生成 8 种创意。”

常用参数示例：

```json
{
  "problem": "设计一种新的软件缓存思路",
  "count": 8,
  "language": "zh",
  "constraints": ["不修改业务数据库"],
  "method": "rd_full",
  "seed": 42
}
```

`count` 最大为 30。`parallel_chains` 默认值为 1，最大为 4。结果会报告请求数、返回数、模型调用次数、去重数量和耗时；设置 `include_trace=true` 可以查看生成使用的联想刺激。

## 运行方式

### 本地 stdio

Codex 等 MCP host 会按配置自动启动 stdio 服务。也可以在项目虚拟环境中手动运行：

```powershell
creativity-mcp
```

stdio 模式不会监听 HTTP 端口。

### Streamable HTTP

Streamable HTTP 必须配置访问 token。先生成一串随机密钥：

```powershell
python -c "import secrets; print(secrets.token_urlsafe(32))"
```

把命令输出保存在本地 `.env` 的 `CREATIVE_MCP_ACCESS_TOKEN` 中，或仅为当前 PowerShell 窗口设置：

```powershell
$env:CREATIVE_MCP_ACCESS_TOKEN = "粘贴生成的随机密钥"
```

然后启动 HTTP 服务：

```powershell
creativity-mcp --transport streamable-http --host 127.0.0.1 --port 8765
```

默认 MCP endpoint 为 `http://127.0.0.1:8765/mcp`。所有 HTTP 请求都必须携带 `Authorization: Bearer <token>`，缺少 token 或 token 错误时返回 `401`。不要把 token 放进 URL、提交到 GitHub，或写入公开的 MCP 配置。

## 部署到远程环境

**GitHub 用于托管源代码和容器镜像，不是运行任意自定义 MCP 进程的主机。** GitHub 官方 [GitHub MCP Server](https://github.com/github/github-mcp-server) 提供访问 GitHub 功能的工具，不能把本项目的 `creative_generate` 等工具安装到它的服务器上。把仓库推到 GitHub 后，还需要一个能运行容器或 Python 服务的主机，才能得到远程 MCP endpoint。

项目支持 Streamable HTTP，可部署到你选择的容器平台或自有服务器。仓库提供 Dockerfile，先在本机验证镜像：

```powershell
docker build -t universal-creativity-mcp .
docker run --rm -p 8080:8080 --env-file .env -e CREATIVE_MCP_HOST=0.0.0.0 -e PORT=8080 universal-creativity-mcp
```

服务 endpoint 为 `http://localhost:8080/mcp`。在云平台部署时：

1. 将 GitHub 仓库连接到支持 Docker 容器的运行平台，或先构建镜像并推送到 GitHub Container Registry（GHCR）。
2. 让平台运行该镜像，并把容器端口设为平台提供的 `PORT`（未提供时默认 `8080`）。
3. 在平台的环境变量 / secrets 中配置模型服务需要的 `CREATIVE_LLM_PROVIDER`、`CREATIVE_LLM_BASE_URL`、`CREATIVE_LLM_MODEL` 和 `CREATIVE_LLM_API_KEY`。将 `CREATIVE_MCP_HOST` 设为 `0.0.0.0`。
4. 设置 `CREATIVE_MCP_ACCESS_TOKEN`，值为一串高强度随机密钥；不要把它提交到仓库。这个项目会在创建 HTTP MCP app 时强制要求该变量。
5. 使用平台给出的 HTTPS 域名，加上 `/mcp`，作为远程 MCP URL，并在支持远程 Streamable HTTP 的 MCP host 中添加它。

若模型服务也在容器外运行，确保容器能访问其地址。不要在云端沿用只对本机有效的 `localhost` 模型地址。

例如，若本地 Docker 容器要连接运行在 Windows 主机上的模型服务，将容器的 `CREATIVE_LLM_BASE_URL` 设为 `http://host.docker.internal:8000/v1`。具体地址以模型服务和部署平台的网络配置为准。

在 Render 的 Environment 设置中添加 `CREATIVE_MCP_ACCESS_TOKEN`，并保存部署。Render 会把环境变量提供给服务进程；不要将 token 写进仓库或 Render 的公开配置文件。详见 [Render 环境变量文档](https://render.com/docs/configure-environment-variables)。

在 Codex 使用的电脑上，把相同 token 保存为用户环境变量 `CREATIVE_MCP_ACCESS_TOKEN`，然后完全退出并重启 Codex。接着在 Codex 的 `config.toml` 添加：

```toml
[mcp_servers.universal-creativity]
url = "https://YOUR_HOST/mcp"
bearer_token_env_var = "CREATIVE_MCP_ACCESS_TOKEN"
```

把 `YOUR_HOST` 替换成 Render 服务域名。Codex 会从该环境变量读取 token，并通过 Bearer Authorization 请求头发送给 MCP 服务；Codex 的该项配置见[官方配置参考](https://developers.openai.com/codex/config-reference)。也可以用 `codex mcp list` 查看已配置的服务器。

GitHub Copilot CLI 的远程配置命令为：

```powershell
copilot mcp add --transport http universal-creativity "https://YOUR_HOST/mcp"
copilot mcp list
```

若要让 **GitHub.com 上的 Copilot cloud agent** 在这个仓库中使用它，由仓库管理员打开 `Settings` → `Copilot` → `MCP servers`，粘贴并保存如下配置：

```json
{
  "mcpServers": {
    "universal-creativity": {
      "type": "http",
      "url": "https://YOUR_HOST/mcp",
      "tools": [
        "creative_generate",
        "creative_expand",
        "creative_mutate",
        "creative_cross"
      ]
    }
  }
}
```

替换为实际 HTTPS 地址。云端 agent 需要能访问该地址；GitHub 当前文档注明 Copilot cloud agent 不支持使用 OAuth 认证的远程 MCP。仓库级 MCP 工具可能由 Copilot 自动调用；只连接你信任的 endpoint，并为网关认证配置适当的 GitHub secrets。详见 [GitHub 官方仓库 MCP 配置说明](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/configure-mcp-servers)。

若前置网关使用 Bearer token，可在 MCP 配置中增加 `"headers": {"Authorization": "Bearer $COPILOT_MCP_ACCESS_TOKEN"}`，并在仓库或组织的 Copilot Agents secrets 中创建 `COPILOT_MCP_ACCESS_TOKEN`。不要把 token 明文写入仓库配置。

访问 token 只能限制持有密钥的客户端；如果密钥泄露，请在 Render 和本机同时更换。它是 MCP 访问密钥，不是模型 API key。当前创意生成工具仍会调用配置的模型服务，因此仅添加访问认证不会移除服务器端模型调用或其费用。GitHub Actions 和 GHCR 可以帮助自动构建、存放镜像，但仍需云平台或自有服务器运行容器。

## 发布到 GitHub

当前工作目录需要先关联一个 GitHub 仓库。创建空仓库后，在项目目录运行以下命令，并替换仓库地址：

```powershell
git init -b main
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/OWNER/REPOSITORY.git
git push -u origin main
```

`git add .` 会遵循 `.gitignore`，不会添加 `.env` 或 `.venv`。在推送前仍建议检查暂存内容：`git status`。

## 语言处理与限制

- `language=auto` 会根据输入中的中日韩字符比例判断中文或英文。
- 中文联想刺激仍属实验性实现；它并不声称复现论文中的英文实验设置。
- 去重采用精确匹配和词项重合度等轻量方法，不是语义去重；可能漏掉改写，也可能过滤掉部分相似但有效的点子。
- 此 MVP 不包含向量数据库、检索、领域知识、自动评分或创意排名。
- 每次工具调用无状态。输入和生成结果会发送给 `.env` 中配置的模型服务。

## 许可证

本项目使用 [MIT License](LICENSE)。你可以免费使用、修改、再分发本项目，也可以将其用于商业用途；再分发时需保留版权声明和许可证文本。

## 研究参考

本项目受 Luo、King、Puett、Smith 的论文 [“Inducing Sustained Creativity and Diversity in Large Language Models”](https://arxiv.org/abs/2603.19519) 启发，是 provider-agnostic 的实验性 MVP，不代表对论文方法的精确复现。