内容
# mcp-super-app
MCP服务器，用于Claude Code：收集常规设置动作（项目框架、技能、着陆页构建环境、guard钩子、图片、图标）到一个入口点。连接服务器后，所有工具都可以通过普通的tool调用从任何聊天中访问。
技术栈：TypeScript + `@modelcontextprotocol/sdk`，传输 **stdio** （本地服务器，不发送任何数据到外部，除了生成图片时使用OpenRouter）。
---
## 安装 — 只需一句
打开 **Claude Code** 并发送以下消息：
```
按照指示安装MCP服务器：https://github.com/AndreyTsibin/mcp-super-app-public/blob/main/INSTALL.md
```
代理将自动完成其余操作：检查环境、克隆仓库、构建并连接服务器。无需深入了解代码。
详细步骤指南（包括故障排除）请参阅 [INSTALL.md](INSTALL.md)。
---
## 要求
- **Node.js ≥ 20**.
- **OpenRouter密钥** - 仅用于 `generate_image`。其他工具无需密钥。每个用户拥有自己的密钥：<https://openrouter.ai/keys>.
- 对于 `install_guard`，需要 `jq` (`brew install jq`) - 否则guard脚本将失效（跳过所有检查）。
## 工具
| 工具 | 功能 |
|---|---|
| `bootstrap_project` | 一键部署新项目框架：`.gitignore`, `.editorconfig`, `.claude/`（设置、钩子、`CLAUDE.md`, `HANDOFF`）, `docs/` 根据 **S/M/L** 配置文件和自动内存。幂等操作，不会覆盖现有文件。 |
| `install_skill` | 在项目中安装技能：bundled → 复制到 `.claude/skills/<id>/`; proxied → 运行官方CLI。自动将产物添加到 `.gitignore`。 |
| `scaffold_landing` | 部署Astro网站生成器项目：包含21个部分、token合约 + 主题、`/kit`（测试）和`/themes`（主题选择）页面，`docs/` 标准（流程、特定配置文件、目录、图片、评论），`send.php` + `lead-form.js` 模板，预览器和 `.claude/check-landing.mjs` 机器校验器（合约、SEO、对比度、死链、图片）。“一个项目 = 一个网站”的模型，支持着陆页或多页面应用。 |
| `install_guard` | 安装防止破坏性命令（`rm`、`find -delete`、`git reset --hard`等）的PreToolUse钩子 - 全局（`target=user`）或项目级别。安全地合并到 `settings.json`。 |
| `generate_image` | 通过OpenRouter生成图片，返回 **图片到聊天** + 保存文件到项目（默认为 `./generated`）+ 返回 `usage.cost`。默认模型为Seedream 4.5（`bytedance-seed/seedream-4.5`，$0.04每张图片）；Nano Banana 2/Pro和GPT Image 2支持通过 `model` 参数指定。使用 `image` 技能作为前缀：没有技能或空 `prompt_source` 将拒绝请求。 |
| `optimize_images` | 准备图片用于生产环境（sharp）：调整到 `max_width`（不放大），转换为webp/jpeg/avif，EXIF旋转，可选的srcset变体（`widths`）。默认替换原始文件并返回最终尺寸（用于 `<img>`中的 `width`/`height`）。 |
| `search_icons` | 根据英文单词/概念在两个集合中搜索图标： **lucide** （~2000个通用UI图标 - wrench, shield, clock…）和 **simple-icons** （~3400个品牌logo - GitHub, HP, Telegram…）。返回 `get_icon` 的精确 `name`/`set`。 |
| `get_icon` | 根据精确的 `name`/`set` 返回原始SVG图标。`size` - 以像素为单位的正方形大小，`color` - CSS颜色（lucide默认为 `currentColor`；simple-icons默认为品牌特定十六进制颜色）。 |
## OpenRouter密钥
仅在生成图片时需要。
```bash
cp .env.example .env
# 输入您的密钥：OPENROUTER_API_KEY=sk-or-v1-...
```
`.env` 被git忽略（参见 `.gitignore`）。密钥从 `.env` 加载 - 服务器启动时自动加载，无需通过配置文件传递。
## 手动连接到Claude Code
如果自动安装方法失败，请使用以下方法：
**1. CLI** （全局安装，对于所有项目 - `-s user`）：
```bash
claude mcp add mcp-super-app -s user -- /绝对路径/到/mcp-super-app/launch.sh
```
**2. `.mcp.json` 文件** （在项目根目录或 `~/.claude.json` - 全局）：
```json
{
"mcpServers": {
"mcp-super-app": {
"command": "/绝对路径/到/mcp-super-app/launch.sh"
}
}
}
```
通过 `launch.sh` 连接（而非直接运行 `node dist/index.js`）实现自动更新：每次启动脚本都会执行 `git pull` 和重建，如果网络故障或构建失败，则静默回退到已编译的 `dist/`。
## 开发
```bash
npm install
npm run build # 编译TS → dist/
npm run dev # tsx watch - 从src/运行而无需构建
npm run typecheck # tsc --noEmit
npx @modelcontextprotocol/inspector node dist/index.js # 手动检查工具
```
服务器入口点为 `dist/index.js`（stdio）。
## 结构
```
src/
├── index.ts # 入口点：工具注册 + stdio传输，加载.env
├── lib/ # 共享基础设施：openrouter, scaffold, project-slug, 错误处理, settings-merge, …
└── tools/ # 每个工具的模块
assets/ # 静态模板：skills/, bootstrap/, landing/, guard/
docs/ # 规格和标准（架构，API）
```
约定和工作方法参见 [`.claude/CLAUDE.md`](.claude/CLAUDE.md)。
