# Stigmergy Mcp

> MCP server implementing digital pheromone-based indirect coordination for AI coding agents

- **Type:** MCP server
- **Install:** `agentstack add mcp-calabamatex-stigmergy-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [calabamatex](https://agentstack.voostack.com/s/calabamatex)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [calabamatex](https://github.com/calabamatex)
- **Source:** https://github.com/calabamatex/Stigmergy-mcp

## Install

```sh
agentstack add mcp-calabamatex-stigmergy-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Stigmergy-mcp

A shared signal layer that lets multiple AI coding agents coordinate without talking to each other. Built as a standalone [MCP](https://modelcontextprotocol.io/) server.

## Why This Exists

Multi-agent AI systems are expensive because every agent reads everything every other agent has said. Anthropic's own production multi-agent Research system [uses approximately 15 times more tokens than chat interactions](https://www.anthropic.com/engineering/multi-agent-research-system), and token usage by itself explains 80% of performance variance on the BrowseComp browsing evaluation. The cost is not the cognitive work each agent performs. The cost is the cumulative conversation history each agent ingests before it can do its slice of the work.

This is a structural problem, not an implementation defect. In direct message-passing coordination, each agent in an N-agent pipeline reads what every predecessor produced. Per-run inter-agent token volume scales quadratically with agent count. Anthropic is explicit about the limit: "domains that require all agents to share the same context or involve many dependencies between agents are not a good fit for multi-agent systems today." Coding is one of those domains.

The effect is measurable. The companion [Stigmergy-mcp-benchmark](https://github.com/calabamatex/Stigmergy-mcp-benchmark) project decomposes every API call into five token categories (content transfer, mechanism overhead, coordination instructions, task reasoning, system identity) and applies bootstrap confidence intervals, Wilcoxon signed-rank tests, and TOST equivalence testing across paired trials. The framework runs against Anthropic, OpenAI, or a mock provider. 

Stigmergy-mcp replaces full conversation handoff with compact, decaying, area-keyed signals. Each agent reads what is relevant near where it is working, not the entire transcript of what came before. Inter-agent token volume scales linearly with agent count instead of quadratically. The cost curve flattens, and dependency-heavy domains like coding become viable for multi-agent coordination.

This is a coordination primitive, not a framework, not an orchestrator, and not an agent runtime. It does one thing: it lets your agents leave traces instead of transcripts.

## What is Stigmergy?

In ant colonies, ants coordinate without communicating directly. An ant leaves a pheromone trail on a path; other ants sense the trail and follow it. Strong trails attract more ants. Trails that aren't reinforced evaporate. The environment itself becomes the communication channel — no messages, no central coordinator.

**stigmergy-mcp** brings this pattern to AI coding agents. Agents leave typed traces on file paths and module names:

- **attraction** — "this path worked well" (draws agents toward an area)
- **danger** — "something is broken here" (warns agents away)
- **info** — neutral annotation (context for future visitors)

Traces decay exponentially over time, so stale signals fade naturally and fresh, reinforced signals dominate. When multiple AI agents work on the same codebase, they can sense each other's traces and adapt — without a message bus, queue, or shared state protocol.

## Quick Start

### Install from npm

```bash
npm install stigmergy-mcp
```

### Or build from source

```bash
git clone https://github.com/calabamatex/stigmergy-mcp.git
cd stigmergy-mcp
npm install && npm run build
```

### Add as an MCP server

```bash
# From npm
claude mcp add stigmergy -- node node_modules/stigmergy-mcp/dist/src/index.js

# From source
claude mcp add stigmergy -- node dist/src/index.js
```

### Verify

```bash
npm run inspect    # Opens MCP Inspector — confirm all 4 tools appear
```

### Database

Traces persist to `./stigmergy.db` by default. Override with:

```bash
STIGMERGY_DB_PATH=/path/to/traces.db    # Custom file path
STIGMERGY_DB_PATH=:memory:              # Ephemeral (no persistence)
```

The database is created automatically on first run.

## Tools

stigmergy-mcp exposes 4 MCP tools. Any MCP-compatible client can call them.

### deposit_trace

Leave a trace in the shared environment.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `area` | string | required | File path or module name (e.g. `"src/auth/session.ts"`) |
| `action` | string | required | What happened (e.g. `"refactored session management"`) |
| `agent_id` | string | required | Which agent is leaving this trace |
| `trace_type` | `"attraction"` \| `"danger"` \| `"info"` | required | Signal type |
| `intensity` | number (0-1) | 0.5 | Signal strength |
| `decay_hours` | number | 24 | Hours until ~37% intensity |
| `tags` | string[] | [] | Searchable labels |
| `metadata` | object | {} | Arbitrary JSON payload |

### sense_environment

Read traces near a given area. Read-only.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `area` | string | required | File path or prefix to scan |
| `radius` | integer | 2 | How many path segments to walk up for matching |
| `min_intensity` | number (0-1) | 0.05 | Minimum effective intensity to include |
| `trace_type` | enum | optional | Filter by type |
| `tags` | string[] | optional | Filter to traces containing ALL of these tags |
| `agent_id` | string | optional | Filter to traces from a specific agent |

**How radius works:** The `radius` parameter controls how broad the search is by walking up the path hierarchy. Given `area="src/auth/session.ts"`:

- `radius=0` → prefix `src/auth/session.ts/` (matches only children, not the file itself)
- `radius=1` → prefix `src/auth/` (sibling files in the same directory)
- `radius=2` → prefix `src/` (broader area)

Returns traces sorted by effective intensity (descending).

### reinforce_trace

Strengthen or weaken an existing trace.

| Parameter | Type | Description |
|-----------|------|-------------|
| `trace_id` | string | ID of trace to reinforce |
| `delta` | number (-1 to 1) | Positive to strengthen, negative to weaken |

### get_gradient

Return the strongest signals across a broad area — the "which direction should I look?" tool. Use this for exploration and orientation. Unlike `sense_environment` (which reads traces near a specific file), `get_gradient` scans a wide prefix and returns the top signals grouped by type.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `area` | string | required | Broad area prefix (e.g. `"src/"`) |
| `limit` | integer | 5 | Max traces to return |

Returns the top N traces by effective intensity. The `by_type` grouping only includes traces within the top N — not all traces in the area.

## Example: Multi-Agent Workflow

```
Agent A (refactoring auth):
  → deposit_trace(area: "src/auth/session.ts", action: "found XSS in session handler",
                  trace_type: "danger", intensity: 0.8, tags: ["security"])

Agent B (working nearby):
  → sense_environment(area: "src/auth/login.ts", radius: 1)
  ← sees danger trace on session.ts — avoids touching it, or fixes the issue
  → reinforce_trace(trace_id: "...", delta: 0.15)  // confirms the danger

Agent C (new to the codebase):
  → get_gradient(area: "src/", limit: 5)
  ← sees strongest signal is a danger on src/auth/session.ts — investigates first
```

## Trace Lifecycle

Traces decay exponentially. The effective intensity at any point:

```
effective = intensity * exp(-elapsed_hours / decay_hours)
```

With `decay_hours=24`, a trace retains ~37% intensity after 24 hours and ~14% after 48 hours. Short-lived warnings (`decay_hours=4`) fade in hours. Long-term memory (`decay_hours=168`) persists for about a week.

Traces below 1% effective intensity are automatically pruned during `deposit()` calls. They are also invisible to `sense_environment` and `get_gradient` below their respective thresholds, so expired traces never pollute query results.

## Programmatic Usage

The package exports the store and server for embedding in your own code:

```typescript
import { TraceStore } from 'stigmergy-mcp/store';
import { createServer, startServer } from 'stigmergy-mcp/server';

// Use the store directly
const store = new TraceStore('/path/to/traces.db');
const trace = store.deposit({ area: 'src/foo.ts', action: 'refactored', agent_id: 'my-agent', trace_type: 'info', intensity: 0.5, decay_hours: 24, tags: [], metadata: {} });

// Or create/start an MCP server with a custom store
const server = createServer(store);
```

See [ARCHITECTURE.md](ARCHITECTURE.md) for internal design details and extension points.

## Benchmarks

The benchmarking harness — comparing stigmergic swarms against single-agent and message-passing baselines — lives in a separate repository: [calabamatex/Stigmergy-mcp-benchmark](https://github.com/calabamatex/Stigmergy-mcp-benchmark).

## Development

```bash
npm run build          # Compile TypeScript
npm run dev            # Compile in watch mode
npm test               # Run all tests
npm run test:coverage  # Run tests with coverage
npm run loc            # Check source/test LOC and file count
npm run inspect        # Launch MCP Inspector
```

## License

MIT

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [calabamatex](https://github.com/calabamatex)
- **Source:** [calabamatex/Stigmergy-mcp](https://github.com/calabamatex/Stigmergy-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-calabamatex-stigmergy-mcp
- Seller: https://agentstack.voostack.com/s/calabamatex
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.