使用说明

MCP服务器生成器

用于创建具有最佳实践的双模MCP服务器的元生成器

概述

生成可在两种模式下工作的完整、生产就绪的MCP（模型上下文协议）服务器：

MCP服务器模式：适用于人工智能代理（Claude Desktop等）
命令行接口命令模式：面向开发者

此工具本身就是MCP服务器，使AI代理能够生成其他MCP服务器！它展示了它创建的双模架构模式，并实现了渐进式披露，以实现上下文高效的工具发现。

为什么使用这个？

⚡ 快速：在5分钟内生成一个完整的MCP服务器
🏗️ 完成：包括测试、文档、包装和CI/CD
✅ 已测试：生成的服务器具有高覆盖率的全面测试套件
🎯 最佳实践：遵循生产MCP服务器的验证模式，并内置指导
🔧 双模：既可作为MCP服务器又可作为CLI工具
🧠 智能发现：用于上下文高效AI代理使用的渐进式披露工具
📦 准备发布：包含用于PyPI发布的GitHub Actions工作流

特性

✅ 双模架构 （MCP+CLI）
✅ 渐进式披露工具 （AI代理的上下文高效工具发现）
✅ 内置指南 （最佳做法和实施指南）
✅ Claude代码集成 （生成斜线命令以指导开发）
✅ 异步/等待支持 （用于I/O操作的异步处理程序，避免了事件循环错误）
✅ 包前缀支持 （避免PyPI命名空间与AUTO检测冲突）
✅ 完整的项目脚手架 （测试、文档、包装）
✅ GitHub操作工作流 （通过pypi工作流生成器）
✅ 全面的测试套件 （92多项高覆盖率测试）
✅ 键入提示和文档
✅ 最佳做法执行
✅ 最小依赖性

安装

MCP服务器使用（推荐）

使用uvx（无需安装）：

将其用作MCP服务器的最简单方法是在Claude Desktop中配置：

{
  "mcpServers": {
    "mcp-server-generator": {
      "command": "uvx",
      "args": ["hitoshura25-mcp-server-generator"]
    }
  }
}

先决条件： 安装紫外线:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

用于CLI使用（替代）

使用pipx（独立安装）：

pipx install hitoshura25-mcp-server-generator

使用pip：

pip install hitoshura25-mcp-server-generator

来源（发展）

git clone https://github.com/hitoshura25/mcp-server-generator.git
cd mcp-server-generator
pip install -e .

快速开始

交互模式（推荐）

最简单的开始方法：

hitoshura25-mcp-server-generator-cli --interactive

这将指导您完成：

项目命名
作者信息
工具定义
配置选项

命令行模式

对于自动化或当您有工具定义文件时：

hitoshura25-mcp-server-generator-cli \
  --project-name my-mcp-tool \
  --description "Does something useful" \
  --author "Your Name" \
  --email "you@example.com" \
  --tools-file tools.json

MCP服务器模式（适用于AI代理）

在Claude Desktop中将mcp服务器生成器配置为mcp服务器，让Claude为您生成mcp服务器：

使用uvx（推荐）：

{
  "mcpServers": {
    "mcp-server-generator": {
      "command": "uvx",
      "args": ["hitoshura25-mcp-server-generator"]
    }
  }
}

使用pipx/pip安装：

{
  "mcpServers": {
    "mcp-server-generator": {
      "command": "hitoshura25-mcp-server-generator"
    }
  }
}

有关MCP配置的详细信息，请参阅 MCP-USAGE.md

MCP服务器工具

当用作MCP服务器（在Claude Desktop或其他MCP客户端中）时，MCP服务器生成器提供了强大的工具 渐进式呈现 支持-允许AI代理高效地发现和使用工具，而无需预先加载所有模式。

发现工具

搜索工具 -通过查询查找相关工具

按关键字、类别或用例搜索
上下文效率的三个细节级别：
- name：仅工具名称（最有效）
- summary：名称+描述+类别
- full：包括用例在内的完整信息
例子： search_tools(query="generate", detail_level="summary")

get_tool_info -获取特定工具的详细信息

两个细节级别： summary 或 full
渐进式披露以提高上下文效率
例子： get_tool_info(tool_name="generate_mcp_server", detail_level="full")

生成工具

generate_mcp-server -生成完整的MCP服务器项目

