@wumingfei/poster-mcp

基于 Node.js 与 Model Context Protocol 的海报模板 MCP 服务：先用 list_templates 浏览索引中的基础字段（与 templates.json 一致，不含内部文件名），再按需用 get_template_detail 按 templateId 拉取正文，减少无效 token。

npm 包名：@wumingfei/poster-mcp；命令行入口（bin）：poster-mcp。

功能概览

• 传输方式：默认 stdio（本地接入 Cursor、Claude Desktop 等）；可选 Streamable HTTP（需 URL 的托管场景，如部分云平台 / 魔搭侧配置）。
• 工具：
  • list_templates：返回索引中的全部模板基础信息，按 id 排序；不做筛选。单条字段与源数据一致（id 及可选的 description、topic、style、theme、category），不包含 schemaFile（该字段仅服务内部解析）。
  • get_template_detail：按 templateId 读取 template/ 下由索引指向的文件。扩展名为 .json 时解析为 JSON 并放在 body.jsonSchema；否则整文件作为 Markdown 放在 body.markdown。响应中的模板对象不包含 schemaFile。
• 数据：根目录 templates.json 为索引；索引中的 schemaFile 仅用于服务端定位 template/ 下的文件，不通过 MCP 对外返回。

目录与数据约定

| 路径 | 说明 | |------|------| | templates.json | 模板索引（version + templates 数组） | | template/ | 模板文件目录，由索引中的 schemaFile（相对路径）引用 |

索引中单条模板须包含：id、schemaFile；可选字段如 description、topic、style、theme、category 会原样出现在 list_templates 结果中。

MCP 工具说明

list_templates

无参数。

返回（同时出现在结构化输出与 content[].text 的 JSON 字符串中）：

• total：模板条数
• templates：{ id, description?, topic?, style?, theme?, category? }[]（均为索引中的基础字段，无 schemaFile）

get_template_detail

| 参数 | 说明 | |------|------| | templateId | 必填；与 list_templates 返回的 id 一致 |

返回：

• 未找到模板：无 template 字段；含 message 与 code: "TEMPLATE_NOT_FOUND"
• 找到：{ template: { id, description?, body } }（无 code / message 表示正文加载成功）
• 找到但正文读取或 JSON 解析失败：{ template: { id, description?, body }, message, code: "TEMPLATE_BODY_LOAD_FAILED" }（body 为占位：JSON 时 jsonSchema 可为 null，Markdown 时可为空字符串）

body 为判别联合：format: "json" 时含 jsonSchema；format: "markdown" 时含 markdown 全文。

环境变量

| 变量 | 说明 | |------|------| | MCP_TRANSPORT | stdio（默认）或 http | | MCP_PORT | HTTP 模式监听端口，默认 3000 | | MCP_HOST | HTTP 模式监听地址，默认 127.0.0.1；公网部署时可设为 0.0.0.0 | | POSTER_MCP_ROOT | 可选，覆盖数据根目录（需包含 templates.json 与 template/）；未设置时以可执行文件所在包根目录为准，便于 npx 安装后解析路径 |

开发与构建

要求：Node.js ≥ 18。

pnpm install
pnpm run build

prepublishOnly 会执行 tsc，发布 npm 包前需能成功构建。

项目根目录 .npmrc 将 安装依赖 默认指向 npmmirror 镜像；发布 由 package.json 中的 publishConfig.registry 固定为 https://registry.npmjs.org/，与安装镜像互不干扰。

发布到 npm（官方源）

1. 在 官方注册表 完成登录（勿把密码或 token 写进仓库文件；可使用交互式登录或仅存在于本机 ~/.npmrc / CI 密钥中的 token）：

   npm login --registry https://registry.npmjs.org/

2. 构建与发布（任选其一，均会尊重 publishConfig）：

   npm publish
   # 或
   pnpm publish

运行

stdio（默认）

pnpm start
# 或
node dist/index.js

Streamable HTTP

pnpm run start:http
# 等价于 MCP_TRANSPORT=http node dist/index.js

HTTP 模式下服务地址形如：http://<MCP_HOST>:<MCP_PORT>/mcp。

在 MCP 客户端中配置示例

本地 stdio（已发布包）

{
  "mcpServers": {
    "poster-mcp": {
      "command": "npx",
      "args": ["-y", "@wumingfei/poster-mcp"]
    }
  }
}

本地开发：在 pnpm run build 之后可用 node dist/index.js；通过包管理器安装后，客户端也可将启动命令设为全局/本地的 poster-mcp（由 bin 暴露）。

HTTP

在支持 Streamable HTTP URL 的客户端中填写上述 /mcp 地址（需网络可达）。

魔搭（ModelScope）与发布说明

• 本地 / npx：将包发布到 npm 后，多数客户端按上节方式配置 command + args 即可。
• 需托管 URL：使用本服务的 MCP_TRANSPORT=http 部署到可访问的节点或容器，将平台要求的 MCP 可访问 URL 填为 http(s)://主机:端口/mcp；平台具体表单项以魔搭当前文档为准。

自检

pnpm run build
pnpm run smoke

smoke 会子进程启动 stdio 服务并调用 list_templates、get_template_detail（含一次不存在的 templateId 以校验 message / code）做端到端校验。

许可证

MIT