Metadata-Version: 2.4
Name: stigmergent-mcp
Version: 0.1.0
Summary: MCP server for Stigmergent — multi-agent coordination via stigmergic blackboard
Project-URL: Homepage, https://github.com/CSI-Platform/stigmergent
Project-URL: Repository, https://github.com/CSI-Platform/stigmergent
Project-URL: Issues, https://github.com/CSI-Platform/stigmergent/issues
Author-email: Copper State Intelligence <cody@copperstateit.com>
License: Apache-2.0
Keywords: a2a,agents,blackboard,mcp,multi-agent,stigmergy
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.0.0
Description-Content-Type: text/markdown

# Stigmergent

**Multi-agent coordination platform using stigmergic intelligence.** Agents coordinate through a shared blackboard -- not through each other -- the same way ant colonies organize millions of workers without a manager.

Five reference agents handle daily business operations: email triage, calendar management, project tracking, meeting prep, and daily briefings. The blackboard protocol is the real product -- agents are the proof it works.

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)

## Quickstart

### Option 1: MCP Server (connect to running agents)

```bash
pip install stigmergent-mcp
```

Configure your agent URLs:

```bash
export CSI_CHIEF_URL=https://your-chief-agent.azurecontainerapps.io
export CSI_COMMS_URL=https://your-comms-agent.azurecontainerapps.io
export CSI_OPS_URL=https://your-ops-agent.azurecontainerapps.io
export CSI_SCHEDULE_URL=https://your-schedule-agent.azurecontainerapps.io
export CSI_KNOWLEDGE_URL=https://your-knowledge-agent.azurecontainerapps.io
```

Add to Claude Code:

```json
{
  "mcpServers": {
    "stigmergent": {
      "command": "stigmergent-mcp",
      "env": {
        "CSI_CHIEF_URL": "https://your-chief-agent.azurecontainerapps.io",
        "CSI_COMMS_URL": "https://your-comms-agent.azurecontainerapps.io",
        "CSI_OPS_URL": "https://your-ops-agent.azurecontainerapps.io",
        "CSI_SCHEDULE_URL": "https://your-schedule-agent.azurecontainerapps.io",
        "CSI_KNOWLEDGE_URL": "https://your-knowledge-agent.azurecontainerapps.io"
      }
    }
  }
}
```

### Option 2: Full Local Stack (agents + blackboard)

```bash
git clone https://github.com/CSI-Platform/stigmergent.git
cd stigmergent
cp .env.template .env
# Fill in your M365 credentials and Anthropic API key
docker-compose up
```

This starts all 5 agents locally on ports 8001-8005.

## What Each Agent Does

| Agent | Port | Role |
|-------|------|------|
| **Communications Specialist** | 8001 | Email triage, drafting, commitment scanning, client pulse |
| **Operations Manager** | 8002 | Project tracking, action items, accountability checks |
| **Knowledge Curator** | 8003 | Meeting prep, transcript processing, knowledge retrieval |
| **Schedule Coordinator** | 8004 | Calendar management, availability, scheduling |
| **Chief of Staff** | 8005 | Morning briefings, delegation, aggregation |

## MCP Tools

The MCP server exposes 9 tools:

| Tool | Description |
|------|-------------|
| `morning_briefing` | Daily briefing -- calendar, projects, blackboard alerts |
| `triage_emails` | Classify and prioritize recent emails |
| `draft_email` | Draft a professional email from instructions |
| `check_calendar` | Show upcoming events |
| `schedule_meeting` | Create calendar events from natural language |
| `list_projects` | Active projects with status and chase dates |
| `accountability_check` | Scan for overdue items and stale projects |
| `scan_commitments` | Find open commitments in sent mail |
| `prep_meeting` | Build context and talking points for meetings |

## How It Works

