Posuer: MCP Manager and Interposer

Posuer：MCP 管理器和中介

功能强大的模型上下文协议（MCP）管理器，为大模型提供以下增强功能：

• Docker 容器化 - 在隔离的容器中运行 MCP 服务，并自动检测
• 动态配置重新加载 - 更新服务配置，无需重启
• 多服务聚合 - 整合来自不同服务的工具和资源
• 智能能力路由 - 将请求转发到合适的后端服务
• 高级配置 - 精细控制工具的暴露方式

项目愿景

Posuer 是 MCP 客户端（如 Claude Desktop）与多个 MCP 服务之间的桥梁。无需将每个服务单独连接到大模型客户端，Posuer 让你能够：

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

工作原理

┌───────────────┐                  ┌──────────────────────────────────────┐
│               │                  │                                      │
│   LLM Client  │◄─── MCP/stdio ──►│               Posuer                 │
│ (Claude, etc) │                  │                                      │
│               │                  │                                      │
└───────────────┘                  └──┬─────────────┬─────────────┬───────┘
                                      │             │             │
                                  MCP/stdio     MCP/stdio     MCP/SSE
                                      │             │             │
                                      ▼             ▼             ▼
                                 ┌─────────┐   ┌─────────┐   ┌─────────┐
                                 │ ServerA │   │ ServerB │   │ ServerC │
                                 └─────────┘   └─────────┘   └─────────┘

Posuer 实现了 MCP 协议的两端：

• 它作为 MCP 服务，为 Claude Desktop 等客户端提供服务
• 它作为 MCP 客户端，连接后端服务
• 它根据能力在两者之间智能路由消息

主要功能

• 动态服务管理 - 配置和管理多个 MCP 服务
• 能力聚合 - 整合所有服务的资源、工具和提示词
• 智能路由 - 将请求转发到合适的后端服务
• 多种传输类型 - 支持 stdio 和 SSE 连接
• 配置导入 - 从多个文件导入服务配置，包括 Claude Desktop 配置
• 错误处理 - 妥善处理服务故障
• 日志记录 - 提供详细日志，便于调试和监控

安装

先决条件

• Go 1.23 或更高版本
• 可访问 MCP 服务（例如 filesystem、weather、search 等）

从源代码构建

# Clone the repository
git clone https://github.com/jkoelker/posuer.git
cd posuer

# Build the binary
make

# The binary will be created in the build directory
ls -la build/posuer

用法

# Run with default configuration (config.yaml)
./build/posuer

# Run with a specific configuration file
./build/posuer -config /path/to/config.yaml

# Show version information
./build/posuer -version

# Run in stdio mode (default)
./build/posuer -stdio

# Run with config file watcher enabled
./build/posuer -config /path/to/config.yaml -watch

配置

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

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

配置示例：

# Posuer configuration file
servers:
  # Direct server definition
  - name: filesystem
    type: stdio
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-filesystem"
      - "/tmp"

  # You can also include other config files
  - ~/other-servers.yaml
  - ~/.config/Claude/claude_desktop_config.json

  # Example of an SSE server (remote)
  - 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  # Enable all capabilities
   
     - name: all-disabled
       type: stdio
       command: npx
       args:
         - -y
         - "@modelcontextprotocol/server-memory"
       enable: false  # Disable all capabilities (or use disable: true)
   

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

   servers:
     - name: specific-tools
       type: stdio
       command: npx
       args:
         - -y
         - "@modelcontextprotocol/server-memory"
       enable:
         - create_entities  # Only enable these specific tools
         - read_graph
   
     - name: blocked-tools
       type: stdio
       command: npx
       args:
         - -y
         - "@modelcontextprotocol/server-filesystem"
         - "/tmp"
       disable:
         - write_file  # Disable these specific tools
         - move_file
   

3. 映射（高级能力筛选）

   servers:
     - name: advanced-filtering
       type: stdio
       command: npx
       args:
         - -y
         - "@modelcontextprotocol/server-memory"
       enable:
         tools:  # Enable specific tools
           - create_entities
           - read_graph
         prompts: system_prompt  # Enable a single prompt
         templates:  # Enable specific templates
           - entity_template
           - graph_template
       disable:
         tools:  # Disable specific tools (even if in enable list)
           - delete_entities
   

映射格式支持按不同能力类型筛选：

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

更多配置示例，请参阅默认配置 pkg/config/config.yaml。

动态配置重新加载

Posuer 支持动态重新加载配置，因此你可以在服务运行时修改配置文件。系统会自动检测更改并应用，无需重启。

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

# Run with configuration file watching enabled
./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  # Would normally use a container automatically
       args:
         - -y
         - "@modelcontextprotocol/server-filesystem"
         - "/tmp"
       container: false  # Explicitly disable container usage
   

容器配置选项：

• image：要使用的容器镜像（必填）
• volumes：主机路径到容器路径的映射
• env：要传递给容器的环境变量
• network：网络模式（host、bridge 等）
• user：容器中运行所用的用户
• workdir：容器中的工作目录
• args：要传递给容器运行时的附加参数

自动容器检测

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

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

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

servers:
  # This will automatically run in a Node.js container
  - name: filesystem
    type: stdio
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-filesystem"
      - "/tmp"
    # No container configuration needed, it will be auto-detected

  # To explicitly disable container detection
  - name: local-npm
    type: stdio
    command: npx
    args:
      - -y
      - some-local-package
    container: false  # Explicitly disable container detection

Posuer 会自动检测系统上是否有容器运行时（podman 或 docker），并优先使用 podman，以便更好地支持无 root 容器。

与 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

开发

# Format code
make fmt

# Run linter
make lint

# Run tests
make test

# Clean build artifacts
make clean

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。