loongclaw-devkit 0.6.0

LoongClaw MCP 开发者工具包 — 创建、加密、打包、发布、下架/重新上架 MCP 插件

LoongClaw DevKit — MCP 插件开发完整指南

目标读者：想开发 LoongClaw MCP 插件的开发者

MCP 插件开发者工具包。一键创建、加密打包、发布 MCP 插件到 LoongClaw 商店。

---

目录

1. 5 分钟上手
2. 一个合格的 MCP 插件长什么样
3. DevKit 提供的五个工具
4. manifest.json 完整字段速查表
5. configFields — 让用户填 API Key
6. postInstallCommands — 需要浏览器/字体/模型时怎么办
7. Python 版本与依赖策略
8. 加密发布（Cython 自动编译）
9. 商店访问控制（public / private）
10. 付费/授权模式如何落地
11. 更新与增量发布
12. 在其他 AI 客户端中使用
13. 常见报错 FAQ
14. 参考代码：duanju-mcp 实战样例
15. 附录

---

1. 5 分钟上手

1.1 什么是 LoongClaw MCP 插件

MCP（Model Context Protocol，模型上下文协议）是 Anthropic 提出的标准，让 AI 能调用外部工具。LoongClaw MCP 插件 = 一个独立的 Python 程序，按 MCP 协议暴露工具给 LoongClaw 桌面客户端里的 AI 调用。

类比：AI 就像一个刚入职的新员工，MCP 插件就是你给他的一本「操作手册」——上面写明这个员工可以用哪些工具、每个工具怎么用、参数有哪些。AI 看完手册就知道「原来我能查短剧库、发布视频、下载素材」。

1.2 DevKit 是什么

loongclaw-devkit 是一个本身也是 MCP 插件的工具包。安装后，你的 AI 助手（LoongClaw、Claude Desktop、Cursor）会多出 5 个工具：

• create_mcp_project — 一句话生成项目骨架
• publish_mcp — 一键加密 + 打包 + 上传
• unpublish_mcp — 下架自己发布的插件（软下架，不影响已安装用户）
• republish_mcp — 重新上架之前下架的插件
• check_mcp_status — 查看已发布状态

一句话：你让 AI 干活，AI 让 DevKit 干活。 你不用记任何命令。

1.3 安装

推荐使用 uvx（零安装直接运行）：

uvx loongclaw-devkit

或用 pip 安装：

pip install loongclaw-devkit

在 LoongClaw 客户端里直接搜索 loongclaw-devkit 一键安装即可，不需要命令行。在 Claude Desktop / Cursor / VS Code 中使用，见第 12 章。

1.4 三句话产出一个插件

在 LoongClaw / Claude Desktop 里直接对 AI 说：

你："帮我在 ~/projects/weather-mcp 创建一个 MCP 插件，ID 叫 weather-mcp，功能是查天气"

AI 调用 create_mcp_project 生成骨架。

你："在 server.py 里加一个工具，接收城市名，返回今天天气"

AI 编辑代码。

你："发布到 LoongClaw 商店"

AI 调用 publish_mcp 完成加密、打包、上传。

就这样。

---

2. 一个合格的 MCP 插件长什么样

这一章是所有 MCP 开发者都要懂的基础——不管你用不用 DevKit。

2.1 最小可运行结构

weather-mcp/
├── server.py            ← MCP 入口（FastMCP 实例 + 工具注册）
├── requirements.txt     ← Python 依赖
└── .publish.json        ← DevKit 发布配置（DevKit 自动生成骨架，access 字段必须你/AI 手动填 public 或 private）

server.py 模板：

#!/usr/bin/env python3
"""weather-mcp — 天气查询插件"""

from mcp.server.fastmcp import FastMCP

mcp = FastMCP(
    "weather-mcp",
    instructions="提供全球城市天气查询能力。"
)

@mcp.tool()
def get_weather(city: str) -> str:
    """查询指定城市今天的天气。

    Args:
        city: 城市名（中文或英文均可，如 "北京" / "Tokyo"）
    """
    # ... 你的业务逻辑
    return f"{city}: 晴，25°C"

if __name__ == "__main__":
    mcp.run(transport="stdio")

requirements.txt：

