📝 Creación de MCP Servers y su uso con GitHub Copilot en modo Agente

📝 创建 MCP Servers 并在 Agent 模式下使用 GitHub Copilot

此仓库包含用于演讲的资料、示例和 MCP（Model Context Protocol）服务实现，用于管理便签。演讲主题是如何将 MCP 服务与 Agent 模式下的 GitHub Copilot 集成。

---

📢 第一部分：演讲简介

📋 描述

这场时长一小时的演讲面向有意通过自定义 MCP 服务扩展 GitHub Copilot 功能并了解 Agent 工作流的开发者。你将学习如何创建 MCP 服务，并将其与 GitHub Copilot 和 Claude AI 集成。

📚 议程

1. MCP 简介及其用途
2. MCP 服务架构
3. 实践示例：创建基础 MCP 服务
4. 将 MCP 服务与 GitHub Copilot（Agent 模式）和 Claude AI 集成
   • 在 VS Code 中配置 MCP 扩展
   • 运行服务并连接到 Copilot
   • 使用 Copilot 与 MCP 服务交互的示例
   • 使用 Claude AI 与 MCP 服务交互的示例
5. 使用场景和最佳实践
6. 问答

⚙️ 要求

• Python：3.10 或更高版本
• Node.js：18 或更高版本
• npm 或 yarn：用于管理 JavaScript 依赖项
• uv：现代化的 Python 环境和依赖项管理工具
• GitHub 账号：可使用 Copilot（Agent 模式）
• 编辑器：推荐使用带有 MCP 扩展的 VS Code
• Claude AI：（可选）用于演示与 Claude 的集成

🚀 安装

# Clonar el repositorio
git clone https://github.com/ingfcetina/mcp-servers.git

# Navegar al directorio del proyecto
cd mcp-servers

🔗 更多资源

• MCP 官方文档
• GitHub Copilot Agent
• MCP 的 Python SDK
• uv 文档

---

🤖 第二部分：AI Sticky Notes MCP 服务

📋 描述

此仓库的实践部分实现了一个用于管理便签的 MCP（Model Context Protocol）服务。它允许 AI 模型创建、读取并总结存储在文本文件中的便签。

🏗️ 架构

graph TD
    A[Cliente MCP] -->|Solicita acción| B[Servidor FastMCP]
    B -->|Herramientas| C[add_note]
    B -->|Herramientas| D[read_notes]
    B -->|Recursos| E[get_latest_note]
    B -->|Prompts| F[note_summary_prompt]
    C -->|Escribe en| G[sticky_notes.txt]
    D -->|Lee de| G
    E -->|Lee de| G
    F -->|Lee de| G

🧩 组件

MCP 服务提供三种主要类型的组件：

🛠️ 工具（@mcp.tool()）

工具是模型可以调用以执行操作的函数。

classDiagram
    class Tool {
        +add_note(message: str) str
        +read_notes() str
    }

• add_note：向文件添加新便签
• read_notes：读取所有已存储的便签

📚 资源（@mcp.resource()）

资源提供模型可以查询的数据。

classDiagram
    class Resource {
        +get_latest_note() str
    }

• get_latest_note：仅返回最新的便签

💬 提示词（@mcp.prompt()）

提示词会为 AI 模型生成自定义指令。

classDiagram
    class Prompt {
        +note_summary_prompt() str
    }

• note_summary_prompt：创建用于总结所有便签的提示词

📊 数据流

sequenceDiagram
    participant AI as Modelo de IA
    participant MCP as Servidor MCP
    participant File as sticky_notes.txt
    
    AI->>MCP: Invocar add_note("Nueva nota")
    MCP->>File: Escribir "Nueva nota"
    MCP->>AI: "Note added: Nueva nota"
    
    AI->>MCP: Invocar read_notes()
    MCP->>File: Leer contenido
    MCP->>AI: "Nueva nota\nOtra nota anterior"
    
    AI->>MCP: Consultar notes://latest
    MCP->>File: Leer última línea
    MCP->>AI: "Nueva nota"
    
    AI->>MCP: Usar note_summary_prompt()
    MCP->>File: Leer contenido
    MCP->>AI: "Summarize the following notes:\nNueva nota\nOtra nota anterior"

🚀 使用方法

环境准备

1. 安装 uv（包和虚拟环境管理工具）：

   # En Windows PowerShell (ejecutar como administrador)
   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
   
   # En Linux/macOS
   curl -LsSf https://astral.sh/uv/install.sh | sh
   