创建双模架构（MCP+CLI）
包括测试、文档和CI/CD工作流
具有最佳实践的生产就绪脚手架
支持异步/等待模式

generate_claude_命令 -创建Claude代码命令文件

生成 .claude/commands/ 目录结构
为指导MCP开发创建斜线命令
常见工作流模板： mcp_generator, best_practices, implementation_helper, custom
提供有指导的开发体验

验证工具

validate_project_name -验证项目名称

检查Python包兼容性
避免Python关键字冲突
确保PyPI命名约定

指导工具

get_best_pactics -MCP开发最佳实践

渐进式披露策略
上下文高效工具设计
控制流优化
安全和隐私考虑
状态管理模式
测试策略

获取实现指南 -分步实施指南

项目设置和初始化
工具实现模式
测试策略
部署和发布
Claude桌面集成

为什么是渐进式披露？

渐进式披露允许AI代理：

无需预先加载完整模式即可发现工具
为实际工作节省上下文窗口空间
扩展到数百或数千个工具
准确获得所需的详细程度

示例工作流（MCP工具调用）：

# 1. Search for relevant tools
search_tools(query="generate", detail_level="name")
# Returns: ["generate_mcp_server", "generate_claude_command"]

# 2. Get summary of specific tool
get_tool_info(tool_name="generate_mcp_server", detail_level="summary")
# Returns: name, description, category

# 3. Get full details when ready to use
get_tool_info(tool_name="generate_mcp_server", detail_level="full")
# Returns: complete information including use cases and parameters

包前缀

为了避免PyPI上的命名空间冲突，mcp服务器生成器支持在包名前加前缀。这是 强烈推荐 用于唯一的包名称。

前缀模式

自动（推荐）

从git配置中自动检测您的GitHub用户名
优先： github.user → 远程URL→ user.name （消毒）
例子： my-tool → username-my-tool

自定义前缀

使用您自己的前缀（组织名称、品牌等）
例子： --prefix acme → acme-my-tool

无

不应用前缀（仅当您有一个真正唯一的名称时）
例子： unique-server-name → unique-server-name

使用示例

交互模式：

hitoshura25-mcp-server-generator-cli --interactive
# You'll be prompted: "Prefix (default: AUTO): "
# - Press Enter for AUTO detection
# - Type "NONE" for no prefix
# - Type "acme" for custom prefix

命令行：

# AUTO mode (default)
hitoshura25-mcp-server-generator-cli --project-name calculator --prefix AUTO ...

# Custom prefix
hitoshura25-mcp-server-generator-cli --project-name calculator --prefix acme ...

# No prefix
hitoshura25-mcp-server-generator-cli --project-name unique-calculator --prefix NONE ...

MCP服务器模式：

{
  "project_name": "calculator",
  "prefix": "AUTO",
  ...
}

生成的名称

带前缀 username 和项目 my-tool:

PyPI包: username-my-tool （安装时 pip install username-my-tool)
Python导入: username_my_tool （在代码中用作 import username_my_tool)
CLI命令: username-my-tool （运行为 username-my-tool --help)
MCP命令: mcp-username-my-tool （在配置中使用）

有关MCP配置的详细信息，请参阅 MCP-USAGE.md

生成什么

一个完整的、可投入生产的MCP服务器项目：

my-mcp-tool/
├── .gitignore
├── README.md
├── MCP-USAGE.md
├── LICENSE
├── setup.py
├── pyproject.toml
├── requirements.txt
├── MANIFEST.in
├── my_mcp_tool/
│   ├── __init__.py
│   ├── server.py          # MCP server implementation
│   ├── cli.py             # CLI interface
│   ├── generator.py       # Business logic (TODO stubs)
│   └── tests/
│       ├── __init__.py
│       ├── test_server.py  # MCP protocol tests
│       └── test_generator.py  # Core logic tests
└── .github/
    └── workflows/
        └── pypi-publish.yml  # PyPI publishing workflow

生成的功能

✅ 通过stdio使用正确的JSON-RPC运行MCP服务器
✅ 带argparse的CLI接口
✅ 完整的测试套件（MCP协议+业务逻辑）
✅ PyPI发布的GitHub操作工作流
✅ 综合文档（README、MCP-USAGE）
✅ 正确的Python打包（setup.py、pyproject.toml）
✅ TODO存根便于实施

工具定义格式

创建一个 tools.json 定义MCP服务器工具的文件：

