mcp-blackboard-graph 0.1.0__tar.gz

mcp_blackboard_graph-0.1.0/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: mcp-blackboard-graph
+Version: 0.1.0
+Summary: MCP server for multi-agent coordination via shared graph - nodes with messages, notes, and status
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0.0

mcp_blackboard_graph-0.1.0/README.md

@@ -0,0 +1,20 @@
+# mcp-blackboard-graph
+A common blackboard for a number of LLM agents to write on for coordination.
+This takes the form of a directed graph. You can send messages to nodes.
+
+This is a relative general structure but could be used for a tree of tasks.
+
+This is pure AI-generated code - review before use.
+
+
+## Installation
+pipx install mcp-blackboard-graph
+
+## Usage
+mcp-blackboard-graph will be on your path. Wire it up to your mcp server.
+
+## Alternatives
+`task-tree-mcp` seems to concern itself with plans. This was too high leel for my interestes.
+
+`mcp-blackboard` did not have messages which I really wanted.
+

mcp_blackboard_graph-0.1.0/mcp_blackboard_graph/main.py

@@ -0,0 +1,354 @@
+#!/usr/bin/env python3
+"""
+MCP server for multi-agent coordination via shared DAG.
+
+Nodes have: id, parents, children, status, notes, messages, data.
+Multiple agents can read/write to the graph.
+"""
+
+import asyncio
+import json
+import os
+from datetime import datetime
+from pathlib import Path
+
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import Tool, TextContent
+
+
+def get_graph_path():
+    """Get path to graph.json file."""
+    path = os.environ.get("BLACKBOARD_GRAPH_PATH")
+    if path:
+        return Path(path)
+    return Path.cwd() / "graph.json"
+
+
+def load_graph():
+    """Load graph from JSON file."""
+    path = get_graph_path()
+    if path.exists():
+        return json.loads(path.read_text())
+    return {
+        "nodes": {
+            "root": {
+                "id": "root",
+                "parents": [],
+                "children": [],
+                "status": "active",
+                "notes": [],
+                "messages": [],
+                "data": {}
+            }
+        }
+    }
+
+
+def save_graph(graph):
+    """Save graph to JSON file."""
+    path = get_graph_path()
+    path.write_text(json.dumps(graph, indent=2) + "\n")
+
+
+def get_node(graph, node_id):
+    """Get a node by id."""
+    return graph["nodes"].get(node_id)
+
+
+def ensure_node_fields(node):
+    """Ensure node has all required fields."""
+    node.setdefault("parents", [])
+    node.setdefault("children", [])
+    node.setdefault("status", "active")
+    node.setdefault("notes", [])
+    node.setdefault("messages", [])
+    node.setdefault("data", {})
+
+
+def format_node(node, show_notes=True, show_messages=True, show_data=True):
+    """Format a single node for display."""
+    parts = [f"{node['id']} [{node.get('status', 'active')}]"]
+    if node.get("parents"):
+        parts.append(f"  parents: {', '.join(node['parents'])}")
+    if node.get("children"):
+        parts.append(f"  children: {', '.join(node['children'])}")
+    if show_notes and node.get("notes"):
+        parts.append(f"  notes: {len(node['notes'])}")
+        for n in node["notes"]:
+            parts.append(f"    - {n[:50]}{'...' if len(n) > 50 else ''}")
+    if show_messages and node.get("messages"):
+        parts.append(f"  messages: {len(node['messages'])}")
+        for m in node["messages"]:
+            parts.append(f"    - [{m.get('from', '?')}] {m['text'][:40]}{'...' if len(m['text']) > 40 else ''}")
+    if show_data and node.get("data"):
+        parts.append(f"  data: {json.dumps(node['data'])[:60]}{'...' if len(json.dumps(node['data'])) > 60 else ''}")
+    return "\n".join(parts)
+
+
+def format_graph(graph, node_id=None, show_notes=True, show_messages=True, show_data=True):
+    """Format graph or single node for display."""
+    if node_id:
+        node = get_node(graph, node_id)
+        if not node:
+            return f"Error: node '{node_id}' not found"
+        return format_node(node, show_notes, show_messages, show_data)
+
+    lines = []
+    for nid, node in graph["nodes"].items():
+        lines.append(format_node(node, show_notes, show_messages, show_data))
+        lines.append("")
+    return "\n".join(lines).strip()
+
+
+async def run_server():
+    """Run the MCP server."""
+    server = Server("mcp-blackboard-graph")
+
+    tools = [
+        Tool(
+            name="show",
+            description="Show the graph or a single node",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "node": {"type": "string", "description": "Node id to show (omit for all)"},
+                    "hide_notes": {"type": "boolean", "description": "Hide notes", "default": False},
+                    "hide_messages": {"type": "boolean", "description": "Hide messages", "default": False},
+                    "hide_data": {"type": "boolean", "description": "Hide data", "default": False}
+                },
+                "required": []
+            }
+        ),
+        Tool(
+            name="add",
+            description="Add a new node to the graph",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "id": {"type": "string", "description": "Node id (unique)"},
+                    "parents": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Parent node ids (for DAG structure)"
+                    },
+                    "status": {"type": "string", "description": "Initial status (default: active)"},
+                    "data": {"type": "object", "description": "Initial data dict"}
+                },
+                "required": ["id"]
+            }
+        ),
+        Tool(
+            name="remove",
+            description="Remove a node from the graph",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "id": {"type": "string", "description": "Node id to remove"}
+                },
+                "required": ["id"]
+            }
+        ),
+        Tool(
+            name="get",
+            description="Get full details of a node as JSON",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "id": {"type": "string", "description": "Node id"}
+                },
+                "required": ["id"]
+            }
+        ),
+        Tool(
+            name="set_status",
+            description="Set status of a node",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "id": {"type": "string", "description": "Node id"},
+                    "status": {"type": "string", "description": "New status"}
+                },
+                "required": ["id", "status"]
+            }
+        ),
+        Tool(
+            name="add_data",
+            description="Merge data dict into a node's data",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "id": {"type": "string", "description": "Node id"},
+                    "data": {"type": "object", "description": "Data to merge"}
+                },
+                "required": ["id", "data"]
+            }
+        ),
+        Tool(
+            name="add_note",
+            description="Add a note to a node",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "id": {"type": "string", "description": "Node id"},
+                    "note": {"type": "string", "description": "Note text"}
+                },
+                "required": ["id", "note"]
+            }
+        ),
+        Tool(
+            name="send_message",
+            description="Send a message to a node",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "id": {"type": "string", "description": "Node id"},
+                    "message": {"type": "string", "description": "Message text"},
+                    "from_agent": {"type": "string", "description": "Sender name (optional)"}
+                },
+                "required": ["id", "message"]
+            }
+        ),
+    ]
+
+    @server.list_tools()
+    async def list_tools():
+        return tools
+
+    @server.call_tool()
+    async def call_tool(name: str, arguments: dict):
+        graph = load_graph()
+
+        if name == "show":
+            node_id = arguments.get("node")
+            show_notes = not arguments.get("hide_notes", False)
+            show_messages = not arguments.get("hide_messages", False)
+            show_data = not arguments.get("hide_data", False)
+            result = format_graph(graph, node_id, show_notes, show_messages, show_data)
+            return [TextContent(type="text", text=result)]
+
+        elif name == "add":
+            node_id = arguments.get("id", "").strip()
+            parents = arguments.get("parents", [])
+            status = arguments.get("status", "active")
+            data = arguments.get("data", {})
+
+            if not node_id:
+                return [TextContent(type="text", text="Error: id is required")]
+            if node_id in graph["nodes"]:
+                return [TextContent(type="text", text=f"Error: node '{node_id}' already exists")]
+
+            # Validate parents exist
+            for p in parents:
+                if p not in graph["nodes"]:
+                    return [TextContent(type="text", text=f"Error: parent '{p}' not found")]
+
+            # Create node
+            graph["nodes"][node_id] = {
+                "id": node_id,
+                "parents": parents,
+                "children": [],
+                "status": status,
+                "notes": [],
+                "messages": [],
+                "data": data
+            }
+
+            # Update parent nodes' children lists
+            for p in parents:
+                if node_id not in graph["nodes"][p]["children"]:
+                    graph["nodes"][p]["children"].append(node_id)
+
+            save_graph(graph)
+            return [TextContent(type="text", text=f"Added node '{node_id}'")]
+
+        elif name == "remove":
+            node_id = arguments.get("id", "")
+            if node_id == "root":
+                return [TextContent(type="text", text="Error: cannot remove root")]
+            if node_id not in graph["nodes"]:
+                return [TextContent(type="text", text=f"Error: node '{node_id}' not found")]
+
+            node = graph["nodes"][node_id]
+
+            # Remove from parents' children lists
+            for p in node.get("parents", []):
+                if p in graph["nodes"]:
+                    graph["nodes"][p]["children"] = [c for c in graph["nodes"][p]["children"] if c != node_id]
+
+            # Remove from children's parents lists
+            for c in node.get("children", []):
+                if c in graph["nodes"]:
+                    graph["nodes"][c]["parents"] = [p for p in graph["nodes"][c]["parents"] if p != node_id]
+
+            del graph["nodes"][node_id]
+            save_graph(graph)
+            return [TextContent(type="text", text=f"Removed node '{node_id}'")]
+
+        elif name == "get":
+            node_id = arguments.get("id", "")
+            node = get_node(graph, node_id)
+            if not node:
+                return [TextContent(type="text", text=f"Error: node '{node_id}' not found")]
+            return [TextContent(type="text", text=json.dumps(node, indent=2))]
+
+        elif name == "set_status":
+            node_id = arguments.get("id", "")
+            status = arguments.get("status", "")
+            node = get_node(graph, node_id)
+            if not node:
+                return [TextContent(type="text", text=f"Error: node '{node_id}' not found")]
+            node["status"] = status
+            save_graph(graph)
+            return [TextContent(type="text", text=f"Set status of '{node_id}' to '{status}'")]
+
+        elif name == "add_data":
+            node_id = arguments.get("id", "")
+            data = arguments.get("data", {})
+            node = get_node(graph, node_id)
+            if not node:
+                return [TextContent(type="text", text=f"Error: node '{node_id}' not found")]
+            ensure_node_fields(node)
+            node["data"].update(data)
+            save_graph(graph)
+            return [TextContent(type="text", text=f"Added data to '{node_id}'")]
+
+        elif name == "add_note":
+            node_id = arguments.get("id", "")
+            note = arguments.get("note", "")
+            node = get_node(graph, node_id)
+            if not node:
+                return [TextContent(type="text", text=f"Error: node '{node_id}' not found")]
+            ensure_node_fields(node)
+            node["notes"].append(note)
+            save_graph(graph)
+            return [TextContent(type="text", text=f"Added note to '{node_id}'")]
+
+        elif name == "send_message":
+            node_id = arguments.get("id", "")
+            message = arguments.get("message", "")
+            from_agent = arguments.get("from_agent", "anonymous")
+            node = get_node(graph, node_id)
+            if not node:
+                return [TextContent(type="text", text=f"Error: node '{node_id}' not found")]
+            ensure_node_fields(node)
+            node["messages"].append({
+                "from": from_agent,
+                "text": message,
+                "time": datetime.now().isoformat()
+            })
+            save_graph(graph)
+            return [TextContent(type="text", text=f"Message sent to '{node_id}'")]
+
+        return [TextContent(type="text", text=f"Unknown tool: {name}")]
+
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(read_stream, write_stream, server.create_initialization_options())
+
+
+def main():
+    asyncio.run(run_server())
+
+
+if __name__ == "__main__":
+    main()

