MCP 服务器开发协议

其他资源

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); // Add 100ms buffer
  });
}

  • 实施适当的速率限制

  • 添加智能缓存

  • 提供优雅降级

  • 添加有关速率限制的透明错误

解决方案 ：

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

API 速率限制

  • 使用可用端点实现回退

  • 在必要时创建模拟功能

  • 转换 API 数据以满足您的需求

解决方案 ：

挑战 ：API 可能无法提供您需要的所有功能。

缺少或有限的 API 功能

// Authenticate using API key from environment
const API_KEY = process.env.ALPHAVANTAGE_API_KEY;
if (!API_KEY) {
  console.error("[Error] Missing ALPHAVANTAGE_API_KEY environment variable");
  process.exit(1);
}

// Initialize API client
const apiClient = new AlphaAdvantageClient({
  apiKey: API_KEY
});

复制

  • 对于 API 密钥，请使用 MCP 配置中的环境变量

  • 对于 OAuth，创建单独的脚本来获取刷新令牌

  • 安全存储敏感令牌

解决方案 ：

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

API 身份验证的复杂性

常见挑战和解决方案

资源使您的 MCP 服务器更加了解上下文，使 Cline-胜算云增强版无需您复制/粘贴即可访问特定信息。更多信息，请参阅官方文档 。

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");
});

  1. 实现读取处理程序来传递内容：

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

  1. 定义您的服务器将公开的资源 ：

向您的 MCP 服务器添加资源

资源允许您的 MCP 服务器无需执行代码即可向Cline-胜算云增强版公开数据。它们非常适合提供 Cline-胜算云增强版在对话过程中可以引用的上下文信息，例如文件、API 响应或数据库记录。

MCP 资源

try {
  switch (request.params.name) {
    case "get_stock_overview": {
      // Implementation...
    }
    
    // Other cases...
    
    default:
      throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
  }
} catch (error) {
  console.error(`[Error] Tool execution failed: ${error instanceof Error ? error.message : String(error)}`);
  
  if (error instanceof McpError) {
    throw error;
  }
  
  return {
    content: [{
      type: "text",
      text: `Error: ${error instanceof Error ? error.message : String(error)}`
    }],
    isError: true
  };
}

实施强大的错误处理以保持良好的用户体验：

优雅的错误处理

// Default cache TTL in seconds
const DEFAULT_CACHE_TTL = {
  STOCK_OVERVIEW: 60 * 60, // 1 hour
  TECHNICAL_ANALYSIS: 60 * 30, // 30 minutes
  FUNDAMENTAL_ANALYSIS: 60 * 60 * 24, // 24 hours
  EARNINGS_REPORT: 60 * 60 * 24, // 24 hours
  NEWS: 60 * 15, // 15 minutes
};

// Check cache first
const cachedData = this.cache.get<T>(cacheKey);
if (cachedData) {
  console.error(`[Cache] Using cached data for: ${cacheKey}`);
  return cachedData;
}

// Cache successful responses
this.cache.set(cacheKey, response.data, cacheTTL);

减少 API 调用并提高性能：

智能缓存

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

/**
 * Validate that a stock symbol is provided and looks valid
 */
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");
  }
  
  // Basic symbol validation (letters, numbers, dots)
  const symbolRegex = /^[A-Za-z0-9.]+$/;
  if (!symbolRegex.test(symbol)) {
    throw new McpError(ErrorCode.InvalidParams, `Invalid stock symbol: ${symbol}`);
  }
}

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

强类型

// Start-up logging
console.error('[Setup] Initializing AlphaAdvantage MCP server...');

// API request logging 
console.error(`[API] Getting stock overview for ${symbol}`);

// Error handling with context
console.error(`[Error] Tool execution failed: ${error.message}`);

// Cache operations
console.error(`[Cache] Using cached data for: ${cacheKey}`);

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

综合测井

