MCP Forge Templates

MCP锻造模板

此存储库包含以下内容的官方和社区模板 MCP锻造，一个用于管理Claude Desktop MCP服务器配置的强大CLI工具。

📋 目录

• 概述
• 模板结构
• 系统
• 模板引擎
• 最佳实践
• 例子
• 贡献
• 验证

🎯 概述

MCP Forge模板提供了一种标准化的方法来配置MCP服务器：

• 变量替换 使用Handlebars模板
• 类型安全变量 通过验证
• 跨平台兼容性
• 元数据 用于发现和记录
• 条件逻辑 用于灵活的配置

📁 模板结构

每个模板都是一个JSON文件，其结构如下：

{
  "name": "template-name",
  "version": "1.0.0",
  "description": "Brief description of what this template does",
  "author": "Your Name or Organization",
  "tags": ["category", "type", "keywords"],
  "platforms": ["windows", "macos", "linux"],
  "variables": {
    // Variable definitions (see Variable System section)
  },
  "config": {
    "command": "executable-name",
    "args": ["arg1", "arg2", "{{variable}}"],
    "env": {
      "ENV_VAR": "{{variable}}"
    }
  },
  "requirements": {
    "nodejs": ">=18.0.0",
    "python": ">=3.8.0"
  },
  "setup_instructions": "Additional setup instructions for users"
}

必填字段

• name：唯一标识符（小写，允许使用连字符）
• version：语义版本（例如“1.0.0”）
• description：清晰、简洁的描述
• author：作者姓名或组织
• tags：用于发现的相关标签数组
• platforms：支持的平台
• config：具有命令、参数和环境的服务器配置

可选字段

• variables：用户输入的变量定义
• requirements：系统要求
• setup_instructions：附加设置指南

🔧 系统

变量支持基于用户输入的动态配置。MCP Forge支持五种变量类型：

1.字符串变量

{
  "api_key": {
    "type": "string",
    "description": "Your API key",
    "required": true
  },
  "host": {
    "type": "string",
    "description": "Server hostname",
    "default": "localhost",
    "required": false
  }
}

属性：

• type：“字符串”
• description：用户友好的描述
• required：布尔值（默认值：false）
• default：默认值
• validation：可选验证规则名称（仅限基本验证）

2.数字变量

{
  "port": {
    "type": "number",
    "description": "Server port",
    "default": 8080,
    "required": false
  }
}

属性：

• type：“数字”
• default：默认编号
• description：用户友好的描述
• required：布尔值（默认值：false）

3.布尔变量

{
  "readonly": {
    "type": "boolean",
    "description": "Enable read-only mode",
    "default": false,
    "required": false
  }
}

属性：

• type：“布尔值”
• default：true | false
• description：用户友好的描述
• required：布尔值（默认值：false）

4.数组变量

{
  "paths": {
    "type": "array",
    "description": "List of directories to access",
    "default": ["/home/user/docs", "/home/user/projects"],
    "required": true
  }
}

属性：

• type：“数组”
• default：默认值数组
• description：用户友好的描述
• required：布尔值（默认值：false）
• validation：应用于每个数组元素的可选验证规则

5.选择变量

{
  "ssl_mode": {
    "type": "select",
    "description": "SSL connection mode",
    "options": ["disable", "allow", "prefer", "require"],
    "default": "prefer",
    "required": false
  }
}

属性：

• type：“选择”
• options：有效选项数组（选择类型需要）
• default：必须是选项之一
• description：用户友好的描述
• required：布尔值（默认值：false）

🎨 模板引擎

MCP Forge使用Handlebars进行变量替换和条件逻辑。

基本变量替换

{
  "config": {
    "command": "myserver",
    "args": ["--host", "{{host}}", "--port", "{{port}}"],
    "env": {
      "API_KEY": "{{api_key}}",
      "DEBUG": "{{debug}}"
    }
  }
}

条件逻辑

使用Handlebars条件语句进行可选配置：

{
  "env": {
    "REQUIRED_VAR": "{{required_value}}",
    "{{#if optional_var}}OPTIONAL_VAR{{/if}}": "{{optional_var}}",
    "{{#unless readonly}}WRITE_MODE{{/unless}}": "true"
  }
}

数组迭代

