twx-mcp

通过 Model Context Protocol（stdio） 调用本仓库 Nest 公开接口，读取组件库全站公开块：按分类计数、分页列表、单条详情（含 code）。不限于当前登录用户，无需 JWT。

运行时：Node.js 20+，使用 npm 安装与构建。

对应后端路由（无需 Authorization）：

• GET /web-published-components/public?category=…&page=…&pageSize=…&q=…&sort=…&authorId=…
• GET /web-published-components/public/:id

分类与创建组件时一致：hero | features | pricing | footer | bento。列表仅包含 visibility=public 的条目。

环境变量

| 变量 | 说明 | |------|------| | TW_API_BASE_URL | API 根地址，默认 http://127.0.0.1:4000 |

复制 .env.example 为 .env 按需覆盖 TW_API_BASE_URL（.env 勿提交 git）。

本地开发（仓库内）

cd packages/twx-mcp
npm install
npm run build
TW_API_BASE_URL='http://127.0.0.1:4000' npm start

源码结构（src/）

| 路径 | 说明 | |------|------| | http/public-blocks-api.ts | 公开组件 HTTP 客户端（列表 / 详情 / 分类计数） | | schemas/block-tools.ts | Zod：categorySchema、sortSchema、各 tool 的 inputSchema | | lib/mcp-text.ts | jsonText、summarizeBlock | | tools/*.ts | 各 MCP tool 的 register*Tool | | tools/register-tools.ts | 汇总注册全部 tools | | index.ts | 入口：McpServer（name: "twx-mcp"）+ stdio transport |

• npm run check：仅类型检查（不产出 dist）。
• npm run build：编译到 dist/（全局安装与本地 node 启动均依赖此步骤；发布前 npm pack / npm publish 会通过 prepack 自动执行）。

发布到 npm

1. 在 package.json 中按需填写 author、repository（可选），确认 name / version；若包名已被占用，可改为作用域包如 @你的用户名/twx-mcp 并增加：

   "publishConfig": { "access": "public" }

2. 登录并发布：

   cd packages/twx-mcp
   npm login
   npm publish

   作用域包：npm publish --access public

3. 安装方使用全局命令（需本机 node 在 PATH 中）：

   npm install -g twx-mcp

   或每次用 npx：

   npx twx-mcp

在 Cursor 里注册 MCP

方式 A：全局安装后用命令名（推荐，发布后）

{
  "mcpServers": {
    "twx": {
      "command": "twx-mcp",
      "args": [],
      "env": {
        "TW_API_BASE_URL": "http://127.0.0.1:4000"
      }
    }
  }
}

若 Cursor 找不到全局 bin，可写 command 为 npx、"args": ["-y", "twx-mcp"]（或带版本 [email protected]）。

方式 B：显式 node + cwd

{
  "mcpServers": {
    "twx": {
      "command": "node",
      "args": ["./dist/index.js"],
      "cwd": "/你的路径/tw/packages/twx-mcp",
      "env": {
        "TW_API_BASE_URL": "http://127.0.0.1:4000"
      }
    }
  }
}

cwd 必须指向本包目录，且该目录下已存在 dist/index.js（先执行 npm run build）。

方式 C：node + 入口绝对路径（可不设 cwd）

{
  "command": "node",
  "args": ["/你的路径/tw/packages/twx-mcp/dist/index.js"],
  "env": { "TW_API_BASE_URL": "http://127.0.0.1:4000" }
}

提供的 Tools

| 名称 | 作用 | |------|------| | twx_block_categories | 各分类下全站公开块数量 + totalAll | | twx_list_blocks | 分页列表（摘要，不含 code）；支持 authorId 筛作者 | | twx_get_block | 按 id 拉公开块完整字段（含 code、作者摘要等） |

（旧工具名 tw_block_* / tw_my_block_* 已废弃，请使用上表名称。）