{
  "tools": [
    {
      "name": "my_function",
      "description": "Does something useful",
      "parameters": [
        {
          "name": "input_text",
          "type": "string",
          "description": "Text to process",
          "required": true
        },
        {
          "name": "max_length",
          "type": "number",
          "description": "Maximum length",
          "required": false
        }
      ]
    }
  ]
}

支持的类型

string / str
number / int / integer / float
boolean / bool
array / list
object / dict

有关完整示例，请参阅示例.md

文档

MCP-USAGE.md -详细的MCP服务器配置指南
ASYNC_GUIDE.md -在生成的MCP服务器中使用async/await的完整指南
示例.md -示例项目和用例
安全.md - 安全准则和最佳做法
贡献.md -发展和贡献指南

安全

🔒 重要：如果没有适当的安全保护，MCP服务器可能会被用于恶意目的。看安全.md 获取全面的安全指南。

关键安全功能

生成的MCP服务器包括：

安全实用程序模块 (security_utils.py)具有随时可用的功能，用于：
- 输入验证和净化
- 路径遍历保护
- 命令注入预防
- 速率限制以防止高速自动攻击
- 安全相关操作的审计日志记录
- 敏感数据编校（PII、凭据、API密钥）
自动化安全分析 -生成器会分析您的工具定义，并发出以下警告：
- 高风险模式（命令执行、代码评估）
- 中等风险模式（文件操作、网络访问、凭证处理）
- 安全实施建议
全面的安全文件 -每个生成的项目都包含SECURITY.md，其中：
- 基于现实世界人工智能编排的网络间谍威胁模型
- 安全编码模式和示例
- 部署安全检查表
- 事故响应程序

最佳实践

创建MCP服务器时：

验证所有输入 -使用白名单，而不是黑名单
应用最小特权原则 -工具应做到最低限度
实施速率限制 -防止高速自动攻击
添加审核日志记录 -跟踪所有与安全相关的操作
更正敏感数据 -不要暴露个人身份信息、凭据或秘密
使用安全实用程序 -利用内置 security_utils.py 模块

威胁模型

MCP服务器可以用于：

人工智能策划的网络间谍活动
通过任务分解尝试越狱
高速侦察与开发
通过工具链获取凭证
大规模数据泄露

参考: Anthropic对人工智能策划的网络间谍活动的研究

测试

该项目包括一个全面的测试套件：

# Run all tests
pytest

# Run with coverage report
pytest --cov=hitoshura25_mcp_server_generator --cov-report=term-missing

# Run specific test file
pytest hitoshura25_mcp_server_generator/tests/test_server.py -v

测试统计：

92+涵盖所有功能的全面测试
所有异步MCP协议测试通过
渐进式披露和发现工具测试通过
模板验证测试通过

需求

Python≥3.8
Jinja2≥3.0
hitoshura25-pypi工作流生成器==0.6.0

发展

看贡献.md 详细的开发说明。

快速设置：

# Clone the repository
git clone https://github.com/hitoshura25/mcp-server-generator.git
cd mcp-server-generator

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .

# Run tests
pytest

建筑

mcp服务器生成器遵循双模架构模式：

┌─────────────────────────────────────┐
│     mcp-server-generator            │
├─────────────────────────────────────┤
│                                     │
│  ┌──────────┐      ┌──────────┐     │
│  │ MCP Mode │      │ CLI Mode │     │
│  └────┬─────┘      └────┬─────┘     │
│       │                 │           │
│       └────────┬────────┘           │
│                │                    │
│         ┌──────▼───────┐            │
│         │ generator.py │            │
│         │ (Core Logic) │            │
│         └──────────────┘            │
│                                     │
└─────────────────────────────────────┘

两种模式使用相同的核心生成器逻辑，确保一致性。

许可证

阿帕奇-2.0

作者

维纳亚克·梅农

链接

PyPI: https://pypi.org/project/hitoshura25-mcp-server-generator/
GitHub: https://github.com/hitoshura25/mcp-server-generator
问题: https://github.com/hitoshura25/mcp-server-generator/issues
参考实现: pypi工作流生成器

致谢

该项目基于在 pypi工作流生成器，一个用于生成GitHub Actions工作流的生产MCP服务器。

逐步披露的实施遵循以下最佳实践：

Anthropic的MCP工程博客：使用MCP执行代码