MCP 服务器

Blackboard MCP

Cross-session coordination server for Claude Code that manages file claims, build locks, shared knowledge, and provides a real-time dashboard to prevent conflicts across multiple sessions.

README

Blackboard MCP

Cross-session coordination server for <a href="https://code.claude.com">Claude Code</a> File locks · Build locks · Knowledge sharing · Real-time dashboard

The Problem

You open 3 Claude Code windows to work on different tasks. Suddenly:

File conflict — Two sessions edit the same file simultaneously, one overwrites the other
Build collision — Two sessions run ./gradlew at the same time, Gradle daemons pile up, OOM
Duplicated work — One session fixes a bug that another session already fixed yesterday
No visibility — You can't see what other sessions are doing

Blackboard solves this. It acts as a registry center where every session registers, claims files, acquires build locks, and shares knowledge.

Features

Feature	Description
Session Registry	Auto-register via SessionStart hook, heartbeat monitoring, stale cleanup
File Conflict Detection	Claim files before editing, detect conflicts across sessions
Build Lock Coordination	Only one session compiles at a time, with 10min timeout
Shared Knowledge Base	Share decisions, bug patterns, and knowledge with confidence scoring + decay
Real-time Dashboard	tkinter GUI with session list, sorting, health checks, and knowledge viewer
Crash Recovery	3-level state recovery: state.json → .bak → events.log replay
MCP Restart Resilient	Sessions survive MCP server restarts, no data loss

Quick Start

1. Clone & Install

git clone https://github.com/RD2100/blackboard-mcp.git
cd blackboard-mcp
pip install mcp  # only dependency

2. Register with Claude Code

claude mcp add -s user blackboard -- python "/path/to/blackboard-mcp/server.py"

3. Add SessionStart Hook

Add to ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash \"/path/to/blackboard-mcp/scripts/bb-hook-session-start.sh\""
          }
        ]
      }
    ]
  }
}

4. Add Rules (Recommended)

Copy rules/blackboard-protocol.md to your project's .claude/rules/ or ~/.claude/rules/.

5. Open Dashboard (Optional)

Windows: Double-click scripts/bb-monitor.bat

macOS/Linux:

python scripts/bb-monitor-gui.py /path/to/your/project

MCP Tools

Session Management

Tool	Description
`bb_register(name, task, session_id)`	Register/update session
`bb_deregister(session_id)`	Unregister session, release all files
`bb_heartbeat(session_id)`	Refresh session heartbeat
`bb_status()`	View full system status with health checks
`bb_session_files(session_id)`	List files claimed by a session

File Coordination

Tool	Description
`bb_claim_file(session_id, file_path)`	Claim file ownership (returns CONFLICT/CLAIMED/OWN)
`bb_release_file(session_id, file_path)`	Release file ownership
`bb_check_conflicts(file_paths)`	Check if files are claimed by others

Build Coordination

Tool	Description
`bb_acquire_build_lock(session_id, project_dir)`	Acquire build lock (returns ACQUIRED/CONFLICT)
`bb_release_build_lock(session_id, project_dir)`	Release build lock

Knowledge Management

Tool	Description
`bb_share_knowledge(session_id, fingerprint, category, text)`	Share knowledge entry (deduped by fingerprint)
`bb_search_knowledge(query, category?)`	Search knowledge base
`bb_validate_knowledge(session_id, fingerprint, verdict)`	Validate/refute knowledge (affects confidence)
`bb_get_recent_knowledge(hours?)`	Get recent knowledge, decisions, and bug patterns
`bb_share_decision(session_id, decision, rationale?)`	Record architecture/design decision
`bb_report_bug_pattern(session_id, pattern, root_cause, fix)`	Report bug pattern / pitfall
`bb_event(session_id, event_type, details?)`	Log custom event

Architecture

Session A ──┐
            ├──▶ MCP Server (blackboard) ──▶ state.json (disk)
Session B ──┤         │
            │    ┌────┴────┐
Session C ──┘    │ Cleanup  │  60s stale cleanup thread
                 │ Decay    │  hourly knowledge confidence decay
                 │ Reload   │  detect hook-written state changes
                 └─────────┘

Dashboard ──▶ reads state.json directly (2s refresh)

Knowledge Lifecycle

Share (conf=0.5) → Validate confirmed (+0.2) → ... → conf ≥ 0.8 → ★ HIGH CONFIDENCE
                  → Validate refuted  (-0.5) → ... → conf ≤ 0.2 → archived
                  → 30 days no reference → confidence decays (half-life)
                  → 60 days no reference → archived

Configuration

Parameter	Default	Description
`STALE_TIMEOUT_MINUTES`	30	Minutes before inactive session is marked stale
`BUILD_LOCK_TIMEOUT_MINUTES`	10	Minutes before build lock auto-releases
`KNOWLEDGE_HALF_LIFE_DAYS`	30	Days before knowledge confidence decays by half
`KNOWLEDGE_ARCHIVE_DAYS`	60	Days before knowledge is archived

Privacy

All data is stored locally in .claude/blackboard/ within your project directory. No data is sent externally. The following files should NOT be committed to version control:

state.json / state.json.bak — runtime session state
events.log — event history

Comparison with Alternatives

Feature	Blackboard	ccsession	claude-presence
Session registry	✅	✅	✅
File conflict detection	✅	❌	❌
Build lock coordination	✅	❌	❌
Shared knowledge base	✅	❌	❌
Confidence scoring + decay	✅	❌	❌
Real-time dashboard	✅	❌	❌
Crash recovery	✅	❌	❌
MCP restart resilient	✅	❌	❌

anthropics/claude-code#24798 — Inter-session communication for multi-Claude workflows
anthropics/claude-code#47997 — Multi-session coordination feature request
Claude Code Agent Teams — Official in-process multi-agent (single session)