firm-mcp-server

Python MCP server (port 8012) that bridges VS Code Copilot agents to the [Firm](https://github.com/the server) Gateway ecosystem. Companion to setup-vs-agent-firm.

Tools (138)

Quick start

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # fill in tokens
bash scripts/start.sh

Add to VS Code settings.json:

"mcp.servers": {
  "firm-extensions": { "url": "http://127.0.0.1:8012/mcp" }
}

Scripts

bash scripts/start.sh    # start in background
bash scripts/stop.sh     # graceful stop
bash scripts/status.sh   # PID + HTTP + tool count

Tests

pip install -r requirements-dev.txt
python -m pytest tests/test_smoke.py -v

2272 tests (1961 unit + 311 integration), 94.6% coverage, covering:

• Server starts and answers ping
• initialize returns correct capabilities + __version__
• All 115 tools registered with valid inputSchema
• vs_context_push degrades gracefully without Gateway
• firm_export_document writes local file
• Unknown method returns JSON-RPC error -32601
• Unknown tool returns descriptive error
• Timing-safe auth (I21), SQL injection guard (I24), session_id regex (I41)
• ConfigPathInput traversal blocking across all 21 config-path models (I27)
• Health/healthz endpoints return correct tool count + version (I35)
• Shared config_helpers: load_config, get_nested, mask_secret (I25)
• Hebbian memory: harvest PII stripping, weight update dry-run, layer validation, drift detection, Pydantic traversal guards

Security

• Auth: timing-safe hmac.compare_digest on Bearer token — no timing side-channel (I21)
• Request limit: client_max_size=2MB on aiohttp Application (I22)
• Tool timeout: asyncio.wait_for with TOOL_TIMEOUT_S (default 120s) on all async tool calls (I23)
• SQL injection guard: table_name validated by Pydantic regex ^[a-zA-Z_][a-zA-Z0-9_]{0,127}$ + runtime whitelist in handler (I24)
• Session ID regex: ^[a-zA-Z0-9_\-:.]+$ on all session_id fields — no injection (I41)
• Centralized version: __version__ in main.py — single source of truth (I37)
• DRY helpers: config_helpers.py — shared load_config, get_nested, mask_secret (I25)
• ConfigPathInput base: 21 models inherit traversal guard from single base class (I27)
• Hebbian PII stripping: 9 regex patterns (email, phone, IP, API keys, SSN, JWT, AWS keys) applied before any session storage — CDC §5.2
• Hebbian drift detection: TF-IDF cosine similarity vs baseline (no external API) — CDC §5.1
• Hebbian weight caps: auto-update capped at 0.95, atrophy floor at 0.0, dry_run=True default — CDC §4.3
• GitHub PRs always created as drafts with needs-review label
• Tokens masked in logs (last 4 chars only) via mask_secret()
• Context capped at 32 KB per WS payload
• fleet.json and acp_sessions.json written atomically (os.replace)
• Workspace lock via fcntl.LOCK_EX | LOCK_NB (advisory, crash-safe)
• fleet_session_inject_env: allowlist regex — only known provider keys accepted
• fleet_cron_schedule: command allowlist regex + blocklist (rm, dd, mkfs…)
• Path traversal guard (..) on all file-path Pydantic fields
• All AI outputs carry human-review disclaimer

Gap coverage (Firm audit)

⚠️ Contenu généré par IA — validation humaine requise avant utilisation.