mcp-blackboard

mcp-blackboard

Version 0.1.0 – **Model Context Protocol（MCP）**向けの軽量なブラックボードメモリサーバー

mcp-blackboard は、複数の AI エージェントが共有の「ブラックボード」にコンテキストや結果（ドキュメント、埋め込み、構造化オブジェクトなど）を保存し、取得するためのシンプルな HTTP/SSE インターフェースを提供します。

既存の MCP 対応ワークフローに組み込むだけで、マルチエージェントシステムが永続化の仕組みを一から作り直すことなく、状態を共有し、協調できます。

---

利用可能なツール

MCP ツール

mcp-blackboard では、以下のツールを利用できます。

• save_plan(plan_id: str, plan: dict | str) -> str 共有状態に計画を保存します。

• mark_plan_as_completed(plan_id: str, step_id: str) -> str 共有状態で計画のステップを完了済みとしてマークします。

• save_result(plan_id: str, agent_name: str, step_id: str, description: str, result: str | dict) -> str 共有状態に結果を保存します。

• save_context_description(plan_id: str, file_path_or_url: str, description: str) -> str コンテキストの説明を共有状態に書き込みます。

• get_blackboard(plan_id: str) -> str | dict | None 計画のブラックボードエントリーを取得します。

• get_plan(plan_id: str) -> str | dict | None 共有状態から計画を取得します。

• get_result(plan_id: str, agent_name: str, step_id: str) -> str | dict | None 結果を取得します。

• get_context(file_path_or_url: str, use_cache: bool = True) -> str メディアコンテンツを読み込み、Markdown 形式に変換します。

ファイルキャッシュ管理スケジューラー

• remove_stale_files(max_age: int = 3600) -> None 指定した経過時間より古いファイルをキャッシュディレクトリから削除します。

✨ 特長

機能	メリット
統合メモリ	エージェントのコンテキストを一元管理できるため、場当たり的な一時ファイルや一時的な Redis キーが不要です。
ファイルシステム抽象化	fsspec を基盤とし、S3、Azure Blob、GCS、ABFS、SFTP、SMB などに対応するオプションのドライバーを利用できます。
リアルタイム更新	Server-Sent Events（SSE）により、接続中のエージェントにコンテキストの変更を即座に配信します。
メンテナンススケジューラー	プラグイン可能な cron ジョブにより、期限切れのキーを自動的に削除し、埋め込みを更新します。
コンテナー対応	uv ロックファイルによる再現性の高いビルドを実現し、軽量な Docker イメージは 90 MB 未満です。

---

🚀 クイックスタート

1. ローカル開発環境

git clone https://github.com/pwc-ca-adv-genai-factory/mcp-blackboard.git
cd mcp-blackboard

# Create an isolated env & install locked deps
uv venv
uv sync

# Copy the sample env and fill in credentials
cp samples/env-sample.txt .env

# Run the server (FastAPI)
uv run src/main.py

API はデフォルトで http://127.0.0.1:8000 でリッスンします（src/server.py を参照）。

2. Docker Compose

docker compose up -d

Compose は以下を起動します。

• mcp-blackboard – ブラックボード MCP サーバー
• mem-blackboard – Redis を使用してキー、スコア、埋め込み、メタデータを保存するインメモリストア

---

⚙️ 設定

すべての設定は環境変数で指定します。

変数	用途
OPENAI_API_KEY	Embeddings／LLM の呼び出し（任意）
OPENAI_API_BASE	カスタム OpenAI API ベース URL（任意）
OPENAI_DEFAULT_MODEL	Embeddings に使用する OpenAI モデル（任意）
MCP_TRANSPORT	イベントのトランスポート（sse または stdio）
CACHE_PATH	ファイルキャッシュのディレクトリ。ローカル、abfs、s3 などを指定できます。
REDIS_HOST、REDIS_PORT、REDIS_DB	Redis 接続
AZURE_STORAGE_ACCOUNT / AWS_ACCESS_KEY_ID / …	リモートファイルシステム用の認証情報

（全項目については samples/env-sample.txt を参照してください）

---

🏗️ プロジェクト構成

├── .devcontainer/                # Dev container setup
│   ├── certs/                    # Custom CA certificates
│   │   └── cacert.pem
│   ├── Dockerfile                # Dev container Dockerfile
│   ├── post-create.sh            # Post-creation setup script
│   └── scripts/                  # Utility scripts for dev container
│       ├── add-dependencies.sh
│       └── add-precommit-hooks.sh
├── .vscode/                      # VS Code workspace settings
│   ├── cspell.json               # Spell checker config
│   ├── settings.json             # Workspace settings
│   ├── tasks.json                # Task runner config
├── src/                          # Application source code
│   ├── common.py                 # Config loader & utility functions
│   ├── config.yaml.j2            # Jinja2 template for config
│   ├── main.py                   # App entry point
│   ├── models.py                 # Pydantic models
│   ├── server.py                 # FastAPI server & scheduler
│   └── tools/                    # Tool implementations
│       ├── context.py            # Document/context tools
│       └── memory.py             # Blackboard/memory tools
├── samples/                      # Example files & templates
│   ├── _task.yml                 # Task definition sample
│   ├── credit_report.pdf         # Sample PDF
│   ├── env-sample.txt            # Env variable template
│   ├── loe_sample.png            # Sample PNG
│   ├── plan.json                 # Sample plan
│   └── ps_sample.png             # Additional PNG
├── tests/                        # Test suite
│   └── conftest.py               # Pytest fixtures
├── docker-compose.yaml           # Docker Compose config
├── Dockerfile                    # Production Dockerfile
├── LICENSE                       # MIT License
├── Makefile                      # Build/test commands
├── pyproject.toml                # Project metadata & deps
├── README.md                     # Project documentation
└── uv.lock                       # Dependency lockfile

---

🧪 テスト

make tests

---

🤝 コントリビューション

1. フォークして、機能ブランチを作成します
2. Conventional Commits に従います（feat:、fix:…）
3. ローカルで make lint test を実行します
4. PR を作成し、承認後にスカッシュマージします

---

📜 ライセンス

MIT License のもとで配布されています。詳細については LICENSE を参照してください。

© 2025 Kwesi Apponsah