mcp>=0.4.0
requests>=2.31.0

就这样。一个合格的 MCP 插件 = FastMCP 实例 + 若干 @mcp.tool() 装饰的函数 + stdio transport 启动。

2.2 三个必知原则

原则一：工具名禁止加前缀 ⚠️ 这是第一大坑

不要这样写：

# ❌ 错误示范
@mcp.tool()
def mcp__weather__get_weather(city: str) -> str:  # 别加前缀！
    ...

LoongClaw 的 MCP Manager 会自动把你的工具重命名为 mcp__weather-mcp__get_weather（对标 Claude Code 标准）。你手动加前缀 → 双重前缀 → 工具名里会变成 mcp__weather-mcp__mcp__weather__get_weather → AI 根本调不到。

正确做法：工具名只写功能名，如 get_weather、send_message、list_accounts。

代码依据：loongclaw/gateway/mcp/mcp-manager.ts:309 —— const prefixedName = \mcp${PREFIX_SEP}${serverName}${PREFIX_SEP}${mcpTool.name}``

原则二：docstring 决定 AI 用不用你的工具

AI 只看 docstring来决定要不要调这个工具。Docstring 写得烂 = 工具形同虚设。

差的 docstring：

@mcp.tool()
def process(data: str) -> str:
    """处理数据"""  # AI 看了一脸懵：啥数据？怎么处理？

好的 docstring：

@mcp.tool()
def get_weather(city: str, unit: str = "celsius") -> str:
    """查询城市今日天气。支持全球 200+ 城市。

    Args:
        city: 城市名，中文或英文均可（如 "北京" / "Tokyo" / "New York"）
        unit: 温度单位，"celsius" 或 "fahrenheit"，默认 celsius

    Returns:
        JSON 格式字符串，包含 temperature, condition, humidity, wind 四个字段

    Example:
        get_weather("北京") → {"temperature": 25, "condition": "晴", ...}
    """

规则：

• 首句用动词开头，一句话说清楚做什么
• 每个参数都写类型 + 示例
• 有返回结构时用 Returns: 块说明
• 有副作用（写文件、发网络请求、花钱）必须标明

LoongClaw 限制：工具 description 超过 2048 字符会被截断（防止 OpenAPI 自动生成的 60KB 文档撑爆上下文）。

原则三：核心业务逻辑放独立文件

# server.py（入口，明文）
from core import query_weather_api

@mcp.tool()
def get_weather(city: str) -> str:
    return query_weather_api(city)

# core.py（核心逻辑，发布时会被 Cython 加密成 .so/.pyd）
def query_weather_api(city: str) -> str:
    # 你的真正业务逻辑，发布后用户看不到源码
    ...

为什么这样分：server.py 是启动入口，必须明文；其他 .py 文件 DevKit 会自动 Cython 编译加密。详见第 8 章。

---

3. DevKit 提供的五个工具

DevKit 本身是一个 MCP 插件，注册在你的 AI 客户端里。对 AI 暴露 5 个工具：

3.1 create_mcp_project — 创建项目

对 AI 说："创建一个 MCP 插件到 ~/projects/weather-mcp，ID 叫 weather-mcp，功能是天气查询"

幕后做了什么：

1. 在目标目录创建骨架：
   • server.py（填入 ID 和描述的 FastMCP 模板）
   • requirements.txt（含 mcp>=0.4.0）
   • AGENTS.md（给 AI 看的开发规范）
   • publish.py（独立可运行的发布脚本副本）
   • .publish.json（DevKit 配置：ID / 版本 / 访问类型）
2. 返回 next_steps 提示 AI 下一步干什么

代码依据：server.py:34-113（create_mcp_project 工具），模板文件在 src/loongclaw_devkit/templates/

3.2 publish_mcp — 一键发布

对 AI 说："把 ~/projects/weather-mcp 发布到 LoongClaw 商店，版本 1.0.0"

幕后 6 个步骤（全自动）：

