@hun-dun/markdown-to-html-mcp

项目简介

本项目基于 modelcontextprotocol/typescript-sdk 实现 Markdown 转 HTML 的 MCP 服务端，支持 npx/全局命令一键启动、远程 HTTP/Streamable HTTP 调用，并可被 Cursor 等 MCP 客户端直接调用。

特性

• 支持 ESM/CJS 双产物，适配多种 Node.js 环境
• 一键 npx/全局命令启动（stdio）
• 支持 HTTP/Streamable HTTP 服务
• 结构现代，类型安全，源码位于 src/，产物位于 dist/（ESM）和 dist-cjs/（CJS）
• bin/主入口均指向 CJS 产物，兼容性强
• 可被 Cursor、curl、代码等多种方式远程调用

快速开始

安装依赖

npm install

构建产物

npm run build

本地启动（stdio）

npx ts-node src/cli.ts
# 或
npm run start

启动 HTTP 服务

npx ts-node src/cli.ts --http
# 或
node dist-cjs/cli.js --http

作为全局命令/被 Cursor 调用

npx @hun-dun/markdown-to-html-mcp
# 或
markdown-to-html-mcp

远程 HTTP/Streamable HTTP 调用

curl -X POST http://localhost:3000/mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{"tool":"markdownToHtml","input":{"markdown":"# Hello"}}'

ESM/CJS 产物说明

• ESM 产物位于 dist/，入口 dist/index.js
• CJS 产物位于 dist-cjs/，入口 dist-cjs/index.js
• bin/主入口均指向 CJS 产物，兼容 npx/全局命令

MCP 工具注册与调用

• registerMarkdownToHtmlTool(server) 注册 markdownToHtml 工具，参数为 markdown，返回 HTML。
• CLI 支持 stdio 和 HTTP 两种模式。

在 Cursor 中调用

本工具可直接集成到 Cursor，支持本地（stdio）和远程（http）两种方式：

方式一：本地调用（stdio，推荐本地开发/临时调用）

在 .cursor/config.json 中添加如下配置：

{
  "mcp": [
    {
      "name": "@hun-dun/markdown-to-html-mcp (本地 npx)",
      "type": "stdio",
      "command": "npx",
      "args": ["@hun-dun/markdown-to-html-mcp"]
    }
  ]
}

• Cursor 会自动用 npx 下载并调用你的包，适合本地/临时场景。
• 不需要你手动启动服务端。
• 结果会直接在 Cursor 工具面板中展示。

方式二：远程调用（http，推荐云端/团队共享）

1. 启动 HTTP 服务：

   npx @hun-dun/markdown-to-html-mcp --http
   # 或 PORT=8080 npx @hun-dun/markdown-to-html-mcp --http

2. 在 .cursor/config.json 中添加如下配置：

{
  "mcp": [
    {
      "name": "@hun-dun/markdown-to-html-mcp (remote)",
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  ]
}

• 适合你用 npx @hun-dun/markdown-to-html-mcp --http 启动服务后，供多台机器/团队成员/云端调用。
• 结果会直接在 Cursor 工具面板中展示。

常见问题

• ts-node 运行 .ts 文件报 "Unknown file extension .ts"——需加 --loader ts-node/esm
• node 运行 dist/index.js 报 "exports is not defined in ES module scope"——需用 CommonJS 产物并移除 package.json 的 "type": "module"，或用 .cjs 后缀
• StreamableHTTPServerTransport 构造参数报错，需根据 SDK 版本传递正确 options

适用场景

• 本地开发、测试
• 远程 HTTP/Streamable HTTP 服务
• Cursor、MCP 客户端一键集成
• 代码/脚本/命令行调用

License

MIT