核心实施最佳实践

  1. 规划 API 限制 ：从一开始就了解并围绕 API 速率限制进行设计

  2. 策略性缓存 ：识别高价值缓存机会以提高性能

  3. 可读性格式 ：投资良好的数据格式以改善用户体验

  4. 测试每条路径 ：完成之前单独测试所有工具

  5. 处理 API 复杂性 ：对于需要多次调用的 API，设计具有更简单范围的工具

AlphaAdvantage 的实施给我们带来了几个重要的教训：

经验教训

  1. API 速率限制 ：

    • 挑战 ：免费套餐每分钟仅限 5 次通话

    • 解决方案 ：实施排队、强制速率限制并添加全面缓存

  2. 数据格式 ：

    • 挑战 ：原始 API 数据不够用户友好

    • 解决方案 ：创建格式化实用程序，以一致地显示财务数据

  3. 超时问题 ：

    • 挑战 ：进行多次 API 调用的复杂工具可能会超时

    • 解决方案 ：建议将复杂的工具分解成更小的部分，优化缓存

在开发过程中，我们遇到了几个挑战：

挑战与解决方案

  • get_stock_overview ：检索 AAPL 股票概览信息

    复制

    # AAPL (Apple Inc) - $241.84 ↑+1.91%

**Sector:** TECHNOLOGY
**Industry:** ELECTRONIC COMPUTERS
**Market Cap:** 3.63T
**P/E Ratio:** 38.26
...

  • get_technical_analysis ：获取价格行为和 RSI 数据

    复制

    # Technical Analysis: AAPL

## Daily Price Action

Current Price: $241.84 (↑$4.54, +1.91%)

### Recent Daily Prices

| Date | Open | High | Low | Close | Volume |
|------|------|------|-----|-------|--------|
| 2025-02-28 | $236.95 | $242.09 | $230.20 | $241.84 | 56.83M |
...

  • get_earnings_report ：检索 MSFT 收益历史记录和格式化报告

    复制

    # Earnings Report: MSFT (Microsoft Corporation)

**Sector:** TECHNOLOGY
**Industry:** SERVICES-PREPACKAGED SOFTWARE
**Current EPS:** $12.43

## Recent Quarterly Earnings

| Quarter | Date | EPS Estimate | EPS Actual | Surprise % |
|---------|------|-------------|------------|------------|
| 2024-12-31 | 2025-01-29 | $3.11 | $3.23 | ↑4.01% |
...

  1. 然后我们分别测试了每个工具：

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

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

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

测试阶段

  • 输入验证

  • 具有错误处理的 API 客户端调用

  • Markdown 格式的响应

  • 综合日志记录

每个工具的处理程序包括：

server.setRequestHandler(ListToolsRequestSchema, async () => {
  console.error("[Setup] Listing available tools");
  
  return {
    tools: [
      {
        name: "get_stock_overview",
        description: "Get basic company info and current quote for a stock symbol",
        inputSchema: {
          type: "object",
          properties: {
            symbol: {
              type: "string",
              description: "Stock symbol (e.g., 'AAPL')"
            },
            market: {
              type: "string",
              description: "Optional market (e.g., 'US')",
              default: "US"
            }
          },
          required: ["symbol"]
        }
      },
      // Additional tools defined here...
    ]
  };
});

我们定义了五种具有清晰界面的工具：

工具实现

/**
 * Format company overview into markdown
 */
export function formatStockOverview(overviewData: any, quoteData: any): string {
  // Extract data
  const overview = overviewData;
  const quote = quoteData["Global Quote"];
  
  // Calculate price change
  const currentPrice = parseFloat(quote["05. price"] || "0");
  const priceChange = parseFloat(quote["09. change"] || "0");
  const changePercent = parseFloat(quote["10. change percent"]?.replace("%", "") || "0");
  
  // Format markdown
  let markdown = `# ${overview.Symbol} (${overview.Name}) - ${formatCurrency(currentPrice)} ${addTrendIndicator(priceChange)}${changePercent > 0 ? '+' : ''}${changePercent.toFixed(2)}%\n\n`;
  
  // Add more details...
  
  return markdown;
}

