许可: 仅限非商业用途，遵循 BUSL-1.1。在 2040 年 4 月 10 日之前禁止商业用途。

InsightLoop 动态 MCP 服务器 SSE、MCP 客户端检查器和开发工具

🚀 概述

本项目提供了一个使用服务器发送事件 (SSE) 进行传输的模型上下文协议 (MCP) 服务器实现。它具有从专用目录（./src/tools 和 ./src/prompts）动态加载工具和提示的功能。该项目还包括一个命令行界面 (CLI)，用于开发辅助（如脚手架和描述增强）以及一个基于 Web 的前端检查器，用于与正在运行的 MCP 服务器进行交互。

📚 目录

• 🚀 概述
• ✨ 主要特性
• 🧩 核心组件
• ⚙️ 快速开始
  • 先决条件
  • 安装
  • 环境配置
  • 运行项目（手动）
  • 🐳 Docker 设置
    • 直接使用 Docker Compose
    • 使用 Makefile（推荐）
• 🕹️ 使用
• 🗺️ 路线图
• ❓ 常见问题解答

✨ 主要特性

• 📡 带有 SSE 传输的 MCP 服务器: 使用高效的服务器发送事件来实现 MCP 标准，以进行实时通信。

• 🧰 动态工具和提示注册: 在服务器启动或新连接时，自动发现并注册工具（./src/tools 中的 .ts 文件）和提示（./src/prompts 中的 .ts 文件）。

• ⚙️ 并发客户端处理: 通过 SSE 管理多个并发客户端连接，每个连接隔离服务器实例。

• 💻 开发 CLI: 提供实用程序来简化开发：

  • 🏗️ 用于新工具和提示的自动脚手架。
  • 🤖 LLM 驱动的工具描述增强，以实现更好的上下文关联。
  • 📝 列出可用的提示。

• ✨ 基于 Web 的 MCP 检查器: 一个前端应用程序（使用 Next.js 和 Shadcn UI 构建），允许用户：

  • 🔗 连接到正在运行的 MCP SSE 服务器。
  • 🔍 查看可用工具和提示的列表及其模式。
  • ⚡ 通过表单提供参数来执行工具和提示。
  • 📊 实时监控连接状态并查看活动日志。

  

🧩 核心组件

1. src/index.ts:

   • MCP 服务器的主要入口点。
   • 使用 Express.js 处理 HTTP 请求并在 /sse 端点建立 SSE 连接。
   • 管理客户端会话和关联的 MCP 服务器实例。
   • 使用辅助函数（registerToolsFromDirectoryRecursive、registerPromptsFromDirectoryRecursive）协调工具和提示的动态加载。
   • 包括动态 CORS 中间件。

2. script/cli.ts:

   • 一个命令行实用程序，旨在帮助开发和维护工具和提示。
   • 提供一个交互式菜单，用于从模板创建新的工具/提示文件，并改进现有工具描述（使用通过环境变量配置的外部 LLM）。

3. mcp-inspector-frontend/:
   • 一个独立的 Next.js 应用程序，用作 MCP 服务器的图形用户界面。
   • 使用 @modelcontextprotocol/sdk/client/sse.js 传输连接到服务器的 /sse 端点。
   • 提供了一种用户友好的方式来检查服务器功能（工具、提示）并与之交互。

⚙️ 快速开始

先决条件

• Node.js（建议使用最新的 LTS）
• Yarn（v1 或更高版本）
• Docker & Docker Compose
• make（通常预安装在 Linux/macOS 上；适用于 Windows）

安装

1. 克隆存储库（如果尚未克隆）。
2. 安装根依赖项：

   yarn install
   

3. 安装前端依赖项：

   cd mcp-inspector-frontend
   yarn install
   cd ..
   

环境配置

1. 服务器： 将 .env.example 复制到项目根目录中的 .env。填写任何必要的环境变量（例如，如果您的工具/CLI 需要 API 密钥）。
2. 前端检查器： 在 mcp-inspector-frontend/ 目录中创建一个 .env.local 文件。添加正在运行的 MCP 服务器的 URL：

   # mcp-inspector-frontend/.env.local
   NEXT_PUBLIC_MCP_SERVER_URL=http://localhost:3001
   

   如果您的服务器在不同的端口或主机上运行，请替换 http://localhost:3001。确保可以从运行前端的位置访问此 URL（例如，如果在 Docker 外部运行前端，但在 Docker Desktop 上的 Docker 内部运行服务器，则使用 http://host.docker.internal:3001，或者如果从另一台机器访问，则使用 http://<your-docker-host-ip>:3001）。使用 make 或 docker-compose 时，服务可能可以直接通过 http://localhost:<port> 访问，具体取决于配置。