mcp_blackboard_graph-0.1.0/mcp_blackboard_graph.egg-info/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: mcp-blackboard-graph
+Version: 0.1.0
+Summary: MCP server for multi-agent coordination via shared graph - nodes with messages, notes, and status
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0.0

mcp_blackboard_graph-0.1.0/mcp_blackboard_graph.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+mcp_blackboard_graph/__init__.py
+mcp_blackboard_graph/main.py
+mcp_blackboard_graph.egg-info/PKG-INFO
+mcp_blackboard_graph.egg-info/SOURCES.txt
+mcp_blackboard_graph.egg-info/dependency_links.txt
+mcp_blackboard_graph.egg-info/entry_points.txt
+mcp_blackboard_graph.egg-info/requires.txt
+mcp_blackboard_graph.egg-info/top_level.txt
+tests/test_graph.py

mcp_blackboard_graph-0.1.0/mcp_blackboard_graph.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mcp_blackboard_graph-0.1.0/mcp_blackboard_graph.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-blackboard-graph = mcp_blackboard_graph.main:main

mcp_blackboard_graph-0.1.0/mcp_blackboard_graph.egg-info/requires.txt

@@ -0,0 +1 @@
+mcp>=1.0.0

mcp_blackboard_graph-0.1.0/mcp_blackboard_graph.egg-info/top_level.txt

