Dynamic MCP Server Framework

动态 MCP 服务框架

一个灵活、可扩展的框架，用于构建支持现代 API 密钥身份验证、用户管理和动态工具共享的模型上下文协议（MCP）服务。

---

🚀 概览

Dynamic MCP Server 支持构建安全、感知用户且可扩展的 AI 工具服务。它支持：

• 基于 API 密钥的身份验证（简单，兼容所有 MCP 客户端）
• 用户管理和授权（由 MongoDB 提供支持）
• 基于会话、按用户加载工具
• 工具共享和精细化访问控制
• 可供下游项目扩展的 HTTP 和数据库层

---

🌟 主要功能

• 动态工具管理：在运行时创建、删除和授权工具——工具不受限于启动时或代码中的静态定义。这实现了真正的运行时可扩展性，也是它与大多数其他 MCP 服务的主要区别。
• 用户管理：添加、更新、删除和列出用户；初始化管理员；基于角色的访问控制。
• 工具共享：与其他用户共享工具、管理访问级别，并接收实时更新。
• 现代身份验证：使用简单的 API 密钥进行身份验证，使用 MongoDB 进行授权。
• 可扩展性：在下游项目中添加自定义 HTTP 路由和 MongoDB 集合。
• 基于会话的工具加载：按用户会话加载工具，而非全局加载。

---

🔑 身份验证（API 密钥）

• 每位用户都会分配一个唯一的 apiKey（创建用户时自动生成）。
• 客户端必须通过查询参数或请求头提供 apiKey 才能通过身份验证：
  • 查询参数：?apiKey=your-key 或 ?apikey=your-key
  • 请求头：x-apikey: your-key 或 apikey: your-key
• Streamable HTTP 传输（现代）：/mcp?apiKey=...，或在 /mcp 请求中使用请求头
• 服务通过在数据库中查找 apiKey 来验证用户身份。

---

🚀 传输协议

Dynamic MCP Server 同时支持旧版和现代 MCP 传输协议：

Streamable HTTP 传输

• 协议版本：2025-03-26
• 端点：/mcp
• 功能：现代、高效的单端点设计
• 身份验证：查询参数 ?apiKey=your-key 或请求头 x-apikey: your-key
• 用途：建议用于新的集成

---

� 文档

• 快速入门
• 传输协议
• 用户管理
• 工具管理与共享
• 身份验证与授权
• 扩展服务（HTTP 和数据库）
• API 参考
• 示例
• 扩展服务：创建处理器和工具包
• 测试模式与模拟策略

工具可见性模型： 默认情况下，所有工具对用户可见。用户可以使用 hide-tool 和 unhide-tool 操作隐藏工具。详情请参阅用户管理和工具管理与共享。

---

🛠️ 快速开始

有关安装和基本用法，请参阅快速入门。

---

📝 贡献

欢迎贡献！更多详情请参阅文档。

📄 许可证

MIT

---

🧩 处理器和工具注册（新模式）

现在通过处理器包注册工具。每个处理器包会将相关工具归组，并提供一个用于执行工具的处理器函数。这是推荐的可扩展、易维护模式。

示例：

const myHandlerPackage = {
  name: "my-domain",
  tools: [
    {
      name: "my-tool",
      description: "A custom tool",
      inputSchema: {
        /* ... */
      },
      handler: { type: "my-domain", config: {} },
      rolesPermitted: ["user", "admin"],
    },
    // ...more tools...
  ],
  handler: async (args, context, config, toolName) => {
    // Dispatch logic based on toolName, if needed
  },
};

const server = new DynamicMcpServer({ name: "my-mcp", version: "1.0.0" });
await server.start();
await server.registerHandler(myHandlerPackage);

更多详情请参阅快速入门和示例。

---

🧩 工具参数映射（config.args）

定义工具时，可以使用 config.args 字段，将用户提供的工具选项（来自 inputSchema）映射为操作处理程序所需的参数。此映射支持：

• 字面值（例如，"country": "US"）
• 模板变量（例如，"city": "{{location}}"）
• 嵌套对象和数组（所有模板都会递归解析）

示例：

handler: {
  type: "weather-tools",
  config: {
    url: "https://api.openweathermap.org/data/2.5/weather",
    args: {
      queryParams: {
        appid: "{{OPENWEATHER_API_KEY}}",
        q: "{{location}}",
        units: "{{units}}"
      }
    }
  }
}

调用工具时，系统会使用工具输入和环境变量，自动解析 config.args 中所有 {{...}} 模板。处理程序会收到合并并解析后的参数，无需手动映射。

完整详情和示例请参阅工具编写。

---