mcp-blackboard

mcp-blackboard

Version 0.1.0 – 面向 Model Context Protocol (MCP) 的轻量级黑板记忆服务

mcp-blackboard 提供简单的 HTTP/SSE 接口，让多个 AI Agent 在共享的“黑板”上存储和检索上下文与结果——包括文档、嵌入向量、结构化对象等。

它旨在集成到任何兼容 MCP 的工作流中，让多 Agent 系统能够共享状态并协同工作，无需重新发明持久化方案。

---

可用工具

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 从缓存目录中移除超过指定时长的文件。

✨ 亮点

功能	重要性
统一记忆	为 Agent 上下文提供唯一可信来源，无需临时创建临时文件或短暂的 Redis 键。
文件系统抽象	基于 fsspec 构建，可选驱动支持 S3、Azure Blob、GCS、ABFS、SFTP、SMB 等。
实时更新	通过服务器发送事件 (SSE) 即时向已连接的 Agent 推送上下文变更。
日常维护调度器	可插拔的 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	嵌入 / LLM 调用（可选）
OPENAI_API_BASE	自定义 OpenAI API 基础 URL（可选）
OPENAI_DEFAULT_MODEL	用于嵌入的 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. Fork 并创建功能分支
2. 使用 Conventional Commits（feat:、fix:……）
3. 在本地运行 make lint test
4. 提交 PR——获批后采用 squash merge

---

📜 许可证

基于 MIT License 发布——详情请参见 LICENSE。

© 2025 Kwesi Apponsah