@@ -0,0 +1 @@
+mcp_blackboard_graph

mcp_blackboard_graph-0.1.0/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "mcp-blackboard-graph"
+version = "0.1.0"
+description = "MCP server for multi-agent coordination via shared graph - nodes with messages, notes, and status"
+requires-python = ">=3.10"
+dependencies = ["mcp>=1.0.0"]
+
+[project.scripts]
+mcp-blackboard-graph = "mcp_blackboard_graph.main:main"
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["mcp_blackboard_graph"]

mcp_blackboard_graph-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mcp_blackboard_graph-0.1.0/tests/test_graph.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""Test the blackboard graph."""
+import os
+import tempfile
+
+# Use temp dir for graph
+tmpdir = tempfile.mkdtemp(prefix="bbg-test-")
+os.environ["BLACKBOARD_GRAPH_PATH"] = f"{tmpdir}/graph.json"
+
+from mcp_blackboard_graph.main import load_graph, save_graph, get_node, ensure_node_fields
+
+
+def test_load_empty():
+    graph = load_graph()
+    assert "nodes" in graph
+    assert "root" in graph["nodes"]
+    print("  load empty: ok")
+
+
+def test_add_node():
+    graph = load_graph()
+    graph["nodes"]["child1"] = {
+        "id": "child1",
+        "parents": ["root"],
+        "children": [],
+        "status": "active",
+        "notes": [],
+        "messages": [],
+        "data": {}
+    }
+    graph["nodes"]["root"]["children"].append("child1")
+    save_graph(graph)
+
+    graph = load_graph()
+    node = get_node(graph, "child1")
+    assert node is not None
+    assert node["id"] == "child1"
+    assert "root" in node["parents"]
+    print("  add node: ok")
+
+
+def test_dag_multiple_parents():
+    graph = load_graph()
+    # Add second parent
+    graph["nodes"]["parent2"] = {
+        "id": "parent2",
+        "parents": ["root"],
+        "children": ["child1"],
+        "status": "active",
+        "notes": [],
+        "messages": [],
+        "data": {}
+    }
+    graph["nodes"]["root"]["children"].append("parent2")
+    graph["nodes"]["child1"]["parents"].append("parent2")
+    save_graph(graph)
+
+    graph = load_graph()
+    node = get_node(graph, "child1")
+    assert len(node["parents"]) == 2
+    assert "root" in node["parents"]
+    assert "parent2" in node["parents"]
+    print("  dag multiple parents: ok")
+
+
+def test_notes_and_messages():
+    graph = load_graph()
+    node = get_node(graph, "child1")
+    ensure_node_fields(node)
+    node["notes"].append("test note")
+    node["messages"].append({"from": "agent1", "text": "hello", "time": "now"})
+    save_graph(graph)
+
+    graph = load_graph()
+    node = get_node(graph, "child1")
+    assert len(node["notes"]) == 1
+    assert len(node["messages"]) == 1
+    print("  notes and messages: ok")
+
+
+def test_data():
+    graph = load_graph()
+    node = get_node(graph, "child1")
+    ensure_node_fields(node)
+    node["data"]["key"] = "value"
+    node["data"]["count"] = 42
+    save_graph(graph)
+
+    graph = load_graph()
+    node = get_node(graph, "child1")
+    assert node["data"]["key"] == "value"
+    assert node["data"]["count"] == 42
+    print("  data: ok")
+
+
+if __name__ == "__main__":
+    tests = [test_load_empty, test_add_node, test_dag_multiple_parents, test_notes_and_messages, test_data]
+    for t in tests:
+        print(f"{t.__name__}:")
+        t()
+    print(f"\nAll {len(tests)} tests passed!")