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)

Module	Tool	Description	Gaps
vs_bridge	vs_context_push	Push VS Code context → Firm session	—
vs_bridge	vs_context_pull	Pull Firm session state → VS Code	—
vs_bridge	vs_session_link	Associate workspace path ↔ session ID	—
vs_bridge	vs_session_status	Bridge health check	—
gateway_fleet	firm_gateway_fleet_status	Parallel health-check all instances	—
gateway_fleet	firm_gateway_fleet_add	Register a Gateway instance	—
gateway_fleet	firm_gateway_fleet_remove	Remove a Gateway instance	—
gateway_fleet	firm_gateway_fleet_broadcast	Broadcast to all instances	—
gateway_fleet	firm_gateway_fleet_sync	Sync config+skills to all instances	—
gateway_fleet	firm_gateway_fleet_list	List instances	—
delivery_export	firm_export_github_pr	Create draft PR on GitHub	—
delivery_export	firm_export_jira_ticket	Create Jira ticket (ADF)	—
delivery_export	firm_export_linear_issue	Create Linear issue (GraphQL)	—
delivery_export	firm_export_slack_digest	Post Slack digest (Block Kit)	—
delivery_export	firm_export_document	Write local Markdown deliverable	—
delivery_export	firm_export_auto	Auto-route by delivery_format	—
security_audit	firm_security_scan	Scan files for SQL injection + XSS patterns	C1
security_audit	firm_sandbox_audit	Detect sandbox.mode: off → CRITICAL	C2
security_audit	firm_session_config_check	Detect ephemeral SESSION_SECRET in .env/compose	C3
security_audit	firm_rate_limit_check	Detect Funnel without rate limiter → CRITICAL	H8
acp_bridge	acp_session_persist	Persist ACP session to ~/.firm/acp_sessions.json	C4
acp_bridge	acp_session_restore	Restore persisted ACP session by run_id	C4
acp_bridge	acp_session_list_active	List ACP sessions active in last N hours	C4
acp_bridge	fleet_session_inject_env	Inject env vars to spawned sessions (allowlist)	H3
acp_bridge	fleet_cron_schedule	Schedule cron with sandbox enforcement	H4
acp_bridge	firm_workspace_lock	Advisory file lock with owner tracking (fcntl)	H5
acp_bridge	firm_acpx_version_check	ACPX plugin version pin (≥0.1.15) + streaming mode check	3.1
reliability_probe	firm_gateway_probe	WS probe with backoff — detects close 1006, returns launchctl	H6/H7
reliability_probe	firm_doc_sync_check	Detect version drift in docs vs package.json	M5
reliability_probe	firm_channel_audit	Detect zombie channel SDK deps (LINE, Baileys…)	M1
reliability_probe	firm_adr_generate	Generate MADR + commit path for architecture decisions	M6
gateway_hardening	firm_gateway_auth_check	Verify Gateway auth config — CRITICAL if Funnel without password	H2
gateway_hardening	firm_credentials_check	Check Baileys/channel credential integrity and freshness	M3
gateway_hardening	firm_webhook_sig_check	Verify HMAC signing secrets for all inbound webhook channels	M4
gateway_hardening	firm_log_config_check	Detect debug/trace logging and missing redactPatterns	M7
gateway_hardening	firm_workspace_integrity_check	Validate ~/.firm/workspace (AGENTS.md, SOUL.md, staleness)	M8
runtime_audit	firm_node_version_check	Verify Node.js ≥ 22.12.0 (CVE-2025-59466, CVE-2026-21636)	C5
runtime_audit	firm_secrets_workflow_check	Detect hardcoded secrets in config.json (migrate to firm secrets)	C6
runtime_audit	firm_http_headers_check	Verify HTTP security headers (HSTS, X-Content-Type-Options, Referrer-Policy)	H9
runtime_audit	firm_nodes_commands_check	Detect dangerous gateway.nodes.allowCommands override	H10
runtime_audit	firm_trusted_proxy_check	Verify trusted-proxy config coherence (bind + trustedProxies + auth mode)	H11
runtime_audit	firm_session_disk_budget_check	Verify session.maintenance.maxDiskBytes / highWaterBytes configured	M15
runtime_audit	firm_dm_allowlist_check	Detect dmPolicy=allowlist with empty allowFrom (fail-closed) across 9 channels	M16
advanced_security	firm_secrets_lifecycle_check	Verify External Secrets lifecycle (audit/configure/apply/reload)	C7
advanced_security	firm_channel_auth_canon_check	Verify channel auth path canonicalization (encoded traversal)	C8
advanced_security	firm_exec_approval_freeze_check	Verify exec approval plan immutability (symlink cwd rebind)	C9
advanced_security	firm_hook_session_routing_check	Verify hook session-key routing hardening	H12
advanced_security	firm_config_include_check	Verify $include hardlink escape + file-size guardrails	H13
advanced_security	firm_config_prototype_check	Detect prototype pollution (proto, constructor, prototype) in config	H14
advanced_security	firm_safe_bins_profile_check	Verify safeBins entries have explicit profiles	H15
advanced_security	firm_group_policy_default_check	Verify group policy default is fail-closed (allowlist)	H16
config_migration	firm_shell_env_check	Verify shell env sanitization (LD_PRELOAD, DYLD_*, ZDOTDIR)	H17
config_migration	firm_plugin_integrity_check	Verify plugin install integrity/pin + drift detection	H18
config_migration	firm_token_separation_check	Verify hooks.token ≠ gateway.auth.token	H19
config_migration	firm_otel_redaction_check	Verify OTEL secret redaction in diagnostics export	M17
config_migration	firm_rpc_rate_limit_check	Verify control-plane RPC rate limiting config	M21
observability	firm_observability_pipeline	Ingest JSONL traces into SQLite for offline analysis	T1
observability	firm_ci_pipeline_check	Validate CI workflow completeness (lint, test, secrets)	T6
memory_audit	firm_pgvector_memory_check	Verify pgvector config (HNSW index, dimensions, distance metrics)	T3
memory_audit	firm_knowledge_graph_check	Audit knowledge graph integrity (orphan nodes, cycles, TTL)	T9
agent_orchestration	firm_agent_team_orchestrate	Task DAG execution with topological sort + parallel layers	T4
agent_orchestration	firm_agent_team_status	Check orchestration status by ID or list all	T4
i18n_audit	firm_i18n_audit	Scan locale files for missing keys, empty values, interpolation mismatches	T5
skill_loader	firm_skill_lazy_loader	Lazy-load SKILL.md metadata (YAML front-matter, 5min cache)	T7
skill_loader	firm_skill_search	Keyword/tag search across cached skills with relevance scoring	T7
n8n_bridge	firm_n8n_workflow_export	Export agent pipeline as n8n-compatible workflow JSON	T8
n8n_bridge	firm_n8n_workflow_import	Validate & import n8n workflow JSON into workspace	T8
browser_audit	firm_browser_context_check	Validate Playwright/Puppeteer headless config for agents	T10
hebbian_memory	firm_hebbian_harvest	Ingest JSONL session logs → SQLite (PII stripped) — CDC §4.1	—
hebbian_memory	firm_hebbian_weight_update	Compute/apply Hebbian weight updates on Layer 2 — CDC §4.3	—
hebbian_memory	firm_hebbian_analyze	Co-activation pattern analysis (Jaccard similarity) — CDC §4.3	—
hebbian_memory	firm_hebbian_status	Dashboard: weights, atrophy, promotions — CDC §7	—
hebbian_memory	firm_hebbian_layer_validate	Validate 4-layer Claude.md structure — CDC §3.3	—
hebbian_memory	firm_hebbian_pii_check	Audit PII stripping config — CDC §5.2	—
hebbian_memory	firm_hebbian_decay_config_check	Validate learning rate, decay, thresholds — CDC §4.3	—
hebbian_memory	firm_hebbian_drift_check	Cosine similarity drift detection vs baseline — CDC §5.1	—
a2a_bridge	firm_a2a_card_generate	Generate agent-card.json from SOUL.md (RC v1.0)	G1
a2a_bridge	firm_a2a_card_validate	Validate A2A Agent Card against RC v1.0 spec	G2
a2a_bridge	firm_a2a_task_send	Send message/task to an A2A agent (SendMessage)	G3
a2a_bridge	firm_a2a_task_status	Get task status or list tasks (RC v1.0)	G4
a2a_bridge	firm_a2a_cancel_task	Cancel a running A2A task (CancelTask)	G5
a2a_bridge	firm_a2a_subscribe_task	Subscribe to task updates via SSE	G6
a2a_bridge	firm_a2a_push_config	CRUD for push notification webhooks (RC v1.0)	G7
a2a_bridge	firm_a2a_discovery	Discover agents via Agent Cards or SOUL.md scan	G8
platform_audit	firm_secrets_v2_audit	Audit Firm secrets v2 lifecycle (2026.2+)	G9
platform_audit	firm_agent_routing_check	Validate agent routing bindings	G10
platform_audit	firm_voice_security_check	TTS/voice channel security audit	G11
platform_audit	firm_trust_model_check	Validate trust model and multi-user heuristics	G12
platform_audit	firm_autoupdate_check	Self-update supply chain integrity check	G13
platform_audit	firm_plugin_sdk_check	Plugin SDK integrity validation	G14
platform_audit	firm_content_boundary_check	Content boundary & anti-prompt-injection audit	G15
platform_audit	firm_sqlite_vec_check	SQLite-vec memory backend validation	G16
platform_audit	firm_adaptive_thinking_check	Claude 4.6 adaptive thinking configuration check	3.1
ecosystem_audit	firm_mcp_firewall_check	MCP Gateway firewall policy audit	G17
ecosystem_audit	firm_rag_pipeline_check	RAG pipeline health & config audit	G18
ecosystem_audit	firm_sandbox_exec_check	Sandbox execution isolation audit	G19
ecosystem_audit	firm_context_health_check	Context rot / cognitive health detection	G20
ecosystem_audit	firm_provenance_tracker	Cryptographic audit trail / provenance tracking	G21
ecosystem_audit	firm_cost_analytics	Usage/cost tracking and analysis	G22
ecosystem_audit	firm_token_budget_optimizer	Token optimization analysis	G23
spec_compliance	firm_elicitation_audit	Audit MCP elicitation capability compliance	S4
spec_compliance	firm_tasks_audit	Audit MCP Tasks capability compliance	S5
spec_compliance	firm_resources_prompts_audit	Audit MCP Resources & Prompts compliance	S6
spec_compliance	firm_audio_content_audit	Audit MCP audio content support	H3
spec_compliance	firm_json_schema_dialect_check	Audit JSON Schema dialect compliance	H5
spec_compliance	firm_sse_transport_audit	Audit Streamable HTTP / SSE transport	H6
spec_compliance	firm_icon_metadata_audit	Audit icon metadata support	H7
prompt_security	firm_prompt_injection_check	Scan text for 16 injection/jailbreak patterns	H2
prompt_security	firm_prompt_injection_batch	Batch scan multiple texts for injection patterns	H2
auth_compliance	firm_oauth_oidc_audit	Audit OAuth 2.1 / OIDC Discovery compliance	H4
auth_compliance	firm_token_scope_check	Check OAuth scopes restrict tool access properly	H4
compliance_medium	firm_tool_deprecation_audit	Audit tool deprecation lifecycle	M1
compliance_medium	firm_circuit_breaker_audit	Audit circuit breaker / resilience config	M2
compliance_medium	firm_gdpr_residency_audit	Audit GDPR compliance and data residency	M3
compliance_medium	firm_agent_identity_audit	Audit agent DID (decentralized identity)	M4
compliance_medium	firm_model_routing_audit	Audit multi-model routing and fallback chain	M5
compliance_medium	firm_resource_links_audit	Audit MCP resource links in tool results	M6
market_research	firm_market_competitive_analysis	Full competitive landscape analysis (feature matrix, SWOT, positioning)	—
market_research	firm_market_sizing	TAM/SAM/SOM market sizing (top-down + bottom-up)	—
market_research	firm_market_financial_benchmark	Financial benchmarking — unit economics, pricing, revenue	—
market_research	firm_market_web_research	Structured web research & OSINT intelligence gathering	—
market_research	firm_market_report_generate	Professional Markdown market research report generator	—
market_research	firm_market_research_monitor	Continuous competitive monitoring (add/remove/update/status)	—
legal_status	firm_legal_status_compare	Compare legal forms (SAS, SARL, EURL…) on multi-criteria grid	—
legal_status	firm_legal_tax_simulate	Simulate IS/IR tax burden per legal form	—
legal_status	firm_legal_social_protection	Analyze social protection by dirigeant status	—
legal_status	firm_legal_governance_audit	Audit governance clauses & shareholder pacts	—
legal_status	firm_legal_creation_checklist	Step-by-step company creation checklist	—
location_strategy	firm_location_geo_analysis	Geo-economic attractiveness analysis by zone	—
location_strategy	firm_location_real_estate	Real estate market scan (buy/rent/coworking)	—
location_strategy	firm_location_site_score	Multi-criteria site scoring (20 criteria)	—
location_strategy	firm_location_incentives	Map tax incentives & public aids by zone	—
location_strategy	firm_location_tco_simulate	Total cost of occupancy simulation over N years	—
supplier_management	firm_supplier_search	Search & filter suppliers by category/region/certification	—
supplier_management	firm_supplier_evaluate	Multi-criteria supplier evaluation (15 criteria)	—
supplier_management	firm_supplier_tco_analyze	Supplier TCO analysis (direct + indirect + hidden costs)	—
supplier_management	firm_supplier_contract_check	Contract clause compliance audit (14 mandatory clauses)	—
supplier_management	firm_supplier_risk_monitor	Supplier risk monitoring (add/remove/update/status)	—

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)