运行项目（手动）

如果您不想使用 Docker，此方法很有用。

1. 构建服务器和 CLI：

   yarn build
   

2. 运行 MCP 服务器：

   yarn start
   

   (或者，如果配置了带有热重载的开发脚本，则使用 yarn dev)

3. 运行前端检查器：

   cd mcp-inspector-frontend
   yarn dev
   

   检查器通常在 http://localhost:3000 上可用。

4. 运行工具管理器 CLI：

   yarn tool-manager
   

   此命令使用 node 执行 build/script/cli.js。按照终端中的交互式提示来管理工具和提示。

🐳 Docker 设置

建议使用 Docker 以获得一致的环境和更轻松的部署。确保您已安装 Docker 和 Docker Compose。

直接使用 Docker Compose

您可以使用提供的 YAML 文件直接与 Docker Compose 交互：

1. 用于开发： 构建并启动 docker-compose.dev.yml 中定义的容器（通常带有热重载）。

   docker-compose -f docker-compose.dev.yml up --build
   

   停止：docker-compose -f docker-compose.dev.yml down

2. 用于生产： 构建并启动 docker-compose.prod.yml 中定义的容器（针对生产进行了优化）。

   docker-compose -f docker-compose.prod.yml up --build -d # -d 在分离模式下运行
   

   停止：docker-compose -f docker-compose.prod.yml down

注意：您可能需要根据您的 Docker 网络设置调整 mcp-inspector-frontend/.env.local 中的 NEXT_PUBLIC_MCP_SERVER_URL。

使用 Makefile（推荐）

项目根目录中提供了一个 Makefile，以简化常见的 Docker 操作。确保您的系统上已安装 make。

• 开发环境：

  • make dev-up：构建镜像（如果需要）并使用 docker-compose.dev.yml 启动开发容器。
  • make dev-down：停止并删除开发容器。
  • make dev-logs：跟踪正在运行的开发容器的日志。

• 生产环境：

  • make prod-up：构建镜像（如果需要）并使用 docker-compose.prod.yml 在分离模式下启动生产容器。
  • make prod-down：停止并删除生产容器。
  • make prod-logs：跟踪正在运行的生产容器的日志。

• 清理：

  • make clean：停止所有项目容器并删除关联的卷、网络以及可能构建的镜像（谨慎使用，因为它会彻底清理）。

示例工作流程（开发）：

1. 启动开发服务：make dev-up
2. 访问前端检查器（通常为 http://localhost:3000）和服务器（通常为 http://localhost:3001）。
3. 如果需要，查看日志：make dev-logs
4. 完成后，停止服务：make dev-down

🕹️ 使用

• 📡 MCP 服务器: 在后台运行（通过 yarn start、yarn dev、docker-compose up 或 make *-up 启动）。侦听配置端口上的 SSE 连接（默认：3001）。
• 💻 开发 CLI: 在终端中执行 yarn tool-manager（如果使用 Docker，则需要手动构建/运行或进入服务器容器）。
• ✨ MCP 检查器: 在 Web 浏览器中访问前端应用程序（手动运行或通过标准 Docker 设置时，默认为 http://localhost:3000）。连接到 NEXT_PUBLIC_MCP_SERVER_URL 中指定的服务器 URL。使用该界面浏览、检查和执行工具/提示。

🗺️ 路线图

• [x] Docker 支持（已添加基本设置，提供 Makefile）
• [ ] 改进布局与 LLM 聊天
• [ ] Python 示例
• [ ] MCP 服务器资源
• [ ] MCP 服务器采样
• [ ] MCP 服务器根
• [ ] 如何部署？（扩展 Docker 部分，添加云/无服务器指南）

✨ 贡献者

• thiagobutignon
• miller00315 - 感谢 Miller 的宝贵贡献。您创新的想法、对 AI 的热情、数学专业知识以及对博弈论的深刻理解对于该项目的成功至关重要。没有您，我们真的无法完成它。 🚀👽🤖
• Obrigado, Vicente, por proporcionar os dias mais felizes da minha vida ao seu lado. Sou grato pelas divertidas brincadeiras de policial e por transformar até os dias de chuva em momentos de alegria, quando, enquanto muitos se abrigam, você escolhe se molhar e fazer disso uma grande festa. 🚔👮🏼‍♂️🚨