我们实现了格式化程序来美观地显示财务数据：

Markdown 格式

/**
 * Manage rate limiting based on free tier (5 calls per minute)
 */
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); // Add 100ms buffer
    });
  }
  
  this.requestsThisMinute++;
  return Promise.resolve();
}

关键实施细节：

  • 速率限制 ：强制执行每分钟 5 个请求的限制

  • 缓存 ：通过策略缓存减少 API 调用

  • 错误处理 ：强大的错误检测和报告

  • 类型接口 ：清除所有数据的 TypeScript 类型

API 客户端实现包括：

API 客户端实现

src/
  ├── api/
  │   └── alphaAdvantageClient.ts  # API client with rate limiting & caching
  ├── formatters/
  │   └── markdownFormatter.ts     # Output formatters for clean markdown
  └── index.ts                     # Main MCP server implementation

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

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

我们首先启动了这个项目：

执行

  1. 定义问题 ：用户需要通过他们的人工智能助手直接访问财务数据、股票分析和市场洞察

  2. 选择的 API ：用于金融市场数据的 AlphaAdvantage API

    • 标准 API 密钥认证

    • 每分钟 5 个请求的速率限制（免费套餐）

    • 不同财务数据类型的各种端点

  3. 设计所需的工具 ：

    • 股票概览信息（当前价格、公司详情）

    • 利用指标进行技术分析（RSI、MACD 等）

    • 基本面分析（财务报表、比率）

    • 收益报告数据

    • 新闻和情绪分析

  4. 计划数据格式 ：

    • 干净、格式良好的 Markdown 输出

    • 结构化数据表

    • 趋势的视觉指标（↑/↓）

    • 财务数字的正确格式

在规划阶段，我们：

规划阶段

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

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

  • 设置项目结构

  • 编写实现代码

  • 配置设置

  • 彻底测试每个组件

  • 完成文档

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

行动模式

  • 定义问题范围

  • 选择合适的 API

  • 规划身份验证方法

  • 设计工具界面

  • 确定数据格式

在此协作阶段，您将与 Cline 合作设计您的 MCP 服务器：

计划模式

理解两种模式

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

Here's the API documentation for the service:
[Paste API documentation here]

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

4.尽早提供 API 文档

准备就绪后，使用聊天底部的开关切换到 ACT MODE 开始实施。

  • 讨论问题范围

  • 审查 API 文档

  • 规划身份验证方法

  • 设计工具界面

Cline 将自动以计划模式启动，指导您完成规划过程：

3. 按照协议进行工作

I want to build an MCP server for the AlphaAdvantage financial API.
It should allow me to get real-time stock data, perform technical 
analysis, and retrieve company financial information.

例如：

  • MCP 服务器的用途

  • 您想要集成哪个 API 或服务

  • 您需要的任何特定工具或功能

在与 Cline-胜算云增强版聊天的开头，清晰地描述你想要构建的内容。具体来说：

2. 用清晰的描述开始聊天

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

1. 创建一个 .clinerules 文件（🚨重要）

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

入门

  1. 在实施之前，先从计划模式开始设计您的服务器

  2. 在 ACT 模式下强制执行正确的实施模式

  3. 要求在完成之前测试所有工具

  4. 指导您完成整个开发生命周期

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

# MCP Server Development Protocol

⚠️ CRITICAL: DO NOT USE attempt_completion BEFORE TESTING ⚠️

## Step 1: Planning (PLAN MODE)
- What problem does this tool solve?
- What API/service will it use?
- What are the authentication requirements?
  □ Standard API key
  □ OAuth (requires separate setup script)
  □ Other credentials

## Step 2: Implementation (ACT MODE)
1. Bootstrap
   - For web services, JavaScript integration, or Node.js environments:
     ```bash
     npx @modelcontextprotocol/create-server my-server
     cd my-server
     npm install
     ```
   - For data science, ML workflows, or Python environments:
     ```bash
     pip install mcp
     # Or with uv (recommended)
     uv add "mcp[cli]"
     ```

