memory-journal-mcp 7.7.0 → 8.0.0

package/skills/agents-sdk/references/mcp/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: mcp-builder
+description: |
+  Core rules for code quality and specifications of Model Context Protocol (MCP) servers. Use when reviewing MCP code quality, enforcing specification rules, or checking schemas/error responses. Must see the explicit keyword "MCP" or "Model Context Protocol". NOT for general REST APIs or Cloudflare Workers. Do NOT trigger for generic 'build a server' requests unless the type is explicitly specified as an MCP server. (Invoke explicitly with `/mcp-builder` — does not auto-trigger).
+disable-model-invocation: true
+---
+
+# MCP Server Builder Guidelines
+
+This skill defines the high-integrity requirements for building MCP servers in this ecosystem.
+
+## 1. Core Requirements
+
+When building or modifying MCP servers, follow these prioritized rules:
+
+- **Must**: Use Zod for all tool argument validation. Do not blindly trust MCP client inputs.
+- **Must**: Return structured errors (`{ isError: true, content: [...] }`) from tools rather than throwing raw unhandled exceptions that crash the server.
+- **Should**: Wrap handlers in try/catch blocks that gracefully surface errors to the LLM context.
+- **Should**: Centralize error logging using standard prefixes (e.g., `[MCP Error]`).
+- **Optional**: Depending on the repository, implement integration testing via Playwright for dual HTTP/SSE verification.
+
+## 2. Security (Defense-in-Depth)
+
+- **Blocklists are Defense-in-Depth**: A blocklist (e.g., forbidding `rm -rf` in a terminal tool) is not a primary security boundary. Your primary security is the sandbox, container, or strict schema validation.
+- **No Secrets in Config**: MCP servers must rely on the environment variables for API keys and secrets, never hardcoded files inside the server repository.
+- **Rate Limiting & Input Sanitization**: Aggressively sanitize path arguments to prevent directory traversal (`../../`), and apply basic rate-limiting to tools that trigger heavy compute or external API calls.
+
+## 3. Deep References
+
+For the complete MCP implementation guide, architecture diagrams, and detailed tooling patterns, consult the full reference:
+
+- **[MCP Implementation Guide](references/implementation-guide.md)**: Contains transport selection (stdio vs. SSE), auth patterns, and multi-tool orchestration diagrams.
+
+## 4. Scaffold Reference
+
+When you need a minimal, fully compliant MCP server scaffold, use this structure:
+
+```typescript
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { z } from 'zod'
+
+// Initialize the modern McpServer pattern
+const server = new McpServer({ name: 'my-mcp', version: '1.0.0' })
+
+// Define tools using server.tool() which auto-registers schemas and handlers
+server.tool(
+  'my_tool',
+  'Does something using an ID',
+  { id: z.string().describe('The user ID to process') },
+  async ({ id }) => {
+    try {
+      // Logic here (input is already validated by Zod)
+      return { content: [{ type: 'text', text: `Got ID: ${id}` }] }
+    } catch (err) {
+      // Graceful error return
+      return { isError: true, content: [{ type: 'text', text: `Error: ${err}` }] }
+    }
+  }
+)
+
+// Connect via standard I/O
+const transport = new StdioServerTransport()
+await server.connect(transport)
+```

package/skills/agents-sdk/references/mcp/code-mode-reference.md

