Posuer: MCP Manager and Interposer

Posuer：MCP マネージャー兼インターポーザー

LLM を強化する強力な Model Context Protocol（MCP）マネージャーです。

• Docker コンテナ化 - MCP サーバーを分離されたコンテナ内で実行し、自動検出します
• 動的な設定の再読み込み - 再起動せずにサーバー設定を更新します
• 複数サーバーの集約 - 異なるサーバーのツールとリソースをまとめます
• スマートな機能ルーティング - リクエストを適切なバックエンドサーバーに転送します
• 高度な設定 - ツール公開をきめ細かく制御します

プロジェクトのビジョン

Posuer は、MCP クライアント（Claude Desktop など）と複数の MCP サーバーをつなぐブリッジとして機能します。各サーバーを LLM クライアントに個別に接続する代わりに、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 プロトコルの両側を実装します。

• Claude Desktop などのクライアントに対しては、MCP サーバーとして機能します
• バックエンドサーバーに対しては、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 は、次の 3 つの形式による柔軟な機能設定を提供します。

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：LLM が呼び出せるツール関数
• prompts：LLM が使用できるシステムプロンプト
• 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 サーバーをコンテナ内で実行できます。コンテナ設定は、次の 3 つの形式で指定できます。

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）がシステムで利用可能かどうかを自動的に検出し、rootless コンテナのサポートが優れている 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 を再起動します

開発

# Format code
make fmt

# Run linter
make lint

# Run tests
make test

# Clean build artifacts
make clean

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細については LICENSE ファイルを参照してください。