2. Core Implementation
   - Use MCP SDK
   - Implement comprehensive logging
     - TypeScript (for web/JS projects):
       ```typescript
       console.error('[Setup] Initializing server...');
       console.error('[API] Request to endpoint:', endpoint);
       console.error('[Error] Failed with:', error);
       ```
     - Python (for data science/ML projects):
       ```python
       import logging
       logging.error('[Setup] Initializing server...')
       logging.error(f'[API] Request to endpoint: {endpoint}')
       logging.error(f'[Error] Failed with: {str(error)}')
       ```
   - Add type definitions
   - Handle errors with context
   - Implement rate limiting if needed

3. Configuration
   - Get credentials from user if needed
   - Add to MCP settings:
     - For TypeScript projects:
       ```json
       {
         "mcpServers": {
           "my-server": {
             "command": "node",
             "args": ["path/to/build/index.js"],
             "env": {
               "API_KEY": "key"
             },
             "disabled": false,
             "autoApprove": []
           }
         }
       }
       ```
     - For Python projects:
       ```bash
       # Directly with command line
       mcp install server.py -v API_KEY=key
       
       # Or in settings.json
       {
         "mcpServers": {
           "my-server": {
             "command": "python",
             "args": ["server.py"],
             "env": {
               "API_KEY": "key"
             },
             "disabled": false,
             "autoApprove": []
           }
         }
       }
       ```

## Step 3: Testing (BLOCKER ⛔️)

<thinking>
BEFORE using attempt_completion, I MUST verify:
□ Have I tested EVERY tool?
□ Have I confirmed success from the user for each test?
□ Have I documented the test results?

If ANY answer is "no", I MUST NOT use attempt_completion.
</thinking>

1. Test Each Tool (REQUIRED)
   □ Test each tool with valid inputs
   □ Verify output format is correct
   ⚠️ DO NOT PROCEED UNTIL ALL TOOLS TESTED

## Step 4: Completion
❗ STOP AND VERIFY:
□ Every tool has been tested with valid inputs
□ Output format is correct for each tool

Only after ALL tools have been tested can attempt_completion be used.

## Key Requirements
- ✓ Must use MCP SDK
- ✓ Must have comprehensive logging
- ✓ Must test each tool individually
- ✓ Must handle errors gracefully
- ⛔️ NEVER skip testing before completion

这是完整的 MCP 服务器开发协议，应放在您的 .clinerules 文件中：

  • 配置 Cline-胜算云增强版的行为并实施最佳实践

  • 将 Cline-胜算云增强版切换为专门的 MCP 开发模式

  • 提供构建服务器的分步协议

  • 实施安全措施，例如防止过早完成

  • 指导您完成规划、实施和测试阶段

.clinerules 文件是一种特殊的配置，Cline 在其所在目录中工作时会自动读取它。这些文件：

使用 .clinerules 文件

高效 MCP 服务器开发的核心在于遵循结构化协议。该协议通过位于 MCP 工作目录根目录 (/Users/your-name/Documents/Cline/MCP) 的 .clinerules 文件实现。

开发协议

没有 MCP，AI 助手虽然功能强大，但却显得孤立。有了 MCP，它们就能与几乎任何数字系统进行交互。

  • 访问外部 API 和服务

  • 检索实时数据

  • 控制应用程序和本地系统

  • 执行超出文本提示所能实现的操作

模型上下文协议 (MCP) 服务器扩展了 Cline 等 AI 助手的功能，使其能够：

什么是 MCP 服务器？

🚀 搭建并与全世界分享您的 MCP 服务器。 创建好 MCP 服务器后，请将其提交至 Cline MCP 市场让成千上万的开发人员可以发现它并一键安装它。

该协议旨在简化使用 Cline-胜算云增强版构建 MCP 服务器的开发过程。

PreviousMCP 传输机制NextMCP Overview

Last updated