# codemind-plugin

**Repository Path**: lymboy/codemind-plugin

## Basic Information

- **Project Name**: codemind-plugin
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-09
- **Last Updated**: 2026-07-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# codewiki-mcp-plugin

> CodeWiki MCP server 插件 —— 装上即用,自动完成 MCP 配置,用户无需手动改任何文件。

## 工作原理

两部分配合,全程用户无感知:

**1. `plugin.json` 用占位符声明 MCP server:**

```json
"mcpServers": {
  "codewiki": {
    "type": "http",
    "url": "${BASE_API}/ksc-ai-codemind/api/mcp/unified",
    "headers": {
      "Authorization": "Bearer ${KSCC_AUTH_TOKEN}",
      "Referer": "${BASE_API}"
    }
  }
}
```

`${VAR}` 从环境变量取值,而 settings.json 只有 `env` 字段的内容会进环境变量。

**2. `hooks/hooks.json` 的 SessionStart hook 自动回填配置:**

每次会话启动时自动执行 `install.js`(纯 node,零依赖,毫秒级),它读取 `~/.claude/settings.json` 里的 `BASE_API` 和 `KSCC_AUTH_TOKEN`——不管在顶层还是 `env` 字段下——回填到 `env`,保证占位符能展开。顶层原值保留不动,kscc 照常读。脚本幂等,配置就绪时完全静默。

> Claude Code 插件没有"安装时执行脚本"的生命周期事件,SessionStart hook 是最接近安装即生效的机制。

## 安装

```bash
# 添加插件市场(仅需一次)
/plugin marketplace add <repo-url>

# 安装插件
/plugin install codewiki-mcp-plugin@kscc-marketplace
```

前提只有一个:kscc 已登录(settings.json 里有 `BASE_API` 和 `KSCC_AUTH_TOKEN`,顶层或 `env` 均可)。

## 安装后

重启 kscc / Claude Code。首次启动时 hook 自动回填配置;如果看到「已回填…重启后生效」提示,再重启一次即可(env 变量在进程启动时加载,回填当次会话取不到)。之后 `/mcp` 里出现 codewiki,工具名形如 `mcp__codewiki__*`。

也可以手动跑一次 `node install.js` 提前完成回填,装完插件重启一次就生效。

## 排查

- `/mcp` 里 codewiki 的 url 显示 `${BASE_API}/...` 没展开 —— 回填还没生效(首次安装后 hook 刚写入),重启一次;或手动 `node install.js` 后重启。
- 插件 `✘ failed to load` 报 `Duplicate hooks file` —— hook 只放在标准位置 `hooks/hooks.json`(自动加载),`plugin.json` 里不要再声明 `"hooks"` 字段,重复声明会冲突。本插件遵循此约定。
- codewiki `✘ Failed to connect` —— 配置展开正常,是后端/网关不可达,确认 `${BASE_API}` 指向的网关已转发 `/ksc-ai-codemind/api/mcp/unified` 到 codewiki 后端。
- `Referer` 是 codewiki 网关必需的请求头,跟随 `${BASE_API}` 展开,无需用户单独配置。

## 兼容性

Windows / macOS / Linux;kscc 与 Claude Code 配置格式兼容。