🤖 MCP Server for Copilot Studio Agents

🤖 Copilot Studio Agent 的 MCP 服务

一种 MCP（Model Context Protocol） 服务实现，可连接到 Microsoft Copilot Studio Agent，让 Copilot Studio Agent 与任何兼容 MCP 的客户端无缝集成。

https://github.com/user-attachments/assets/19fdd17b-2837-4797-8653-fe9439de355f

✨ 功能

• 🔌 通过 DirectLine API 连接到 Copilot Studio Agent
• 🧠 在多次查询之间保留对话上下文
• 🔄 轻松集成任何兼容 MCP 的客户端
• 💬 通过对话 ID 和水位标记跟踪实现有状态对话
• ⚙️ 可配置的 Agent 定义

🛠️ 工具

此 MCP 服务提供以下工具：

• 📮 query_agent：向 Copilot Studio Agent 发送查询并接收回复
  • 🔄 使用对话 ID 和水位标记，在多次查询之间保留对话上下文
  • 📊 返回包含成功／错误状态的结构化回复

🔧 配置

前置条件

• 🔐 确保已设置 Copilot Studio Agent，并配置 direct line channel security。
• 📝 更新 src/main.py 文件中的 agent_definitions，加入 Agent 的详细信息。
• agent_definitions 应包含以下字段：
  • 📛 name：Agent 的名称
  • 📄 description：对 Agent 的简要说明，供 MCP 客户端识别 Agent 的职责。

环境变量

此服务需要以下环境变量：

• 🔗 DIRECTLINE_ENDPOINT：Copilot Studio Agent 的 DirectLine API 端点
• 🔑 COPILOT_AGENT_SECRET：用于通过 DirectLine API 对 Copilot Studio Agent 进行身份验证的 Bot 密钥

你可以在项目根目录的 .env 文件中设置这些变量，也可以通过系统环境变量进行配置。

📦 安装

前置条件

• 🐍 Python 3.12 或更高版本
• 🚀 uv 包管理器（推荐）或 pip

Python 设置

# Setup environment with uv
uv venv
.venv\Scripts\activate  # On Windows
source .venv/bin/activate  # On macOS/Linux

# Install dependencies
uv sync

如果你更倾向于使用 pip：

# Create a virtual environment
python -m venv .venv
.venv\Scripts\activate  # On Windows
source .venv/bin/activate  # On macOS/Linux

# Install dependencies
pip install -e .

使用 MCP Inspector 测试

激活环境后，你可以使用 MCP Inspector 在本地运行 MCP 服务。

1. 使用以下命令运行 MCP 服务：

mcp dev src/main.py

2. 系统会提示你安装 @modelcontextprotocol/inspector 包。输入 y 进行安装。
   

3. 启动 MCP Inspector 并连接到 MCP 服务。

4. 前往 Tools，点击 List Tools，查看 MCP 服务中的所有可用工具。

5. 选择 query_agent 工具，向 Copilot Studio Agent 发送查询。
   

在 Claude Desktop 中使用

如需在 Claude Desktop 中使用，请将以下内容添加到配置文件：

1. 下载并安装 Claude Desktop，如果你尚未安装。
2. 前往 File > Settings > Developer > Edit Config。
3. 打开 claude_desktop_config.json 文件，并将以下配置添加到 mcpServers 部分。你可以使用 uv、python 或 docker 来运行服务。
   
4. 保存配置文件并重启 Claude Desktop。
5. 将 MCP 服务添加到 Claude Desktop 后，你可以在工具部分查看它。

Claude Desktop 的 MCP 服务配置

通过 uv 运行

{
  "mcpServers": {
    "agent-name": {
      "command": "uv", // you might need to use the full path to uv if it's not in your PATH. use `which uv` to find the path.
      "args": [
        "--directory",
        "<PATH_TO_THE_PARENT_FOLDER>",
        "run",
        "mcp",
        "run",
        "<PATH_TO_THE_PARENT_FOLDER>/src/main.py"
      ],
      "env": {
        "DIRECTLINE_ENDPOINT": "endpoint-url",
        "COPILOT_AGENT_SECRET": "secret-key"
      }
    }
  }
}

通过 python 运行

设置好虚拟环境并安装必要的软件包后，你可以使用以下命令运行服务：

{
  "mcpServers": {
    "agent-name": {
      "command": "<PATH_TO_VENV>/bin/python",
      "args": [
        "<PATH_TO_THE_PARENT_FOLDER>/src/main.py"
      ],
      "env": {
        "DIRECTLINE_ENDPOINT": "endpoint-url",
        "COPILOT_AGENT_SECRET": "secret-key"
      }
    }
  }
}

或者，你可以在虚拟环境中运行以下命令，将服务安装到 Claude Desktop：

mcp install src/main.py -f .env

通过 docker 运行

你可以使用 Docker 将 MCP 服务作为容器运行。请确保已在计算机上安装并运行 Docker。

构建 Docker 镜像：

docker build -t mcp-server-copilot-agent .

将以下内容添加到 Claude Desktop 配置文件中：

{
  "mcpServers": {
    "agent-name": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-p", "8000:8000",
        "--env-file", "<PATH_TO_THE_PARENT_FOLDER>/.env",
        "mcp-server-copilot-agent"
      ]
    }
  }
}

配置好 Claude Desktop 后，

🌐 与其他 MCP 客户端搭配使用

此服务遵循 MCP 协议规范，可与任何兼容 MCP 的客户端搭配使用。请参阅客户端文档，了解如何连接到外部 MCP 服务的具体说明。

👩‍💻 开发

如需为此项目做出贡献，请设置开发环境：

# Install development dependencies
uv sync -e dev

此项目使用 Ruff 进行代码检查：

# Run linter
ruff check .