ID	Severity	Description	Coverage
C1	CRITICAL	SQL injection in API endpoints	firm_security_scan
C2	CRITICAL	Sandbox disabled (mode: off)	firm_sandbox_audit
C3	CRITICAL	SESSION_SECRET ephemeral / in config	firm_session_config_check
C4	CRITICAL	ACP sessions lost on restart (in-memory)	acp_session_persist/restore
H1	HIGH	@buape/carbon frozen at 0.0.0-beta	firm_adr_generate + CTO SOUL.md
H2	HIGH	Gateway Funnel without auth.mode=password	firm_gateway_auth_check
H3	HIGH	Spawned sessions get no env vars	fleet_session_inject_env
H4	HIGH	Cron not blocked in sandbox	fleet_cron_schedule
H5	HIGH	Race condition on workspace lock	firm_workspace_lock
H6	HIGH	Gateway silently drops on macOS sleep	firm_gateway_probe
H7	HIGH	WS close code 1006 not handled	firm_gateway_probe
H8	HIGH	No rate limiting on Tailscale Funnel	firm_rate_limit_check
M1	MEDIUM	@line/bot-sdk zombie dependency	firm_channel_audit
M2	MEDIUM	Test coverage threshold 70%	factory 80% threshold + CTO SOUL.md
M3	MEDIUM	Baileys creds.json no integrity/age check	firm_credentials_check
M4	MEDIUM	Webhook HMAC signature verification missing	firm_webhook_sig_check
M5	MEDIUM	Docs version stale vs package.json	firm_doc_sync_check
M6	MEDIUM	No ADRs for architecture decisions	firm_adr_generate
M7	MEDIUM	Logging verbose / no redactPatterns	firm_log_config_check
M8	MEDIUM	~/.firm/workspace integrity unchecked	firm_workspace_integrity_check
C5	CRITICAL	Node.js < 22.12.0 (CVE-2025-59466, CVE-2026-21636)	firm_node_version_check
C6	CRITICAL	Hardcoded secrets in config.json (no secrets workflow)	firm_secrets_workflow_check
H9	HIGH	HTTP security headers absent (HSTS, X-Content-Type-Options)	firm_http_headers_check
H10	HIGH	gateway.nodes.allowCommands dangerous override	firm_nodes_commands_check
H11	HIGH	Trusted-proxy misconfigured (bind+proxies+auth mode)	firm_trusted_proxy_check
M15	MEDIUM	Session disk budget not configured (maxDiskBytes)	firm_session_disk_budget_check
M16	MEDIUM	dmPolicy=allowlist with empty allowFrom (fail-open)	firm_dm_allowlist_check
C7	CRITICAL	External Secrets lifecycle not validated (inline creds)	firm_secrets_lifecycle_check
C8	CRITICAL	Plugin channel HTTP auth bypass (path canonicalization)	firm_channel_auth_canon_check
C9	CRITICAL	Exec approval plan mutability (symlink cwd rebind)	firm_exec_approval_freeze_check
H12	HIGH	Hook session-key routing unrestricted	firm_hook_session_routing_check
H13	HIGH	Config $include hardlink escape + file-size	firm_config_include_check
H14	HIGH	Prototype pollution in config merge	firm_config_prototype_check
H15	HIGH	SafeBins without explicit profile = unrestricted interpreter	firm_safe_bins_profile_check
H16	HIGH	Group policy default not fail-closed	firm_group_policy_default_check
H17	HIGH	Shell env not sanitized (LD_PRELOAD, DYLD_*)	firm_shell_env_check
H18	HIGH	Plugin install integrity/pin not tracked	firm_plugin_integrity_check
H19	HIGH	hooks.token = gateway.auth.token (reuse)	firm_token_separation_check
M17	MEDIUM	OTEL secret redaction missing in diagnostics	firm_otel_redaction_check
M21	MEDIUM	Control-plane RPC rate limiting absent	firm_rpc_rate_limit_check
T1	TOOL	No observability pipeline for JSONL traces	firm_observability_pipeline
T3	TOOL	pgvector memory config unchecked	firm_pgvector_memory_check
T4	TOOL	No parallel agent orchestration (task DAG)	firm_agent_team_orchestrate
T5	TOOL	No i18n/localization audit	firm_i18n_audit
T6	TOOL	No CI pipeline completeness check	firm_ci_pipeline_check
T7	TOOL	Skills loaded eagerly (no lazy loading)	firm_skill_lazy_loader + firm_skill_search
T8	TOOL	No n8n workflow automation bridge	firm_n8n_workflow_export + firm_n8n_workflow_import
T9	TOOL	Knowledge graph integrity unchecked	firm_knowledge_graph_check
T10	TOOL	Browser automation config unchecked	firm_browser_context_check

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