What is Mcp Blackboard

mcp-blackboard is a lightweight MCP server designed for managing context and memory in multi-agent task execution using an agentic directed acyclic graph. It allows multiple AI agents to store and retrieve context and results on a shared ‘blackboard’.

Use cases

Use cases for mcp-blackboard include collaborative project management, AI-driven content generation, multi-agent systems in research, and any application where shared memory and context management are essential.

How to use

To use mcp-blackboard, integrate it into any MCP-compatible workflow. Agents can interact with the server through its HTTP/SSE interface to save plans, mark steps as completed, store results, and retrieve context and results.

Key features

Key features of mcp-blackboard include a simple HTTP/SSE interface, the ability to save and retrieve plans, results, and context descriptions, as well as file cache management for stale files.

Where to use

mcp-blackboard can be used in various fields such as AI research, collaborative planning, data extraction, analysis, and any scenario that requires multiple agents to work together efficiently.

mcp-blackboard

Version 0.1.0 – A lightweight blackboard memory server for the Model Context Protocol (MCP)

mcp-blackboard exposes a simple HTTP/SSE interface that lets multiple AI agents store, and retrieve context and results—documents, embeddings, structured objects, and more—on a shared “blackboard”.

It is designed to be dropped into any MCP‑compatible workflow so your planner,
researcher, extractor, analyzer, writer, editor, and evaluator agents can collaborate without reinventing persistence.

Available Tools

MCP Tools

The following tools are available in mcp-blackboard:

• save_plan(plan_id: str, plan: dict | str) -> str
  Save a plan to the shared state.

• mark_plan_as_completed(plan_id: str, step_id: str) -> str
  Mark a plan step as completed in the shared state.

• save_result(plan_id: str, agent_name: str, step_id: str, description: str, result: str | dict) -> str
  Save a result to the shared state.

• save_context_description(plan_id: str, file_path_or_url: str, description: str) -> str
  Write a context description to the shared state.

• get_blackboard(plan_id: str) -> str | dict | None
  Fetch a blackboard entry for a plan.

• get_plan(plan_id: str) -> str | dict | None
  Fetch a plan from the shared state.

• get_result(plan_id: str, agent_name: str, step_id: str) -> str | dict | None
  Fetch a result from the shared state.

• get_context(file_path_or_url: str, use_cache: bool = True) -> str
  Read and convert media content to Markdown format.

File Cache Management Scheduler

• remove_stale_files(max_age: int = 3600) -> None
  Remove files older than the specified age from the cache directory.

✨ Highlights

🚀 Quick Start

1. Local dev environment

git clone https://github.com/your‑org/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

The API listens on http://127.0.0.1:8000 by default (see src/server.py).

2. Docker Compose

docker compose up -d

Compose starts:

• mcp-blackboard – FastAPI+SSE service
• redis – in‑memory store for keys, scores, embeddings

⚙️ Configuration

All settings are environment‑driven:

(see samples/env-sample.txt for the full list)

🏗️ Project Layout

.
├── src/
│   ├── common.py       # Config loader & helpers
│   ├── models.py       # Pydantic data models
│   ├── server.py       # FastAPI + APScheduler
│   └── tools.py        # Context ingestion utilities
├── samples/            # Env template & demo assets
├── tests/              # pytest suite
├── Dockerfile          # Production image
└── docker-compose.yml  # Local stack

🧪 Testing

pytest -q

🤝 Contributing

1. Fork and create a feature branch
2. Use conventional commits (feat:, fix:…)
3. Run make lint test locally
4. Open a PR—squash merge once approved

📜 License

Distributed under the MIT License – see LICENSE for details.

© 2025 Kwesi Apponsah