Posuer: MCP 管理器和中介器

一个强大的模型上下文协议 (MCP) 管理器，通过以下方式增强大型语言模型：

• Docker 容器化 - 在隔离的容器中运行 MCP 服务器，并自动检测
• 动态配置重载 - 无需重启即可更新服务器配置
• 多服务器聚合 - 组合来自不同服务器的工具和资源
• 智能能力路由 - 将请求定向到适当的后端服务器
• 高级配置 - 对工具公开进行细粒度控制

项目愿景

Posuer 充当 MCP 客户端（如 Claude Desktop）和多个 MCP 服务器之间的桥梁。无需将每个服务器单独连接到您的 LLM 客户端，Posuer 允许您：

1. 整合多个服务器 - 通过单个连接点管理所有 MCP 服务器
2. 聚合能力 - 组合来自不同服务器的工具、资源和提示
3. 简化配置 - 使用单个 YAML 文件定义所有服务器连接
4. 增强可靠性 - 监控服务器健康状况并优雅地处理故障

工作原理

┌───────────────┐                  ┌──────────────────────────────────────┐
│               │                  │                                      │
│   LLM 客户端  │◄─── MCP/stdio ──►│               Posuer                 │
│ (Claude 等) │                  │                                      │
│               │                  │                                      │
└───────────────┘                  └──┬─────────────┬─────────────┬───────┘
                                      │             │             │
                                  MCP/stdio     MCP/stdio     MCP/SSE
                                      │             │             │
                                      ▼             ▼             ▼
                                 ┌─────────┐   ┌─────────┐   ┌─────────┐
                                 │ ServerA │   │ ServerB │   │ ServerC │
                                 └─────────┘   └─────────┘   └─────────┘

Posuer 实现了 MCP 协议的两端：

• 它充当 Claude Desktop 等客户端的 MCP 服务器
• 它充当后端服务器的 MCP 客户端
• 它根据能力智能地在它们之间路由消息

主要特性

• 动态服务器管理 - 配置和管理多个 MCP 服务器
• 能力聚合 - 组合来自所有服务器的资源、工具和提示
• 智能路由 - 将请求定向到适当的后端服务器
• 多种传输类型 - 支持 stdio 和 SSE 连接
• 配置包含 - 从多个文件（包括 Claude Desktop 配置）包含服务器配置
• 错误处理 - 优雅地处理服务器故障
• 日志记录 - 用于调试和监控的详细日志

安装

前提条件

• Go 1.23 或更高版本
• 访问 MCP 服务器（例如，文件系统、天气、搜索等）

从源代码构建

# 克隆存储库
git clone https://github.com/jkoelker/posuer.git
cd posuer

# 构建二进制文件
make

# 二进制文件将在 build 目录中创建
ls -la build/posuer

用法

# 使用默认配置 (config.yaml) 运行
./build/posuer

# 使用特定的配置文件运行
./build/posuer -config /path/to/config.yaml

# 显示版本信息
./build/posuer -version

# 在 stdio 模式下运行（默认）
./build/posuer -stdio

# 启用配置文件监视器运行
./build/posuer -config /path/to/config.yaml -watch

配置

Posuer 使用 YAML 文件进行配置。默认情况下，它在以下位置查找 config.yaml（按顺序）：

1. -config 标志指定的路径
2. 用户配置目录（例如，~/.config/posuer/config.yaml）

配置示例：

# Posuer 配置文件
servers:
  # 直接服务器定义
  - name: filesystem
    type: stdio
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-filesystem"
      - "/tmp"

  # 您还可以包含其他配置文件
  - ~/other-servers.yaml
  - ~/.config/Claude/claude_desktop_config.json

  # SSE 服务器（远程）的示例
  - name: remote-server
    type: sse
    url: https://example.com/sse

能力配置选项

Posuer 提供灵活的能力配置，具有三种格式：

1. 布尔值（启用/禁用整个服务器）

   servers:
     - name: all-enabled
       type: stdio
       command: npx
       args:
         - -y
         - "@modelcontextprotocol/server-memory"
       enable: true  # 启用所有能力
   
     - name: all-disabled
       type: stdio
       command: npx
       args:
         - -y
         - "@modelcontextprotocol/server-memory"
       enable: false  # 禁用所有能力（或使用 disable: true）
   

2. 列表（工具的快速格式）

   servers:
     - name: specific-tools
       type: stdio
       command: npx
       args:
         - -y
         - "@modelcontextprotocol/server-memory"
       enable:
         - create_entities  # 仅启用这些特定工具
         - read_graph
   
     - name: blocked-tools
       type: stdio
       command: npx
       args:
         - -y
         - "@modelcontextprotocol/server-filesystem"
         - "/tmp"
       disable:
         - write_file  # 禁用这些特定工具
         - move_file
   

