mcp

MCP：构建和管理协议服务

构建可集成 API 的 MCP 服务，并执行已配置服务中的工具。

适用场景

构建：创建 MCP 服务（Python/TypeScript）、集成 API、设计以 Agent 为中心的工具、实现验证和错误处理、创建评估

管理：通过 Gemini CLI 发现/执行工具、为任务筛选工具、管理多服务配置

核心概念

MCP = 一种标准化协议，供 AI Agent 访问外部工具/数据。

组件：工具（可执行函数）、资源（只读数据）、提示词（模板） 传输方式：Stdio（本地）、HTTP（远程）、SSE（实时）

加载：references/protocol-basics.md，了解完整的协议详情

---

第 1 部分：构建 MCP 服务

构建高质量的 MCP 服务，让大模型能够完成现实世界中的任务。

开发工作流

阶段 1：调研与规划

1. 学习以 Agent 为中心的设计原则（工作流优先于端点）
2. 全面调研目标 API 文档
3. 加载框架文档（Python SDK 或 TypeScript SDK）
4. 规划工具选择、共享实用程序、输入/输出设计和错误处理

阶段 2：实现

1. 设置项目结构（Python 使用单文件，TypeScript 使用完整结构）
2. 实现核心基础设施（API 客户端、错误处理器、格式化程序）
3. 使用合适的架构和注解注册工具
4. 遵循特定语言的最佳实践

阶段 3：测试与质量

1. 进行代码质量审查（DRY、可组合性、一致性）
2. 运行构建和语法检查
3. 使用质量检查清单

阶段 4：评估

1. 创建 10 个复杂、贴近实际的评估问题
2. 问题必须为只读、彼此独立且可验证
3. 测试大模型有效使用服务的能力

参考：references/building-servers.md——加载完整开发指南，其中包括：

• 以 Agent 为中心的设计原则
• Python（FastMCP）实现指南和 Pydantic 模型
• TypeScript（MCP SDK）实现指南和 Zod 架构
• 工具命名约定、响应格式、分页模式
• 字符数限制、错误处理、安全最佳实践
• 完整的可运行示例和质量检查清单
• 评估创建和测试方法

关键最佳实践

工具设计：

• 使用带服务前缀的名称（例如 slack_send_message，而非 send_message）
• 支持 JSON 和 Markdown 两种响应格式
• 使用 limit、offset、has_more 实现分页
• 设置 CHARACTER_LIMIT 常量（通常为 25,000）
• 提供可执行的错误消息，帮助 Agent 采取相应操作

代码质量：

• 将通用功能提取为可复用函数
• 所有 I/O 操作都使用 async/await
• 全程使用类型提示（Python）或严格的 TypeScript
• 编写包含明确架构的完整文档字符串

参考：references/best-practices.md——加载完整指南

---

第 2 部分：使用 MCP 工具

高效执行和管理已配置 MCP 服务中的工具。

配置

在 .claude/.mcp.json 中配置 MCP 服务：

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "package-name"],
      "env": {"API_KEY": "${ENV_VAR}"}
    }
  }
}

Gemini CLI 集成：创建共享配置的符号链接：

mkdir -p .gemini && ln -sf .claude/.mcp.json .gemini/settings.json

参考：references/using-tools.md——加载完整的配置和使用指南

执行方式（按优先级排序）

1. Gemini CLI（主要方式）

通过自然语言自动发现并执行工具。

# CRITICAL: Use stdin piping, NOT -p flag (deprecated, skips MCP init)
echo "Take a screenshot of https://example.com" | gemini -y -m gemini-2.5-flash

优点：

• 自动发现和选择工具
• 结构化 JSON 响应（如果已配置 GEMINI.md）
• 执行速度最快
• 无需手动指定工具

GEMINI.md 响应格式：放置在项目根目录中，以强制仅返回 JSON 响应：

# Gemini CLI Instructions
Always respond in this exact JSON format:
{"server":"name","tool":"name","success":true,"result":<data>,"error":null}
Maximum 500 characters. No markdown, no explanations.

2. 直接使用 CLI 脚本（次要方式）

在确切知道所需的服务/工具时手动指定：

npx tsx scripts/cli.ts call-tool memory create_entities '{"entities":[...]}'

3. mcp-manager 子 Agent（备用方式）

当 Gemini 不可用或需要处理复杂的多工具工作流时，委派给子 Agent。

参考：references/using-tools.md——需要时加载：

