Maple

Unified MCP server for agent observability, safety control, and behavior evolution.

Maple is the "Sentry + Git" layer for high-agency agents:

• Observe every step

• Replay/fork risky branches

• Audit and intervene with guardrails

• Learn from anonymized traces to evolve safer skills

Built with mcp-use + Apps SDK widgets.

What Is Implemented

1) Observability + Control

• observe_session: capture and render timeline widget

• replay_fork: branch from any step and simulate forward

• audit_risk: rule + anomaly risk dashboard

• guard_action: allow/block/pending with quarantine support

• ingest_session_event: stream external bridge events into active trace

2) ML Anomaly Detection (Simple Embeddings)

• ml_anomaly_report: embedding-based behavior outlier detection

• Lightweight hash embeddings + cosine similarity baseline

• Supports community baseline from anonymized shared traces

3) Network Effects

• share_trace_anon: anonymize and publish trace patterns to shared pool

• suggest_evolved_skills: generate evolved skill suggestions from shared traces

• Behavior signatures + shared dataset create compound data advantage

4) YC App Layer (Moat / Traction / Revenue)

• yc_app_brief: live YC-ready narrative generated from product metrics

• Emphasizes:

  • Moat: trace + fork + risk label data flywheel

  • Traction: OpenClaw integration and safety intervention activity

  • Revenue: freemium ladder (Free, Pro $9, Team $29, Enterprise $99)

MCP Tools

• observe_session

• replay_fork

• audit_risk

• ml_anomaly_report

• guard_action

• ingest_session_event

• share_trace_anon

• suggest_evolved_skills

• yc_app_brief

• list_traces

• export_trace

API Endpoints

• GET /health

• GET /judge (judge standalone page)

• GET /api/traces

• GET /api/traces/:traceId

• GET /api/community/stats

• GET /api/community/traces

• GET /api/yc/brief?focus=full|moat|traction|revenue

• GET /api/firewall/state

• POST /api/firewall/chat

• POST /api/firewall/decision (strict pre-execution allow/block gate)

Key Project Files

• index.ts: tool + route orchestration

• src/core/risk-engine.ts: rule engine + embedding anomaly integration

• src/ml/embeddings.ts: simple embedding implementation

• src/ml/anomaly-detector.ts: cosine-sim anomaly detection

• src/network/anonymizer.ts: anonymized trace transformation

• src/network/shared-trace-store.ts: community pool + skill suggestions

• src/strategy/yc-narrative.ts: moat/traction/revenue narrative builder

• resources/trace-timeline/widget.tsx

• resources/replay-simulator/widget.tsx

• resources/risk-dashboard/widget.tsx

Quick Start

Inspector: http://localhost:3000/inspector

Hardcoded Demo Stack (OpenClaw + Maple)

This repo now includes a one-command hardcoded demo setup:

• OpenClaw gateway on ws://127.0.0.1:19001

• OpenClaw bridge adapter on http://127.0.0.1:8787

• Maple API key generated at startup (or provided via env)

• Bridge token generated at startup (or provided via env)

Then open:

• Judge GUI: http://localhost:3000/judge

• Inspector: http://localhost:3000/inspector

Guided Demo Mode (No Manual JSON)

The Judge GUI now has Guided Demo Controls so you can run the full flow without Inspector copy/paste:

1. Enter API key and click Connect

2. Click Run Full Flow

Or step through:

1. 1) Start

2. 2) Audit

3. 3) Block

4. 4) Fork

Judge page now includes Firewall Chat in Control view:

• Ask natural-language questions ("status update", "why blocked?", "what should we do next?")

• Chat replies are generated from live firewall context (/api/firewall/state)

This uses internal demo APIs:

• POST /api/demo/start

• POST /api/demo/audit

• POST /api/demo/block

• POST /api/demo/fork

• POST /api/demo/full

demo:up also auto-opens both pages on macOS (set DEMO_OPEN_BROWSER=0 to disable).

Single-Trace Agent Action Logging (Hackathon)

For a reliable judge demo, run one stable trace and append every action to it.

What this does:

• Starts (or reuses) one trace for a stable sessionId

• Logs all agent actions through POST /api/openclaw/events using the same traceId

• Includes type, actor, prompt/message, command, url, toolName, and unique eventId

• Runs a preflight firewall preview and logs Maple's block/allow message into the same trace

Open http://localhost:3000/judge, then select the printed trace ID to see #0, #1, #2....

If you want to integrate this into your own runtime, use:

• scripts/maple-trace-logger.mjs

• logAction(...) for generic events

• logWebGet(...), logMarketplaceSearch(...), logMarketplaceToolCall(...) wrappers

Example:

Hackathon Gateway Mode (9 Curated MCP Tools)

Canonical startup (local + Railway) for single-source hackathon routing:

Equivalent local alias:

This starts a local downstream MCP app (toolhub) and route-locks Maple so all downstream calls go through it. Marketplace mode is canonically disabled in this build; execution only routes through cleared downstream apps.

