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

npm install
npm run dev

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)

OPENCLAW_VERSION=<pin-a-version> npm run demo:install-openclaw
npm run demo:up

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.

MAPLE_API_KEY=local-demo-key npm run trace:demo

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:

import { createMapleTraceLogger } from "./scripts/maple-trace-logger.mjs";

const logger = createMapleTraceLogger({
  baseUrl: "http://localhost:3000",
  apiKey: process.env.MAPLE_API_KEY,
  sessionId: "maple-live",
});

await logger.startRun({ reuseLatest: true });
await logger.logAction({
  type: "tool_call",
  actor: "agent",
  toolName: "web_get",
  prompt: "Fetch provider docs",
  url: "https://docs.mcp.so/providers",
});

Hackathon Gateway Mode (9 Curated MCP Tools)

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

npm start

Equivalent local alias:

npm run hackathon:up

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:

npm run hackathon:verify

Stop services:

npm run hackathon:down

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:

npm run demo:down

Environment

MCP_URL=http://localhost:3000
OPENCLAW_BRIDGE_URL=http://localhost:8787
OPENCLAW_BRIDGE_TOKEN=your_token
MAPLE_API_KEY=your_long_random_key
MAPLE_LOCK_BRIDGE_TARGET=true

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:

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
MAPLE_FIREWALL_CHAT_PRIMARY=openai   # openai | anthropic
MAPLE_FIREWALL_CHAT_OPENAI_MODEL=gpt-4o-mini
MAPLE_FIREWALL_CHAT_ANTHROPIC_MODEL=claude-sonnet-4-6
MAPLE_FIREWALL_CHAT_TIMEOUT_MS=15000

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:

MAPLE_FIREWALL_ENABLED=true
MAPLE_FIREWALL_DEFAULT_ACTION=allow   # allow | deny | log_only
MAPLE_FIREWALL_LOG_DIR=~/.maple/firewall-logs

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

{
  "tool": "ml_anomaly_report",
  "input": {
    "traceId": "<trace-id>",
    "useCommunityBaseline": true,
    "threshold": 0.58,
    "topAnomalies": 5
  }
}

{
  "tool": "share_trace_anon",
  "input": {
    "traceId": "<trace-id>",
    "taskLabel": "Inbox triage",
    "objective": "Safely automate inbound support triage",
    "tags": ["support", "email", "guarded"]
  }
}

{
  "tool": "suggest_evolved_skills",
  "input": {
    "query": "safe inbox triage automation",
    "limit": 3,
    "minConfidence": 0.4
  }
}

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

npm run 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:

NODE_ENV=production
HOST=0.0.0.0
MCP_URL=https://<your-railway-domain>
MAPLE_API_KEY=<long-random-key>
MAPLE_LOCK_BRIDGE_TARGET=true
OPENCLAW_BRIDGE_URL=<bridge-url-reachable-from-railway>
OPENCLAW_BRIDGE_TOKEN=<bridge-token>
MAPLE_FIREWALL_ENABLED=true

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.