❓ 常见问题解答

<details> <summary>1. 什么是 MCP SSE 服务器？</summary>

答： MCP（模型上下文协议）SSE 服务器是一个实时通信服务器，它使用服务器发送事件 (SSE) 将消息传递给连接的客户端。它遵循 MCP 标准，为 AI 驱动的工具和提示提供结构化且可扩展的通信协议。这种设计能够实现高效的更新和交互，使其成为需要动态、实时数据流和命令执行的项目的理想选择。

</details>

<details> <summary>2. 动态工具和提示注册如何工作？</summary>

答： 在启动时或建立新的客户端连接时，MCP 服务器会自动扫描专用目录（./src/tools 和 ./src/prompts）。它注册在那里找到的任何新的或更新的 TypeScript 文件。这种动态发现过程确保对您的工具和提示的任何更改或添加都可以立即提供给连接的客户端，而无需手动重启服务器（或者如果使用 Docker，则无需重启容器）。

</details>

<details> <summary>3. 什么是服务器发送事件 (SSE)？为什么使用它们？</summary>

答： 服务器发送事件 (SSE) 提供了一种机制，允许服务器通过标准 HTTP 连接将数据推送到客户端。与启用双向通信的 WebSockets 不同，SSE 侧重于从服务器到客户端的单向通信。这使得 SSE 特别适合实时更新，例如监控日志、显示动态工具执行状态或实时流式传输通知。

</details>

<details> <summary>4. 如何添加或创建新工具和提示？</summary>

答： 将新的 TypeScript 文件添加到 ./src/tools 或 ./src/prompts。如果使用 yarn dev 手动运行，或者使用带有卷挂载和热重载的 Docker 设置（make dev-up），则更改应自动反映。或者，使用 CLI 工具 yarn tool-manager（手动运行或 docker exec <container_id> yarn tool-manager）进行引导式脚手架和描述增强。

</details>

<details> <summary>5. 如何配置项目？</summary>

答： 配置环境变量：

• 服务器：将 .env.example 复制到根目录中的 .env。根据需要更新设置。此 .env 文件通常由手动运行和 Docker 设置使用。
• 前端检查器：创建 mcp-inspector-frontend/.env.local 并设置 NEXT_PUBLIC_MCP_SERVER_URL（例如，http://localhost:3001）。确保此 URL 对于您的设置（手动与 Docker）是正确的。

</details>

<details> <summary>6. 如何运行 MCP 服务器和检查器？</summary>

答： 选择您的方法：

• 手动： yarn build，然后 yarn start 用于服务器，cd mcp-inspector-frontend && yarn dev 用于检查器。
• Docker（推荐）： 使用 Makefile 命令：
  • 开发：make dev-up（启动两者），make dev-down（停止）。在 http://localhost:3000（前端）和 http://localhost:3001（服务器）访问。
  • 生产：make prod-up，make prod-down。
• Docker Compose： 直接使用 docker-compose -f <file> up/down 命令。

</details>

<details> <summary>7. 开发 CLI 的作用是什么？</summary>

答： CLI (yarn tool-manager) 辅助开发：

• 自动脚手架：生成新的工具/提示文件。
• LLM 驱动的增强：改进工具描述。
• 提示列表：列出可用的提示。 如果使用容器，则手动运行或通过 docker exec 运行。

</details>

<details> <summary>8. 基于 Web 的 MCP 检查器如何使我受益？</summary>

答： MCP 检查器（通常为 http://localhost:3000）提供了一个 GUI 来：

• 检查可用的工具/提示和模式。
• 通过表单执行工具/提示。
• 实时监控连接状态和日志。 它简化了与 MCP 服务器的交互和调试。

</details>

<details> <summary>9. 如何为该项目做出贡献或寻求支持？</summary>

答： 欢迎贡献！

• 问题/请求：使用 GitHub 问题跟踪器。
• 拉取请求：遵循贡献指南。
• 社区：如果可用，通过项目论坛或聊天频道参与。

</details>

<details> <summary>10. 路线图中提到的未来增强功能是什么？</summary>

答： 未来的计划包括：

• 增强的 Docker/部署：改进容器配置并添加部署指南。
• MCP 服务器功能：添加资源管理、采样。
• 示例和集成：Python 示例，改进的 UI（聊天）。
• 改进现有功能以实现可扩展性和易用性。

</details>