@@ -0,0 +1,245 @@
+# Code Mode Reference — MCP Builder Skill
+
+> Comprehensive implementation guide for adding Code Mode (sandboxed JS execution) to MCP servers. This is the standard pattern for all servers with 15+ tools.
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Main Thread                              │
+│                                                              │
+│  MCP Client ──► {prefix}_execute_code tool handler           │
+│       │                                                      │
+│       ▼                                                      │
+│  1. Security validation (blocked patterns, rate limit)       │
+│  2. Build API bridge from ToolDefinition[]                   │
+│  3. Serialize method names ──► Worker Thread                 │
+│                                    │                         │
+│  ┌──── RPC Host ◄──── MessagePort ─┘                        │
+│  │                                                           │
+│  │  Dispatches tool.handler() calls                         │
+│  │  Returns results via RpcResponse                          │
+│  └──────────────────────────────────────────────────────────┘
+│
+│  ┌──── Worker Thread (V8 Isolate) ──────────────────────────┐
+│  │                                                           │
+│  │  workerData: { code, methodList, timeoutMs, rpcPort }    │
+│  │                                                           │
+│  │  1. Build mj.* Proxy from methodList                     │
+│  │  2. vm.createContext (secondary isolation)                │
+│  │  3. Execute: (async () => { transformAutoReturn(code) })()               │
+│  │  4. RPC calls ──► MessagePort ──► Main thread            │
+│  │  5. Return result/error + ExecutionMetrics                │
+│  │                                                           │
+│  │  resourceLimits: maxOldGenerationSizeMb                  │
+│  │  Hard timeout: worker.terminate() from main thread       │
+│  └──────────────────────────────────────────────────────────┘
+```
+
+## File-by-File Breakdown
+
+### `types.ts`
+
+Core type definitions. Key interfaces:
+
+- **`SandboxOptions`** — `memoryLimitMb` (128), `timeoutMs` (30000), `cpuLimitMs` (10000)
+- **`PoolOptions`** — `minInstances` (2), `maxInstances` (10), `idleTimeoutMs` (60000)
+- **`SandboxResult`** — `{ success, result?, error?, stack?, metrics }`
+- **`SecurityConfig`** — `maxCodeLength`, `maxExecutionsPerMinute`, `maxResultSize`, `blockedPatterns`
+- **`RpcRequest`** — `{ id, group, method, args }` (worker → main thread)
+- **`RpcResponse`** — `{ id, result?, error? }` (main → worker thread)
+- **`ExecuteCodeOptions`** — `{ code, timeout?, readonly? }` (tool input)
+
+### `security.ts`
+
+Pre-execution security validation:
+
+- **Code validation** — length check, empty check, blocked pattern scan
+- **Rate limiting** — sliding 1-minute window per client ID, configurable limit
+- **Result validation** — post-execution JSON serialization size check
+- **Cleanup** — periodic `cleanupRateLimits()` to prevent memory leaks
+- **Additional blocked patterns** — `Reflect.*`, `Symbol.*`, `new Proxy` (escape aids), `(SELECT` (WHERE clause subquery injection)
+
+> [!IMPORTANT]
+> The `(SELECT` pattern prevents blind data exfiltration via `CASE WHEN (SELECT ...) THEN ... ELSE ...` in WHERE clauses passed to Code Mode tools. This is distinct from the semicolon-chained patterns in `validateWhereClause()` — both layers are required.
+
+### `sandbox.ts` (VM-based — dev/test only)
+
+Lightweight sandbox using `node:vm`. Use only for testing environments as it does not securely isolate memory or CPU execution boundaries:
+
+- **LRU script cache** (50 entries) — avoid recompilation
+- **Nulled globals** — `process`, `require`, `global`, `globalThis`, `setTimeout`, `setInterval`
+- **Frozen built-in prototypes** — All built-in prototypes (`Object`, `Function`, `Error`, `Array`, `Promise`, `String`, `Number`, `Boolean`, `RegExp`, `Map`, `Set`, typed arrays) must be frozen inside the `vm` context to prevent constructor chain escapes via string concatenation (e.g., `'con'+'structor'` bypasses static blocked pattern scanning)
+- **`microtaskMode: "afterEvaluate"`** — prevents async escapes (safe here because VM sandbox doesn't use async IIFE execution)
+- **`SandboxPool`** — concurrent execution with max instances guard
+- **Auto-return transform** — applies `transformAutoReturn()` before IIFE wrapping so bare expressions surface their return value
+
+> ⚠️ **Do NOT use `microtaskMode: 'afterEvaluate'` in the worker-thread sandbox** — it prevents async function Promises from resolving, causing the worker to hang forever.
+
+### `worker-sandbox.ts` (Production Standard)
+
+True V8 isolate via `node:worker_threads` (Mandatory for production release):
+
+- **`WorkerSandbox.execute(code, apiBindings)`** — spawns fresh worker per execution
+- **RPC bridge** — `MessageChannel` with `hostPort` (main) and `workerPort` (worker)
+- **MessagePort transfer** — pass `workerPort` via `workerData.rpcPort` + `transferList: [workerPort]` in the constructor. **Never** double-transfer with a separate `postMessage` — the port becomes detached after the first transfer.
+- **Binding serialization** — separate group objects → method name arrays and top-level function aliases → `_topLevel` key. The RPC handler must dispatch `_topLevel` methods from `apiBindings` root.
+- **Resource limits** — `maxOldGenerationSizeMb` and `maxYoungGenerationSizeMb`
+- **Hard timeout** — `worker.terminate()` after `timeoutMs + 1000ms` grace
+- **Two message channels**: `hostPort.on('message')` for RPC only; `worker.on('message')` for completion results
+- **Timeout forwarding** — The tool handler **must** destructure `timeout` from the parsed Zod input and pass it as `timeoutMs` to `pool.execute()`. If omitted, all executions silently use the default 30s regardless of user input. This was a production bug in memory-journal-mcp (March 2026). The pattern is: `const { code, timeout, readonly } = Schema.parse(params); await pool.execute(code, bindings, { timeoutMs: timeout ?? DEFAULT_TIMEOUT });`
+- **Negative `memoryUsedMb` clamping** — Worker memory metrics can report negative values due to GC timing. Always clamp: `memoryUsedMb: Math.max(0, (rss - baseline) / 1048576)`. This prevents confusing negative memory usage in execution metrics returned to the client.
+
+### `worker-script.ts` (Worker entry point)
+
+Runs inside the worker thread:
+
+- Receives `{ code, methodList, timeoutMs, rpcPort }` via `workerData`
+- Builds **async Proxy API** — each method sends `RpcRequest` over `rpcPort`, awaits `RpcResponse`. Readonly mode wraps undefined mutation methods in a Proxy `'get'` trap that rejects the promise, natively catching and returning a structured `{ success: false, error }` response.
+- `_topLevel` methods are mounted directly on the API root (e.g., `mj.createEntry`)
+- Wraps code in `(async () => { transformAutoReturn(user_code) })()` for async support — `transformAutoReturn()` prepends `return` to the last expression statement so bare expressions surface their value (Node REPL semantics)
+- Secondary `vm.createContext` isolation within the worker — **do NOT use `microtaskMode: 'afterEvaluate'`** and **do NOT explicitly inject built-ins** (`Promise`, `JSON`, etc.) — they inherit from the worker's global scope
+- **Frozen built-in prototypes** — Same freezing as `sandbox.ts`. Apply `Object.freeze(builtin.prototype)` to all built-ins inside the `vm` context before executing user code
+- **Result path**: close `rpcPort` with `unref()` + `close()`, then send result via `parentPort.postMessage()`
+- Measures CPU time via `process.cpuUsage()`
+
+### `sandbox-factory.ts`
+
+Runtime mode selection:
+
+- `createSandbox(mode)` → `CodeModeSandbox` or `WorkerSandbox`
+- `createSandboxPool(mode)` → `SandboxPool` or `WorkerSandboxPool`
+- `getSandboxModeInfo()` → description, security level, isolation type
+- Default mode: `'worker'`
+
+### `api.ts`
+
+The API bridge — transforms `ToolDefinition[]` into the namespaced API object:
+
+**Key functions:**
+
+- `toolNameToMethodName(name, group)` — strips prefix, converts snake_case → camelCase
+- `normalizeParams(method, args)` — maps positional args to named params using `POSITIONAL_PARAM_MAP`. Handles multiple input types: string, number, boolean single args (not just strings). For non-string primitives passed as a single positional arg, wraps into the first parameter name.
+- `createGroupApi(group, tools)` — builds one group namespace with handlers, aliases, and `help()`
+- `{Api}.createSandboxBindings()` — assembles the complete `{prefix}.*` object
+- `{prefix}.reportProgress(current, total, message)` — utility for sandboxed code to emit MCP progress notifications. Bridges to the main thread's `sendProgress()` via the RPC channel. Silently no-ops when the client doesn't request progress
+
+**`help()` behavior:** The `help()` method at both top level and per group lists **ALL methods regardless of the `readonly` flag**. Write methods are wrapped with readonly guards that return structured errors when called in readonly mode, but they still appear in the `help()` listing for discoverability.
+
+**Positional parameter completeness:** When adding new tools or groups, verify that the `POSITIONAL_PARAM_MAP` covers all methods that accept a single "primary" argument. Missing mappings force agents to use verbose object syntax even for simple calls.
+
+**Recursion prevention:** Filters out `codemode` group tools during construction.
+
+### `api-constants.ts`
+
+Static configuration maps:
+
+- **`METHOD_ALIASES`** — shorthand names per group (e.g., `core.create` → `createEntry`). Ensure semantic correctness: `log` and `record` aliases must point to the right methods.
+- **`GROUP_EXAMPLES`** — usage examples for `help()` output
+- **`POSITIONAL_PARAM_MAP`** — enables `mj.core.createEntry("note")` → `{ content: "note" }`
+- **`GROUP_PREFIX_MAP`** — prefix stripping rules per group
+- **`KEEP_PREFIX_GROUPS`** — groups that retain meaningful prefixes (e.g., `github`, `team`)
+
+### `api/` Subdirectory Variant (Adapter Servers)
+
+For adapter-based servers with large tool sets (50+ tools, extensive aliases), the single `api.ts` + `api-constants.ts` pattern becomes unwieldy. Split into a dedicated subdirectory:
+
+```
+src/codemode/api/
+  index.ts       — Main API bridge — exposes tools to sandbox
+  maps.ts        — Tool name → handler function mapping (can grow to 20KB+)
+  group-api.ts   — Per-group API surface generation
+  aliases.ts     — Tool alias resolution (can grow to 15KB+)
+  normalize.ts   — Parameter normalization utilities
+```
+
+**When to split:** When `api.ts` exceeds ~500 lines or `api-constants.ts` exceeds ~300 lines. Adapter servers with 200+ tools (postgres-mcp, mysql-mcp) should always use the subdirectory pattern.
+
+**Key difference from single-file:** The `maps.ts` file replaces the `POSITIONAL_PARAM_MAP` and `METHOD_ALIASES` constants, while `group-api.ts` replaces the `createGroupApi()` function. The `normalize.ts` file extracts parameter normalization from `api.ts`.
+
+## Tool Handler Pattern
+
+The `{prefix}_execute_code` tool handler sits in `src/handlers/tools/codemode.ts`:
+
+```typescript
+// Key flow:
+// 1. Parse input (code, timeout, readonly)
+// 2. Security validation → early return if blocked
+// 3. Rate limit check → early return if exceeded
+// 4. Collect non-codemode tools from all group modules
+// 5. Optional readonly filter (only readOnlyHint: true tools)
+// 6. Build API bridge from tool definitions
+// 7. Execute in sandbox pool
+// 8. Validate result size → return structured result
+```
+
+> [!CAUTION]
+> **`outputSchema` pitfall**: Do NOT define `outputSchema` with `z.unknown()` on the Code Mode tool. It produces a bare `{}` JSON Schema that crashes AntiGravity's `structuredContent` processing. Omit `outputSchema` entirely — dynamically-typed results should use the plain text JSON response path.
+
+**Import strategy:** Import from leaf tool group modules (e.g., `./core.js`, `./search.js`) directly — NOT from the tool barrel `./index.js` to avoid circular dependencies.
+
+## Integration Checklist
+
+When adding Code Mode to a new MCP server:
+
+- [ ] Create `src/codemode/` directory with all 10 files (or 5 + `api/` subdir for adapter servers)
+- [ ] Add `'codemode'` to the `ToolGroup` union type
+- [ ] Create `src/handlers/tools/codemode.ts` handler
+- [ ] Wire `getCodeModeTools()` into `getAllToolDefinitions()`
+- [ ] Add `codemode` to `TOOL_GROUPS` record in `ToolFilter`
+- [ ] Add `'codemode'` to the `'full'` meta-group
+- [ ] Add codemode icon to the icon map
+- [ ] Add `--sandbox-mode` CLI flag (optional)
+- [ ] Update `server-instructions.ts` with Code Mode preference guidance
+- [ ] Update README, code-map, and tool-reference docs
+- [ ] Write tests: API bridge, security, sandbox, worker sandbox, handler integration
+
+## Testing Patterns
+
+### API Bridge Tests (`tests/codemode/api.test.ts`)
+
+- `toolNameToMethodName()` — verify snake_case → camelCase for all groups
+- `normalizeParams()` — test positional args, object passthrough, multi-arg mapping
+- `JournalApi` construction — verify group count, method count, alias resolution
+- `createSandboxBindings()` — verify all namespaces present, `help()` returns valid info
+
+### Security Tests (`tests/codemode/security.test.ts`)
+
+- Blocked patterns — each pattern individually and in combinations
+- Code length limits — boundary values (exactly at, one over)
+- Rate limiting — within limit, at limit, over limit, window reset
+- Result size — within limit, over limit, non-serializable results
+
+### Sandbox Tests (`tests/codemode/sandbox.test.ts`)
+
+- Basic execution — `return 1 + 1`
+- Async execution — `return await Promise.resolve(42)`
+- Nulled globals — `process`, `require`, `eval` should be undefined
+- Timeout enforcement — infinite loop should terminate
+- Script cache — verify cache hit on repeated execution
+
+### Worker Sandbox Tests (`tests/codemode/worker-sandbox.test.ts`)
+
+- RPC bridge — verify tool calls route to main thread and return results
+- Resource limits — OOM should terminate worker gracefully
+- Hard timeout — long-running code should be terminated
+- Fresh state — each execution gets a clean worker
+
+### Handler Integration Tests (`tests/handlers/codemode-tool-handlers.test.ts`)
+
+- Happy path — simple code execution returns result
+- Error path — invalid code returns `{ success: false, error }`
+- Readonly mode — write tools should be filtered out
+- Cross-group workflow — code that uses multiple API groups
+- Security rejection — blocked patterns return structured error
+
+## AntiGravity Agent Considerations
+
+When deploying an MCP server with Code Mode inside AntiGravity:
+
+- AntiGravity defaults to raw parameter schemas and doesn't implicitly know about internal API mappings or aliases
+- **Always provide a reference** to the injected API bindings via `server-instructions.ts` — include group namespaces, method signatures, and positional argument examples
+- Add a system prompt rule instructing the agent to prefer Code Mode for multi-step operations:
+  > _"When using this server, prefer `{prefix}_execute_code` (Code Mode) for multi-step operations to minimize token usage."_
+- The `help()` method at top level and per group provides runtime discoverability as a fallback
+- **`outputSchema` pitfall**: Do NOT define `outputSchema` with `z.unknown()` on the Code Mode tool. It produces a bare `{}` JSON Schema that crashes AntiGravity's `structuredContent` processing. Omit `outputSchema` entirely — dynamically-typed results should use the plain text JSON response path. (Also documented above in Tool Handler Pattern.)