2. 使用 Python 3.10 或更高版本创建虚拟环境：

   # Navega al directorio del proyecto
   cd C:\mcp-servers
   
   # Crea el entorno virtual
   uv venv --python=3.10 .venv
   

3. 激活虚拟环境：

   • 在 PowerShell 中：

     .venv\Scripts\Activate.ps1
     
     # Si tienes problemas de permisos, ejecuta primero:
     Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
     

   • 在 CMD 中：

     .venv\Scripts\activate.bat
     

   • 在 Bash 中：

     source .venv/Scripts\activate
     

4. 安装 MCP 及其他所需依赖项：

   # SDK de MCP con CLI incluido
   uv pip install "mcp[cli]"
   
   # Otras dependencias útiles
   uv pip install pydantic python-dotenv pyyaml
   

与 VS Code 集成

1. 确保已安装 GitHub Copilot：

   • 打开 VS Code
   • 转到扩展选项卡（Ctrl+Shift+X）
   • 搜索“GitHub Copilot”并安装官方扩展
   • 确保有权使用 Copilot 的 Agent 模式功能

2. 在 settings.json 中配置 MCP 服务：

   • 如图所示 ，VS Code 已有 MCP 配置
   • 可以在 settings.json 中检查或修改配置：

   "mcp": {
       "servers": {
           "Demo": {
               "command": "uv",
               "args": [
                   "run",
                   "--with",
                   "mcp[cli]",
                   "mcp",
                   "run",
                   "C:\\mcp-servers\\project\\main.py"
               ]
           }
       }
   }
   

3. 通过 GitHub Copilot 与 MCP 服务交互：

   • 在 Copilot 的 Agent 模式下，可以直接使用 add_note、read_notes 和 get_latest_note 等命令

与 Claude AI 集成

1. 在 Claude AI 中安装 MCP 服务：

   # Asegúrate de tener el entorno virtual activado
   .venv\Scripts\Activate.ps1
   
   # Instala tu servidor en Claude AI
   mcp install C:\mcp-servers\project\main.py
   

2. 配置 claude_desktop_config.json：

   {
     "mcpServers": {
       "Demo": {
         "command": "uv",
         "args": [
           "run",
           "--with",
           "mcp[cli]",
           "mcp",
           "run",
           "C:\\mcp-servers\\project\\main.py"
         ]
       }
     }
   }
   

3. 通过 Claude AI 与服务交互：

   • 重启 Claude AI 客户端
   • 在配置中选择 MCP 服务“Demo”
   • 在对话中使用 add_note、read_notes 和 get_latest_note 等命令

直接运行以进行开发

要直接运行 MCP 服务：

# Activa el entorno virtual
.venv\Scripts\Activate.ps1

# Ejecuta el servidor MCP en modo desarrollo
uv run --with mcp mcp dev project/main.py

# Alternativa para ejecución sin inspector
uv run --with mcp mcp run project/main.py

MCP Inspector 将自动在浏览器中打开，地址为 http://localhost:6277。

🔧 常见问题排查

• 错误：端口已被占用（6277）

  # Identifica el proceso usando el puerto
  netstat -ano | findstr :6277
  
  # Termina el proceso (reemplaza <PID> con el número identificado)
  taskkill /F /PID <PID>
  

• 连接错误：如果看到“Connection Error, is your MCP server running?”：

  • 确保服务正在运行
  • 检查是否有防火墙阻止连接
  • 检查 main.py 文件的路径是否正确

• 虚拟环境未激活：

  • 如果同时使用 conda 和 uv，请先停用 conda：

    conda deactivate
    

  • 然后激活 uv 环境

📋 便签 MCP 服务组件参考

下面详细介绍此 MCP 服务中已实现的组件，并按类型和功能进行整理：

类型	名称	描述	参数	返回值
🛠️ 工具	add_note	将一条新便签添加到存储文件	message (str)：要保存的便签文本	确认信息，包含已添加的便签文本
🛠️ 工具	read_notes	检索并显示所有已存储的便签	无	所有现有便签的完整列表
📚 资源	notes://latest	快速访问最新便签	无	最近添加的便签文本
💬 提示词	note_summary_prompt	生成指令，让模型创建结构化摘要	无	包含当前便签的提示词模板

这些组件协同工作，通过模型上下文协议（MCP）提供全面的便签管理功能。

---

📄 许可证

本仓库中的代码和示例采用 GNU General Public License v3.0（GPL-3.0）许可证。你可以根据此许可证的条款使用、修改和分发代码。更多详情请参阅 LICENSE 文件。