步骤	做什么	失败后果
1. 校验项目	检查 server.py 是否有 FastMCP 实例 + mcp.run()、requirements.txt 是否存在	返回错误并给修复建议
2. 检测跨平台风险	扫 requirements.txt，警告 greenlet==X.Y.Z 等严格锁版（Windows 可能装不上）	警告但不中断
3. Cython 加密	除 server.py/publish.py/__init__.py/setup.py 外，所有 .py 编译成 .so/.pyd	某文件编译失败 → 回退明文 + 打日志
4. 离线 wheel 打包	根据 requirements.txt 下载所有依赖到 _vendor/（用户无网也能装）	默认 PyPI 失败 → 自动重试清华镜像
5. 打 zip	明文 + .so + _vendor/ → project.zip（排除 __pycache__ / .venv / 上次残留的 project.zip）	—
6. 生成 manifest + 上传	算每个文件的 SHA-256 + zip 整体 SHA-256，组装 manifest.json，上传到 Cloud API	缺 Store Key → 报错并提示申请地址

代码依据：publish.py（单文件 ~780 行，涵盖全部 6 步）

不用 DevKit 也能跑：create_mcp_project 会把 publish.py 复制到你的项目里。你之后可以直接 cd ~/projects/weather-mcp && python publish.py 走交互式发布，不依赖 DevKit。

3.3 check_mcp_status — 查状态

对 AI 说："查下 weather-mcp 现在商店里是什么版本"

幕后做了什么：从 Cloud 拉 registry.json，对比本地 .publish.json 的版本号，告诉你是否需要 bump version。

3.4 unpublish_mcp — 下架自己发布的插件

对 AI 说："我的 weather-mcp 有严重 bug，先下架"

幕后做了什么：调用 Cloud 的 POST /v1/store/unpublish，服务端校验「当前 Store Key 的 userId == manifest.uploadedBy」才允许操作。下架后：

• 新用户在商店里看不到这个插件
• 已安装的用户不受影响——他们本地已有的代码继续工作（LoongClaw 不会远程禁用用户本地代码，这是用户权益铁律）
• 你之后上传同 id 的新版本不会自动复活——防止带 bug 的旧版本又被重新展示。确认新版本修复了问题后，调用 republish_mcp 才重新上架

参数：plugin_id（必填）、store_type（mcp|skill，默认 mcp）、reason（可选，便于 admin 后续排查）

3.5 republish_mcp — 重新上架

对 AI 说："weather-mcp 新版本 1.2.0 我已经测过了，重新上架"

幕后做了什么：调用 POST /v1/store/republish，把 store_revocations 表里的记录标为 restored，registry 自动刷新后用户就能再次看到。

只能操作你自己发布的插件（uploadedBy 校验），别人的下架不了。

---

4. manifest.json 完整字段速查表

DevKit 发布时会自动生成 manifest.json，你一般不用手写。但你得懂里面每个字段在 LoongClaw 客户端对应什么行为——调试 bug 时就靠它。

字段	类型	必填	作用
id	string	✅	插件唯一 ID。仅允许 [a-zA-Z0-9_-]，长度 ≤100。DevKit 从 .publish.json 读取
name	string	✅	显示名（用户在商店看到的）
description	string	✅	插件描述，AI 选择插件时会读这个
version	string	✅	语义版本号（如 1.0.0）。LoongClaw 通过字符串比较判断「是否有更新」
author	string	✅	作者名
icon	string	✅	emoji 或 URL
runtime	string	✅	目前仅支持 "python"（"node" 类型定义里预留但未落地）
entrypoint	string	✅	入口文件，始终 "server.py"
files	object	✅	新格式：{ "文件相对路径": { "hash": "SHA-256", "size": 字节数 } }。用于增量更新判断
sourceArchive	string	✅	zip 文件名，DevKit 统一为 "project.zip"
sourceArchiveHash	string	✅	zip 整体 SHA-256。增量更新的关键判断依据（见第 11 章）
env	object	❌	默认环境变量（用户可在客户端 UI 覆盖）
configFields	array	❌	用户可填的配置项，见第 5 章
postInstallCommands	string[][]	❌	pip install 后执行的命令，见第 6 章
requiredPython	string	❌	Python 版本约束，见第 7 章
replaces	string[]	❌	替代的内置工具组名（安装后自动隐藏，避免 UI 重复）
companionSkill	string	❌	配套 Skill 名（前端用于关联提示）
accessType	"public" | "private"	✅	访问控制，见第 9 章。必填，无默认值；Cloud 白名单拒绝任何非法值，DevKit publish.py 上传前本地预校验拦截
mcp	object	❌	MCP 标准字段（transport/command/args）。填了会优先于自动推导