3. 映射（高级能力过滤）

   servers:
     - name: advanced-filtering
       type: stdio
       command: npx
       args:
         - -y
         - "@modelcontextprotocol/server-memory"
       enable:
         tools:  # 启用特定工具
           - create_entities
           - read_graph
         prompts: system_prompt  # 启用单个提示
         templates:  # 启用特定模板
           - entity_template
           - graph_template
       disable:
         tools:  # 禁用特定工具（即使在启用列表中）
           - delete_entities
   

映射格式支持按不同的能力类型进行过滤：

• tools: LLM 可以调用的工具函数
• prompts: LLM 可以使用的系统提示
• templates: 用于动态内容的资源模板
• resources: 静态资源（文件等）

有关更详细的配置示例，请参见默认配置 pkg/config/config.yaml。

动态配置重载

Posuer 支持动态配置重载，允许您在服务运行时修改配置文件。会自动检测更改并在无需重启的情况下应用。

要启用此功能，请使用 -watch 标志：

# 启用配置文件监视运行
./posuer -config /path/to/config.yaml -watch

当配置文件被修改时：

1. Posuer 自动检测更改
2. 加载并验证新配置
3. 添加新服务器，更新现有服务器，并关闭已删除的服务器
4. 应用所有更改，而不会中断活动连接

此功能对于以下情况很有用：

• 动态添加新的 MCP 服务器
• 在不重启 Posuer 的情况下删除或禁用服务器
• 在开发期间测试不同的配置
• 在生产环境中轮换 API 密钥或更新端点

文件监视器包括防抖动，以防止在快速编辑期间过度重载。

配置选项

• servers: 服务器配置或要包含的文件路径的数组
  • 对于直接服务器定义：
    • name: 服务器名称（用于命名空间能力）
    • type: 服务器连接类型（“stdio”或“sse”）
    • command: 要运行的命令（对于 stdio）
    • args: 命令行参数
    • env: 环境变量
    • url: 服务器 URL（对于 sse 类型）
    • enable: 启用特定能力（请参见下面的格式选项）
    • disable: 禁用特定能力（请参见下面的格式选项）
    • container: 容器配置（请参见下面的容器选项）
  • 对于文件包含，只需提供文件路径作为字符串

容器配置

Posuer 支持在容器中运行 MCP 服务器，以提高隔离性和依赖项管理。可以在三种格式中指定容器配置：

1. 简单格式：仅将镜像名称指定为字符串

   servers:
     - name: filesystem
       type: stdio
       command: npx
       args:
         - -y
         - "@modelcontextprotocol/server-filesystem"
         - "/tmp"
       container: "node:18-alpine"
   

2. 完整配置：指定包含所有容器选项的映射

   servers:
     - name: database
       type: stdio
       command: npx
       args:
         - -y
         - "@modelcontextprotocol/server-sqlite"
       container:
         image: node:18-alpine
         volumes:
           "/data": "/app/data"
         env:
           DB_PATH: "/app/data/database.sqlite"
         network: host
         workdir: "/app"
         args:
           - "--cap-add=SYS_ADMIN"
   

3. 显式禁用：设置为 false 以禁用容器隔离，包括自动检测

   servers:
     - name: no-container
       type: stdio
       command: npx  # 通常会自动使用容器
       args:
         - -y
         - "@modelcontextprotocol/server-filesystem"
         - "/tmp"
       container: false  # 显式禁用容器使用
   

容器配置选项：

• image: 要使用的容器镜像（必需）
• volumes: 主机路径到容器路径的映射
• env: 要传递给容器的环境变量
• network: 网络模式（主机、桥接等）
• user: 在容器中运行的用户
• workdir: 容器中的工作目录
• args: 要传递给容器运行时的其他参数

自动容器检测

Posuer 可以自动检测某些命令并在适当的容器中运行它们：

• npx 命令会自动在 docker.io/node:alpine 中运行
• uvx 命令会自动在 ghcr.io/astral-sh/uv:alpine 中运行

当使用常见的 Node.js 和 Python 包管理器时，此自动检测简化了配置。例如：

servers:
  # 这将自动在 Node.js 容器中运行
  - name: filesystem
    type: stdio
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-filesystem"
      - "/tmp"
    # 无需容器配置，它将被自动检测

  # 要显式禁用容器检测
  - name: local-npm
    type: stdio
    command: npx
    args:
      - -y
      - some-local-package
    container: false  # 显式禁用容器检测

Posuer 将自动检测系统上是否存在容器运行时（podman 或 docker），并优先选择 podman 以获得更好的无根容器支持。

与 Claude Desktop 集成

要将 Posuer 与 Claude Desktop 一起使用：

1. 如上所述构建 Posuer
2. 使用所需的 MCP 服务器创建配置文件
3. 更新您的 Claude Desktop 配置以使用 Posuer 作为 MCP 服务器：

{
  "mcpServers": {
    "posuer": {
      "command": "/path/to/posuer",
      "args": ["-watch"]
    }
  }
}

4. 重启 Claude Desktop

开发

# 格式化代码
make fmt

# 运行 linter
make lint

# 运行测试
make test

# 清理构建工件
make clean

许可证

该项目已获得 MIT 许可证的许可 - 有关详细信息，请参见 LICENSE 文件。