> ## Documentation Index
> Fetch the complete documentation index at: https://cat.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP 服务器开发协议

> 本协议旨在简化使用 Cline 构建 MCP 服务器的开发过程。

> 🚀 **构建并与世界分享你的 MCP 服务器。** 创建出色的 MCP 服务器后，将其提交到 [Cline MCP 市场](https://github.com/cline/mcp-marketplace)，让成千上万的开发者可以发现并一键安装。

## 什么是 MCP 服务器？

模型上下文协议（MCP）服务器通过赋予 AI 助手如 Cline 以下能力来扩展它们：

* 访问外部 API 和服务
* 检索实时数据
* 控制应用程序和本地系统
* 执行仅凭文本提示无法实现的操作

没有 MCP，AI 助手虽然强大但孤立。有了 MCP，它们获得了与几乎任何数字系统交互的能力。

## 开发协议

有效 MCP 服务器开发的核心是遵循结构化协议。此协议通过位于你的 MCP 工作目录根目录（/Users/your-name/Documents/Cline/MCP）的 `.clinerules` 文件实现。

### 使用 `.clinerules` 文件

`.clinerules` 文件是一个特殊配置，Cline 在工作于放置该文件的目录时会自动读取。这些文件：

* 配置 Cline 的行为并强制执行最佳实践
* 将 Cline 切换到专用的 MCP 开发模式
* 提供构建服务器的分步协议
* 实施安全措施，如防止过早完成
* 指导你完成规划、实施和测试阶段

以下是应放置在你的 `.clinerules` 文件中的完整 MCP 服务器开发协议：

````markdown
# MCP 服务器开发协议

⚠️ 关键：测试前不要使用 attempt_completion ⚠️

## 步骤 1：规划（计划模式）

-   这个工具解决什么问题？
-   它将使用什么 API/服务？
-   身份验证要求是什么？
    □ 标准 API 密钥
    □ OAuth（需要单独的设置脚本）
    □ 其他凭据

## 步骤 2：实施（操作模式）

1. 引导

    - 对于 Web 服务、JavaScript 集成或 Node.js 环境：
        ```bash
        npx @modelcontextprotocol/create-server my-server
        cd my-server
        npm install
        ```
    - 对于数据科学、ML 工作流或 Python 环境：
        ```bash
        pip install mcp
        # 或使用 uv（推荐）
        uv add "mcp[cli]"
        ```

2. 核心实施

    - 使用 MCP SDK
    - 实施全面日志记录
        - TypeScript（用于 web/JS 项目）：
            ```typescript
            console.error("[Setup] Initializing server...")
            console.error("[API] Request to endpoint:", endpoint)
            console.error("[Error] Failed with:", error)
            ```
        - Python（用于数据科学/ML 项目）：
            ```python
            import logging
            logging.error('[Setup] Initializing server...')
            logging.error(f'[API] Request to endpoint: {endpoint}')
            logging.error(f'[Error] Failed with: {str(error)}')
            ```
    - 添加类型定义
    - 处理带上下文的错误
    - 如需要，实施速率限制

3. 配置

    - 如需要，从用户获取凭据
    - 添加到 MCP 设置：

        - 对于 TypeScript 项目：
            ```json
            {
            	"mcpServers": {
            		"my-server": {
            			"command": "node",
            			"args": ["path/to/build/index.js"],
            			"env": {
            				"API_KEY": "key"
            			},
            			"disabled": false,
            			"autoApprove": []
            		}
            	}
            }
            ```
        - 对于 Python 项目：

            ```bash
            # 直接通过命令行
            mcp install server.py -v API_KEY=key

            # 或在 settings.json 中
            {
              "mcpServers": {
                "my-server": {
                  "command": "python",
                  "args": ["server.py"],
                  "env": {
                    "API_KEY": "key"
                  },
                  "disabled": false,
                  "autoApprove": []
                }
              }
            }
            ```

## 步骤 3：测试（阻塞器 ⛔️）

<thinking>
在使用 attempt_completion 之前，我必须验证：
□ 我是否测试了每个工具？
□ 我是否确认了用户对每个测试的成功？
□ 我是否记录了测试结果？

如果任何答案是"否"，我绝不能使用 attempt_completion。
</thinking>

1. 测试每个工具（必需）
   □ 使用有效输入测试每个工具
   □ 验证输出格式正确
   ⚠️ 在所有工具测试完成前不要继续

## 步骤 4：完成

❗ 停止并验证：
□ 每个工具都已使用有效输入测试
□ 每个工具的输出格式正确

只有在所有工具都已测试后才能使用 attempt_completion。

## 关键要求

-   ✓ 必须使用 MCP SDK
-   ✓ 必须有全面的日志记录
-   ✓ 必须单独测试每个工具
-   ✓ 必须优雅处理错误
-   ⛔️ 完成前绝不跳过测试
````

当此 `.clinerules` 文件存在于你的工作目录中时，Cline 将：

1. 在**计划模式**中开始，在实施前设计你的服务器
2. 在**操作模式**中强制执行正确的实施模式
3. 在允许完成前要求测试所有工具
4. 指导你完成整个开发生命周期

## 入门指南

创建 MCP 服务器只需几个简单步骤即可开始：

### 1. 创建 `.clinerules` 文件（🚨 重要）

首先，使用上述协议在你的 MCP 工作目录根目录添加 `.clinerules` 文件。此文件配置 Cline 在此文件夹中工作时使用 MCP 开发协议。

### 2. 以清晰的描述开始聊天

通过清楚描述你想要构建的内容来开始你的 Cline 聊天。具体说明：

* 你的 MCP 服务器的目的
* 你想要集成的 API 或服务
* 你需要的任何特定工具或功能

例如：

```plaintext
我想为 AlphaAdvantage 金融 API 构建一个 MCP 服务器。
它应该允许我获取实时股票数据、进行技术分析
和检索公司财务信息。
```

### 3. 按协议工作

Cline 将自动在计划模式中开始，指导你完成规划过程：

* 讨论问题范围
* 审查 API 文档
* 规划身份验证方法
* 设计工具接口

准备好后，使用聊天底部的切换按钮切换到操作模式开始实施。

### 4. 及早提供 API 文档

帮助 Cline 构建你的 MCP 服务器的最有效方法之一是在开始时就分享官方 API 文档：

```plaintext
这里是服务的 API 文档：
[在此粘贴 API 文档]
```

提供全面的 API 详细信息（端点、身份验证、数据结构）显著提高了 Cline 实施有效 MCP 服务器的能力。

## 理解两种模式

### 计划模式

在此协作阶段，你与 Cline 一起设计你的 MCP 服务器：

* 定义问题范围
* 选择适当的 API
* 规划身份验证方法
* 设计工具接口
* 确定数据格式

### 操作模式

完成规划后，Cline 帮助实施服务器：

* 设置项目结构
* 编写实施代码
* 配置设置
* 彻底测试每个组件
* 完成文档

## 案例研究：AlphaAdvantage 股票分析服务器

让我们走过我们的 AlphaAdvantage MCP 服务器的开发过程，它提供股票数据分析和报告功能。

### 规划阶段

在规划阶段，我们：

1. **定义了问题**：用户需要通过他们的 AI 助手直接访问金融数据、股票分析和市场洞察
2. **选择了 API**：用于金融市场数据的 AlphaAdvantage API
   * 标准 API 密钥身份验证
   * 每分钟 5 次请求的速率限制（免费层）
   * 用于不同金融数据类型的各种端点
3. **设计了所需的工具**：
   * 股票概览信息（当前价格、公司详情）
   * 带指标的技术分析（RSI、MACD 等）
   * 基本面分析（财务报表、比率）
   * 收益报告数据
   * 新闻和情绪分析
4. **规划了数据格式**：
   * 清洁、格式良好的 markdown 输出
   * 结构化数据表格
   * 趋势视觉指标（↑/↓）
   * 金融数字的正确格式

### 实施

我们首先引导项目：

```bash
npx @modelcontextprotocol/create-server alphaadvantage-mcp
cd alphaadvantage-mcp
npm install axios node-cache
```

接下来，我们构建了项目结构：

```plaintext
src/
  ├── api/
  │   └── alphaAdvantageClient.ts  # 带速率限制和缓存的 API 客户端
  ├── formatters/
  │   └── markdownFormatter.ts     # 清洁 markdown 的输出格式化器
  └── index.ts                     # 主 MCP 服务器实施
```

#### API 客户端实施

API 客户端实施包括：

* **速率限制**：强制执行每分钟 5 次请求限制
* **缓存**：通过策略性缓存减少 API 调用
* **错误处理**：强健的错误检测和报告
* **类型接口**：所有数据的清晰 TypeScript 类型

关键实施细节：

```typescript
/**
 * 基于免费层管理速率限制（每分钟 5 次调用）
 */
private async enforceRateLimit() {
  if (this.requestsThisMinute >= 5) {
    console.error("[Rate Limit] Rate limit reached. Waiting for next minute...");
    return new Promise<void>((resolve) => {
      const remainingMs = 60 * 1000 - (Date.now() % (60 * 1000));
      setTimeout(resolve, remainingMs + 100); // 添加 100ms 缓冲
    });
  }

  this.requestsThisMinute++;
  return Promise.resolve();
}
```

### 测试阶段

这个关键阶段涉及系统性地测试每个工具：

1. 首先，我们在设置中配置了 MCP 服务器：

```json
{
	"mcpServers": {
		"alphaadvantage-mcp": {
			"command": "node",
			"args": ["/path/to/alphaadvantage-mcp/build/index.js"],
			"env": {
				"ALPHAVANTAGE_API_KEY": "YOUR_API_KEY"
			},
			"disabled": false,
			"autoApprove": []
		}
	}
}
```

## 核心实施最佳实践

### 全面日志记录

有效的日志记录对于调试 MCP 服务器至关重要：

```typescript
// 启动日志记录
console.error("[Setup] Initializing AlphaAdvantage MCP server...")

// API 请求日志记录
console.error(`[API] Getting stock overview for ${symbol}`)

// 带上下文的错误处理
console.error(`[Error] Tool execution failed: ${error.message}`)

// 缓存操作
console.error(`[Cache] Using cached data for: ${cacheKey}`)
```

### 强类型

类型定义防止错误并提高可维护性：

```typescript
export interface AlphaAdvantageConfig {
	apiKey: string
	cacheTTL?: Partial<typeof DEFAULT_CACHE_TTL>
	baseURL?: string
}

/**
 * 验证提供了股票符号且看起来有效
 */
function validateSymbol(symbol: unknown): asserts symbol is string {
	if (typeof symbol !== "string" || symbol.trim() === "") {
		throw new McpError(ErrorCode.InvalidParams, "A valid stock symbol is required")
	}

	// 基本符号验证（字母、数字、点）
	const symbolRegex = /^[A-Za-z0-9.]+$/
	if (!symbolRegex.test(symbol)) {
		throw new McpError(ErrorCode.InvalidParams, `Invalid stock symbol: ${symbol}`)
	}
}
```

### 智能缓存

减少 API 调用并提高性能：

```typescript
// 默认缓存 TTL（秒）
const DEFAULT_CACHE_TTL = {
	STOCK_OVERVIEW: 60 * 60, // 1 小时
	TECHNICAL_ANALYSIS: 60 * 30, // 30 分钟
	FUNDAMENTAL_ANALYSIS: 60 * 60 * 24, // 24 小时
	EARNINGS_REPORT: 60 * 60 * 24, // 24 小时
	NEWS: 60 * 15, // 15 分钟
}

// 首先检查缓存
const cachedData = this.cache.get<T>(cacheKey)
if (cachedData) {
	console.error(`[Cache] Using cached data for: ${cacheKey}`)
	return cachedData
}

// 缓存成功响应
this.cache.set(cacheKey, response.data, cacheTTL)
```

## MCP 资源

资源让你的 MCP 服务器向 Cline 暴露数据而无需执行代码。它们非常适合提供文件、API 响应或数据库记录等上下文，Cline 可以在对话中引用这些内容。

### 向你的 MCP 服务器添加资源

1. **定义你的服务器将暴露的资源**：

```typescript
server.setRequestHandler(ListResourcesRequestSchema, async () => {
	return {
		resources: [
			{
				uri: "file:///project/readme.md",
				name: "Project README",
				mimeType: "text/markdown",
			},
		],
	}
})
```

2. **实施读取处理程序**以传递内容：

```typescript
server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
	if (request.params.uri === "file:///project/readme.md") {
		const content = await fs.promises.readFile("/path/to/readme.md", "utf-8")
		return {
			contents: [
				{
					uri: request.params.uri,
					mimeType: "text/markdown",
					text: content,
				},
			],
		}
	}

	throw new Error("Resource not found")
})
```

资源使你的 MCP 服务器更具上下文感知能力，允许 Cline 访问特定信息而无需你复制/粘贴。有关更多信息，请参考[官方文档](https://modelcontextprotocol.io/docs/concepts/resources)。

## 常见挑战和解决方案

### API 身份验证复杂性

**挑战**：API 通常有不同的身份验证方法。

**解决方案**：

* 对于 API 密钥，在 MCP 配置中使用环境变量
* 对于 OAuth，创建单独的脚本获取刷新令牌
* 安全存储敏感令牌

### 缺失或有限的 API 功能

**挑战**：API 可能不提供你需要的所有功能。

**解决方案**：

* 使用可用端点实施回退
* 必要时创建模拟功能
* 转换 API 数据以匹配你的需求

### API 速率限制

**挑战**：大多数 API 都有可能导致失败的速率限制。

**解决方案**：

* 实施适当的速率限制
* 添加智能缓存
* 提供优雅降级
* 添加关于速率限制的透明错误

## 其他资源

* [MCP 协议文档](https://github.com/modelcontextprotocol/mcp)
* [MCP SDK 文档](https://github.com/modelcontextprotocol/sdk-js)
* [MCP 服务器示例](https://github.com/modelcontextprotocol/servers)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.