zhiji-mcp

智技 MCP Server：让 Cursor / Claude Code / jrjb-agent 等 Agent 通过工具创建与维护本站 Prompt、Skill 与社区 MCP。

环境变量

| 变量 | 说明 | |------|------| | BIGAPP_API_KEY | 必填。主站个人中心签发的个人空间 Agent 密钥（bigapp_...） | | BIGAPP_API_BASE | 可选覆盖。未设置时使用构建环境写入的默认地址 |

默认 BIGAPP_API_BASE 由构建命令对应的 .env.* 决定：

| 构建 | 默认 BIGAPP_API_BASE | |------|----------------------| | npm run build | http://127.0.0.1:5202（直连，无 /api） | | npm run build:test | https://zhiji.test.atbigapp.com/api | | npm run build:production | https://zhiji.atbigapp.com/api |

本地直连后端端口 5202 不要带 /api；测试/生产域名一般带 /api。

构建

cd zhiji-mcp
npm install
npm run build            # development → 127.0.0.1:5202
npm run build:test
npm run build:production

Cursor 配置

见 cursor-mcp.example.json。入口为 dist/index.js，一般只需配置 BIGAPP_API_KEY；需要指向非构建默认后端时再设 BIGAPP_API_BASE。

本地无 bigapp Key 时，可临时使用后端 zhiji.mcp.fallback-token（仅开发，见 application-dev.yml）。

首次使用前，Key 签发者需在智技 Web 登录一次，以便同步本地 sys_user；否则写操作会提示未同步账号。

能力边界

• 草稿 CRUD：list_my_* / create_* / update_* / delete_* 操作的是当前用户在 SkillIDE / MCP IDE 的草稿，与 Web 同一数据源。
• 广场检索：search_skills / search_mcps 只读已发布卡片；get_skill(skillSlug) / get_mcp(mcpSlug) 读广场详情。
• 「上传」语义：把文本文件树或元数据写入草稿（如 import_skill），不是往本机装包。
• publish_* 语义：提交审核进入管理端队列，通过后才上架；不是绕过审核直接上架。
• 安装：仍由 Aido 桌面完成，不要用本 MCP 往本机装包。
• 审核管理：管理端审核接口不暴露给普通 Agent Key。

Agent 推荐工作流

Skill（本地包 → 草稿 → 投稿）

1. list_my_skills(keyword?, reviewStatus?) 查是否已有草稿
2. 有整棵文本树：优先 import_skill（可覆盖本人草稿）；否则 create_skill + 多次 upsert_skill_file
3. validate_skill → 通过后再 publish_skill
4. 审核中可用 withdraw_skill 退回草稿

广场浏览：search_skills → get_skill(skillSlug)。

社区 MCP（登记可安装包元数据）

1. list_my_mcps(keyword?, reviewStatus?)
2. create_mcp（可附带 tools）或 update_mcp；只改工具行用 replace_mcp_tools
3. 需要时 list_mcp_versions 查看历史提交
4. validate_mcp → publish_mcp（必填 recommendedVersion + submitNote）
5. 审核中可用 withdraw_mcp

广场浏览：search_mcps → get_mcp(mcpSlug)。

工具清单（提示词）

| 工具 | 副作用 | 说明 | |------|--------|------| | whoami | read | 连通性与工作空间摘要 | | list_prompts | read | 分页列出我的 Prompt（支持 keyword） | | get_prompt | read | Prompt 详情（正文 / 变量 / 版本） | | create_prompt | write | 创建 Prompt | | update_prompt | write | 更新；upgrade=true 另存新版本 | | delete_prompt | write | 删除 | | list_prompt_versions | read | 历史版本 | | list_prompt_runs | read | 试跑历史 | | restore_prompt_version | write | 恢复指定版本 | | save_prompt_variables | write | 覆盖变量定义 | | run_prompt | write | 非流式试跑 | | list_prompt_models | read | 可用模型 | | optimize_prompt | write | AI 生成 / 优化正文 | | suggest_prompt_meta | read | 建议发布分类 / 标签 / 简介 | | publish_prompt | write | 发布到目录 / 提示词广场（支持 tagIds / tags） |

工具清单（Skill）

| 工具 | 副作用 | 说明 | |------|--------|------| | search_skills | read | 检索技能广场已发布 Skill（官方置顶） | | get_skill | read | 读已发布包（skillSlug）或当前用户草稿（skillId） | | list_my_skills | read | 列出 SkillIDE 草稿；支持 keyword / reviewStatus | | import_skill | write | 一次导入整棵文本文件树为草稿（不投稿） | | create_skill | write | 创建草稿，默认带 SKILL.md 模板 | | update_skill | write | 更新草稿元数据 | | upsert_skill_file | write | 写入或覆盖草稿文本文件 | | delete_skill_file | write | 删除草稿文件（不能删 SKILL.md） | | validate_skill | read | 校验 frontmatter / slug / 文件树 | | publish_skill | write | 提交审核，管理端通过后上架 | | withdraw_skill | write | 撤回审核中的投稿 | | delete_skill | write | 删除草稿 |

工具清单（社区 MCP）

| 工具 | 副作用 | 说明 | |------|--------|------| | search_mcps | read | 检索 MCP 广场已发布卡片 | | list_my_mcps | read | 列出社区 MCP 草稿；支持 keyword / reviewStatus | | get_mcp | read | 草稿（mcpId）或广场已发布详情（mcpSlug） | | create_mcp | write | 创建草稿，可附带 tools | | update_mcp | write | 更新草稿元数据 / tools | | replace_mcp_tools | write | 全量替换工具行，不改文案 | | list_mcp_versions | read | 历史提交版本 | | delete_mcp | write | 删除草稿 | | validate_mcp | read | 投稿前校验 | | publish_mcp | write | 提交审核（后端 /mcps/{id}/submit） | | withdraw_mcp | write | 撤回审核中的投稿 |

后端路径前缀：/internal/mcp/v1/*。与 Web PromptIDE / SkillIDE / MCP IDE 同一数据源。