# 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
```bash
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)
```bash
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.
```bash
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:
```js
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:
```bash
npm start
```
Equivalent local alias:
```bash
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:
```bash
npm run hackathon:verify
```
Stop services:
```bash
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:
```bash
npm run demo:down
```
## Environment
```bash
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:
```bash
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:
```bash
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
```json
{
"tool": "ml_anomaly_report",
"input": {
"traceId": "<trace-id>",
"useCommunityBaseline": true,
"threshold": 0.58,
"topAnomalies": 5
}
}
```
```json
{
"tool": "share_trace_anon",
"input": {
"traceId": "<trace-id>",
"taskLabel": "Inbox triage",
"objective": "Safely automate inbound support triage",
"tags": ["support", "email", "guarded"]
}
}
```
```json
{
"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
```bash
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:
```bash
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.
