npm package: @nowfun/codefree-helper
Description: CodeFree 助手
Latest version: 1.1.1

# CodeFree Helper

CodeFree Helper 是 CodeFree 平台辅助工具，提供用于 CodeFree CLI 的 OAuth2 授权、API Key 管理和 Claude Code 集成功能。

## 功能介绍

- **独立授权**：独立生成 CodeFree CLI 所需的认证凭证文件 oauth_creds.json，解决 CodeFree CLI 在授权过程中无法自动打开浏览器的问题。
- **CLI API Key 提取**：解密并显示已保存的 API Key，便于用户直接使用或配置到其他工具。
- **Claude Code 集成**：将 SRDCloud Transformer 安装到 Claude Code Router 插件目录，实现 SRDCloud API 与 Claude Code 的无缝集成。
- **MCP 服务器安装**：从 SRDCloud 获取 MCP 服务器配置，批量安装到 Claude Code，提供 API中心、Wiki文档、工作项、文档空间等 MCP 服务。

## 前置要求

- Node.js >= 20.0.0

## 安装

### 推荐：使用 npx（无需安装到本地）

```bash
npx @nowfun/codefree-helper
```

### 全局安装

```bash
npm install -g @nowfun/codefree-helper
```

## 使用

### npx 方式

```bash
npx @nowfun/codefree-helper
```

### 全局安装方式

运行命令：

```bash
cfh
```

工具会提供交互式菜单，支持以下操作：

1. **生成 CLI OAuth 凭证文件** - 执行完整的 OAuth2 授权流程，生成包含加密 API Key 的凭证文件
2. **提取 CLI API Key** - 解密并显示已保存的 API Key
3. **安装 CCR Transformer** - 将 SRDCloud Transformer 安装到 Claude Code Router 插件目录
4. **安装 SRDCloud MCP 服务器配置** - 从 SRDCloud 获取 MCP 服务器列表，批量安装到 Claude Code


## 凭证存储

凭证文件保存在 `~/.codefree-cli/oauth_creds.json`，包含：
- access_token
- id_token
- apikey（加密存储）
- baseUrl

## Claude Code 集成

> **注意**：此集成方式仅使用 SRDCloud API 大模型接口，并不包含使用数据统计。
>
> 如需使用数据统计功能，请参考 **[CodeFree Stat](https://cnb.cool/nowfun/codefree-stat)** 工具。

### 安装 SRDCloud Transformer

Claude Code Router 用于将 SRDCloud API 转换为 Anthropic 接口协议。安装过程中会自动检测并提示安装 Claude Code Router（如未安装）。

Transformer 安装路径为 `~/.claude-code-router/plugins/srdcloud.transformer.js`。

安装完成后需配置路由。可通过 `ccr ui` 命令打开 UI，或直接编辑 `~/.claude-code-router/config.json` 添加如下配置：

```json
{
  "Router": {
    "default": "srdcloud,GLM-4.7",
    "background": "srdcloud,GLM-4.7",
    "think": "srdcloud,GLM-4.7",
    "longContext": "srdcloud,GLM-4.7",
    "longContextThreshold": 60000,
    "webSearch": "srdcloud,GLM-4.7",
    "image": "srdcloud,Qwen3.5-122B-A10B"
  }
}
```

请根据实际需求调整，对于长上下文场景，建议选择支持更大上下文的模型。

**注意：配置修改后需执行 `ccr restart` 使其生效。**

### 安装 SRDCloud MCP 服务器

本功能通过 `claude mcp add-json` 命令将 SRDCloud 提供的 MCP 服务器批量注册到 Claude Code，实现 API中心、Wiki文档、工作项、文档空间等 MCP 服务的直接调用。

#### headersHelper 认证方案

**优势：**
- ✅ **凭证集中管理**：所有 MCP 服务器共享同一凭证文件
- ✅ **无明文存储**：userId/apiKey/mcpId 都不在配置文件中明文存储
- ✅ **自动更新**：凭证更新后无需重新配置 MCP 服务器
- ✅ **无需本地脚本**：使用 `npx` 直接调用，无需安装本地脚本文件
- ✅ **动态 mcpId**：每个 MCP 服务器通过 `--mcp-id` 参数传递对应的 mcpId

#### 安装流程

1. 从凭证文件读取并解密认证信息
2. 调用 SRDCloud API 获取可用的 MCP 服务器列表
3. 选择要安装的 MCP 服务器（支持多选）
4. 选择安装范围（local/user/project）
5. 确认后逐个安装

安装完成后可通过 `claude mcp list` 查看已注册的 MCP 服务器。

#### 手动测试认证头

```bash
# 测试不带 mcpId（返回基础认证头）
npx @nowfun/codefree-helper get-mcp-headers

# 测试带 mcpId（返回包含 mcpId 的认证头）
npx @nowfun/codefree-helper get-mcp-headers --mcp-id 123

# 或使用已安装的 CLI
cfh get-mcp-headers                # 不带 mcpId
cfh get-mcp-headers --mcp-id 123   # 带 mcpId
```

### 安装 Claude Code

本工具并不提供 Claude Code 的安装功能，可直接 npm 方式安装：

```bash
npm install -g @anthropic-ai/claude-code
```

其他安装方式可参考 Claude Code 官方文档：https://code.claude.com/docs/zh-CN/overview.

由于 SRDCloud API 提供的模型上下文有限，在 Claude Code 默认配置情况下使用可能出现 **424 错误（Failed Dependency）**，解决方法是调整自动压缩阈值，通过修改环境变量 `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 实现：

| 设置 | 说明 |
|------|------|
| 默认值 95 | 当输入占用上下文超过 95% 时才压缩 |
| 建议值 30 | 当输入占用上下文超过 30% 时即压缩 |

可直接修改系统环境变量或者编辑 `~/.claude/settings.json` 添加以下配置：
```json
{
  "env": {
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": 30
  }
}
```

## 已知问题

- Windows 系统下执行 `claude mcp add` 可能出现错误，建议使用 PowerShell 或 WSL
- 暂不支持 MCP 服务器覆盖安装（需要先手动删除再重新安装）

## 版本历史

- **1.1.0** - 支持 MCP 服务器批量安装，使用 headersHelper 动态认证
- **1.0.x** - 初始版本，支持 OAuth 授权和 CCR Transformer 安装

---

## 发布流程（开发者）

本部分适用于项目维护者发布新版本。

### 发布步骤

```bash
# 1. 登录 npm（首次发布或登录过期时）
npm login

# 2. 更新版本号（推荐使用 npm version 自动同步）
npm version patch   # 补丁版本：1.1.0 → 1.1.1
npm version minor   # 次版本：1.1.0 → 1.2.0
npm version major   # 主版本：1.1.0 → 2.0.0
# 或直接指定版本号
npm version 1.2.0

# 3. 发布到 npm
npm run publish
```

### 使用 `npm version` 的优势

- ✅ **自动同步**：同时更新 `package.json` 和 `package-lock.json`
- ✅ **自动提交**：创建 git commit 和 tag
- ✅ **避免错误**：无需手动修改版本号，减少遗漏风险

### 方式二：手动修改版本号（不推荐）

```bash
# 1. 手动修改 package.json 版本号
# 2. 执行 npm install 同步 package-lock.json
npm install
# 3. 发布
npm run publish
```