Included tools (diverse coverage):

1. web_search (general web search)

2. web_fetch (browser-style page fetch/extraction)

3. wikipedia_summary (encyclopedia knowledge)

4. github_repo_info (code/repo intelligence)

5. weather_forecast (real-time practical data)

6. slack_post_message (messaging integration via Slack)

7. hn_search (live tech/news discovery on Hacker News)

8. arxiv_search (academic/research paper search)

9. openlibrary_search (books and publication lookup)

Slack config for slack_post_message:

• Incoming webhook mode: set SLACK_WEBHOOK_URL

• Bot mode: set SLACK_BOT_TOKEN and optionally SLACK_DEFAULT_CHANNEL

Verify wiring end-to-end:

Stop services:

Implementation files:

• scripts/hackathon-toolhub.mjs (downstream MCP server with 9 tools)

• scripts/hackathon-up.sh (starts toolhub + Maple in deterministic route-lock mode)

• scripts/hackathon-verify.sh (smoke tests for routed tool calls through Maple)

• scripts/hackathon-down.sh (stops Maple + toolhub)

Stop local demo processes:

Environment

observe_session falls back to mock only when source=auto. For source=openclaw, bridge failures are returned as errors (no silent mock downgrade).

API Key Auth

• Auth methods: x-api-key: <key> or Authorization: Bearer <key>

• Protected surfaces: MCP endpoints (/mcp, /sse) and internal APIs (/api/*)

• Auth is fail-closed by default. Set MAPLE_API_KEY or MAPLE_API_KEYS.

• Optional local-only bypass: MAPLE_ALLOW_NO_AUTH=true (not recommended).

• GET /health remains public for deployment health checks

Bridge Lockdown (Maple-First Routing)

• Set MAPLE_LOCK_BRIDGE_TARGET=true to deny per-request bridgeUrl / token overrides.

• Bridge override is denied by default.

• Optional local-only override: MAPLE_ALLOW_BRIDGE_OVERRIDE=true.

• In production, bridge override lock is enabled automatically.

• In production, OPENCLAW_BRIDGE_URL and OPENCLAW_BRIDGE_TOKEN must be explicitly set.

• This forces all OpenClaw bridge traffic through configured OPENCLAW_BRIDGE_URL + OPENCLAW_BRIDGE_TOKEN.

• Override attempts return 403 Bridge override denied.

Pre-Execution Firewall Decision API

• POST /api/firewall/decision evaluates a candidate action before execution.

• enforce=true (default): persist decision into trace and quarantine on deny.

• enforce=false: preview mode (no trace mutation), useful for dry-run checks.

Firewall Status Chat API

• GET /api/firewall/state returns normalized live firewall context for a trace/session.

• POST /api/firewall/chat answers status questions using that context.

• Body accepts message, optional traceId / sessionId, and includeContext.

• POST /api/chat/stream powers the Judge UI chatbot and can use AI with provider fallback.

• If OPENAI_API_KEY and/or ANTHROPIC_API_KEY are set, Maple enables AI mode with automatic fallback.

• If both model providers fail, Maple falls back to deterministic rules-based firewall answers.

Optional chat model environment variables:

Firewall Hardening (mcpwall-inspired)

Maple now enforces deterministic firewall policy checks on every trace step before risk scoring:

• First-match rules for high-risk behavior (pipe-to-shell, destructive commands, credential/secret access)

• Secret scanning + in-place redaction with marker: [REDACTED BY MAPLE]

• Automatic quarantine (guardStatus=block) when deny rules hit

• JSONL firewall audit logs at ~/.maple/firewall-logs/YYYY-MM-DD.jsonl

Optional environment variables:

Demo Script (2-3 min)

1. observe_session on an OpenClaw session

2. audit_risk to surface risky steps

3. ml_anomaly_report to show embedding anomalies

4. guard_action block a risky step

5. replay_fork from blocked step with safe edits

6. share_trace_anon to publish anonymized pattern

7. suggest_evolved_skills from community data

8. yc_app_brief to show moat/traction/revenue narrative

Example Calls

Current Limits

• Persistence is in-memory for hackathon speed

• Embedding model is intentionally simple (fast + local)

• External model providers are optional for firewall chat; rules mode works without them

Deploy

Railway Deployment (Recommended)

Yes, Maple can run on Railway with production safeguards.

This repo now includes railway.json, so Railway can use canonical settings automatically:

• Build command: npm run build

• Start command: npm run start

• Health check path: /health

Required environment variables:

Important notes:

• Railway provides PORT automatically; do not hardcode it.

• scripts/hackathon-start.sh is Railway-safe and no longer requires a local .env file to boot.

• In production, Maple enforces API key auth and requires explicit OPENCLAW_BRIDGE_URL + OPENCLAW_BRIDGE_TOKEN.

• Do not use localhost for OPENCLAW_BRIDGE_URL unless the bridge runs in the same container.

• If bridge connectivity is unavailable during demo, use source=mock to keep UI + guardrail flow live.