服务器开发
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 人工智能
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS · Linux · Windows
- 运行环境要求
- Node.js · Python
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
列出每个工具及其名称、描述、参数和返回格式。应用整合原则:比起众多狭窄的工具,更喜欢功能较少的工具。对于每个工具,写下 3-4 句话的描述(什么、何时使用、何时不使用、行为注释)。这是最重要的一步——良好的描述可以防止误用。
使用模板作为起点: Python:`templates/mcp-server-python-template/` TypeScript:`templates/mcp-server-typescript-template/` 核心目录结构:Python:
按照特定于语言的参考中的模式编写每个工具处理程序: Python:`references/python-server-patterns.md` TypeScript:`references/typescript-server-patterns.md` 所有工具的关键原则:验证每个处理程序顶部的输入
Python (uvx): 在 `pyproject.toml` 中设置 `[project.scripts]`: TypeScript (npx): 在 `package.json` 中设置 `bin`:
实现正常关闭(SIGINT/SIGTERM 处理)。当客户端断开连接时,这对于干净的进程终止至关重要。
分三个级别进行测试: 单元:导入处理程序、使用 dict 调用、断言输出 集成:启动服务器、通过 MCP 客户端调用工具 模式验证:验证工具定义与预期模式匹配 请参阅`references/server-testing-guide.md` 了解详细模式。
# MCP Server Creation
Create multi-tool MCP servers in Python or TypeScript that follow the Model Context Protocol specification and Anthropic's tool design best practices.
## What MCP Servers Are
An MCP server is a process that exposes one or more tools (and optionally resources and prompts) over the Model Context Protocol. Servers communicate via stdio transport — they read JSON-RPC from stdin and write responses to stdout.
MCP servers are how you package and distribute tool capabilities. An LLM client (Claude Code, Claude Desktop, etc.) starts the server process and calls its tools.
## When to Create a Server
- You have **2+ related tools** that share configuration, state, or domain
- You want to **distribute tools** for others to use (via `uvx` or `npx`)
- Tools need **shared resources** (database connections, API clients, auth tokens)
- You're building a **domain-specific toolkit** (GitHub, database, monitoring, etc.)
## When NOT to Create a Server
- Single utility tool — use a standalone tool file (see `mcp-tool-dev` skill)
- Claude Code agent, skill, or command — use their respective creation skills
- REST API — MCP is for LLM tool calling, not general HTTP services
## Python vs TypeScript
| Factor | Python (FastMCP) | TypeScript (@modelcontextprotocol/sdk) |
|--------|-------------------|----------------------------------------|
| **Distribution** | `uvx` (uv tool) | `npx` |
| **Type system** | Type hints + docstrings | Zod schemas |
| **Packaging** | `pyproject.toml` | `package.json` with bin |
| **Async** | Native `async/await` | Native `async/await` |
| **Best for** | Data science, Python tooling, API wrappers | Frontend tooling, Node.js ecosystem, npm distribution |
Choose Python when the tools interact with Python libraries or you prefer pyproject.toml packaging. Choose TypeScript when targeting the npm ecosystem or when tools interact with Node.js libraries.
## Creation Workflow
### Step 1: Design Your Tools
List every tool with its name, description, parameters, and return format. Apply the consolidation principle: prefer fewer capable tools over many narrow ones.
For each tool, write the 3-4 sentence description (what, when to use, when NOT to use, behavior notes). This is the most important step — good descriptions prevent misuse.
### Step 2: Scaffold the Project
Use the templates as starting points:
- Python: `templates/mcp-server-python-template/`
- TypeScript: `templates/mcp-server-typescript-template/`
Core directory structure:
**Python:**
```
my-server/
├── pyproject.toml # uvx entry point
├── src/my_server/
│ ├── __init__.py
│ ├── server.py # FastMCP instance + tool registration
│ └── tools/ # One file per tool or tool group
│ └── search.py
├── tests/
│ ├── conftest.py
│ └── test_tools.py
└── README.md
```
**TypeScript:**
```
my-server/
├── package.json # npx entry point with bin
├── tsconfig.json
├── src/
│ ├── index.ts # Entry: CLI args, transport, shutdown
│ ├── server.ts # Tool registration
│ └── tools/
│ └── search.ts
├── tests/
│ └── tools.test.ts
└── README.md
```
### Step 3: Implement Tools
Write each tool handler following the patterns in the language-specific reference:
- Python: `references/python-server-patterns.md`
- TypeScript: `references/typescript-server-patterns.md`
Key principles for all tools:
- Validate inputs at the top of every handler
- Return formatted text, not raw JSON dumps
- Include corrective guidance in error messages
- Keep handlers focused — one tool, one job
### Step 4: Configure Packaging
**Python (uvx):** Set `[project.scripts]` in `pyproject.toml`:
```toml
[project.scripts]
my-server = "my_server.server:main"
```
**TypeScript (npx):** Set `bin` in `package.json`:
```json
{
"bin": { "my-server": "dist/index.js" }
}
```
### Step 5: Handle Server Lifecycle
Implement graceful shutdown (SIGINT/SIGTERM handling). This is critical for clean process termination when the client disconnects.
### Step 6: Write Tests
Test at three levels:
1. **Unit**: Import handler, call with dict, assert output
2. **Integration**: Start server, call tools via MCP client
3. **Schema validation**: Verify tool definitions match expected schemas
See `references/server-testing-guide.md` for detailed patterns.
## Tool Description Best Practices
- Write 3-4 sentences: what, when to use, when not to use, behavior notes
- Include parameter semantics in descriptions (regex vs full-text, format expectations)
- For 10+ tools, use discovery-first architecture: provide a `list_capabilities` tool
## Common Mistakes
1. **No graceful shutdown** — server hangs when client disconnects; always handle SIGINT/SIGTERM
2. **Stdout pollution** — logging or print() to stdout corrupts JSON-RPC; use stderr for logging
3. **Missing tool descriptions** — tools without descriptions are invisible to the LLM
4. **Monolithic handlers** — 200-line tool handlers; split logic into helper functions
5. **No packaging config** — forgetting `[project.scripts]` or `bin` entry; server can't be installed
6. **Ignoring transport** — MCP uses stdio, not HTTP; don't create an HTTP server
For detailed patterns per language, see the `references/` directory.
---
> Source: [andisab/swe-marketplace](https://github.com/andisab/swe-marketplace) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->
按说明文件中的顺序排列。
什么是 MCP 服务器
何时创建服务器
何时不创建服务器
Python 与 TypeScript
第 1 步:设计你的工具
文件/命令 -> uvx · npx · mcp-tool-dev · pyproject.toml · package.json · async/await · templates/mcp-server-python-template/ · templates/mcp-server-typescript-template/
内容校验值 -> ae61c2a685f3
当前原文的自动摘译,尚未人工审校。
什么是 MCP 服务器
MCP 服务器是一个通过模型上下文协议公开一个或多个工具(以及可选的资源和提示)的进程。服务器通过 stdio 传输进行通信——它们从 stdin 读取 JSON-RPC 并将响应写入 stdout。 MCP 服务器是您打包和分发工具功能的方式。 LLM 客户端(Claude Code、Claude Desktop 等)启动服务器进程并调用其工具。
何时创建服务器
您有 2 个以上共享配置、状态或域的相关工具 您想要分发工具供其他人使用(通过
uvx或npx) 工具需要共享资源(数据库连接、API 客户端、身份验证令牌) 您正在构建特定于域的工具包(GitHub、数据库、监控等)何时不创建服务器
单一实用工具 — 使用独立的工具文件(参见
mcp-tool-dev技能) Claude Code 代理、技能或命令 — 使用各自的创建技能 REST API — MCP 用于 LLM 工具调用,而不是一般的 HTTP 服务Python 与 TypeScript
因素 · Python (FastMCP) · TypeScript (@modelcontextprotocol/sdk) 分发 ·
uvx(uv 工具) ·npx类型系统 · 类型提示 + 文档字符串 · Zod 模式 打包 ·pyproject.toml·package.json带 bin 异步 · 本机async/await· 本机async/await