MCP Forge — Model Context Protocol Server Builder
Version: 1.1.0 | Author: Shadows Company | License: MIT
WHEN TO TRIGGER
- - User wants to create an MCP server
- Integrating an external API/service with AI agents
- User says "build MCP", "create a tool server", "MCP server"
- Connecting a database, API, or service to Claude/OpenClaw
WHEN NOT TO TRIGGER
- - Using existing MCP servers (just configure them)
- Building regular REST APIs (use standard web framework)
PREREQUISITES
Requires at least one of: python/python3/uv (for Python MCP servers) or node (for TypeScript MCP servers). The skill auto-detects the user's preferred stack based on available binaries.
- - Python path: Requires
fastmcp package (pip install fastmcp). Optional: httpx for HTTP clients, pytest for testing. - TypeScript path: Requires
@modelcontextprotocol/sdk and zod packages (npm install). Optional: tsx for development. - uv path: Can replace pip/python with
uv run for faster setup.
Additional tooling (pip, npm) is used only for dependency installation when explicitly requested by the user.
QUICK DECISION: PYTHON OR TYPESCRIPT?
| Factor | Python (FastMCP) | TypeScript (MCP SDK) |
|---|
| Speed to build | Faster (less boilerplate) | More setup |
| Type safety |
Runtime checks | Compile-time checks |
| Ecosystem | Data/ML/scripting | Web/Node ecosystem |
| Hosting | uvx, pip | npx, npm |
Default: Python with FastMCP unless the user needs TypeScript.
PYTHON — FastMCP Template
Minimal Server
CODEBLOCK0
Project Structure
CODEBLOCK1
Running
CODEBLOCK2
TYPESCRIPT — MCP SDK Template
Minimal Server
CODEBLOCK3
Project Structure
CODEBLOCK4
DESIGN PRINCIPLES
1. Tool Design
- - One tool = one action — do not create god tools that handle multiple unrelated operations
- Clear names —
get_user, create_issue, not INLINECODE17 - Descriptive parameters — use docstrings/descriptions for every param
- Return structured data — JSON-serializable results
- Error handling — return error messages in the response, never let the server crash
2. Security
- - Never hardcode secrets — use environment variables via
os.environ or INLINECODE19 - Validate inputs — check types, ranges, formats at every tool boundary
- Sanitize outputs — strip internal paths, stack traces, and system details from responses
- Rate limiting — protect against runaway agent loops with request throttling
- Principle of least privilege — only request the permissions the tool actually needs
3. Performance
- - Async by default — use
async/await for all I/O operations - Connection pooling — reuse HTTP clients and DB connections across tool calls
- Timeouts — set explicit timeouts (e.g., 30s) on all external calls
- Caching — cache frequently-accessed, rarely-changing data with TTL
4. Testing
CODEBLOCK5
CONFIGURATION FORMAT
For OpenClaw/Claude Desktop:
{
"mcpServers": {
"my-service": {
"command": "python",
"args": ["-m", "my_mcp_server.server"],
"env": {
"API_KEY": "from-env-or-secrets"
}
}
}
}
SECURITY CONSIDERATIONS
This skill generates new source code files (scaffolding MCP servers). It does NOT execute the generated code during scaffolding.
- - Commands suggested:
pip install fastmcp, npm install @modelcontextprotocol/sdk — these install packages from public registries. Review package names before running. - Data read: The skill reads the user's project structure to determine stack preferences. No sensitive files are accessed.
- Network access: None from the skill itself. Generated servers may make network calls depending on their purpose — this is by design and documented per-server.
- Credentials: The skill explicitly instructs to use environment variables for secrets and never hardcode credentials in source files.
- Persistence: Generated files are written to the working directory only. No global config changes.
- Sandboxing: Recommended to run generated MCP servers in isolated environments (containers, venvs) during development.
RULES
- 1. One purpose per server — do not mix unrelated tools in a single server
- Document every tool — description + parameter docs are mandatory for each tool
- Environment variables for secrets — never hardcode API keys or tokens
- Test before publishing — verify all tools work with a client before distribution
- README is mandatory — every server must include installation, configuration, and usage examples
Published by Shadows Company — "We work in the shadows to serve the Light."MCP Forge — 模型上下文协议服务器构建器
版本: 1.1.0 | 作者: Shadows Company | 许可证: MIT
触发时机
- - 用户想要创建MCP服务器
- 将外部API/服务与AI代理集成
- 用户说构建MCP、创建工具服务器、MCP服务器
- 将数据库、API或服务连接到Claude/OpenClaw
不触发时机
- - 使用现有的MCP服务器（只需配置它们）
- 构建常规REST API（使用标准Web框架）
前置条件
至少需要以下之一：python/python3/uv（用于Python MCP服务器）或node（用于TypeScript MCP服务器）。该技能会根据可用的二进制文件自动检测用户偏好的技术栈。
- - Python路径：需要fastmcp包（pip install fastmcp）。可选：httpx用于HTTP客户端，pytest用于测试。
- TypeScript路径：需要@modelcontextprotocol/sdk和zod包（npm install）。可选：tsx用于开发。
- uv路径：可以用uv run替代pip/python以实现更快的设置。
额外的工具（pip、npm）仅在用户明确请求时用于安装依赖。
快速决策：Python还是TypeScript？
| 因素 | Python (FastMCP) | TypeScript (MCP SDK) |
|---|
| 构建速度 | 更快（样板代码少） | 设置更多 |
| 类型安全 |
运行时检查 | 编译时检查 |
| 生态系统 | 数据/机器学习/脚本 | Web/Node生态系统 |
| 托管方式 | uvx, pip | npx, npm |
默认：除非用户需要TypeScript，否则使用Python和FastMCP。
Python — FastMCP模板
最小服务器
python
from fastmcp import FastMCP
mcp = FastMCP(my-service, description=该服务器的功能描述)
@mcp.tool()
async def my_tool(param: str) -> str:
该工具的功能描述。
Args:
param: 参数描述
# 在此实现
return f{param}的结果
@mcp.resource(resource://{name})
async def get_resource(name: str) -> str:
获取命名资源。
return f{name}的内容
项目结构
my-mcp-server/
init.py
server.py # FastMCP实例 + 工具
config.py # 环境变量、常量
requirements.txt # fastmcp, httpx等
README.md # 使用说明
运行方式
bash
开发模式
fastmcp dev server.py
安装到Claude/OpenClaw
fastmcp install server.py --name My Service
或在设置中手动配置
TypeScript — MCP SDK模板
最小服务器
typescript
import { McpServer } from @modelcontextprotocol/sdk/server/mcp.js;
import { StdioServerTransport } from @modelcontextprotocol/sdk/server/stdio.js;
import { z } from zod;
const server = new McpServer({
name: my-service,
version: 1.0.0,
});
server.tool(
my-tool,
该工具的功能描述,
{ param: z.string().describe(参数描述) },
async ({ param }) => ({
content: [{ type: text, text: ${param}的结果 }],
})
);
const transport = new StdioServerTransport();
await server.connect(transport);
项目结构
my-mcp-server/
src/
index.ts # McpServer实例 + 工具
config.ts # 环境变量
package.json # @modelcontextprotocol/sdk, zod
tsconfig.json
README.md
设计原则
1. 工具设计
- - 一个工具 = 一个操作 — 不要创建处理多个不相关操作的万能工具
- 清晰的命名 — 使用getuser、createissue，而不是do_thing
- 描述性参数 — 为每个参数使用文档字符串/描述
- 返回结构化数据 — JSON可序列化的结果
- 错误处理 — 在响应中返回错误消息，绝不让服务器崩溃
2. 安全性
- - 绝不硬编码密钥 — 通过os.environ或process.env使用环境变量
- 验证输入 — 在每个工具边界检查类型、范围和格式
- 清理输出 — 从响应中剥离内部路径、堆栈跟踪和系统细节
- 速率限制 — 通过请求限流防止失控的代理循环
- 最小权限原则 — 只请求工具实际需要的权限
3. 性能
- - 默认异步 — 对所有I/O操作使用async/await
- 连接池 — 在工具调用间复用HTTP客户端和数据库连接
- 超时设置 — 对所有外部调用设置明确的超时时间（如30秒）
- 缓存机制 — 对频繁访问、很少变化的数据使用TTL缓存
4. 测试
python
使用FastMCP进行Python测试
import pytest
from fastmcp import Client
@pytest.fixture
def client():
return Client(mcp)
@pytest.mark.asyncio
async def testmytool(client):
result = await client.calltool(mytool, {param: test})
assert 结果 in result.text
配置格式
用于OpenClaw/Claude Desktop：
json
{
mcpServers: {
my-service: {
command: python,
args: [-m, mymcpserver.server],
env: {
API_KEY: from-env-or-secrets
}
}
}
}
安全注意事项
该技能会生成新的源代码文件（搭建MCP服务器框架）。在搭建过程中不会执行生成的代码。
- - 建议的命令：pip install fastmcp、npm install @modelcontextprotocol/sdk — 这些命令从公共注册表安装包。运行前请检查包名。
- 读取的数据：该技能会读取用户的项目结构以确定技术栈偏好。不会访问敏感文件。
- 网络访问：技能本身无网络访问。生成的服务器可能根据其用途进行网络调用 — 这是设计使然，每个服务器都有相应文档说明。
- 凭据：该技能明确指示使用环境变量存储密钥，绝不在源文件中硬编码凭据。
- 持久性：生成的文件仅写入工作目录。不会更改全局配置。
- 沙箱隔离：建议在开发期间在隔离环境（容器、虚拟环境）中运行生成的MCP服务器。
规则
- 1. 每个服务器一个用途 — 不要在一个服务器中混合不相关的工具
- 记录每个工具 — 每个工具必须有描述和参数文档
- 密钥使用环境变量 — 绝不硬编码API密钥或令牌
- 发布前测试 — 在分发前验证所有工具能正常与客户端配合
- README是必需的 — 每个服务器必须包含安装、配置和使用示例
由Shadows Company发布 — 我们在暗处工作，为光明服务。