• 完整的 Gemini CLI 指南及示例
• 直接使用脚本的方法和选项
• 子 Agent 委派模式
• 工具发现和筛选策略
• 多服务编排
• 故障排除和调试

工具发现

列出可用工具以了解其功能：

# Saves to assets/tools.json for offline reference
npx tsx scripts/cli.ts list-tools

# List prompts and resources
npx tsx scripts/cli.ts list-prompts
npx tsx scripts/cli.ts list-resources

智能选择：LLM 直接读取 assets/tools.json，根据上下文筛选工具（优于关键词匹配）。

---

快速入门示例

构建服务

Python：

from mcp.server.fastmcp import FastMCP
from pydantic import BaseModel, Field

mcp = FastMCP("github_mcp")

class SearchInput(BaseModel):
    query: str = Field(..., min_length=2, max_length=200)
    limit: int = Field(default=20, ge=1, le=100)

@mcp.tool(name="github_search_repos", annotations={"readOnlyHint": True})
async def search_repos(params: SearchInput) -> str:
    # Implementation
    pass

if __name__ == "__main__":
    mcp.run()

TypeScript：

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({name: "github-mcp-server", version: "1.0.0"});

const SearchSchema = z.object({
  query: z.string().min(2).max(200),
  limit: z.number().int().min(1).max(100).default(20)
}).strict();

server.registerTool("github_search_repos", {
  description: "Search GitHub repositories",
  inputSchema: SearchSchema,
  annotations: {readOnlyHint: true}
}, async (params) => {
  // Implementation
});

如需完整的实现指南，请加载 references/building-servers.md。

使用工具

Gemini CLI：

# IMPORTANT: Use stdin piping, NOT -p flag
echo "Search GitHub for MCP servers and summarize top 3" | gemini -y -m gemini-2.5-flash

直接使用脚本：

npx tsx scripts/cli.ts call-tool github search_repos '{"query":"mcp","limit":3}'

如需完整的使用模式，请加载 references/using-tools.md。

---

参考文件

根据工作需要加载以下文件：

核心参考资料

• references/building-servers.md - 完整的 MCP 服务开发指南

  • 以 Agent 为中心的设计原则
  • Python（FastMCP）和 TypeScript（MCP SDK）实现
  • 工具模式、响应格式、分页和错误处理
  • 完整示例和质量检查清单
  • 评估创建方法

• references/using-tools.md - 完整的 MCP 工具执行指南

  • Gemini CLI 集成和配置
  • 直接执行脚本的模式
  • 子 Agent 委派策略
  • 工具发现和筛选
  • 多服务编排

• references/best-practices.md - 通用 MCP 指南

  • 服务和工具的命名约定
  • 响应格式标准（JSON 与 Markdown）
  • 分页、字符限制和截断
  • 安全和隐私注意事项
  • 测试和合规要求

辅助参考资料

• references/protocol-basics.md - JSON-RPC 协议详情
• references/python-guide.md - Python/FastMCP 特定内容（Pydantic 模型、异步模式）
• references/typescript-guide.md - TypeScript/Zod 特定内容（严格类型、项目结构）
• references/evaluation-guide.md - 创建有效的 MCP 服务评估

---

渐进式披露

此 SKILL.md 提供高层概述。在以下情况下加载参考文件：

构建服务：

• 开始实现 → 加载 references/building-servers.md
• 需要语言特定的细节 → 加载 references/python-guide.md 或 references/typescript-guide.md
• 创建评估 → 加载 references/evaluation-guide.md

使用工具：

• 设置 Gemini CLI → 加载 references/using-tools.md
• 调试工具执行 → 加载 references/using-tools.md
• 配置多服务 → 加载 references/using-tools.md

最佳实践：

• 审查标准 → 加载 references/best-practices.md
• 安全注意事项 → 加载 references/best-practices.md

---

集成模式

构建 + 使用：创建 MCP 服务，然后使用 Gemini CLI 测试 多服务：配置多个服务，通过 Gemini CLI 进行编排 评估驱动：构建服务、创建评估，并根据 LLM 反馈迭代

---

边界

会：

• 指导使用 Python 或 TypeScript 开发 MCP 服务
• 通过 Gemini CLI 或脚本提供工具执行策略
• 确保遵循以 Agent 为中心的设计最佳实践
• 帮助创建有效的评估
• 配置多服务设置

不会：

• 在主线程中运行长时间运行的服务进程（使用 tmux 或评估框架）
• 跳过输入验证或错误处理
• 创建缺少完整文档的工具
• 在构建服务时不考虑 Agent 上下文限制