Signal MCP

An MCP server that sits between an AI agent and your project's developer tooling — tests, linters, type checkers, builds — and compresses noisy output into compact, actionable diagnostics.

When an AI agent runs a test suite or linter directly, it receives hundreds or thousands of lines of raw output that flood the context window. Signal solves this by running the command, storing the full log on disk, parsing errors with a language-aware adapter, grouping duplicates by normalized fingerprint, and returning only a structured summary. The model sees one line per error group instead of the full log.

huge logs → grouped errors → compact diagnostic → fewer tokens

How it works

Agent → run_check("backend_test")
      → Signal runs the command
      → stores full log on disk
      → parses errors with the configured adapter (auto-detected if not set)
      → groups duplicates by fingerprint
      → returns: N failing tests, M groups + raw_tail if nothing parsed
      → Agent fixes code
      → run_check again
      → diff_runs → "2 fixed, 1 persisting"
      → done

The model never sees the full log unless it explicitly requests a slice with get_log_slice.

Related MCP server: projscan

Setup

npm install
npm run build

Create a signal.config.json in your project root (see signal.config.example.json for reference):

{
  "projects": {
    "my-project": {
      "root": "/path/to/my-project",
      "checks": {
        "test": {
          "cmd": "npx vitest run"
        },
        "lint": {
          "cmd": "pnpm exec biome check src --reporter json 2>&1"
        }
      }
    }
  }
}

The adapter field is optional — Signal auto-detects the right adapter from the command (vitest, pytest, cargo test, eslint, etc.). Set it explicitly only when auto-detection would be wrong.

Register as MCP server

node dist/index.js install --config /path/to/signal.config.json

Or add it manually to your ~/.claude.json:

{
  "mcpServers": {
    "signal": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/signal-mcp/dist/index.js"],
      "env": {
        "SIGNAL_CONFIG": "/path/to/signal.config.json"
      }
    }
  }
}

Signal auto-detects the active project from the working directory — it matches any subdirectory of a configured project root.

Environment variables in config

Use ${VAR} in any string field of signal.config.json to avoid hardcoding machine-specific values like Docker container names or paths:

{
  "projects": {
    "my-project": {
      "root": "/path/to/my-project",
      "checks": {
        "test": {
          "cmd": "docker exec ${APP_CONTAINER} pytest"
        }
      }
    }
  }
}

Define the variables in the MCP server registration so each developer sets their own values without touching the shared config:

{
  "mcpServers": {
    "signal": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/signal-mcp/dist/index.js"],
      "env": {
        "SIGNAL_CONFIG": "/path/to/signal.config.json",
        "APP_CONTAINER": "my-app-container-1"
      }
    }
  }
}

If a variable is not set, the literal ${VAR} is kept unchanged. Variables without braces ($VAR) are not interpolated.

MCP tools

Typical agent workflow

1. list_checks                               → discover available checks
2. run_check { name: "test" }                → summary returned directly
3. (fix the errors)
4. run_check { name: "test" }                → run again after the fix
5. diff_runs { check: "test" }               → verify what changed
6. get_log_slice { run_id, stream }          → zoom into raw log if needed

Run frontend and backend checks simultaneously:

run_checks { names: ["frontend_test", "backend_test"] }   → both run in parallel, one summary per check

For long-running checks (E2E, integration):

1. start_check { name: "e2e" }          → run_id returned immediately
2. get_run_status { run_id }            → poll until status != "running"
3. get_run_summary { run_id }           → read the compact diagnostic

Summary options

get_run_summary and run_check accept these optional parameters:

run_check also accepts:

raw_tail fallback

When a check fails but the adapter parses zero errors (unrecognized output format), the summary automatically includes a raw_tail field with the last 30 lines of output — so the agent always has something actionable without needing get_log_slice.

Multi-step pipelines

For checks where order matters (clean → prepare → test):

{
  "checks": {
    "full": {
      "steps": [
        { "name": "clean",   "cmd": "rm -rf var/cache/*",  "timeout_ms": 30000 },
        { "name": "prepare", "cmd": "bin/prepare-test-db", "timeout_ms": 120000 },
        { "name": "test",    "cmd": "vendor/bin/behat",    "timeout_ms": 300000 }
      ],
      "fail_fast": true
    }
  }
}

Each step gets its own adapter (auto-detected from cmd). get_run_summary returns which step failed and grouped errors from that step.

Adapters

Signal auto-detects the adapter from the command — no need to set adapter explicitly for common tools.

Adding an adapter is ~30–50 lines + tests. The interface is:

parse({ stdout, stderr, projectRoot }): ParsedError[]

Fingerprint algorithm

Errors are grouped by a 12-character SHA1 fingerprint:

• If a symbol was extracted (test name, function name): type:sym:<symbol>

• Otherwise: type:msg:<normalized_message> — quoted strings → <str>, paths → <path>, numbers → N

Errors that differ only in line numbers, paths, or quoted values collapse into one group. diff_runs compares fingerprints between runs to identify fixed vs. new vs. persisting errors.

Storage layout

.signal/runs/<check>_<timestamp>_<random>/
├── stdout.log
├── stderr.log
├── meta.json
└── steps/                    # only for multi-step runs
    ├── 1-clean/
    ├── 2-prepare/
    └── 3-test/

run_id is validated against ^[a-zA-Z0-9_-]+$ — path traversal is rejected before any disk I/O.

Runs are cleaned up automatically after each execution: the last 20 runs per check are kept, older ones are deleted.

Configuration reference

Per-check fields (single command)

Per-check fields (multi-step)

Development

npm test          # run all tests (vitest)
npm run typecheck # tsc --noEmit
npm run build     # compile to dist/

Tests are colocated under tests/. Each adapter has its own .test.ts file.

License

MIT