```
You (Claude Code / any MCP client)
    |
    v
MCP Server (stigmergent-mcp)
    |
    v  A2A JSON-RPC
+-------+-------+-----+-------+------+
| Chief | Comms | Ops | Sched | Know |  <-- Agents (Docker / Azure)
+-------+-------+-----+-------+------+
    |       |       |
    v       v       v
  Dataverse    Graph API    SharePoint
 (Blackboard)  (Mail/Cal)   (Projects)
```

**Stigmergic coordination:** Agents write entries to the blackboard (Dataverse). Other agents sense those entries and act. The Communications Specialist writes a `Classification` entry; the Operations Manager reads it during an accountability check. No direct messaging needed for routine coordination.

**Peer delegation:** For complex tasks, agents call each other via A2A protocol. Ops asks Comms to draft follow-up emails. Comms asks Knowledge for context before drafting.

**LLM-first routing:** Each agent uses Claude Haiku for fast intent classification with keyword fallback. Novel phrasing gets routed correctly without brittle pattern matching.

## Configuration

Copy `.env.template` to `.env` and fill in:

| Variable | Required | Description |
|----------|----------|-------------|
| `CSI_TENANT_ID` | Yes | Azure AD tenant ID |
| `CSI_CLIENT_ID` | Yes | App registration client ID |
| `CSI_CLIENT_SECRET` | Yes | App registration client secret |
| `CSI_DATAVERSE_URL` | Yes | Dataverse environment URL |
| `CSI_SHAREPOINT_HOST` | Yes | SharePoint host domain |
| `CSI_SHAREPOINT_SITE_PATH` | Yes | SharePoint site path |
| `CSI_USER_EMAIL` | Yes | User email for Graph API calls |
| `ANTHROPIC_API_KEY` | Yes | Anthropic API key for LLM |
| `CSI_LLM_MODEL` | No | Main model (default: claude-sonnet-4-6) |
| `CSI_LLM_ROUTER_MODEL` | No | Router model (default: claude-haiku-4-5-20251001) |
| `TZ` | No | Timezone (default: America/Phoenix) |

### Prerequisites

- **Microsoft 365 tenant** with Outlook, Calendar, SharePoint
- **Azure AD app registration** with Graph API permissions (Mail.Read, Calendars.ReadWrite, Sites.ReadWrite.All)
- **Dataverse environment** with the blackboard table provisioned
- **Anthropic API key** for Claude
- **Docker** for running agents locally
- **Python 3.13+** for the MCP server

## Blackboard Protocol

The blackboard is the coordination surface. Agents write entries with:
- **Entry type** (Classification, ActionRequired, AccountabilityAlert, ClientPulse, etc.)
- **Status lifecycle** (New -> Read -> Acted -> Expired)
- **Priority** (Low, Normal, High, Urgent)
- **Source agent** identity
- **Payload** (flexible JSON)

Any A2A-compliant agent can participate by reading and writing blackboard entries. The protocol spec: [extensions/blackboard/extension-spec.yaml](extensions/blackboard/extension-spec.yaml)

## Project Structure

```
stigmergent/
  agents/
    chief-of-staff/          # Briefings, delegation, aggregation
    communications-specialist/ # Email, commitments, client pulse
    operations-manager/       # Projects, action items, accountability
    knowledge-curator/        # Meeting prep, knowledge management
    schedule-coordinator/     # Calendar, scheduling, availability
  csi-core/                  # Shared library (auth, blackboard, Graph, LLM, router)
  mcp-server/                # MCP server (9 tools, stdio transport)
  extensions/                # Blackboard protocol spec
  docker-compose.yml         # Local development stack
```

## Building Your Own Agent

Any Python A2A server can participate in Stigmergent coordination by reading and writing blackboard entries. The key contract: write entries to announce what you've done or discovered. Read entries to sense what other agents have done. The blackboard handles the coordination -- you just participate.

## License

Apache License 2.0. See [LICENSE](LICENSE) for the full text.

Built by [Copper State Intelligence](https://copperstateit.com).
