MCP 开发最佳实践

什么是 MCP？

Model Context Protocol (MCP) 是 Anthropic 推出的开放协议，让 AI 助手能够与外部工具和数据源交互。作为 AI Engineer，掌握 MCP 开发是核心技能。

I. General Tool Configuration & Behavior

1. Sensible Defaults

All environment variables must have sensible defaults for easy out-of-the-box usage.

2. Dynamic Versioning

The tool's version is emitted in its description. This version must be read dynamically (e.g., from package.json) and not hardcoded.

3. Tool & Parameter Descriptions

Tool Titles: Use descriptive, human-friendly titles for tools.
Parameter Descriptions: All parameters must offer a clear description.
Optional/Required Parameters: Parameters must be explicitly noted as "optional" or "required."
Default Values: If a parameter is optional, its default value must be explained.

4. Parameter Parsing

Parameter parsing should be lenient (e.g., accept path if project_path is formally defined). Generally, advertise stricter schemas but be more lenient in execution to accommodate variations from agents.

5. Runtime Error Handling

In case of an error, emit a helpful message to the caller with information to potentially recover.

6. Configuration Error Handling

Misconfigurations (e.g., wrongly set environment variables) must not crash the tool. Instead, provide a useful explanation when the tool is run, enabling the user to self-correct their setup.

7. No stdio Output

CRITICAL: There must be absolutely NO output to stdout or stderr during any tool operation. This includes:

No console.log(), console.error(), console.warn(), etc.
No process.stdout.write() or process.stderr.write()
No print statements or debug output to stdio
Even during errors or initialization, all output must go through the file logger
Any stdio output will disrupt MCP clients (like Claude) and cause loading errors
File-based logging (e.g., Pino to log files) is the only acceptable method

8. `info` Command

At least one tool must offer an info sub command (find the most appropriate tool and add there). This command shall list:

The version of the MCP tool.
The status of any required native dependencies (if applicable)
Any detected configuration issues or missing environment variables

II. Logging (Pino)

正确的日志配置对于调试和运维至关重要：

Default File Logger: Pino is used for logging with a default file logger in the system's log directory (e.g., ~/Library/Logs/). The log file path is configurable via the [ProjectName]_LOG_FILE environment variable.
Log Path Resilience:
- Pino logic must automatically create missing parent directories for the specified log file path.
- If pino cannot write to the [ProjectName]_LOG_FILE path, it must fall back to logging to the default temporary directory path.
Configurable Log Level: The log level is set using the [ProjectName]_LOG_LEVEL environment variable (accepts upper, lower, or mixed case values).
Optional Console Logging: An environment variable, [ProjectName]_CONSOLE_LOGGING=true, enables logging to the console in addition to the pino file logger.
Logger Flush: The logger must be flushed before the process exits to ensure all log messages are written.

III. Code, Dependencies & Build

代码质量和构建配置的最佳实践：

Dependency Management: All dependencies should be kept at their latest stable versions.
Static Analysis: There must be no linter (e.g., ESLint) or TypeScript errors.
File Size: No single file should exceed 500 lines of code (LOC); aim for below 300 LOC.
Execution with Compiled Code: The startup logic and all tool operations must always use the compiled JavaScript output (e.g., from the dist folder).
Shebangs: Compiled JavaScript files intended for direct execution must have the correct shebang:

#!/usr/bin/env node

NPM Package Contents: The published npm package must contain only the absolute minimum files: the dist/ folder, any potential native components, the README.md, and a LICENSE file.

IV. Testing

测试是确保 MCP 工具质量的关键：

Test Framework: Tests must use vitest.
TypeScript Test Suite: A comprehensive test suite for the TypeScript layer is required.
End-to-End (E2E) Tests: E2E tests that validate the complete setup are necessary.
NPM Scripts:
- npm run prepare-release executes a comprehensive test suite
- npm run inspector executes npx @modelcontextprotocol/inspector node path/to/server/index.js

V. Native Binary Rules (If Applicable)

如果你的 MCP 工具包含原生二进制文件：

macOS Compatibility: The binary must be universal (Apple Silicon & Intel) and support macOS >= n-1.
Build Optimization: Compiler and linker flags must be set to achieve a minimal binary file size.
Version Synchronization: The native CLI and the MCP tool (TypeScript package) must have the same version number.
JSON Communication: The native binary part of the tool must have a mode to communicate in JSON back to the TypeScript server for easier parsing.
CLI Help Command: The binary must respond to --help with a helpful command explaining its use and all options.

VI. Release Checklist

发布前的完整检查清单：

Git & Version Control

Check current branch (main or designated release branch)
Check for uncommitted changes
Check if synced with origin/main
Version availability check
Version consistency between package.json and package-lock.json
Changelog entry for current version

Code Quality & Security

Dependency installation check
Outdated dependencies check
Security audit (fails on critical/high vulnerabilities)
TypeScript compilation
TypeScript tests
TypeScript declaration files generation
No build warnings

Package Validation

Required fields in package.json
Package size check (warns if >2MB)
Critical files included (dist/index.js, README.md, LICENSE)
MCP server smoke test (JSON-RPC request/response)
Full integration tests

实践建议

先做 info 命令 - 帮助用户诊断问题
日志优先于 console - 避免干扰 MCP 通信
容错设计 - 错误不应导致崩溃
版本一致性 - 保持各组件版本同步

下一步

学习 MCP 发布流程了解如何将你的 MCP 工具发布到 NPM。

MCP 开发最佳实践

注册解锁完整内容