Stigmergy-mcp: Instructions file for Claude Code

CLAUDE.md — Stigmergy MCP Server

Project Identity

Stigmergy-MCP: a standalone MCP server implementing digital pheromone-based indirect coordination for AI coding agents. Inspired by ant colony stigmergy — agents leave typed traces in a shared environment; other agents sense and respond to those traces without direct messaging.

This is a NOVEL COORDINATION PRIMITIVE, not another framework. Ship tight or don't ship.

Hard Constraints (Non-Negotiable)

• Total source files in src/: MAX 12
• Total source LOC (src/**/*.ts): MAX 1500
• Total test LOC (tests/**/*.ts): MAX 800
• Runtime dependencies: ONLY @modelcontextprotocol/sdk, better-sqlite3, zod
• NO additional npm packages without explicit human approval
• NO files outside the defined structure without explicit human approval
• After every code change, run: npm run build && npm test

Forbidden Actions

• NEVER create documentation files beyond README.md and ARCHITECTURE.md
• NEVER create a dashboard, CLI, plugin system, or configuration file loader
• NEVER add a logging library — use console.error() to stderr per MCP convention
• NEVER create "utils", "helpers", or "common" directories
• NEVER create index.ts barrel files except the root src/index.ts entry point
• NEVER add uuid — use crypto.randomUUID()
• NEVER create template files, example configs, or scaffolding scripts
• NEVER auto-commit or auto-checkpoint
• NEVER create files "for future use" or "to be implemented later"
• NEVER add badges, banners, or CI workflow files in initial build

Architecture

src/
  index.ts              # Entry point: init store, start server (~15 lines)
  server.ts             # McpServer setup, register 4 tools, stdio transport (~50 lines)
  store/
    schema.ts           # Zod schemas + TypeScript types for Trace, SenseQuery, etc.
    trace-store.ts      # SQLite persistence, TTL decay math, CRUD operations
  tools/
    deposit.ts          # deposit_trace — agent leaves a trace in the environment
    sense.ts            # sense_environment — agent reads nearby traces
    reinforce.ts        # reinforce_trace — agent strengthens an existing trace
    gradient.ts         # get_gradient — returns strongest signals in an area