代码依据：store-types.ts —— StoreManifest 接口（约第 57 行起）

Cloud 端额外自动注入的字段（你不用写）：

• uploadedBy — 上传者的 userId，用于防止他人覆盖你的插件（所有权校验）
• uploadedAt — 上传时间

---

5. configFields — 让用户填 API Key

5.1 场景

你的天气插件需要调和风天气 API，用户得先去注册账号拿自己的 Key。你不能把 Key 硬编码进代码（那是你的 Key，用户用你的额度）。

5.2 声明方式

在 server.py 里直接写 os.environ.get("HEFENG_API_KEY", "")，DevKit 的 publish.py 会自动扫描并生成 configFields！

import os

HEFENG_API_KEY = os.environ.get("HEFENG_API_KEY", "")  # DevKit 自动识别
HEFENG_UNIT    = os.environ.get("HEFENG_UNIT", "celsius")

生成的 manifest 里：

{
  "configFields": [
    { "key": "HEFENG_API_KEY", "label": "Hefeng Api Key", "default": "", "required": true },
    { "key": "HEFENG_UNIT",    "label": "Hefeng Unit",    "default": "celsius", "required": false }
  ]
}

规则：无默认值 → required: true；有默认值 → required: false。

代码依据：publish.py:372 —— re.finditer(r'os\.environ\.get\(...)

5.3 手动覆盖（密码类型）

自动生成的字段是纯文本输入框。如果字段是密码/API Key，你想让 UI 打码显示，可以在发布后手动编辑 .publish.json 或用参数重新发布。或者直接在 publish_mcp 后，让 AI 帮你改 manifest。

手动编辑时加 "type": "password"：

{ "key": "HEFENG_API_KEY", "label": "和风天气 API Key", "type": "password", "required": true }

5.4 用户视角

用户在 LoongClaw 商店点「安装」→ 弹出填写表单 → 用户填完 → 客户端把值以环境变量形式注入你的 Python 进程。你在 server.py 里 os.environ.get(...) 直接拿到。

---

6. postInstallCommands — 需要浏览器/字体/模型时怎么办

6.1 场景

playwright 需要下载 Chromium；transformers 需要拉模型权重；matplotlib 需要装中文字体。这些不能靠 pip install 解决，必须在安装完依赖之后跑额外命令。

6.2 写法

在 .publish.json 里加一项（或让 AI 帮你改 manifest）：

{
  "postInstallCommands": [
    ["python", "-m", "playwright", "install", "chromium"],
    ["python", "-m", "nltk.downloader", "punkt"]
  ]
}

每个元素是一个命令数组（不是字符串，防 shell 注入）。LoongClaw 客户端会在 pip install 完成后逐个执行。

6.3 特殊处理

命令数组里如果第一个元素是 "python"，客户端自动替换为 venv 内的 Python 路径（Windows 是 venv\Scripts\python.exe，Unix 是 venv/bin/python）。你不用关心跨平台。

---

7. Python 版本与依赖策略

7.1 requiredPython 版本范围

{ "requiredPython": ">=3.10,<3.13" }

解析规则：

• 语法：op major.minor[,op major.minor]，op 支持 >= > <= < ==
• 不填默认 >=3.10（兼容旧插件）
• 客户端安装时查系统 PATH 里所有 Python，挑第一个符合的
• 都不符合 → 给用户中文错误提示（如"你的 Python 3.9 版本过低，建议安装 3.12"）

代码依据：mcp-store-python.ts:147-210 —— findPython()

7.2 requirements.txt 避坑

第一坑：C 扩展严格锁版

# ❌ 风险
greenlet==2.0.1
# 问题：Windows 用户没 MSVC Build Tools → pip 要源码编译 → 失败

# ✅ 推荐
greenlet>=2.0
# pip 找预编译 wheel，三平台都能装

DevKit publish.py 会扫 requirements.txt，对以下包的严格锁版发出警告： greenlet / numpy / scipy / pandas / lxml / pillow / cryptography / grpcio / psycopg2

代码依据：publish.py:111-135

第二坑：跨平台特定依赖

uvloop 只支持 Linux/macOS，Windows 装不上。用环境标记：

uvloop>=0.17; sys_platform != "win32"

7.3 离线 wheel 机制

DevKit 发布时会提前下载所有 wheel 包到 _vendor/ 目录，打进 project.zip。用户安装时即使无网也能装。

客户端 pip install 时会优先用 _vendor/ 里的 wheel。

---

8. 加密发布（Cython 自动编译）

8.1 为什么要加密

你的核心算法、接入的 API Key 逻辑、独特的数据处理流程……不想被用户直接 cat core.py 看光光。

8.2 DevKit 自动做了什么

发布时自动把除以下白名单外的所有 .py 编译成 .so（macOS/Linux）或 .pyd（Windows）：

白名单（始终保留明文）：

• server.py —— 入口文件，必须明文（Python 识别 FastMCP 装饰器）
• publish.py —— 你的发布脚本
• __init__.py / setup.py —— Python 打包约定

其他所有 .py 都会被加密。流程：

core.py  →  复制为 core.pyx  →  Cython 编译为 core.cpython-312-darwin.so  →  删除 .pyx 和 .c 中间文件

8.3 跨平台

DevKit 只编译当前平台的产物。用户装你的插件时，客户端会在用户机器上重新跑 pip install，但 .so/.pyd 是二进制，不会重新编译。

所以：macOS 开发者发布 → .so 打进 zip → Windows 用户装了 → 缺 .pyd → 报错 ImportError: no such module。

解决方案二选一：

1. 在每个目标平台各跑一次 DevKit 发布，最终 zip 里同时包含 core.cpython-312-darwin.so + core.cp312-win_amd64.pyd + core.cpython-312-x86_64-linux-gnu.so。
2. 不用 Cython：让 AI 从 publish_mcp 的参数里传 skip_encrypt="core.py,utils.py" 保留明文。

DevKit 路线图：未来会加 GitHub Actions 模板一次性跨平台编译。当前阶段建议方案 1。

8.4 ⚠️ 禁忌

• 禁止 把 .pyx 源码上传到商店。DevKit 会自动删除中间文件，但如果你自己手动打包，要确保 zip 里没有 .pyx。
• 禁止 生产发布传 --skip-encrypt 跳过所有加密。该参数仅限本地调试。
• 禁止 把敏感信息（API Key、内部 URL）写死在代码里——就算 .so 也能被逆向工程师用 Ghidra/IDA 看出大概逻辑。敏感信息应用 configFields 让用户填。

---

9. 商店访问控制（public / private）

9.1 两种访问类型

值	谁能下载	使用场景
"public"	所有已登录 LoongClaw 用户	开源插件、免费工具、推广插件
"private"	授权列表内的用户	企业定制、付费插件、内测阶段插件

⚠️ 关键澄清：

1. private 不等于「付费」——它只是「需要授权」。付费模式本身由商务流程处理（付款后把用户加入授权表），商店代码不碰价格。
2. accessType 必填且只能是 "public" 或 "private"。Fail-Close 三层防护（Cloud 安全升级后）：
   • DevKit publish.py 上传前本地预校验：缺失/非法 → 立即退出，不浪费构建时间
   • Cloud /v1/store/upload 入口：白名单拒绝，返回 400 错误
   • Cloud registry 重建时：遗留的未知值降级为 "private"（更安全的默认，不是 public） 任何拼写错误（如 "paid" / "premium"）都会被拒绝上传。

代码依据：store-upload.ts —— ALLOWED_ACCESS_TYPES + validateManifest 严格校验

9.2 DevKit 怎么设

在 .publish.json 里必填：

{ "access": "private" }

create_mcp_project 生成的模板里 access 字段是空字符串（""），并带 ⚠️ 必填 注释——你或 AI 必须显式改为 public 或 private 后才能上传，否则 publish.py 会在本地预校验阶段报错退出。这是有意设计：防止 AI 走神漏填导致插件被默认公开。

也可以发布时让 AI 说："发布 weather-mcp，版本 1.0.0，access 设为 private"；或命令行 python publish.py --auto --access private --version 1.0.0。

9.3 客户端行为

情况	用户体验
public 插件	商店直接「安装」按钮
private 插件，用户已授权	正常安装
private 插件，用户未授权	按钮变灰，提示「此插件需联系客服开通」
private 插件已安装，随后授权被撤销	下次启动时加载失败，UI 提示需重新开通

9.4 授权数据存哪

Cloud 端有个表 mcp_permissions (user_id, mcp_id)。管理员在后台添加记录即开通权限。

下载时校验逻辑：

用户请求下载 private 插件
 → Cloud 查 accessTypeCache（5 分钟 TTL）
 → private → 查 mcp_permissions 表
 → 有记录 → 放行；无记录 → 403

代码依据：store-download.ts:26-45 —— accessTypeCache + 5 分钟 TTL

---

10. 付费/授权模式如何落地

LoongClaw MCP 商店目前的「付费插件」模式：

10.1 流程

1. 开发者发布插件时 accessType: "private"
2. 用户在客户端看到插件 → 点「安装」
3. 客户端调用 Cloud API → 未授权 → 返回 403 + 友好提示
4. 用户看到提示联系客服 / 开发者
5. 商务走完付款流程，管理员在后台 mcp_permissions 表加记录
6. 用户在客户端重试安装 → 通过

10.2 你（开发者）需要做什么

1. 发布时设 access: "private"
2. 提供联系方式（微信/邮箱，在 description 里写清楚）
3. 收款 + 授权（和 LoongClaw 管理员协调，或自己走付款然后通知平台加记录）

10.3 运营方做什么

• 维护 mcp_permissions 表（加/删记录）
• 管理 Store Key 体系（谁能上传插件）
• 提供授权管理后台 UI（规划中）

10.4 不支持的模式（现阶段）

• ❌ 按调用次数计费（客户端不上报调用数据到 Cloud）
• ❌ 订阅制自动扣费（无订阅系统）
• ❌ 零散充值余额兑换（积分和 LLM 余额是分开的）

如需这些模式，请联系 LoongClaw 团队走定制化方案。

---

11. 更新与增量发布

11.1 用户侧的增量更新体验

用户点「更新」时，LoongClaw 并不无脑重新下载。流程：

1. 拉新版 manifest.json
2. 对比 sourceArchiveHash：
   ├─ 相同 → 整个目录从旧版「硬链接」复用（O(1)，零下载，秒更新）
   └─ 不同 → 重新下载 project.zip + 重建 venv
3. 失败自动回滚到旧版

硬链接是什么：类比「快捷方式的升级版」，两个路径指向磁盘同一份数据，不占额外空间，切换比复制快 1000 倍。

失败回滚：旧目录在更新期间先改名 .old，成功才删，失败则改回。用户永远不会遇到「更新一半插件坏掉」。

代码依据：mcp-store.ts:230-370

11.2 开发者要做什么

什么都不用做。 DevKit publish_mcp 每次都会：

1. 重新算 zip 的 SHA-256 → 写入 sourceArchiveHash
2. 代码没变 → zip 相同 → hash 相同 → 用户秒更新
3. 代码变了 → zip 变了 → hash 变了 → 用户重新下载

你只需要 bump version 字段。

11.3 版本号规则

• 建议使用语义版本：主.次.修订（如 1.2.3）
• 客户端判断「是否有更新」用字符串不等（local.version !== entry.version），不做大小比较也不做 semver 解析——任何不相等的版本号都会触发更新，哪怕新版本号「更小」
• 因此每次发布都必须 bump version，否则客户端认为「无更新」；反之只要改了版本号就一定能触发

代码依据：mcp-store.ts:105 / 440 —— local.version !== entry.version

11.4 所有权保护

插件一旦被你上传过，manifest 里会注入 uploadedBy: "你的 userId"。之后别人用自己的 Store Key 上传同 ID 插件会被 403 拒绝——防止恶意覆盖。

代码依据：store-upload.ts:109-130 —— existing.uploadedBy !== userId 拒绝 + 新记录注入 uploadedBy

---

12. 在其他 AI 客户端中使用

12.1 LoongClaw 桌面客户端

在 MCP 商店中搜索 loongclaw-devkit 一键安装。

12.2 Claude Desktop / Cursor / VS Code

在 MCP 配置文件中添加：

{
  "mcpServers": {
    "loongclaw-devkit": {
      "command": "uvx",
      "args": ["loongclaw-devkit"]
    }
  }
}

12.3 命令行直接使用

也可以不通过 AI，直接命令行运行：

# 启动 MCP server（开发调试用）
loongclaw-devkit

# 或用 Python 模块方式
python -m loongclaw_devkit

---

13. 常见报错 FAQ

Q1. 安装后工具不可用，AI 说「不知道有这个工具」

症结：工具名双重前缀（第 2.2 节原则一）。

检查：

grep "def mcp__" server.py  # 应该没有任何匹配

修正：去掉所有以 mcp__ 开头的函数名，只写功能名。

Q2. publish_mcp 报 LOONGCLAW_STORE_KEY 缺失

# 方式 1：环境变量
export LOONGCLAW_STORE_KEY="lc-store-xxxxx"

# 方式 2：.publish.json
{ "token": "lc-store-xxxxx" }

Store Key 获取：loongclaw.net.cn/dev/ 登录 → 申请开发者 → 审批通过 → 生成 Store Key。

Q3. 上传被拒 无权更新此插件（不是原上传者）

原因：你的 Store Key 对应的 userId ≠ 插件第一次上传时的 userId（manifest 里的 uploadedBy）。

解决：

• 用原 userId 的 Store Key 上传
• 或换个 id（改 .publish.json 里的 id 字段）
• 或联系管理员清掉旧所有权

Q4. Cython 编译失败，某个 .py 没被加密

DevKit 的行为：编译失败 → 自动回退为明文 + 打日志，不中断发布。

常见原因：

• macOS 缺 Xcode CLI：xcode-select --install
• Windows 缺 MSVC Build Tools：装 Visual Studio Build Tools 或从 python.org 装 Python（自带）

临时方案：传 skip_encrypt="core.py" 显式跳过该文件（生产发布前修好编译环境再重发）。

Q5. Windows 用户装不上，报 C 扩展编译错误

99% 原因：requirements.txt 里有严格锁版的 C 扩展（numpy==1.24.0 等），Windows 没预编译 wheel。

解决：改成 >= 宽松版本：

# 改之前
numpy==1.24.0

# 改之后
numpy>=1.24,<2.0

Q6. configFields 没有被自动识别

DevKit 靠正则扫 os.environ.get("KEY", "default")。以下写法不会被识别：

# ❌ 不识别
k = "MY_KEY"
v = os.environ.get(k, "")

# ❌ 不识别（非字符串字面量）
v = os.environ.get(MY_CONST)

# ✅ 识别
v = os.environ.get("MY_KEY", "")

实在不行，手动改 manifest.json（让 AI 帮你改，然后重新上传）。

Q7. 更新了代码但用户客户端说「无更新」

可能原因：

1. 没 bump version（最常见）
2. Cloud registry 更新失败（上传返回 ok 但 registry 没同步，5 分钟内缓存过期）
3. 用户客户端缓存（重启客户端）

排查：

# 查 Cloud registry 最新版本
curl https://api.loongclaw.net.cn/v1/store/mcp/registry.json | jq '.servers[] | select(.id == "your-id")'

Q8. 本地测试 python server.py 正常，上传后装不起来

常见原因：

• requirements.txt 漏了运行时依赖（你本地 venv 有但 requirements 里没写）
• _vendor/ wheel 下载失败（检查 publish.py 输出的警告）
• 用了相对路径导入 __file__ 的资源，但 zip 解压层级错了

排查：解压 project.zip 手动 pip install -r requirements.txt && python server.py 跑一遍。

Q9. 发布报 .publish.json 缺少必填字段 / 字段 access 必填且只能是 ['private', 'public']

原因：v0.6.0 起 publish.py 在上传前本地预校验 id / name / description / version / author / access 六个字段，缺任何一个或 access 不在白名单内 → 立即退出。

修法：编辑 .publish.json 补全字段：

{
  "id": "weather-mcp",
  "name": "和风天气插件",
  "description": "查询全球城市天气，支持中英文城市名（≥10 字符）",
  "version": "1.0.0",
  "author": "你的名字",
  "access": "public"
}

或用 python publish.py --reconfigure 重新走交互式配置。

为什么这么严：2026-04-22 发生过「5 个 MCP 上传后全被标成 public 可免费下载」的事故，根因是旧版本对 access 字段有默认降级 fallback。修复后本地 + Cloud 双层拦截，宁可报错也不静默默认。

---

14. 参考代码：duanju-mcp 实战样例

duanju-mcp 是短剧自动发布插件，LoongClaw 内部使用，是一个复杂场景样例。

关键看点：

1. 多模块拆分：mcp_server.py 作为入口，逻辑分散在 mcp_preflight_tools.py / mcp_query_tools.py / mcp_pipeline_tools.py
2. configFields 复杂用法：比特浏览器端口、发布路径等 15+ 配置项
3. postInstallCommands：装 Playwright Chromium
4. companionSkill：关联 duanju-full-pipeline-executor Skill

建议当作写复杂插件时的参考——结构清晰、分层合理。

---

15. 附录

附录 A：DevKit 命令行参数（高级用法）

DevKit 除了通过 AI 调用，也可以直接命令行用：

# 启动 DevKit 自己作为 MCP server（调试用）
loongclaw-devkit

# 或：直接跑项目里的 publish.py（DevKit 会把它复制到你的项目）
cd ~/projects/weather-mcp
python publish.py                             # 交互模式（人类友好）
python publish.py --auto --version 1.0.1      # 自动模式
python publish.py --auto --access private --version 1.0.1  # 同时改 access
python publish.py --auto --no-upload          # 只打包不上传
python publish.py --auto --skip-encrypt "a.py,b.py"  # 指定文件不加密
python publish.py --reconfigure               # 重新走交互式配置（修 .publish.json）

--access 只接受 public / private，其他值 argparse 直接拒绝。

附录 B：Store Key 申请流程

1. 访问 loongclaw.net.cn/dev/ 登录
2. 提交开发者申请（填个人/公司信息、开发目的）
3. 等待管理员审批（通常 1 个工作日）
4. 审批通过后生成 Store Key（形如 lc-store-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx）
5. 配置到环境变量或 .publish.json

⚠️ Store Key 保管：

• 不要上传到 Git（.publish.json 默认在 .gitignore 里的话 OK；否则用环境变量）
• 泄露后立即到开发者中心吊销 + 重新生成

附录 C：调试技巧

本地测试 MCP server（不发布）：

cd ~/projects/weather-mcp

# 方式 1：直接跑（会等待 stdin）
python server.py
# 输入 JSON-RPC 请求（高级用户）

# 方式 2：MCP Inspector（可视化调试）
npx @modelcontextprotocol/inspector python server.py
# 浏览器打开 http://localhost:5173 图形化调工具

装到 LoongClaw 本地调试（不过 Cloud）：

编辑 ~/.loongclaw/mcp-servers.json，手动加一项：

{
  "servers": [
    {
      "name": "weather-mcp-dev",
      "command": "python",
      "args": ["/Users/you/projects/weather-mcp/server.py"],
      "env": { "HEFENG_API_KEY": "..." }
    }
  ]
}

重启 LoongClaw 即生效。这种方式不走商店，不需要上传。

附录 D：能力边界速查

能力	DevKit 支持？	备注
FastMCP + stdio	✅	核心
HTTP/SSE transport	❌	未来支持
Cython 加密 .py	✅	自动
离线 wheel 打包	✅	自动
增量更新	✅	对开发者透明
configFields 自动生成	✅	扫 os.environ.get
多 Python 版本约束	✅	requiredPython
postInstallCommands	✅	manifest 字段
Private 授权	✅	accessType: private
跨平台一次性编译	⚠️	需各平台各发一次
Node.js runtime	❌	类型定义预留，未落地
按调用计费	❌	不支持
MCP Resources / Prompts	⚠️	FastMCP 原生支持，但 LoongClaw 当前主要消费 tools

---

License

MIT

---

文档结束。 有问题？到 LoongClaw 开发者中心 反馈。