MCP OpenClaw Extensions

firm-mcp-server

Python MCP 服务（端口 8012），用于连接 VS Code Copilot Agent 与 [Firm](https://github.com/the server) Gateway 生态系统。 与 setup-vs-agent-firm 配套使用。

工具（138）

模块	工具	描述	差距
vs_bridge	vs_context_push	推送 VS Code 上下文 → Firm 会话	—
vs_bridge	vs_context_pull	拉取 Firm 会话状态 → VS Code	—
vs_bridge	vs_session_link	关联工作区路径 ↔ 会话 ID	—
vs_bridge	vs_session_status	桥接健康检查	—
gateway_fleet	firm_gateway_fleet_status	并行检查所有实例的运行状况	—
gateway_fleet	firm_gateway_fleet_add	注册 Gateway 实例	—
gateway_fleet	firm_gateway_fleet_remove	移除 Gateway 实例	—
gateway_fleet	firm_gateway_fleet_broadcast	向所有实例广播	—
gateway_fleet	firm_gateway_fleet_sync	将配置和技能同步到所有实例	—
gateway_fleet	firm_gateway_fleet_list	列出实例	—
delivery_export	firm_export_github_pr	在 GitHub 上创建草稿 PR	—
delivery_export	firm_export_jira_ticket	创建 Jira 工单（ADF）	—
delivery_export	firm_export_linear_issue	创建 Linear 问题（GraphQL）	—
delivery_export	firm_export_slack_digest	发布 Slack 摘要（Block Kit）	—
delivery_export	firm_export_document	写入本地 Markdown 交付文档	—
delivery_export	firm_export_auto	根据 delivery_format 自动路由	—
security_audit	firm_security_scan	扫描文件中的 SQL 注入和 XSS 模式	C1
security_audit	firm_sandbox_audit	检测 sandbox.mode: off → 严重	C2
security_audit	firm_session_config_check	检测 .env/compose 中的临时 SESSION_SECRET	C3
security_audit	firm_rate_limit_check	检测未配置速率限制器的 Funnel → 严重	H8
acp_bridge	acp_session_persist	将 ACP 会话持久化到 ~/.firm/acp_sessions.json	C4
acp_bridge	acp_session_restore	按 run_id 恢复已持久化的 ACP 会话	C4
acp_bridge	acp_session_list_active	列出过去 N 小时内活跃的 ACP 会话	C4
acp_bridge	fleet_session_inject_env	为启动的会话注入环境变量（允许列表）	H3
acp_bridge	fleet_cron_schedule	在沙箱强制执行下安排 cron	H4
acp_bridge	firm_workspace_lock	带所有者跟踪的建议性文件锁（fcntl）	H5
acp_bridge	firm_acpx_version_check	ACPX 插件版本固定（≥0.1.15）并检查流式模式	3.1
reliability_probe	firm_gateway_probe	带退避机制的 WS 探测——检测关闭代码 1006，并返回 launchctl	H6/H7
reliability_probe	firm_doc_sync_check	检测文档与 package.json 中的版本偏差	M5
reliability_probe	firm_channel_audit	检测僵尸频道 SDK 依赖（LINE、Baileys 等）	M1
reliability_probe	firm_adr_generate	为架构决策生成 MADR 和提交路径	M6
gateway_hardening	firm_gateway_auth_check	验证 Gateway 身份验证配置——Funnel 未设置密码时标记为严重	H2
gateway_hardening	firm_credentials_check	检查 Baileys/频道凭据的完整性和时效性	M3
gateway_hardening	firm_webhook_sig_check	验证所有入站 webhook 频道的 HMAC 签名密钥	M4
gateway_hardening	firm_log_config_check	检测调试/跟踪日志记录及缺失的 redactPatterns	M7
gateway_hardening	firm_workspace_integrity_check	验证 ~/.firm/workspace（AGENTS.md、SOUL.md、新旧程度）	M8
runtime_audit	firm_node_version_check	验证 Node.js ≥ 22.12.0（CVE-2025-59466、CVE-2026-21636）	C5
runtime_audit	firm_secrets_workflow_check	检测 config.json 中硬编码的密钥（迁移到 firm secrets）	C6
runtime_audit	firm_http_headers_check	验证 HTTP 安全标头（HSTS、X-Content-Type-Options、Referrer-Policy）	H9
runtime_audit	firm_nodes_commands_check	检测危险的 gateway.nodes.allowCommands 覆盖项	H10
runtime_audit	firm_trusted_proxy_check	验证可信代理配置的一致性（bind + trustedProxies + 身份验证模式）	H11
runtime_audit	firm_session_disk_budget_check	验证是否配置了 session.maintenance.maxDiskBytes / highWaterBytes	M15
runtime_audit	firm_dm_allowlist_check	检测 9 个频道中 dmPolicy=allowlist 且 allowFrom 为空的情况（默认拒绝）	M16
advanced_security	firm_secrets_lifecycle_check	验证外部密钥生命周期（审计/配置/应用/重新加载）	C7
advanced_security	firm_channel_auth_canon_check	验证频道身份验证路径规范化（编码路径遍历）	C8
advanced_security	firm_exec_approval_freeze_check	验证 exec 审批计划不可变性（符号链接 cwd 重新绑定）	C9
advanced_security	firm_hook_session_routing_check	验证 hook 会话密钥路由加固	H12
advanced_security	firm_config_include_check	验证 $include 硬链接逃逸防护和文件大小限制	H13
advanced_security	firm_config_prototype_check	检测配置中的原型污染（proto、constructor、prototype）	H14
advanced_security	firm_safe_bins_profile_check	验证 safeBins 条目是否具有明确的配置文件	H15
advanced_security	firm_group_policy_default_check	验证组策略默认为拒绝访问（允许列表）	H16
config_migration	firm_shell_env_check	验证 shell 环境变量清理（LD_PRELOAD、DYLD_*、ZDOTDIR）	H17
config_migration	firm_plugin_integrity_check	验证插件安装完整性/版本固定并检测偏差	H18
config_migration	firm_token_separation_check	验证 hooks.token ≠ gateway.auth.token	H19
config_migration	firm_otel_redaction_check	验证诊断导出中的 OTEL 密钥脱敏	M17
config_migration	firm_rpc_rate_limit_check	验证控制平面 RPC 速率限制配置	M21
observability	firm_observability_pipeline	将 JSONL 跟踪数据导入 SQLite，以供离线分析	T1
observability	firm_ci_pipeline_check	验证 CI 工作流是否完整（lint、test、密钥）	T6
memory_audit	firm_pgvector_memory_check	验证 pgvector 配置（HNSW 索引、维度、距离指标）	T3
memory_audit	firm_knowledge_graph_check	审计知识图谱完整性（孤立节点、环、TTL）	T9
agent_orchestration	firm_agent_team_orchestrate	通过拓扑排序和并行层执行任务 DAG	T4
agent_orchestration	firm_agent_team_status	按 ID 检查编排状态，或列出全部状态	T4
i18n_audit	firm_i18n_audit	扫描区域设置文件，检查缺失键、空值和插值不匹配	T5
skill_loader	firm_skill_lazy_loader	延迟加载 SKILL.md 元数据（YAML 前置内容，缓存 5 分钟）	T7
skill_loader	firm_skill_search	跨缓存技能进行关键词/标签搜索，并计算相关性评分	T7
n8n_bridge	firm_n8n_workflow_export	将 Agent 工作流导出为兼容 n8n 的工作流 JSON	T8
n8n_bridge	firm_n8n_workflow_import	验证 n8n 工作流 JSON 并将其导入工作区	T8
browser_audit	firm_browser_context_check	验证 Agent 的 Playwright/Puppeteer 无头配置	T10
hebbian_memory	firm_hebbian_harvest	将 JSONL 会话日志导入 SQLite（移除 PII）——CDC §4.1	—
hebbian_memory	firm_hebbian_weight_update	在第 2 层计算/应用 Hebbian 权重更新——CDC §4.3	—
hebbian_memory	firm_hebbian_analyze	共激活模式分析（Jaccard 相似度）——CDC §4.3	—
hebbian_memory	firm_hebbian_status	仪表板：权重、萎缩、晋升——CDC §7	—
hebbian_memory	firm_hebbian_layer_validate	验证 4 层 Claude.md 结构——CDC §3.3	—
hebbian_memory	firm_hebbian_pii_check	审计 PII 移除配置——CDC §5.2	—
hebbian_memory	firm_hebbian_decay_config_check	验证学习率、衰减和阈值——CDC §4.3	—
hebbian_memory	firm_hebbian_drift_check	检测相对于基线的余弦相似度偏移——CDC §5.1	—
a2a_bridge	firm_a2a_card_generate	根据 SOUL.md 生成 agent-card.json（RC v1.0）	G1
a2a_bridge	firm_a2a_card_validate	根据 RC v1.0 规范验证 A2A Agent Card	G2
a2a_bridge	firm_a2a_task_send	向 A2A Agent 发送消息/任务（SendMessage）	G3
a2a_bridge	firm_a2a_task_status	获取任务状态或列出任务（RC v1.0）	G4
a2a_bridge	firm_a2a_cancel_task	取消正在运行的 A2A 任务（CancelTask）	G5
a2a_bridge	firm_a2a_subscribe_task	通过 SSE 订阅任务更新	G6
a2a_bridge	firm_a2a_push_config	推送通知 webhook 的 CRUD 操作（RC v1.0）	G7
a2a_bridge	firm_a2a_discovery	通过 Agent Cards 或扫描 SOUL.md 发现 Agent	G8
platform_audit	firm_secrets_v2_audit	审计 Firm 密钥 v2 生命周期（2026.2+）	G9
platform_audit	firm_agent_routing_check	验证 Agent 路由绑定	G10
platform_audit	firm_voice_security_check	TTS/语音频道安全审计	G11
platform_audit	firm_trust_model_check	验证信任模型和多用户启发式规则	G12
platform_audit	firm_autoupdate_check	自更新供应链完整性检查	G13
platform_audit	firm_plugin_sdk_check	插件 SDK 完整性验证	G14
platform_audit	firm_content_boundary_check	内容边界和提示词注入防护审计	G15
platform_audit	firm_sqlite_vec_check	SQLite-vec 内存后端验证	G16
platform_audit	firm_adaptive_thinking_check	Claude 4.6 自适应思考配置检查	3.1
ecosystem_audit	firm_mcp_firewall_check	MCP Gateway 防火墙策略审计	G17
ecosystem_audit	firm_rag_pipeline_check	RAG 流水线健康状况和配置审计	G18
ecosystem_audit	firm_sandbox_exec_check	沙箱执行隔离审计	G19
ecosystem_audit	firm_context_health_check	检测上下文腐化/认知健康问题	G20
ecosystem_audit	firm_provenance_tracker	加密审计追踪/溯源跟踪	G21
ecosystem_audit	firm_cost_analytics	用量/成本跟踪与分析	G22
ecosystem_audit	firm_token_budget_optimizer	Token 优化分析	G23
spec_compliance	firm_elicitation_audit	审计 MCP 引出能力合规性	S4
spec_compliance	firm_tasks_audit	审计 MCP Tasks 能力合规性	S5
spec_compliance	firm_resources_prompts_audit	审计 MCP Resources 和 Prompts 合规性	S6
spec_compliance	firm_audio_content_audit	审计 MCP 音频内容支持	H3
spec_compliance	firm_json_schema_dialect_check	审计 JSON Schema 方言合规性	H5
spec_compliance	firm_sse_transport_audit	审计 Streamable HTTP / SSE 传输	H6
spec_compliance	firm_icon_metadata_audit	审计图标元数据支持	H7
prompt_security	firm_prompt_injection_check	扫描文本中的 16 种注入/越狱模式	H2
prompt_security	firm_prompt_injection_batch	批量扫描多段文本中的注入模式	H2
auth_compliance	firm_oauth_oidc_audit	审计 OAuth 2.1 / OIDC Discovery 合规性	H4
auth_compliance	firm_token_scope_check	检查 OAuth 作用域是否正确限制工具访问	H4
compliance_medium	firm_tool_deprecation_audit	审计工具弃用生命周期	M1
compliance_medium	firm_circuit_breaker_audit	审计熔断器/弹性配置	M2
compliance_medium	firm_gdpr_residency_audit	审计 GDPR 合规性和数据驻留	M3
compliance_medium	firm_agent_identity_audit	审计 Agent DID（去中心化身份）	M4
compliance_medium	firm_model_routing_audit	审计多模型路由和回退链	M5
compliance_medium	firm_resource_links_audit	审计工具结果中的 MCP 资源链接	M6
market_research	firm_market_competitive_analysis	全面的竞争格局分析（功能矩阵、SWOT、定位）	—
market_research	firm_market_sizing	TAM/SAM/SOM 市场规模测算（自上而下 + 自下而上）	—
market_research	firm_market_financial_benchmark	财务基准分析——单位经济效益、定价、收入	—
market_research	firm_market_web_research	结构化网络研究和 OSINT 情报收集	—
market_research	firm_market_report_generate	专业 Markdown 市场研究报告生成器	—
market_research	firm_market_research_monitor	持续竞争监控（添加/移除/更新/状态）	—
legal_status	firm_legal_status_compare	按多标准评分表比较法律形式（SAS、SARL、EURL 等）	—
legal_status	firm_legal_tax_simulate	按法律形式模拟 IS/IR 税负	—
legal_status	firm_legal_social_protection	按 dirigeants 身份分析社会保障	—
legal_status	firm_legal_governance_audit	审计治理条款和股东协议	—
legal_status	firm_legal_creation_checklist	逐步创建公司的检查清单	—
location_strategy	firm_location_geo_analysis	按区域分析地理经济吸引力	—
location_strategy	firm_location_real_estate	房地产市场扫描（购买/租赁/共享办公）	—
location_strategy	firm_location_site_score	多标准选址评分（20 项标准）	—
location_strategy	firm_location_incentives	按区域梳理税收优惠和公共补助	—
location_strategy	firm_location_tco_simulate	模拟 N 年内的总占用成本	—
supplier_management	firm_supplier_search	按类别/地区/认证搜索和筛选供应商	—
supplier_management	firm_supplier_evaluate	多标准供应商评估（15 项标准）	—
supplier_management	firm_supplier_tco_analyze	供应商 TCO 分析（直接成本 + 间接成本 + 隐性成本）	—
supplier_management	firm_supplier_contract_check	合同条款合规性审计（14 项必备条款）	—
supplier_management	firm_supplier_risk_monitor	供应商风险监控（添加/移除/更新/状态）	—

快速开始

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

添加到 VS Code settings.json：

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

脚本

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

测试

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

2272 项测试（1961 项单元测试 + 311 项集成测试），94.6% 覆盖率，涵盖：

• 服务启动并响应 ping
• initialize 返回正确的功能和 __version__
• 已注册的全部 115 个工具均具有有效的 inputSchema
• 没有 Gateway 时，vs_context_push 可平稳降级
• firm_export_document 写入本地文件
• 未知方法返回 JSON-RPC 错误 -32601
• 未知工具返回描述性错误
• 时序安全的身份验证（I21）、SQL 注入防护（I24）、session_id 正则表达式（I41）
• 所有 21 个配置路径模型均通过 ConfigPathInput 阻止路径遍历（I27）
• Health/healthz 端点返回正确的工具数量和版本（I35）
• 共享的 config_helpers：load_config、get_nested、mask_secret（I25）
• Hebbian 记忆：收集时剔除 PII、权重更新试运行、层验证、漂移检测、Pydantic 遍历防护

安全

• 身份验证：对 Bearer token 使用时序安全的 hmac.compare_digest，不会产生时序侧信道（I21）
• 请求限制：aiohttp Application 上的 client_max_size=2MB（I22）
• 工具超时：所有异步工具调用均使用 asyncio.wait_for 和 TOOL_TIMEOUT_S（默认 120s）（I23）
• SQL 注入防护：通过 Pydantic 正则表达式 ^[a-zA-Z_][a-zA-Z0-9_]{0,127}$ 验证 table_name，并在处理程序中使用运行时白名单（I24）
• Session ID 正则表达式：所有 session_id 字段均使用 ^[a-zA-Z0-9_\-:.]+$，防止注入（I41）
• 版本集中管理：在 main.py 中定义 __version__，作为唯一事实来源（I37）
• DRY 辅助函数：config_helpers.py 中的共享函数 load_config、get_nested、mask_secret（I25）
• ConfigPathInput 基类：21 个模型从单一基类继承路径遍历防护（I27）
• Hebbian PII 剔除：在任何会话存储之前应用 9 种正则表达式模式（邮箱、电话、IP、API 密钥、SSN、JWT、AWS 密钥），符合 CDC §5.2
• Hebbian 漂移检测：使用 TF-IDF 余弦相似度与基线进行比较（不调用外部 API），符合 CDC §5.1
• Hebbian 权重上限：自动更新上限为 0.95，衰减下限为 0.0，默认 dry_run=True，符合 CDC §4.3
• GitHub PR 始终以草稿形式创建，并带有 needs-review 标签
• 日志中的 token 会通过 mask_secret() 脱敏（仅显示最后 4 个字符）
• 每个 WS 负载的上下文上限为 32 KB
• fleet.json 和 acp_sessions.json 以原子方式写入（os.replace）
• 使用 fcntl.LOCK_EX | LOCK_NB 锁定工作区（建议性锁定，可安全应对崩溃）
• fleet_session_inject_env：白名单正则表达式，只接受已知的提供商密钥
• fleet_cron_schedule：命令白名单正则表达式 + 屏蔽列表（rm、dd、mkfs…）
• 所有文件路径 Pydantic 字段均有路径遍历防护（..）
• 所有 AI 输出均附有人类审核免责声明

缺口覆盖率（Firm 审计）

ID	严重性	描述	覆盖情况
C1	严重	API 端点存在 SQL 注入	firm_security_scan
C2	严重	沙箱已禁用（mode: off）	firm_sandbox_audit
C3	严重	SESSION_SECRET 是临时值 / 位于配置中	firm_session_config_check
C4	严重	ACP 会话在重启后丢失（存储在内存中）	acp_session_persist/restore
H1	高	@buape/carbon 固定在 0.0.0-beta 版本	firm_adr_generate + CTO SOUL.md
H2	高	Gateway Funnel 未设置 auth.mode=password	firm_gateway_auth_check
H3	高	派生的会话未获取环境变量	fleet_session_inject_env
H4	高	沙箱未阻止 Cron	fleet_cron_schedule
H5	高	工作区锁存在竞态条件	firm_workspace_lock
H6	高	macOS 睡眠时 Gateway 会静默断开	firm_gateway_probe
H7	高	未处理 WS 关闭代码 1006	firm_gateway_probe
H8	高	Tailscale Funnel 未进行速率限制	firm_rate_limit_check
M1	中	@line/bot-sdk 是僵尸依赖项	firm_channel_audit
M2	中	测试覆盖率阈值为 70%	工厂阈值为 80% + CTO SOUL.md
M3	中	Baileys creds.json 未检查完整性 / 使用时长	firm_credentials_check
M4	中	缺少 Webhook HMAC 签名验证	firm_webhook_sig_check
M5	中	文档版本与 package.json 不一致	firm_doc_sync_check
M6	中	缺少架构决策记录（ADR）	firm_adr_generate
M7	中	日志过于详细 / 未设置 redactPatterns	firm_log_config_check
M8	中	未检查 ~/.firm/workspace 的完整性	firm_workspace_integrity_check
C5	严重	Node.js < 22.12.0（CVE-2025-59466、CVE-2026-21636）	firm_node_version_check
C6	严重	config.json 中硬编码了密钥（无密钥工作流）	firm_secrets_workflow_check
H9	高	缺少 HTTP 安全标头（HSTS、X-Content-Type-Options）	firm_http_headers_check
H10	高	gateway.nodes.allowCommands 存在危险的覆盖设置	firm_nodes_commands_check
H11	高	可信代理配置错误（bind+proxies+auth mode）	firm_trusted_proxy_check
M15	中	未配置会话磁盘空间限额（maxDiskBytes）	firm_session_disk_budget_check
M16	中	dmPolicy=allowlist 但 allowFrom 为空（默认放行）	firm_dm_allowlist_check
C7	严重	未验证外部密钥的生命周期（内联凭据）	firm_secrets_lifecycle_check
C8	严重	插件通道 HTTP 身份验证可绕过（路径规范化）	firm_channel_auth_canon_check
C9	严重	Exec 审批计划可变（符号链接导致 cwd 重新绑定）	firm_exec_approval_freeze_check
H12	高	Hook 会话密钥路由不受限制	firm_hook_session_routing_check
H13	高	配置 $include 可通过硬链接逃逸，且未限制文件大小	firm_config_include_check
H14	高	配置合并存在原型污染	firm_config_prototype_check
H15	高	SafeBins 未设置显式配置文件时，解释器不受限制	firm_safe_bins_profile_check
H16	高	组策略默认设置未采用失败关闭策略	firm_group_policy_default_check
H17	高	Shell 环境变量未清理（LD_PRELOAD、DYLD_*）	firm_shell_env_check
H18	高	未跟踪插件安装完整性 / 固定版本	firm_plugin_integrity_check
H19	高	hooks.token 与 gateway.auth.token 相同（重复使用）	firm_token_separation_check
M17	中	诊断信息中缺少 OTEL 密钥脱敏	firm_otel_redaction_check
M21	中	控制平面 RPC 未进行速率限制	firm_rpc_rate_limit_check
T1	工具	缺少 JSONL 跟踪的可观测性管道	firm_observability_pipeline
T3	工具	未检查 pgvector 内存配置	firm_pgvector_memory_check
T4	工具	不支持 Agent 并行编排（任务 DAG）	firm_agent_team_orchestrate
T5	工具	缺少 i18n / 本地化审计	firm_i18n_audit
T6	工具	缺少 CI 管道完整性检查	firm_ci_pipeline_check
T7	工具	技能会立即加载（不支持延迟加载）	firm_skill_lazy_loader + firm_skill_search
T8	工具	缺少 n8n 工作流自动化桥接	firm_n8n_workflow_export + firm_n8n_workflow_import
T9	工具	未检查知识图谱完整性	firm_knowledge_graph_check
T10	工具	未检查浏览器自动化配置	firm_browser_context_check

⚠️ AI 生成的内容 — 使用前需经人工审核。