使用以下方法处理阵列 {{#each}}:

{
  "args": [
    "myserver",
    "{{#each paths}}--path={{this}}{{#unless @last}} {{/unless}}{{/each}}"
  ]
}

内置变量

MCP Forge提供内置变量：

• {{home_dir}}：用户的主目录
• {{config_dir}}：应用程序配置目录
• {{platform}}：当前平台（windows/macos/linux）

✨ 最佳实践

1.命名约定

• 模板名称：带连字符的小写字母
• 变量名：蛇病例
• 环境变量：上箱

2.安全考虑

• 适当标记敏感变量（它们将在输出中被屏蔽）
• 为凭证变量使用描述性名称（api_key、令牌、密码）
• 提供凭证管理的设置说明

3.用户体验

• 提供清晰、有用的描述
• 尽可能使用合理的默认值
• 按逻辑对相关变量进行分组
• 包括全面的设置说明

4.跨平台兼容性

• 在所有支持的平台上进行测试
• 尽可能使用与平台无关的路径
• 考虑平台特定要求

5.错误处理

• 使用验证来捕获常见错误
• 在描述中提供清晰的错误消息
• 在安装说明中包括故障排除

📚 例子

简单API服务器模板

{
  "name": "simple-api",
  "version": "1.0.0",
  "description": "Simple API server with authentication",
  "author": "MCP-Forge",
  "tags": ["api", "simple", "auth"],
  "platforms": ["windows", "macos", "linux"],
  "variables": {
    "api_key": {
      "type": "string",
      "description": "Your API key for authentication",
      "required": true
    },
    "base_url": {
      "type": "string",
      "description": "API base URL",
      "default": "https://api.example.com",
      "required": false
    },
    "timeout": {
      "type": "number",
      "description": "Request timeout in seconds",
      "default": 30,
      "required": false
    }
  },
  "config": {
    "command": "npx",
    "args": ["-y", "@example/api-server"],
    "env": {
      "API_KEY": "{{api_key}}",
      "BASE_URL": "{{base_url}}",
      "TIMEOUT": "{{timeout}}"
    }
  },
  "requirements": {
    "nodejs": ">=18.0.0"
  },
  "setup_instructions": "Obtain an API key from https://example.com/api-keys and ensure Node.js is installed."
}

数据库连接模板

{
  "name": "mysql-connector",
  "version": "1.0.0",
  "description": "MySQL database connection with SSL support",
  "author": "MCP-Forge",
  "tags": ["database", "mysql", "sql"],
  "platforms": ["windows", "macos", "linux"],
  "variables": {
    "host": {
      "type": "string",
      "description": "MySQL server hostname",
      "default": "localhost",
      "required": true
    },
    "port": {
      "type": "number",
      "description": "MySQL server port",
      "default": 3306,
      "required": false
    },
    "database": {
      "type": "string",
      "description": "Database name",
      "required": true
    },
    "username": {
      "type": "string",
      "description": "Database username",
      "required": true
    },
    "password": {
      "type": "string",
      "description": "Database password",
      "required": true
    },
    "ssl_mode": {
      "type": "select",
      "description": "SSL connection mode",
      "options": ["disabled", "preferred", "required", "verify_ca", "verify_identity"],
      "default": "preferred",
      "required": false
    },
    "connection_limit": {
      "type": "number",
      "description": "Maximum number of connections",
      "default": 10,
      "required": false
    }
  },
  "config": {
    "command": "npx",
    "args": ["-y", "@example/mysql-server"],
    "env": {
      "MYSQL_HOST": "{{host}}",
      "MYSQL_PORT": "{{port}}",
      "MYSQL_DATABASE": "{{database}}",
      "MYSQL_USER": "{{username}}",
      "MYSQL_PASSWORD": "{{password}}",
      "MYSQL_SSL_MODE": "{{ssl_mode}}",
      "{{#if connection_limit}}CONNECTION_LIMIT{{/if}}": "{{connection_limit}}"
    }
  },
  "requirements": {
    "nodejs": ">=18.0.0",
    "mysql": ">=8.0.0"
  },
  "setup_instructions": "Ensure MySQL server is running and accessible. Create the database and user with appropriate permissions. For production, use SSL certificates and secure connection settings."
}

文件系统访问模板

{
  "name": "advanced-filesystem",
  "version": "1.0.0",
  "description": "Advanced filesystem access with multiple directories and permissions",
  "author": "MCP-Forge",
  "tags": ["filesystem", "files", "advanced"],
  "platforms": ["windows", "macos", "linux"],
  "variables": {
    "read_paths": {
      "type": "array",
      "description": "Directories with read access",
      "default": ["{{home_dir}}/Documents", "{{home_dir}}/Desktop"],
      "required": true
    },
    "write_paths": {
      "type": "array",
      "description": "Directories with write access",
      "default": ["{{home_dir}}/Projects"],
      "required": false
    },
    "readonly_mode": {
      "type": "boolean",
      "description": "Enable global read-only mode",
      "default": false,
      "required": false
    },
    "max_file_size": {
      "type": "number",
      "description": "Maximum file size in MB",
      "default": 100,
      "required": false
    }
  },
  "config": {
    "command": "npx",
    "args": [
      "-y",
      "@example/filesystem-server",
      "{{#each read_paths}}--read={{this}}{{#unless @last}} {{/unless}}{{/each}}",
      "{{#if write_paths}}{{#each write_paths}}--write={{this}}{{#unless @last}} {{/unless}}{{/each}}{{/if}}"
    ],
    "env": {
      "{{#if readonly_mode}}READONLY_MODE{{/if}}": "{{readonly_mode}}",
      "{{#if max_file_size}}MAX_FILE_SIZE{{/if}}": "{{max_file_size}}"
    }
  },
  "requirements": {
    "nodejs": ">=18.0.0"
  },
  "setup_instructions": "Ensure all specified directories exist and have appropriate permissions. The server will respect system file permissions in addition to the configured access levels."
}

🤝 贡献

添加新模板

1. 创建模板文件 在相应的目录中：

- official/ 用于官方模板 - community/ 社区贡献

1. 遵循命名约定:

- 文件： template-name.json - 模板名称： template-name

1. 更新catalog.json 使用模板元数据：

{
  "template-name": {
    "name": "template-name",
    "version": "1.0.0",
    "description": "Template description",
    "author": "Your Name",
    "tags": ["tag1", "tag2"],
    "platforms": ["windows", "macos", "linux"],
    "category": "community",
    "path": "community/template-name.json"
  }
}

1. 彻底测试:

- 验证JSON语法 - 测试变量替换 - 验证跨平台兼容性 - 使用MCP Forge CLI进行测试

模板类别

• 官方的：由MCP Forge团队维护
• 社区：社区贡献的模板
• 实验性的：实验或测试模板

质量指南

• 完整的文件：所有字段均已正确记录
• 合理的违约：在适当的情况下提供默认值
• 清晰的描述：用户友好的变量描述
• 基本验证：使用验证字段进行基本检查
• 安全意识：适当处理凭据（它们将被自动屏蔽）
• 跨平台：在多个平台上进行测试

✅ 验证

JSON模式验证

模板根据JSON模式进行验证，该模式强制执行：

• 必填字段存在
• 正确的数据类型
• 有效的平台名称
• 正确的变量类型定义
• 选择变量必须具有选项数组

运行时验证

MCP Forge执行额外的验证：

• 使用Handlebars的变量替换语法
• 必须提供必需的变量
• 选择变量必须使用已定义的选项之一
• 基本模板渲染验证

测试您的模板

# Validate template syntax
mcp-forge template validate your-template.json

# Test template installation
mcp-forge add test-server your-template --dry-run

# Test with variables
mcp-forge add test-server your-template --vars "key=value" --dry-run

🏷️ 常用标签

使用这些标准化标签以获得更好的可发现性：

类别：

• api -API集成
• database -数据库连接
• filesystem -文件系统访问
• search -搜索引擎
• web -Web服务
• ai -AI/ML服务
• cloud -云服务
• dev-tools -开发工具

类型：

• official -官方模板
• community -社区模板
• experimental -实验模板
• core -核心功能
• advanced -高级功能

技术：

• nodejs -基于Node.js
• python -基于Python
• rest -REST API
• graphql -GraphQL API
• sql -SQL数据库
• nosql -NoSQL数据库

📖 额外资源

• MCP锻造文档
• 手柄杆文档
• MCP协议规范
• 模板示例

______________________________________________________________________

模板制作愉快！ 🚀

如有疑问或需要支持，请在 MCP Forge存储库.