服务器
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 运维部署
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需手动接入
- 是否需要外部接口密钥
- 需要 · Vendor-specific
- 兼容的系统
- Docker
- 运行环境要求
- Node.js · Python · Docker
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 读取环境变量
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
第一阶段:发现
在编码之前,了解用例。问这些问题:
第2阶段:推荐部署模型
根据发现答案,推荐一条路径:
第四阶段:选择框架
框架 · 语言 · 何时使用 FastMCP 3.x · Python · Python 首选项,包装 Python 库 TypeScript SDK · TypeScript · 默认选择,最佳规范覆盖范围 两者都产生相同的有线协议。
# MCP Server Development
Guide for designing and building MCP (Model Context Protocol) servers that connect Claude to external tools, APIs, and data sources.
## Overview
MCP servers bridge Claude with external systems using a standardized protocol. Three primitives are available:
| Primitive | Controlled By | Purpose |
|-----------|---------------|---------|
| **Tools** | Model (Claude) | Functions Claude can invoke |
| **Resources** | Application | Contextual data Claude can read |
| **Prompts** | User | Templates users can invoke |
---
## Phase 1: Discovery
Before coding, understand the use case. Ask these questions:
### 1. What does it connect to?
| Connection Type | Recommended Approach |
|-----------------|----------------------|
| Cloud API (SaaS, REST, GraphQL) | Remote HTTP server |
| Local process, filesystem, desktop app | MCPB or local stdio |
| Hardware, OS-level APIs | MCPB |
| Pure logic/computation | Either - default to remote |
### 2. Who will use it?
- **Just me / my team** → Local stdio acceptable
- **Anyone who installs it** → Remote HTTP (preferred) or MCPB
- **Claude desktop with UI widgets** → MCP app
### 3. How many distinct actions?
- **Under ~15 actions** → One tool per action
- **Dozens to hundreds** → Search + execute pattern
### 4. Does a tool need user input mid-call?
- **Simple forms (pick, enter, confirm)** → Elicitation (spec-native)
- **Rich UI (charts, search, dashboards)** → MCP app widgets
- **Neither** → Plain tool returning text/JSON
### 5. What authentication does the service use?
- None / API key → Straightforward
- OAuth 2.0 → Remote server with CIMD or DCR support
---
## Phase 2: Recommend Deployment Model
Based on discovery answers, recommend ONE path:
### ⭐ Remote HTTP Server (Default)
Hosted service speaking MCP over streamable HTTP. Best for cloud API wrappers.
**Benefits:**
- Zero install friction - users add a URL
- One deployment serves all users
- OAuth flows work properly
- Works across Claude desktop, Claude Code, Claude.ai
**Choose unless** server must touch local machine.
### MCPB (Bundled Local Server)
Local server packaged with its runtime. No Node/Python needed on user machine.
**Choose when** server must run on user's machine:
- Reads local files
- Drives desktop apps
- Talks to localhost services
- Needs OS-level access
### Local stdio (Prototypes Only)
Script launched via `npx` / `uvx`. Fine for personal tools and prototypes.
**Not recommended for distribution** - users need runtime, no update mechanism.
---
## Phase 3: Pick Tool Design Pattern
### Pattern A: One Tool Per Action (Small Surface)
When action space is small (< ~15 operations), each gets a dedicated tool.
```
create_issue — Create a new issue
update_issue — Update an existing issue
search_issues — Search issues by query
add_comment — Add a comment
```
**Benefits:** Claude reads tool list once, knows exactly what's possible.
### Pattern B: Search + Execute (Large Surface)
When wrapping large APIs (dozens+ endpoints), use TWO tools:
```
search_actions — Return matching actions with IDs and schemas
execute_action — Run an action by ID with params
```
**Benefits:** Server holds catalog internally, context stays lean.
**Hybrid:** Promote 3-5 most-used actions to dedicated tools.
---
## Phase 4: Pick Framework
| Framework | Language | When to Use |
|-----------|----------|-------------|
| **FastMCP 3.x** | Python | Python preference, wrapping Python libraries |
| **TypeScript SDK** | TypeScript | Default choice, best spec coverage |
Both produce identical wire protocol.
---
## Phase 5: Scaffold Server
### FastMCP (Python)
```python
from fastmcp import FastMCP
mcp = FastMCP("server-name")
@mcp.tool
def my_tool(query: str) -> dict:
"""Tool description Claude sees."""
return process(query)
if __name__ == "__main__":
mcp.run() # stdio (default)
# mcp.run(transport="http", port=8000) # HTTP
```
### TypeScript SDK
```typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer({
name: "server-name",
version: "1.0.0"
});
server.tool("myTool", { query: z.string() }, async ({ query }) => ({
content: [{ type: "text", text: JSON.stringify(process(query)) }]
}));
server.connect(transport);
```
---
## Phase 6: Test and Publish
### Testing
```bash
# MCP Inspector - official testing tool
npx @modelcontextprotocol/inspector uv run python -m my_mcp
```
**Critical:** Log to stderr, NOT stdout (stdout is the protocol).
**Testing Before Release:**
1. Test ALL tools with MCP Inspector before releasing
2. Test with actual provider (e.g., real IMAP server) if wrapping external APIs
3. Verify environment variables are passed correctly
4. Check provider-specific quirks (see Provider Quirks section)
### Claude Code Plugin Deployment
When bundling MCP servers in Claude Code plugins:
#### The `cwd` Bug (Issue #17565)
**CRITICAL:** Claude Code ignores the `cwd` field in `.mcp.json`. Always use the `bash -c` workaround:
```json
{
"mcpServers": {
"my-server": {
"command": "bash",
"args": ["-c", "cd \"${CLAUDE_PLUGIN_ROOT}/my-server\" && exec uv run python -m my_mcp"]
}
}
}
```
#### Dependency Management
Use `uv run` for portable dependency management:
```json
"command": "bash",
"args": ["-c", "cd \"${CLAUDE_PLUGIN_ROOT}/server\" && exec uv run python -m server"]
```
This ensures dependencies are automatically installed from `pyproject.toml`.
#### Environment Variables
Only include **required** environment variables in `.mcp.json`. Optional variables should use defaults in code:
```python
# Bad - will fail if EMAIL_OAUTH2_TOKEN is empty
oauth2_token: str = Field(alias="OAUTH2_TOKEN")
# Good - optional with default
oauth2_token: str | None = Field(default=None, alias="OAUTH2_TOKEN")
```
For Pydantic settings, use `env_parse_none_str=""` to treat empty strings as None:
```python
model_config = SettingsConfigDict(
env_prefix="MY_",
env_parse_none_str="", # Empty strings become None
)
```
### Provider Quirks
When wrapping external services, test with the actual provider:
| Provider | Quirk | Solution |
|----------|-------|----------|
| iCloud IMAP | SEARCH returns status message instead of IDs | Check for "completed" in response |
| iCloud IMAP | LIST requires specific quoting | Use `list('""', '"*"')` |
| iCloud IMAP | FETCH returns bytearray | Handle both bytes and bytearray |
### Pre-submission Checklist
- Read/write tool split for destructive operations
- Required annotations on all tools
- Tool names under 128 characters
- No prompt injection in tool output
- Input validation on all parameters
- Tested with MCP Inspector
- Tested with actual provider (not just mocks)
### Distribution
- Submit to Anthropic Directory
- Create plugin wrapper for skills
- Document installation clearly
- Require `uv` for dependency management
---
## Security Essentials
| Priority | Practice |
|----------|----------|
| CRITICAL | Use stdio for local servers (no network) |
| CRITICAL | Require TLS for remote servers |
| CRITICAL | Validate all inputs (types, ranges, formats) |
| CRITICAL | Reject path traversal (`../`) |
| CRITICAL | Load credentials from environment only |
| CRITICAL | Never return secrets in tool output |
| HIGH | Run as non-root user |
| HIGH | Use argument lists, never shell strings |
---
## Additional Resources
### Reference Files
Consult these for detailed implementation guidance:
- **`references/fastmcp-patterns.md`** — FastMCP decorator patterns, type hints, context injection
- **`references/security-best-practices.md`** — Input validation, credential management, path traversal prevention
- **`references/testing-debugging.md`** — MCP Inspector, stderr logging, CI/CD integration
- **`references/deployment-options.md`** — stdio, HTTP/SSE, Cloudflare Workers, Docker, MCPB
### External Links
- [MCP Specification](https://modelcontextprotocol.io/specification/latest)
- [FastMCP Documentation](https://gofastmcp.com/)
- [MCP Python SDK](https://py.sdk.modelcontextprotocol.io/)
---
> Source: [christophevg/c3](https://github.com/christophevg/c3) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->
章节与文件索引
按说明文件中的顺序排列。
概述
第一阶段:发现
1.它连接到什么?
2. 谁会使用它?
3. 有多少个不同的动作?
文件/命令 -> npx · uvx · cwd · .mcp.json · bash -c · uv run · pyproject.toml · env_parse_none_str=""
内容校验值 -> 615bf40b8f20
当前原文的自动摘译,尚未人工审校。
概述
MCP 服务器使用标准化协议将 Claude 与外部系统连接起来。提供三种原语: 原语 · 控制者 · 目的工具 · 模型 (Claude) · 克劳德可以调用的函数 资源 · 应用程序 · 克劳德可以读取的上下文数据 提示 · 用户 · 用户可以调用的模板
1.它连接到什么?
连接类型 · 推荐方法 云 API(SaaS、REST、GraphQL) · 远程 HTTP 服务器 本地进程、文件系统、桌面应用程序 · MCPB 或本地 stdio 硬件、操作系统级 API · MCPB 纯逻辑/计算 · 任一 - 默认为远程
2. 谁会使用它?
只有我/我的团队 → 本地 stdio 可接受任何安装它的人 → 远程 HTTP(首选)或带有 UI 小部件的 MCPB Claude 桌面 → MCP 应用程序
3. 有多少个不同的动作?
大约 15 个操作 → 每个操作一个工具 数十到数百个 → 搜索 + 执行模式