# MCP 服务器开发协议
⚠️ 重要：未测试前禁止使用 attempt_completion
 
## 步骤 1：规划（PLAN MODE）
- 该工具解决什么问题？
- 将使用哪个 API/服务？
- 认证需求？
  □ 标准 API key
  □ OAuth（需单独脚本）
  □ 其他凭证
 
## 步骤 2：实现（ACT MODE）
1. 初始化
   - Web 服务/JS/Node.js 环境：
     ```bash
     npx @modelcontextprotocol/create-server my-server
     cd my-server
     npm install

当该 `.clinerules` 文件存在于工作目录时，Cline 会：

1. 以 **PLAN MODE** 启动，先设计服务器
2. 在 **ACT MODE** 强制规范实现
3. 要求所有工具测试通过后才允许完成
4. 全程引导你完成开发生命周期

---

## 快速开始

开发 MCP 服务器只需几个简单步骤：

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

首先，将上述协议内容保存为 `.clinerules` 文件，放在 MCP 工作目录根目录。此文件会让 Cline 按开发协议工作。

### 2. 发起清晰描述的对话

在 Cline 聊天中，明确描述你要构建的内容，包括：

- 服务器用途
- 需集成的 API 或服务
- 所需工具或功能

示例：

```text
我想为 AlphaAdvantage 金融 API 构建一个 MCP 服务器，能获取实时股票数据、做技术分析、查询公司财报信息。

这是该服务的 API 文档：[粘贴 API 文档]

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

src/
  ├── api/
  │   └── alphaAdvantageClient.ts   # API 客户端，含限流与缓存
  ├── formatters/
  │   └── markdownFormatter.ts      # Markdown 格式化输出
  └── index.ts                      # MCP 服务器主实现

/** 管理免费版限流（每分钟 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();
}

/** 将公司概览格式化为 markdown */
export function formatStockOverview(overviewData: any, quoteData: any): string {
  // 提取数据
  const overview = overviewData;
  const quote = quoteData["Global Quote"];
  // 计算价格变动
  const currentPrice = parseFloat(quote["05. price"] || "0");
  const priceChange = parseFloat(quote["09. change"] || "0");
  const changePercent = parseFloat(quote["10. change percent"]?.replace("%", "") || "0");
  // 格式化 markdown
  let markdown = `# ${overview.Symbol} (${overview.Name}) - ${formatCurrency(currentPrice)} ${addTrendIndicator(priceChange)}${changePercent > 0 ? '+' : ''}${changePercent.toFixed(2)}%\n\n`;
  // 更多细节...
  return markdown;
}

server.setRequestHandler(ListToolsRequestSchema, async () => {
  console.error("[Setup] Listing available tools");
  return {
    tools: [
      {
        name: "get_stock_overview",
        description: "获取股票代码的公司信息和当前报价",
        inputSchema: {
          type: "object",
          properties: {
            symbol: { type: "string", description: "股票代码（如 'AAPL')" },
            market: { type: "string", description: "可选市场（如 'US')", default: "US" }
          },
          required: ["symbol"]
        }
      }
      // 其他工具...
    ]
  };
});

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

// 启动日志
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}`);

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

// 默认缓存时间（秒）
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);

try {
  switch (request.params.name) {
    case "get_stock_overview": {
      // 实现...
    }
    // 其他工具...
    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
  };
}

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

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

// 用环境变量认证
const API_KEY = process.env.ALPHAVANTAGE_API_KEY;
if (!API_KEY) {
  console.error("[Error] Missing ALPHAVANTAGE_API_KEY environment variable");
  process.exit(1);
}
// 初始化 API 客户端
const apiClient = new AlphaAdvantageClient({ apiKey: API_KEY });

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 缓冲
  });
}