5.2 KiB

Raw Blame History

MCP Swagger Server CLI 工具发布改进计划

🎯 总体评估

当前状态: ✅ 可以发布，但需要关键配置调整

mcp-swagger-server 项目已经具备了完整的 CLI 功能实现，包括：

完善的命令行参数解析
多种传输协议支持 (stdio, http, sse, streamable)
文件监控和自动重载
进程管理和自动重启
环境变量配置支持

但要作为 NPM CLI 工具发布，还需要完成以下关键配置。

🔧 必需改进 (发布前必须完成)

1. 添加 `bin` 字段配置

问题: 缺少 NPM CLI 工具的核心配置

解决方案: 在 packages/mcp-swagger-server/package.json 中添加：

{
  "bin": {
    "mcp-swagger-server": "./dist/cli.js",
    "mcp-swagger": "./dist/cli.js"
  }
}

2. 确保 CLI 文件可执行

问题: 编译后的 CLI 文件需要 shebang 和执行权限

解决方案:

确保 src/cli.ts 顶部有 #!/usr/bin/env node
构建后验证 dist/cli.js 的 shebang 完整性

3. 调整 package.json 发布配置

当前配置:

{
  "main": "dist/index.js",
  "scripts": {
    "start": "node dist/index.js"
  }
}

建议改进:

{
  "main": "dist/index.js",
  "types": "dist/types/index.d.ts",
  "bin": {
    "mcp-swagger-server": "./dist/cli.js",
    "mcp-swagger": "./dist/cli.js"
  },
  "files": [
    "dist/**/*",
    "!dist/**/*.map",
    "README.md"
  ],
  "engines": {
    "node": ">=16.0.0"
  },
  "publishConfig": {
    "access": "public"
  }
}

4. 创建 README.md

问题: 缺少包级别的 README 文档

解决方案: 在 packages/mcp-swagger-server/ 创建 README.md

🚀 发布准备步骤

步骤 1: 配置调整

# 1. 修改 package.json 添加 bin 字段
# 2. 确保 TypeScript 编译正确
# 3. 验证 dist 目录结构

步骤 2: 构建验证

# 清理重建
cd packages/mcp-swagger-server
pnpm run build

# 检查编译产物
ls -la dist/
cat dist/cli.js | head -1  # 应该显示 #!/usr/bin/env node

步骤 3: 本地测试

# 打包测试
npm pack

# 临时安装测试
npm install -g ./mcp-swagger-server-1.0.0.tgz

# 测试命令
mcp-swagger-server --help
mcp-swagger --help

# 功能测试
mcp-swagger-server --transport stdio --openapi https://petstore.swagger.io/v2/swagger.json

步骤 4: 发布

# 登录 NPM
npm login

# 发布
npm publish

# 验证发布
npm info mcp-swagger-server

📈 发布后使用流程

全局安装使用

# 用户安装
npm install -g mcp-swagger-server

# 直接使用
mcp-swagger-server --transport streamable --port 3322 --openapi https://api.github.com/openapi.json

# 查看帮助
mcp-swagger-server --help

项目依赖使用

# 项目中安装
npm install mcp-swagger-server

# 编程式使用
const { createMcpServer } = require('mcp-swagger-server');

🔄 后续改进计划

短期改进 (v1.1.0)

配置文件支持

# 支持 .mcprc.json 配置文件
mcp-swagger-server  # 自动读取配置

增强的错误处理
- 更友好的错误提示
- 详细的调试信息
- 自动问题诊断
性能优化
- OpenAPI 规范缓存
- 增量解析更新
- 内存使用优化

中期改进 (v1.2.0)

插件系统

# 支持自定义转换插件
mcp-swagger-server --plugin ./my-transformer.js

多实例管理

# 管理多个 API 实例
mcp-swagger-server --config ./multi-api.json

监控和日志
- 集成 Prometheus 指标
- 结构化日志输出
- 健康检查端点

长期改进 (v2.0.0)

Web 管理界面
- 可视化配置管理
- 实时监控面板
- API 测试工具
企业级功能
- 身份认证支持
- 访问控制列表
- 审计日志
生态系统集成
- Docker 官方镜像
- Kubernetes Helm Chart
- CI/CD 集成插件

🎯 发布建议

版本策略

v1.0.0: 基础 CLI 功能 (当前)
v1.1.0: 配置文件支持 + 错误处理改进
v1.2.0: 插件系统 + 监控功能
v2.0.0: Web 界面 + 企业级功能

发布渠道

NPM 公共仓库 (主要)
GitHub Releases (附加)
Docker Hub (未来)

文档维护

保持 README.md 更新
维护 CHANGELOG.md
提供详细的 API 文档
创建使用示例和教程

📊 成功指标

发布成功标准

NPM 包成功发布
全局命令 mcp-swagger-server 可用
基本功能测试通过
文档完整可用

用户采用指标

NPM 下载量
GitHub Stars 数量
社区反馈和 Issues
功能请求和贡献

🎉 结论

mcp-swagger-server 已经具备了发布到 NPM 的所有核心功能，只需要添加 bin 字段配置就可以作为 CLI 工具使用。

推荐立即发布，理由：

✅ 功能完整 - 支持多种传输协议
✅ 代码质量高 - TypeScript + 完整类型定义
✅ 架构清晰 - 良好的模块化设计
✅ 易于使用 - 丰富的命令行选项
✅ 文档齐全 - 完整的使用指南

这个工具将极大地简化 OpenAPI 到 MCP 的转换过程，为 AI 生态系统提供重要的基础设施支持。

5.2 KiB Raw Blame History