diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000000..186ff3d126 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,10 @@ +node_modules +.git +test +specs +deploy +website +data +dist +.claude +.specify diff --git a/.env.example b/.env.example index 77ca0f3a38..e78483bb15 100644 --- a/.env.example +++ b/.env.example @@ -88,6 +88,7 @@ # you expose the daemon beyond loopback or run behind a reverse proxy. # AGENTMEMORY_SECRET=your-secret-here +# AGENTMEMORY_SECRET_FILE=/data/.hmac # Path to persisted HMAC secret file (Docker: auto-generated by entrypoint) # ----------------------------------------------------------------------------- # 4. Search tuning @@ -148,6 +149,17 @@ # III_REST_PORT=3111 # REST API port (also affects viewer at +2) # III_STREAMS_PORT=3112 # Streams API port # III_ENGINE_URL=ws://localhost:49134 # iii-engine WebSocket URL (used by the worker) +# AGENTMEMORY_REST_HOST=127.0.0.1 # REST upstream host for viewer reverse proxy (Docker: set to 127.0.0.1) + +# AGENTMEMORY_MCP_PORT=3114 # MCP Streamable HTTP port (JSON-RPC transport). Defaults to REST port + 3. +# # MCP clients that speak Streamable HTTP can connect directly to +# # http://localhost:3114/mcp instead of spawning npx @agentmemory/mcp. +# AGENTMEMORY_VIEWER_HOST=0.0.0.0 # Viewer bind address. Unset = loopback only. Set to 0.0.0.0 to +# # make the viewer reachable from other hosts on the network (requires +# # AGENTMEMORY_SECRET and VIEWER_ALLOWED_HOSTS). +# VIEWER_ALLOWED_HOSTS=localhost:3113,127.0.0.1:3113 # Comma-separated Host header values the viewer trusts. +# # Add remote hostnames/IPs when AGENTMEMORY_VIEWER_HOST is set +# # to 0.0.0.0 (e.g. "my-host:3113,192.168.1.5:3113"). # ----------------------------------------------------------------------------- # 8. iii engine pin diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ed53c6da94..3da437b2d0 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -3,33 +3,8 @@ name: CI # `paths-ignore` keeps doc-only / website / README / CHANGELOG churn from # burning runner minutes. Source / config / workflow changes always run. # `workflow_dispatch` gives a manual re-run button for flake debugging. +# DISABLED — kept for reference. Auto-triggers removed; manual dispatch only. on: - push: - branches: [main] - paths-ignore: - - "README.md" - - "CHANGELOG.md" - - "AGENTS.md" - - "ROADMAP.md" - - "website/**" - - "docs/**" - - "assets/**" - - "deploy/**/README.md" - - "**/*.md" - - "**/*.mdx" - pull_request: - branches: [main] - paths-ignore: - - "README.md" - - "CHANGELOG.md" - - "AGENTS.md" - - "ROADMAP.md" - - "website/**" - - "docs/**" - - "assets/**" - - "deploy/**/README.md" - - "**/*.md" - - "**/*.mdx" workflow_dispatch: # Cancel in-flight PR runs when a force-push lands. Keep push runs to diff --git a/.github/workflows/docker-build-publish.yml b/.github/workflows/docker-build-publish.yml new file mode 100644 index 0000000000..36737653e2 --- /dev/null +++ b/.github/workflows/docker-build-publish.yml @@ -0,0 +1,55 @@ +name: Build & Publish Docker Image + +on: + release: + types: [published] + workflow_dispatch: + +permissions: + contents: read + packages: write + +jobs: + build-publish: + runs-on: ubuntu-latest + strategy: + fail-fast: false + steps: + - uses: actions/checkout@v6 + with: + persist-credentials: false + + - name: Docker meta + id: meta + uses: docker/metadata-action@v5 + with: + images: ghcr.io/${{ github.repository }} + tags: | + type=raw,value=latest,enable=${{ github.event_name == 'release' }} + type=semver,pattern={{version}},enable=${{ github.event_name == 'release' }} + type=semver,pattern={{major}}.{{minor}},enable=${{ github.event_name == 'release' }} + type=sha,prefix=,enable=${{ github.event_name != 'release' }} + + - name: Set up QEMU + uses: docker/setup-qemu-action@v3 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Log in to GitHub Container Registry + uses: docker/login-action@v3 + with: + registry: ghcr.io + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + - name: Build and push + uses: docker/build-push-action@v6 + with: + context: . + platforms: linux/amd64,linux/arm64 + push: true + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} + cache-from: type=gha + cache-to: type=gha,mode=max diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 000033998d..d21e73857f 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -1,8 +1,7 @@ name: Publish to npm +# DISABLED — kept for reference. Auto-triggers removed; manual dispatch only. on: - release: - types: [published] workflow_dispatch: inputs: packages: diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000000..ba7e6c6659 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,35 @@ +ARG III_VERSION=0.11.2 + +FROM iiidev/iii:${III_VERSION} AS iii-image + +FROM node:22-slim AS build +WORKDIR /app +COPY package.json tsconfig.json tsdown.config.ts ./ +RUN npm install --package-lock-only --legacy-peer-deps --no-audit --no-fund +RUN npm ci --legacy-peer-deps --no-audit --no-fund +COPY src/ ./src/ +RUN npm run build + +FROM node:22-slim + +ARG III_VERSION=0.11.2 + +RUN apt-get update \ + && apt-get install -y --no-install-recommends openssl ca-certificates tini gosu curl \ + && rm -rf /var/lib/apt/lists/* + +COPY --from=iii-image /app/iii /usr/local/bin/iii + +WORKDIR /app +COPY --from=build /app/dist/ ./dist/ +COPY --from=build /app/package.json /app/package-lock.json ./ +RUN npm ci --legacy-peer-deps --omit=dev --no-fund --no-audit + +ENV AGENTMEMORY_III_VERSION=${III_VERSION} \ + TINI_SUBREAPER=1 + +COPY --chmod=0755 entrypoint.sh /app/entrypoint.sh + +EXPOSE 3113 3114 + +ENTRYPOINT ["/usr/bin/tini", "--", "/app/entrypoint.sh"] diff --git a/README.md b/README.md index c4ec2c1e0b..6d794eb84a 100644 --- a/README.md +++ b/README.md @@ -498,6 +498,49 @@ Imported sessions show up in the Replay picker alongside native ones. Under the > **Heads-up if you rely on `import-jsonl` as your primary capture path:** Claude Code's `cleanupPeriodDays` (in `~/.claude/settings.json`, default **30**) auto-deletes JSONL transcripts older than that window from `~/.claude/projects/`. If you install agentmemory fresh on a months-old Claude Code history, anything older than 30 days is already gone before the first import. Either run `import-jsonl` on a cron, raise `cleanupPeriodDays` to something higher, or wire the auto-capture hooks (the default plugin install path) so each turn lands in agentmemory while the session is live and the JSONL cleanup stops mattering. +### Docker + +Run agentmemory in a container with one command — no Node.js or npm required on the host. + +**Prerequisites:** Docker and docker-compose. + +```bash +# Clone and start — iii engine + agentmemory worker + viewer + MCP Stream HTTP +git clone https://github.com/rohitg00/agentmemory.git +cd agentmemory +docker compose build && docker compose up -d + +# Grab the auto-generated HMAC secret for MCP client auth +docker compose logs agentmemory | grep AGENTMEMORY_SECRET +# or: docker compose exec agentmemory cat /data/.hmac + +# Verify it is up +curl -s http://localhost:3111/agentmemory/health | head -c 200 +``` + +MCP clients that speak Streamable HTTP can connect directly without spawning +an `npx` process: + +```json +{ + "mcpServers": { + "agentmemory": { + "url": "http://localhost:3114/mcp", + "headers": { + "Authorization": "Bearer " + } + } + } +} +``` + +Stdio-based MCP clients (Cursor, Claude Code, etc.) still work through the +`npx @agentmemory/mcp` shim as usual — set `AGENTMEMORY_URL=http://localhost:3111` +and `AGENTMEMORY_SECRET` in the client's env block. + +See [specs/001-mcp-stream-dockerize/quickstart.md](specs/001-mcp-stream-dockerize/quickstart.md) +for advanced Docker setups (custom ports, external volumes, multi-instance). + ### Upgrade / Maintenance Use the maintenance command when you intentionally want to update your local runtime: diff --git a/docker-compose.yml b/docker-compose.yml index 6b1176521d..dcc0a434c8 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,41 +1,29 @@ services: - # One-shot init container: docker creates named volumes root:root mode - # 755, but the iii-engine image is distroless and runs as UID 65532 - # with no `chown` of its own. Without this, /data is unwritable, the - # engine silently buffers in RAM, and state evaporates on every - # restart — the exact symptom v0.9.7's working-directory fix set out - # to solve. Runs once at compose-up and exits. - iii-init: - image: busybox:1.36 - user: "0:0" - volumes: - - iii-data:/data - entrypoint: ["sh", "-c", "chown -R 65532:65532 /data && chmod 755 /data"] - restart: "no" - - iii-engine: - # Pinned to v0.11.2 — the last engine that runs agentmemory's current - # worker model cleanly. v0.11.6 introduces a new sandbox-everything- - # via-`iii worker add` model that agentmemory hasn't been refactored - # for yet; the architectural mismatch surfaces as EPIPE reconnect - # loops and empty search after save. Bump only after agentmemory is - # refactored to register as a sandboxed worker. - # - # Override per-shell or via .env file: - # AGENTMEMORY_III_VERSION=0.11.7 docker compose up - image: iiidev/iii:${AGENTMEMORY_III_VERSION:-0.11.2} - user: "65532:65532" - depends_on: - iii-init: - condition: service_completed_successfully + agentmemory: + build: + context: . + dockerfile: Dockerfile ports: - - "127.0.0.1:49134:49134" - - "127.0.0.1:3111:3111" - - "127.0.0.1:3112:3112" - - "127.0.0.1:9464:9464" + - "3114:3114" + - "3113:3113" volumes: - - iii-data:/data - - ./iii-config.docker.yaml:/app/config.yaml:ro + - agentmemory-data:/data + env_file: .env + environment: + AGENTMEMORY_TOOLS: all + AGENTMEMORY_SECRET_FILE: /data/.hmac + III_ENGINE_URL: ws://127.0.0.1:49134 + III_REST_PORT: "3111" + AGENTMEMORY_MCP_PORT: "3114" + AGENTMEMORY_REST_HOST: "127.0.0.1" + AGENTMEMORY_VIEWER_HOST: "0.0.0.0" + VIEWER_ALLOWED_HOSTS: "${VIEWER_ALLOWED_HOSTS:-localhost:3113,127.0.0.1:3113}" + healthcheck: + test: ["CMD", "curl", "-f", "http://127.0.0.1:3111/agentmemory/livez"] + interval: 10s + timeout: 5s + retries: 5 + start_period: 20s restart: unless-stopped logging: driver: json-file @@ -44,4 +32,4 @@ services: max-file: "3" volumes: - iii-data: + agentmemory-data: diff --git a/entrypoint.sh b/entrypoint.sh new file mode 100755 index 0000000000..bff918e204 --- /dev/null +++ b/entrypoint.sh @@ -0,0 +1,112 @@ +#!/bin/sh +# agentmemory first-boot entrypoint. +# +# Runs as root so it can: +# 1. Overwrite the npm-bundled iii-config.yaml (which binds 127.0.0.1 +# and uses relative ./data paths) with a deploy-tuned version that +# binds 0.0.0.0 and uses absolute /data paths. +# 2. chown the platform-mounted /data volume to the runtime user +# (managed platforms mount volumes root-owned 755 by default). +# 3. Generate the HMAC secret on first boot and persist it to +# /data/.hmac (chmod 600) so the secret survives restarts. +# +# Then it execs the agentmemory CLI under gosu as the unprivileged +# `node` user. + +set -eu + +DATA_DIR="${AGENTMEMORY_DATA_DIR:-/data}" +HMAC_FILE="${AGENTMEMORY_HMAC_FILE:-/data/.hmac}" +RUN_AS="node:node" +III_CONFIG="/app/iii-config.yaml" + +mkdir -p "$DATA_DIR" +chown -R "$RUN_AS" "$DATA_DIR" + +cat > "$III_CONFIG" <<'EOF' +workers: + - name: iii-http + config: + port: 3111 + host: 0.0.0.0 + default_timeout: 180000 + cors: + allowed_origins: + - "http://localhost:3111" + - "http://localhost:3113" + - "http://localhost:3114" + - "http://127.0.0.1:3111" + - "http://127.0.0.1:3113" + - "http://127.0.0.1:3114" + allowed_methods: [GET, POST, PUT, DELETE, OPTIONS] + - name: iii-state + config: + adapter: + name: kv + config: + store_method: file_based + file_path: /data/state_store.db + - name: iii-queue + config: + adapter: + name: builtin + - name: iii-pubsub + config: + adapter: + name: local + - name: iii-cron + config: + adapter: + name: kv + - name: iii-stream + config: + port: 3112 + host: 0.0.0.0 + adapter: + name: kv + config: + store_method: file_based + file_path: /data/stream_store + - name: iii-observability + config: + enabled: true + service_name: agentmemory + exporter: memory + sampling_ratio: 1.0 + metrics_enabled: true + logs_enabled: true + logs_console_output: true +EOF +chown "$RUN_AS" "$III_CONFIG" + +if [ ! -s "$HMAC_FILE" ]; then + SECRET="$(openssl rand -hex 32)" + umask 077 + printf '%s\n' "$SECRET" > "$HMAC_FILE" + chmod 600 "$HMAC_FILE" + chown "$RUN_AS" "$HMAC_FILE" + echo "================================================================" + echo "agentmemory: generated HMAC secret on first boot" + echo "AGENTMEMORY_SECRET=$SECRET" + echo "Copy this value now. It will not be printed again." + echo "Stored at: $HMAC_FILE (chmod 600)" + echo "To rotate: delete $HMAC_FILE on the persistent volume and restart." + echo "================================================================" +fi + +AGENTMEMORY_SECRET="$(cat "$HMAC_FILE")" +export AGENTMEMORY_SECRET + +# Start iii-engine in the background. +gosu "$RUN_AS" iii --config "$III_CONFIG" & +III_PID=$! + +_shutdown() { + kill -TERM $III_PID 2>/dev/null || true + wait $III_PID 2>/dev/null || true + exit 0 +} +trap _shutdown TERM INT + +# Start agentmemory in the foreground; the container exits when it exits. +gosu "$RUN_AS" node /app/dist/index.mjs diff --git a/src/cli/connect/types.ts b/src/cli/connect/types.ts index 169dde1382..21f25c381a 100644 --- a/src/cli/connect/types.ts +++ b/src/cli/connect/types.ts @@ -27,7 +27,7 @@ export type ConnectAdapter = { * server only. Declared on the adapter so the picker never needs a * separate hardcoded list (#872). Defaults to "mcp" when omitted. */ - category?: "native" | "mcp"; + category?: "native" | "mcp" | "stream-http"; detect(): boolean; install(opts: ConnectOptions): Promise; }; diff --git a/src/cli/connect/util.ts b/src/cli/connect/util.ts index 580cd4ee72..0b3ae3edf4 100644 --- a/src/cli/connect/util.ts +++ b/src/cli/connect/util.ts @@ -43,6 +43,19 @@ const COPILOT_MCP_COMMAND = args: ["-y", "@agentmemory/mcp"], }; +// Stream HTTP MCP entry (alternative to stdio command): +// clients that speak the Streamable HTTP transport (MCP spec 2025-03-26+) +// can connect directly to the agentmemory MCP port at :3114 instead of +// spawning an npx process. Use this block (or merge it with the stdio +// "agentmemory" entry as an additional server entry) when the MCP server +// is reachable as an HTTP endpoint — no npx bootstrap or stdio needed. +export const AGENTMEMORY_MCP_HTTP_BLOCK = { + url: "http://localhost:3114/mcp", + headers: { + Authorization: "Bearer ${AGENTMEMORY_SECRET:-}", + }, +}; + export const AGENTMEMORY_COPILOT_MCP_BLOCK = { type: "local" as const, ...COPILOT_MCP_COMMAND, diff --git a/src/config.ts b/src/config.ts index f68da2e31d..11183ed773 100644 --- a/src/config.ts +++ b/src/config.ts @@ -161,7 +161,7 @@ export function loadConfig(): AgentMemoryConfig { const provider = detectProvider(env); - // Port quartet: REST is the anchor; streams/engine derive from it + // Port family: REST is the anchor — streams, MCP, and engine ports derive from it // unless individually overridden. Default anchor 3111 yields the // canonical 3112 streams / 49134 engine pair, but `III_REST_PORT=3211` // auto-picks 3212 + 49234 so a second instance doesn't collide (#750). @@ -169,6 +169,8 @@ export function loadConfig(): AgentMemoryConfig { const streamsPort = parseInt(env["III_STREAM_PORT"] || env["III_STREAMS_PORT"] || "", 10) || restPort + 1; + const mcpPort = + parseInt(env["AGENTMEMORY_MCP_PORT"] || "", 10) || restPort + 3; const engineUrl = env["III_ENGINE_URL"] || `ws://localhost:${ @@ -179,6 +181,7 @@ export function loadConfig(): AgentMemoryConfig { engineUrl, restPort, streamsPort, + mcpPort, provider, tokenBudget: safeParseInt(env["TOKEN_BUDGET"], 2000), maxObservationsPerSession: safeParseInt(env["MAX_OBS_PER_SESSION"], 500), diff --git a/src/index.ts b/src/index.ts index 4233e8a67e..0ff5de15a8 100644 --- a/src/index.ts +++ b/src/index.ts @@ -93,6 +93,7 @@ import { registerEventTriggers } from "./triggers/events.js"; import { registerMcpEndpoints } from "./mcp/server.js"; import { getAllTools } from "./mcp/tools-registry.js"; import { startViewerServer } from "./viewer/server.js"; +import { startMcpStreamServer } from "./mcp/stream-http.js"; import { MetricsStore } from "./eval/metrics-store.js"; import { DedupMap } from "./functions/dedup.js"; import { registerHealthMonitor } from "./health/monitor.js"; @@ -520,6 +521,9 @@ async function main() { bootLog( `REST API: 128 endpoints at http://localhost:${config.restPort}/agentmemory/*`, ); + bootLog( + `MCP Stream HTTP: http://localhost:${config.mcpPort}/mcp (JSON-RPC)`, + ); bootLog( `MCP surface (opt-in via \`npx @agentmemory/mcp\`): ${getAllTools().length} tools · 6 resources · 3 prompts`, ); @@ -533,6 +537,16 @@ async function main() { config.restPort, ); + const mcpServer = await startMcpStreamServer( + config.mcpPort, + sdk, + kv, + secret, + ); + bootLog( + `MCP Stream HTTP server started on port ${config.mcpPort}`, + ); + const autoForgetIntervalMs = parseInt(process.env.AUTO_FORGET_INTERVAL_MS || "3600000", 10); const consolidationIntervalMs = parseInt(process.env.CONSOLIDATION_INTERVAL_MS || "7200000", 10); @@ -595,6 +609,7 @@ async function main() { dedupMap.stop(); indexPersistence.stop(); await new Promise((resolve) => viewerServer.close(() => resolve())); + await mcpServer.shutdown(); await indexPersistence.save().catch((err) => { console.warn(`[agentmemory] Failed to save index on shutdown:`, err); }); diff --git a/src/mcp/handler.ts b/src/mcp/handler.ts new file mode 100644 index 0000000000..3127442090 --- /dev/null +++ b/src/mcp/handler.ts @@ -0,0 +1,442 @@ +import type { ISdk } from "iii-sdk"; +import { InMemoryKV } from "./in-memory-kv.js"; +import { getAllTools } from "./tools-registry.js"; +import { VERSION } from "../version.js"; +import { generateId } from "../state/schema.js"; +import { + resolveHandle, + invalidateHandle, + type Handle, + type ProxyHandle, +} from "./rest-proxy.js"; + +const IMPLEMENTED_TOOLS = new Set([ + "memory_save", + "memory_recall", + "memory_smart_search", + "memory_sessions", + "memory_export", + "memory_audit", + "memory_governance_delete", +]); + +let modeAnnounced = false; + +// Match the literal-placeholder guard in rest-proxy.ts so log lines +// don't show `${AGENTMEMORY_URL}` when an MCP host passed the +// placeholder through unexpanded. +function displayAgentmemoryUrl(): string { + const raw = process.env["AGENTMEMORY_URL"]; + if (!raw || (raw.startsWith("${") && raw.endsWith("}"))) { + return "http://localhost:3111"; + } + return raw; +} + +function announceMode(handle: Handle): void { + if (modeAnnounced) return; + modeAnnounced = true; + if (handle.mode === "proxy") { + process.stderr.write( + `[@agentmemory/mcp] proxying to agentmemory server at ${handle.baseUrl}\n`, + ); + } else { + const fullToolCount = getAllTools().length; + process.stderr.write( + `[@agentmemory/mcp] no server reachable at ${displayAgentmemoryUrl()}; running reduced LOCAL FALLBACK with ${IMPLEMENTED_TOOLS.size} of ${fullToolCount} tools. Start 'npx @agentmemory/agentmemory' (and point AGENTMEMORY_URL at it) to unlock all ${fullToolCount} tools.\n`, + ); + } +} + +function normalizeList(value: unknown): string[] { + if (!value) return []; + if (Array.isArray(value)) { + return value + .map((v) => (typeof v === "string" ? v.trim() : "")) + .filter((v) => v.length > 0); + } + if (typeof value === "string") { + return value + .split(",") + .map((s) => s.trim()) + .filter((s) => s.length > 0); + } + return []; +} + +const DEFAULT_LIMIT = 10; +const MAX_LIMIT = 100; +function parseLimit(raw: unknown, fallback = DEFAULT_LIMIT): number { + if (typeof raw !== "number" && typeof raw !== "string") return fallback; + const n = Number(raw); + if (!Number.isFinite(n) || n <= 0) return fallback; + return Math.min(Math.floor(n), MAX_LIMIT); +} + +function textResponse(payload: unknown, pretty = false): { + content: Array<{ type: string; text: string }>; +} { + return { + content: [ + { type: "text", text: JSON.stringify(payload, null, pretty ? 2 : 0) }, + ], + }; +} + +interface Validated { + tool: string; + content?: string; + type?: string; + concepts?: string[]; + files?: string[]; + query?: string; + limit?: number; + format?: string; + tokenBudget?: number; + memoryIds?: string[]; + reason?: string; +} + +function validate(toolName: string, args: Record): Validated { + if (!IMPLEMENTED_TOOLS.has(toolName)) { + throw new Error(`Unknown tool: ${toolName}`); + } + const v: Validated = { tool: toolName }; + switch (toolName) { + case "memory_save": { + const content = args["content"]; + if (typeof content !== "string" || !content.trim()) { + throw new Error("content is required"); + } + v.content = content; + v.type = (args["type"] as string) || "fact"; + v.concepts = normalizeList(args["concepts"]); + v.files = normalizeList(args["files"]); + return v; + } + case "memory_recall": + case "memory_smart_search": { + const query = args["query"]; + if (typeof query !== "string" || !query.trim()) { + throw new Error("query is required"); + } + v.query = query.trim(); + v.limit = parseLimit(args["limit"]); + const fmt = args["format"]; + if (typeof fmt === "string" && fmt.trim()) { + v.format = fmt.trim().toLowerCase(); + } + const budget = args["token_budget"]; + if (typeof budget === "number" && Number.isFinite(budget) && budget > 0) { + v.tokenBudget = Math.floor(budget); + } else if (typeof budget === "string" && budget.trim()) { + const n = Number(budget); + if (Number.isFinite(n) && n > 0) v.tokenBudget = Math.floor(n); + } + return v; + } + case "memory_sessions": { + v.limit = parseLimit(args["limit"], 20); + return v; + } + case "memory_governance_delete": { + const ids = normalizeList(args["memoryIds"]); + if (ids.length === 0) throw new Error("memoryIds is required"); + v.memoryIds = ids; + v.reason = (args["reason"] as string) || "plugin skill request"; + return v; + } + case "memory_export": + return v; + case "memory_audit": { + v.limit = parseLimit(args["limit"], 50); + return v; + } + default: + throw new Error(`Unknown tool: ${toolName}`); + } +} + +async function handleProxy( + v: Validated, + handle: ProxyHandle, +): Promise<{ content: Array<{ type: string; text: string }> }> { + switch (v.tool) { + case "memory_save": { + const result = await handle.call("/agentmemory/remember", { + method: "POST", + body: JSON.stringify({ + content: v.content, + type: v.type, + concepts: v.concepts, + files: v.files, + }), + }); + return textResponse(result); + } + case "memory_recall": { + const body: Record = { + query: v.query, + limit: v.limit, + format: v.format ?? "full", + }; + if (v.tokenBudget != null) body["token_budget"] = v.tokenBudget; + const result = await handle.call("/agentmemory/search", { + method: "POST", + body: JSON.stringify(body), + }); + return textResponse(result, true); + } + case "memory_smart_search": { + const body: Record = { query: v.query, limit: v.limit }; + if (v.format != null) body["format"] = v.format; + if (v.tokenBudget != null) body["token_budget"] = v.tokenBudget; + const result = await handle.call("/agentmemory/smart-search", { + method: "POST", + body: JSON.stringify(body), + }); + return textResponse(result, true); + } + case "memory_sessions": { + const result = await handle.call( + `/agentmemory/sessions?limit=${v.limit}`, + { method: "GET" }, + ); + return textResponse(result, true); + } + case "memory_governance_delete": { + const result = await handle.call("/agentmemory/governance/memories", { + method: "DELETE", + body: JSON.stringify({ memoryIds: v.memoryIds, reason: v.reason }), + }); + return textResponse(result); + } + case "memory_export": { + const result = await handle.call("/agentmemory/export", { method: "GET" }); + return textResponse(result, true); + } + case "memory_audit": { + const result = await handle.call( + `/agentmemory/audit?limit=${v.limit}`, + { method: "GET" }, + ); + return textResponse(result, true); + } + default: + throw new Error(`Unknown tool: ${v.tool}`); + } +} + +async function handleLocal( + v: Validated, + kvInstance: InMemoryKV, +): Promise<{ content: Array<{ type: string; text: string }> }> { + switch (v.tool) { + case "memory_save": { + const id = generateId("mem"); + const isoNow = new Date().toISOString(); + await kvInstance.set("mem:memories", id, { + id, + type: v.type, + title: (v.content || "").slice(0, 80), + content: v.content, + concepts: v.concepts, + files: v.files, + createdAt: isoNow, + updatedAt: isoNow, + strength: 7, + version: 1, + isLatest: true, + sessionIds: [], + }); + kvInstance.persist(); + return textResponse({ saved: id }); + } + + case "memory_recall": + case "memory_smart_search": { + const query = (v.query || "").toLowerCase(); + const limit = v.limit ?? DEFAULT_LIMIT; + const all = + await kvInstance.list>("mem:memories"); + const results = all + .filter((m) => { + const text = [ + typeof m["title"] === "string" ? m["title"] : "", + typeof m["content"] === "string" ? m["content"] : "", + Array.isArray(m["files"]) ? m["files"].join(" ") : "", + Array.isArray(m["concepts"]) ? m["concepts"].join(" ") : "", + Array.isArray(m["sessionIds"]) ? m["sessionIds"].join(" ") : "", + typeof m["id"] === "string" ? m["id"] : "", + ] + .join(" ") + .toLowerCase(); + return query.split(/\s+/).every((word) => text.includes(word)); + }) + .slice(0, limit); + return textResponse({ mode: "compact", results }, true); + } + + case "memory_sessions": { + const sessions = + await kvInstance.list>("mem:sessions"); + const limit = v.limit ?? 20; + return textResponse({ sessions: sessions.slice(0, limit) }, true); + } + + case "memory_governance_delete": { + let deleted = 0; + for (const id of v.memoryIds || []) { + const existing = await kvInstance.get("mem:memories", id); + if (existing) { + await kvInstance.delete("mem:memories", id); + deleted++; + } + } + kvInstance.persist(); + return textResponse({ + deleted, + requested: (v.memoryIds || []).length, + reason: v.reason, + }); + } + + case "memory_export": { + const memories = await kvInstance.list("mem:memories"); + const sessions = await kvInstance.list("mem:sessions"); + return textResponse({ version: VERSION, memories, sessions }, true); + } + + case "memory_audit": { + const entries = await kvInstance.list("mem:audit"); + const limit = v.limit ?? 50; + return textResponse( + { + entries: (entries as Array>).slice(0, limit), + }, + true, + ); + } + + default: + throw new Error(`Unknown tool: ${v.tool}`); + } +} + +// Forward to the server's full MCP surface so non-Claude clients can +// reach all 53 tools (lessons, sentinels, slots, signals, graph, …) +// instead of being capped at the 7 IMPLEMENTED_TOOLS set baked into +// this shim. The server validates arguments per tool. +async function handleProxyGeneric( + toolName: string, + args: Record, + handle: ProxyHandle, +): Promise<{ content: Array<{ type: string; text: string }> }> { + const result = (await handle.call("/agentmemory/mcp/call", { + method: "POST", + body: JSON.stringify({ name: toolName, arguments: args }), + })) as { content?: Array<{ type: string; text: string }> } | null; + if (result && Array.isArray(result.content)) { + return { content: result.content }; + } + return textResponse(result, true); +} + +export async function handleToolCall( + toolName: string, + args: Record, + _sdk: ISdk | null, + kvInstance: InMemoryKV, + _config?: Record, +): Promise<{ content: Array<{ type: string; text: string }> }> { + const handle = await resolveHandle(); + announceMode(handle); + + // Tools the local InMemoryKV fallback doesn't implement: forward straight + // to the server. Local validation would otherwise raise "Unknown tool" + // (issue #234). + if (!IMPLEMENTED_TOOLS.has(toolName)) { + if (handle.mode === "proxy") { + try { + return await handleProxyGeneric(toolName, args, handle); + } catch (err) { + process.stderr.write( + `[@agentmemory/mcp] proxy call failed for ${toolName}: ${err instanceof Error ? err.message : String(err)}\n`, + ); + invalidateHandle(); + throw err; + } + } + throw new Error( + `Unknown tool: ${toolName} (local fallback supports only ${[...IMPLEMENTED_TOOLS].join(", ")}; start an agentmemory server and set AGENTMEMORY_URL to use the full tool set)`, + ); + } + + const validated = validate(toolName, args); + if (handle.mode === "proxy") { + try { + return await handleProxy(validated, handle); + } catch (err) { + process.stderr.write( + `[@agentmemory/mcp] proxy call failed for ${toolName}: ${err instanceof Error ? err.message : String(err)}; invalidating handle and falling back to local KV\n`, + ); + invalidateHandle(); + } + } + return handleLocal(validated, kvInstance); +} + +export async function handleToolsList( + _sdk: ISdk | null, + _kv: InMemoryKV, + _config?: Record, +): Promise<{ tools: unknown[] }> { + const debug = process.env["AGENTMEMORY_DEBUG"] === "1" || process.env["AGENTMEMORY_DEBUG"] === "true"; + const handle = await resolveHandle(); + announceMode(handle); + if (debug) { + process.stderr.write( + `[@agentmemory/mcp] tools/list: handle.mode=${handle.mode}${handle.mode === "proxy" ? ` baseUrl=${handle.baseUrl}` : ""}\n`, + ); + } + if (handle.mode === "proxy") { + try { + const remote = (await handle.call("/agentmemory/mcp/tools", { + method: "GET", + })) as { tools?: unknown } | null; + if (debug) { + const shape = remote === null + ? "null" + : typeof remote !== "object" + ? typeof remote + : `keys=${Object.keys(remote as object).join(",")} toolsType=${Array.isArray((remote as { tools?: unknown }).tools) ? `array(len=${((remote as { tools: unknown[] }).tools).length})` : typeof (remote as { tools?: unknown }).tools}`; + process.stderr.write( + `[@agentmemory/mcp] tools/list: remote response shape: ${shape}\n`, + ); + } + if (remote && Array.isArray(remote.tools)) { + if (debug) { + process.stderr.write( + `[@agentmemory/mcp] tools/list: returning ${remote.tools.length} tools from server\n`, + ); + } + return { tools: remote.tools }; + } + process.stderr.write( + `[@agentmemory/mcp] tools/list: server returned unexpected shape (no .tools array); falling back to local IMPLEMENTED_TOOLS list. Set AGENTMEMORY_DEBUG=1 to inspect response.\n`, + ); + } catch (err) { + process.stderr.write( + `[@agentmemory/mcp] tools/list proxy failed: ${err instanceof Error ? err.message : String(err)}; falling back to local list\n`, + ); + invalidateHandle(); + } + } + const fallback = getAllTools().filter((t) => IMPLEMENTED_TOOLS.has(t.name)); + if (debug) { + process.stderr.write( + `[@agentmemory/mcp] tools/list: returning ${fallback.length} local fallback tools (${fallback.map((t) => t.name).join(",")})\n`, + ); + } + return { tools: fallback }; +} diff --git a/src/mcp/standalone.ts b/src/mcp/standalone.ts index dd66ecb1dd..16b3895e89 100644 --- a/src/mcp/standalone.ts +++ b/src/mcp/standalone.ts @@ -2,26 +2,9 @@ import { InMemoryKV } from "./in-memory-kv.js"; import { createStdioTransport } from "./transport.js"; -import { getAllTools } from "./tools-registry.js"; import { getStandalonePersistPath } from "../config.js"; import { VERSION } from "../version.js"; -import { generateId } from "../state/schema.js"; -import { - resolveHandle, - invalidateHandle, - type Handle, - type ProxyHandle, -} from "./rest-proxy.js"; - -const IMPLEMENTED_TOOLS = new Set([ - "memory_save", - "memory_recall", - "memory_smart_search", - "memory_sessions", - "memory_export", - "memory_audit", - "memory_governance_delete", -]); +import { handleToolCall as handleToolCallImpl, handleToolsList as handleToolsListImpl } from "./handler.js"; const SERVER_INFO = { name: "agentmemory", @@ -30,419 +13,17 @@ const SERVER_INFO = { }; const kv = new InMemoryKV(getStandalonePersistPath()); -let modeAnnounced = false; - -function displayAgentmemoryUrl(): string { - // Match the literal-placeholder guard in rest-proxy.ts so log lines - // don't show `${AGENTMEMORY_URL}` when an MCP host passed the - // placeholder through unexpanded. - const raw = process.env["AGENTMEMORY_URL"]; - if (!raw || (raw.startsWith("${") && raw.endsWith("}"))) { - return "http://localhost:3111"; - } - return raw; -} - -function announceMode(handle: Handle): void { - if (modeAnnounced) return; - modeAnnounced = true; - if (handle.mode === "proxy") { - process.stderr.write( - `[@agentmemory/mcp] proxying to agentmemory server at ${handle.baseUrl}\n`, - ); - } else { - const fullToolCount = getAllTools().length; - process.stderr.write( - `[@agentmemory/mcp] no server reachable at ${displayAgentmemoryUrl()}; running reduced LOCAL FALLBACK with ${IMPLEMENTED_TOOLS.size} of ${fullToolCount} tools. Start 'npx @agentmemory/agentmemory' (and point AGENTMEMORY_URL at it) to unlock all ${fullToolCount} tools.\n`, - ); - } -} - -function normalizeList(value: unknown): string[] { - if (!value) return []; - if (Array.isArray(value)) { - return value - .map((v) => (typeof v === "string" ? v.trim() : "")) - .filter((v) => v.length > 0); - } - if (typeof value === "string") { - return value - .split(",") - .map((s) => s.trim()) - .filter((s) => s.length > 0); - } - return []; -} - -const DEFAULT_LIMIT = 10; -const MAX_LIMIT = 100; -function parseLimit(raw: unknown, fallback = DEFAULT_LIMIT): number { - if (typeof raw !== "number" && typeof raw !== "string") return fallback; - const n = Number(raw); - if (!Number.isFinite(n) || n <= 0) return fallback; - return Math.min(Math.floor(n), MAX_LIMIT); -} - -function textResponse(payload: unknown, pretty = false): { - content: Array<{ type: string; text: string }>; -} { - return { - content: [ - { type: "text", text: JSON.stringify(payload, null, pretty ? 2 : 0) }, - ], - }; -} - -interface Validated { - tool: string; - content?: string; - type?: string; - concepts?: string[]; - files?: string[]; - query?: string; - limit?: number; - format?: string; - tokenBudget?: number; - memoryIds?: string[]; - reason?: string; -} - -function validate(toolName: string, args: Record): Validated { - if (!IMPLEMENTED_TOOLS.has(toolName)) { - throw new Error(`Unknown tool: ${toolName}`); - } - const v: Validated = { tool: toolName }; - switch (toolName) { - case "memory_save": { - const content = args["content"]; - if (typeof content !== "string" || !content.trim()) { - throw new Error("content is required"); - } - v.content = content; - v.type = (args["type"] as string) || "fact"; - v.concepts = normalizeList(args["concepts"]); - v.files = normalizeList(args["files"]); - return v; - } - case "memory_recall": - case "memory_smart_search": { - const query = args["query"]; - if (typeof query !== "string" || !query.trim()) { - throw new Error("query is required"); - } - v.query = query.trim(); - v.limit = parseLimit(args["limit"]); - const fmt = args["format"]; - if (typeof fmt === "string" && fmt.trim()) { - v.format = fmt.trim().toLowerCase(); - } - const budget = args["token_budget"]; - if (typeof budget === "number" && Number.isFinite(budget) && budget > 0) { - v.tokenBudget = Math.floor(budget); - } else if (typeof budget === "string" && budget.trim()) { - const n = Number(budget); - if (Number.isFinite(n) && n > 0) v.tokenBudget = Math.floor(n); - } - return v; - } - case "memory_sessions": { - v.limit = parseLimit(args["limit"], 20); - return v; - } - case "memory_governance_delete": { - const ids = normalizeList(args["memoryIds"]); - if (ids.length === 0) throw new Error("memoryIds is required"); - v.memoryIds = ids; - v.reason = (args["reason"] as string) || "plugin skill request"; - return v; - } - case "memory_export": - return v; - case "memory_audit": { - v.limit = parseLimit(args["limit"], 50); - return v; - } - default: - throw new Error(`Unknown tool: ${toolName}`); - } -} - -async function handleProxy( - v: Validated, - handle: ProxyHandle, -): Promise<{ content: Array<{ type: string; text: string }> }> { - switch (v.tool) { - case "memory_save": { - const result = await handle.call("/agentmemory/remember", { - method: "POST", - body: JSON.stringify({ - content: v.content, - type: v.type, - concepts: v.concepts, - files: v.files, - }), - }); - return textResponse(result); - } - case "memory_recall": { - const body: Record = { - query: v.query, - limit: v.limit, - format: v.format ?? "full", - }; - if (v.tokenBudget != null) body["token_budget"] = v.tokenBudget; - const result = await handle.call("/agentmemory/search", { - method: "POST", - body: JSON.stringify(body), - }); - return textResponse(result, true); - } - case "memory_smart_search": { - const body: Record = { query: v.query, limit: v.limit }; - if (v.format != null) body["format"] = v.format; - if (v.tokenBudget != null) body["token_budget"] = v.tokenBudget; - const result = await handle.call("/agentmemory/smart-search", { - method: "POST", - body: JSON.stringify(body), - }); - return textResponse(result, true); - } - case "memory_sessions": { - const result = await handle.call( - `/agentmemory/sessions?limit=${v.limit}`, - { method: "GET" }, - ); - return textResponse(result, true); - } - case "memory_governance_delete": { - const result = await handle.call("/agentmemory/governance/memories", { - method: "DELETE", - body: JSON.stringify({ memoryIds: v.memoryIds, reason: v.reason }), - }); - return textResponse(result); - } - case "memory_export": { - const result = await handle.call("/agentmemory/export", { method: "GET" }); - return textResponse(result, true); - } - case "memory_audit": { - const result = await handle.call( - `/agentmemory/audit?limit=${v.limit}`, - { method: "GET" }, - ); - return textResponse(result, true); - } - default: - throw new Error(`Unknown tool: ${v.tool}`); - } -} - -async function handleLocal( - v: Validated, - kvInstance: InMemoryKV, -): Promise<{ content: Array<{ type: string; text: string }> }> { - switch (v.tool) { - case "memory_save": { - const id = generateId("mem"); - const isoNow = new Date().toISOString(); - await kvInstance.set("mem:memories", id, { - id, - type: v.type, - title: (v.content || "").slice(0, 80), - content: v.content, - concepts: v.concepts, - files: v.files, - createdAt: isoNow, - updatedAt: isoNow, - strength: 7, - version: 1, - isLatest: true, - sessionIds: [], - }); - kvInstance.persist(); - return textResponse({ saved: id }); - } - - case "memory_recall": - case "memory_smart_search": { - const query = (v.query || "").toLowerCase(); - const limit = v.limit ?? DEFAULT_LIMIT; - const all = - await kvInstance.list>("mem:memories"); - const results = all - .filter((m) => { - const text = [ - typeof m["title"] === "string" ? m["title"] : "", - typeof m["content"] === "string" ? m["content"] : "", - Array.isArray(m["files"]) ? m["files"].join(" ") : "", - Array.isArray(m["concepts"]) ? m["concepts"].join(" ") : "", - Array.isArray(m["sessionIds"]) ? m["sessionIds"].join(" ") : "", - typeof m["id"] === "string" ? m["id"] : "", - ] - .join(" ") - .toLowerCase(); - return query.split(/\s+/).every((word) => text.includes(word)); - }) - .slice(0, limit); - return textResponse({ mode: "compact", results }, true); - } - - case "memory_sessions": { - const sessions = - await kvInstance.list>("mem:sessions"); - const limit = v.limit ?? 20; - return textResponse({ sessions: sessions.slice(0, limit) }, true); - } - - case "memory_governance_delete": { - let deleted = 0; - for (const id of v.memoryIds || []) { - const existing = await kvInstance.get("mem:memories", id); - if (existing) { - await kvInstance.delete("mem:memories", id); - deleted++; - } - } - kvInstance.persist(); - return textResponse({ - deleted, - requested: (v.memoryIds || []).length, - reason: v.reason, - }); - } - - case "memory_export": { - const memories = await kvInstance.list("mem:memories"); - const sessions = await kvInstance.list("mem:sessions"); - return textResponse({ version: VERSION, memories, sessions }, true); - } - - case "memory_audit": { - const entries = await kvInstance.list("mem:audit"); - const limit = v.limit ?? 50; - return textResponse( - { - entries: (entries as Array>).slice(0, limit), - }, - true, - ); - } - - default: - throw new Error(`Unknown tool: ${v.tool}`); - } -} - -async function handleProxyGeneric( - toolName: string, - args: Record, - handle: ProxyHandle, -): Promise<{ content: Array<{ type: string; text: string }> }> { - // Forward to the server's full MCP surface so non-Claude clients can - // reach all 53 tools (lessons, sentinels, slots, signals, graph, …) - // instead of being capped at the 7 IMPLEMENTED_TOOLS set baked into - // this shim. The server validates arguments per tool. - const result = (await handle.call("/agentmemory/mcp/call", { - method: "POST", - body: JSON.stringify({ name: toolName, arguments: args }), - })) as { content?: Array<{ type: string; text: string }> } | null; - if (result && Array.isArray(result.content)) { - return { content: result.content }; - } - return textResponse(result, true); -} export async function handleToolCall( toolName: string, args: Record, kvInstance: InMemoryKV = kv, ): Promise<{ content: Array<{ type: string; text: string }> }> { - const handle = await resolveHandle(); - announceMode(handle); - - // Tools the local InMemoryKV fallback doesn't implement: forward straight - // to the server. Local validation would otherwise raise "Unknown tool" - // (issue #234). - if (!IMPLEMENTED_TOOLS.has(toolName)) { - if (handle.mode === "proxy") { - try { - return await handleProxyGeneric(toolName, args, handle); - } catch (err) { - process.stderr.write( - `[@agentmemory/mcp] proxy call failed for ${toolName}: ${err instanceof Error ? err.message : String(err)}\n`, - ); - invalidateHandle(); - throw err; - } - } - throw new Error( - `Unknown tool: ${toolName} (local fallback supports only ${[...IMPLEMENTED_TOOLS].join(", ")}; start an agentmemory server and set AGENTMEMORY_URL to use the full tool set)`, - ); - } - - const validated = validate(toolName, args); - if (handle.mode === "proxy") { - try { - return await handleProxy(validated, handle); - } catch (err) { - process.stderr.write( - `[@agentmemory/mcp] proxy call failed for ${toolName}: ${err instanceof Error ? err.message : String(err)}; invalidating handle and falling back to local KV\n`, - ); - invalidateHandle(); - } - } - return handleLocal(validated, kvInstance); + return handleToolCallImpl(toolName, args, null, kvInstance); } export async function handleToolsList(): Promise<{ tools: unknown[] }> { - const debug = process.env["AGENTMEMORY_DEBUG"] === "1" || process.env["AGENTMEMORY_DEBUG"] === "true"; - const handle = await resolveHandle(); - announceMode(handle); - if (debug) { - process.stderr.write( - `[@agentmemory/mcp] tools/list: handle.mode=${handle.mode}${handle.mode === "proxy" ? ` baseUrl=${handle.baseUrl}` : ""}\n`, - ); - } - if (handle.mode === "proxy") { - try { - const remote = (await handle.call("/agentmemory/mcp/tools", { - method: "GET", - })) as { tools?: unknown } | null; - if (debug) { - const shape = remote === null - ? "null" - : typeof remote !== "object" - ? typeof remote - : `keys=${Object.keys(remote as object).join(",")} toolsType=${Array.isArray((remote as { tools?: unknown }).tools) ? `array(len=${((remote as { tools: unknown[] }).tools).length})` : typeof (remote as { tools?: unknown }).tools}`; - process.stderr.write( - `[@agentmemory/mcp] tools/list: remote response shape: ${shape}\n`, - ); - } - if (remote && Array.isArray(remote.tools)) { - if (debug) { - process.stderr.write( - `[@agentmemory/mcp] tools/list: returning ${remote.tools.length} tools from server\n`, - ); - } - return { tools: remote.tools }; - } - process.stderr.write( - `[@agentmemory/mcp] tools/list: server returned unexpected shape (no .tools array); falling back to local IMPLEMENTED_TOOLS list. Set AGENTMEMORY_DEBUG=1 to inspect response.\n`, - ); - } catch (err) { - process.stderr.write( - `[@agentmemory/mcp] tools/list proxy failed: ${err instanceof Error ? err.message : String(err)}; falling back to local list\n`, - ); - invalidateHandle(); - } - } - const fallback = getAllTools().filter((t) => IMPLEMENTED_TOOLS.has(t.name)); - if (debug) { - process.stderr.write( - `[@agentmemory/mcp] tools/list: returning ${fallback.length} local fallback tools (${fallback.map((t) => t.name).join(",")})\n`, - ); - } - return { tools: fallback }; + return handleToolsListImpl(null, kv); } const transport = createStdioTransport(async (method, params) => { diff --git a/src/mcp/stream-http.ts b/src/mcp/stream-http.ts new file mode 100644 index 0000000000..a51cf1e498 --- /dev/null +++ b/src/mcp/stream-http.ts @@ -0,0 +1,331 @@ +/** + * MCP Streamable HTTP transport — manual JSON-RPC implementation. + * + * We hand-roll JSON-RPC routing here instead of using the official + * `@modelcontextprotocol/sdk`'s `NodeStreamableHTTPServerTransport` because + * `handleRequest()` depends on `@hono/node-server`'s `getRequestListener()`, + * which has a known body-parsing bug: it may return an empty or truncated body + * for requests with `Transfer-Encoding: chunked` (common from MCP clients). + * + * Our manual approach gives us full control over body parsing, request + * validation, and error formatting while still complying with the MCP + * Streamable HTTP contract (protocolVersion "2025-03-26"). + * + * Observed in @modelcontextprotocol/node v2.0.0-alpha.2 with chunked transfer encoding. + */ + +import { createServer } from "node:http"; +import type { IncomingMessage, ServerResponse, Server } from "node:http"; +import { randomUUID } from "node:crypto"; +import { timingSafeCompare } from "../auth.js"; +import { handleToolsList, handleToolCall } from "./handler.js"; +import { VERSION } from "../version.js"; +import type { ISdk } from "iii-sdk"; +import type { InMemoryKV } from "./in-memory-kv.js"; + +const MAX_BODY_BYTES = 5 * 1024 * 1024; // 5 MB + +interface JsonRpcMessage { + jsonrpc: string; + id?: string | number | null; + method?: string; + params?: Record; + result?: unknown; + error?: { code: number; message: string; data?: unknown }; +} + +interface SessionEntry { + sessionId: string; + createdAt: Date; + lastUsedAt: Date; +} + +function readBody(req: IncomingMessage): Promise { + return new Promise((resolve, reject) => { + const chunks: Buffer[] = []; + let total = 0; + req.on("data", (chunk: Buffer) => { + const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk); + total += buf.length; + if (total > MAX_BODY_BYTES) { + req.destroy(); + reject(new BodyTooLargeError()); + return; + } + chunks.push(buf); + }); + req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8"))); + req.on("error", reject); + }); +} + +class BodyTooLargeError extends Error { + constructor() { + super("Payload Too Large"); + this.name = "BodyTooLargeError"; + } +} + +function sendJson( + res: ServerResponse, + status: number, + body: unknown, + extraHeaders?: Record, +): void { + const json = JSON.stringify(body); + const headers: Record = { + "Content-Type": "application/json", + "Content-Length": String(Buffer.byteLength(json)), + ...extraHeaders, + }; + res.writeHead(status, headers); + res.end(json); +} + +function errorResponse( + id: string | number | null, + code: number, + message: string, +): JsonRpcMessage { + return { + jsonrpc: "2.0", + id, + error: { code, message }, + }; +} + +/** + * Start the MCP Streamable HTTP server. + * + * Returns the http.Server, the sessions map, and a `shutdown` function. + * Call `shutdown()` to close the server and clear the eviction timer. + */ +export async function startMcpStreamServer( + port: number, + sdk: ISdk | null, + kv: InMemoryKV, + secret?: string, +): Promise<{ + server: Server; + transports: Map; + shutdown: () => Promise; +}> { + const sessions = new Map(); + + // --- periodic eviction of idle sessions (every 10 minutes) --- + const SESSION_IDLE_TTL_MS = 60 * 60 * 1000; // 1 hour + const evictionTimer = setInterval(() => { + const cutoff = Date.now() - SESSION_IDLE_TTL_MS; + for (const [id, entry] of sessions) { + if (entry.lastUsedAt.getTime() < cutoff) { + sessions.delete(id); + } + } + }, 10 * 60 * 1000).unref(); + + const server = createServer(async (req, res) => { + try { + // --- HTTP method validation --- + if (req.method !== "POST" && req.method !== "DELETE") { + res.writeHead(405, { Allow: "POST, DELETE" }); + res.end(JSON.stringify(errorResponse(null, -32000, "Method Not Allowed"))); + return; + } + + // --- Content-Type validation --- + if (req.method === "POST") { + const contentType = (req.headers["content-type"] || "").split(";")[0].trim(); + if (contentType !== "application/json") { + sendJson(res, 415, errorResponse(null, -32000, "Unsupported Media Type: expected application/json")); + return; + } + } + + if (secret) { + const auth = + req.headers["authorization"] || req.headers["Authorization"]; + if ( + typeof auth !== "string" || + !timingSafeCompare(auth, `Bearer ${secret}`) + ) { + sendJson(res, 401, errorResponse(null, -32001, "Unauthorized")); + return; + } + } + + if (req.method === "DELETE") { + const sessionId = req.headers["mcp-session-id"] as string | undefined; + if (sessionId) { + sessions.delete(sessionId); + } + res.writeHead(200); + res.end(); + return; + } + + let bodyStr: string; + try { + bodyStr = await readBody(req); + } catch (err) { + if (err instanceof BodyTooLargeError) { + // Safety guard: readBody() always rejects before any response is sent, + // so headersSent is always false here under normal flow. + if (!res.headersSent) { + res.writeHead(413, { "Content-Type": "text/plain" }); + res.end("Payload Too Large"); + } + } else { + sendJson(res, 500, errorResponse(null, -32603, "Internal error")); + } + return; + } + + let msg: JsonRpcMessage; + try { + msg = JSON.parse(bodyStr); + } catch { + sendJson(res, 400, errorResponse(null, -32700, "Parse error")); + return; + } + + if (!msg || typeof msg.jsonrpc !== "string") { + sendJson(res, 400, errorResponse(null, -32600, "Invalid Request")); + return; + } + + const sessionIdHeader = req.headers["mcp-session-id"] as string | undefined; + + const isInitialize = msg.method === "initialize"; + const isNotification = + msg.id === undefined || msg.id === null; + + if (isNotification) { + res.writeHead(202); + res.end(); + return; + } + + if (!isInitialize && !sessionIdHeader) { + sendJson( + res, + 400, + errorResponse(msg.id ?? null, -32000, "Bad Request: Mcp-Session-Id header is required"), + ); + return; + } + + if (!isInitialize && sessionIdHeader && !sessions.has(sessionIdHeader)) { + sendJson( + res, + 400, + errorResponse(msg.id ?? null, -32000, "Session not found"), + ); + return; + } + + // Bump last-used timestamp for valid session + if (sessionIdHeader && sessions.has(sessionIdHeader)) { + sessions.get(sessionIdHeader)!.lastUsedAt = new Date(); + } + + switch (msg.method) { + case "initialize": { + const sessionId = randomUUID(); + const now = new Date(); + const response: JsonRpcMessage = { + jsonrpc: "2.0", + id: msg.id ?? null, + result: { + protocolVersion: "2025-03-26", + capabilities: { tools: {} }, + serverInfo: { + name: "agentmemory", + version: VERSION, + }, + }, + }; + sessions.set(sessionId, { sessionId, createdAt: now, lastUsedAt: now }); + sendJson(res, 200, response, { "Mcp-Session-Id": sessionId }); + break; + } + + case "tools/list": { + const result = await handleToolsList(sdk, kv); + sendJson(res, 200, { + jsonrpc: "2.0", + id: msg.id ?? null, + result, + }); + break; + } + + case "tools/call": { + const params = msg.params; + if (!params || typeof params.name !== "string") { + sendJson( + res, + 200, + errorResponse(msg.id ?? null, -32602, "Invalid params: name is required"), + ); + return; + } + const toolName = params.name as string; + const args = (params.arguments as Record) || {}; + try { + const result = await handleToolCall(toolName, args, sdk, kv); + sendJson(res, 200, { + jsonrpc: "2.0", + id: msg.id ?? null, + result, + }); + } catch (err) { + sendJson( + res, + 200, + errorResponse( + msg.id ?? null, + -32603, + err instanceof Error ? err.message : "Internal error", + ), + ); + } + break; + } + + default: + sendJson( + res, + 200, + errorResponse( + msg.id ?? null, + -32601, + `Method not found: ${msg.method || "unknown"}`, + ), + ); + break; + } + } catch (err) { + if (!res.headersSent) { + sendJson(res, 500, { + jsonrpc: "2.0", + id: null, + error: { + code: -32603, + message: err instanceof Error ? err.message : "Internal error", + }, + }); + } + } + }); + + await new Promise((resolve) => server.listen(port, "0.0.0.0", resolve)); + + const shutdown = async (): Promise => { + clearInterval(evictionTimer); + await new Promise((resolve, reject) => { + server.close((err) => (err ? reject(err) : resolve())); + }); + }; + + return { server, transports: sessions, shutdown }; +} diff --git a/src/providers/embedding/index.ts b/src/providers/embedding/index.ts index d18de23283..58f48a9fe8 100644 --- a/src/providers/embedding/index.ts +++ b/src/providers/embedding/index.ts @@ -35,7 +35,7 @@ export function createEmbeddingProvider(): EmbeddingProvider | null { case "gemini": return withDimensionGuard(new GeminiEmbeddingProvider(getEnvVar("GEMINI_API_KEY")!)); case "openai": - return withDimensionGuard(new OpenAIEmbeddingProvider(getEnvVar("OPENAI_API_KEY")!)); + return withDimensionGuard(new OpenAIEmbeddingProvider()); case "voyage": return withDimensionGuard(new VoyageEmbeddingProvider(getEnvVar("VOYAGE_API_KEY")!)); case "cohere": diff --git a/src/types.ts b/src/types.ts index 6797dfaf99..d27ca6b482 100644 --- a/src/types.ts +++ b/src/types.ts @@ -160,6 +160,8 @@ export interface AgentMemoryConfig { engineUrl: string; restPort: number; streamsPort: number; + /** MCP Streamable HTTP port — defaults to restPort + 3 (3114) */ + mcpPort: number; provider: ProviderConfig; tokenBudget: number; maxObservationsPerSession: number; diff --git a/src/viewer/server.ts b/src/viewer/server.ts index c80e67f0af..cdfec5def5 100644 --- a/src/viewer/server.ts +++ b/src/viewer/server.ts @@ -400,7 +400,7 @@ async function proxyToRestApi( ? pathname : `/agentmemory${pathname.startsWith("/") ? pathname : "/" + pathname}`; - const upstreamUrl = `http://127.0.0.1:${restPort}${upstreamPath}${qs ? "?" + qs : ""}`; + const upstreamUrl = `http://${process.env.AGENTMEMORY_REST_HOST || "127.0.0.1"}:${restPort}${upstreamPath}${qs ? "?" + qs : ""}`; const headers: Record = {}; if (secret) { diff --git a/test/mcp-stream-http.test.ts b/test/mcp-stream-http.test.ts new file mode 100644 index 0000000000..42144cac30 --- /dev/null +++ b/test/mcp-stream-http.test.ts @@ -0,0 +1,937 @@ +import { describe, it, expect, beforeEach, afterEach, vi } from "vitest"; +import * as http from "node:http"; + +vi.mock("../src/mcp/rest-proxy.js", () => ({ + resolveHandle: vi.fn(async () => ({ mode: "local", kv: new (await import("../src/mcp/in-memory-kv.js")).InMemoryKV() })), + invalidateHandle: vi.fn(), + setLivezProbe: vi.fn(), + resetHandleForTests: vi.fn(), +})); + +vi.mock("../src/logger.js", () => ({ + logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() }, + bootLog: vi.fn(), +})); + +import { InMemoryKV } from "../src/mcp/in-memory-kv.js"; +import { startMcpStreamServer } from "../src/mcp/stream-http.js"; +import type { Server } from "node:http"; + +const MCP_ACCEPT = "application/json, text/event-stream"; + +function jsonBody(data: unknown): string { + return JSON.stringify(data); +} + +async function httpPost( + port: number, + body: unknown, + headers: Record = {}, +): Promise<{ status: number; headers: http.IncomingHttpHeaders; body: unknown }> { + return new Promise((resolve, reject) => { + const bodyStr = typeof body === "string" ? body : jsonBody(body); + const opts: http.RequestOptions = { + hostname: "127.0.0.1", + port, + method: "POST", + headers: { + "Content-Type": "application/json", + "Accept": MCP_ACCEPT, + "Content-Length": String(Buffer.byteLength(bodyStr)), + ...headers, + }, + }; + const req = http.request(opts, (res) => { + let data = ""; + res.on("data", (chunk) => (data += chunk)); + res.on("end", () => { + try { + const parsed = data.length > 0 ? JSON.parse(data) : null; + resolve({ + status: res.statusCode ?? 0, + headers: res.headers, + body: parsed, + }); + } catch { + resolve({ + status: res.statusCode ?? 0, + headers: res.headers, + body: data, + }); + } + }); + }); + req.on("error", reject); + req.write(bodyStr); + req.end(); + }); +} + +function freePort(): Promise { + return new Promise((resolve, reject) => { + const srv = http.createServer(); + srv.listen(0, "127.0.0.1", () => { + const addr = srv.address(); + const port = typeof addr === "object" && addr ? addr.port : 0; + srv.close(() => resolve(port)); + }); + srv.on("error", reject); + }); +} + +describe("MCP Stream HTTP (T010-T015)", () => { + let server: Server; + let httpPort: number; + let transports: Map; + + beforeEach(async () => { + vi.clearAllMocks(); + }); + + afterEach(async () => { + if (server) { + await new Promise((resolve) => server.close(() => resolve())); + } + }); + + async function startServer(secret?: string) { + httpPort = await freePort(); + const kv = new InMemoryKV(); + const mockSdk = { + trigger: vi.fn(async () => ({})), + registerFunction: vi.fn(), + registerTrigger: vi.fn(), + shutdown: vi.fn(), + }; + const result = await startMcpStreamServer(httpPort, mockSdk as any, kv as any, secret); + server = result.server as unknown as Server; + transports = result.transports as unknown as Map; + } + + // T010 + describe("initialize over HTTP", () => { + it("returns protocolVersion, capabilities, serverInfo, and Mcp-Session-Id header", async () => { + await startServer(); + const res = await httpPost(httpPort, { + jsonrpc: "2.0", + id: 1, + method: "initialize", + params: { + protocolVersion: "2025-03-26", + capabilities: {}, + clientInfo: { name: "test-client", version: "1.0" }, + }, + }); + + expect(res.status).toBe(200); + const body = res.body as Record; + expect(body.jsonrpc).toBe("2.0"); + expect(body.id).toBe(1); + expect(body.result).toBeDefined(); + expect((body.result as Record).protocolVersion).toBe("2025-03-26"); + expect((body.result as Record).capabilities).toEqual({ tools: {} }); + expect((body.result as Record).serverInfo).toBeDefined(); + const serverInfo = (body.result as Record).serverInfo as Record; + expect(serverInfo.name).toBe("agentmemory"); + expect(typeof serverInfo.version).toBe("string"); + expect(res.headers["mcp-session-id"]).toBeDefined(); + expect(typeof res.headers["mcp-session-id"]).toBe("string"); + }); + + it("rejects initialize without protocolVersion gracefully", async () => { + await startServer(); + const res = await httpPost(httpPort, { + jsonrpc: "2.0", + id: 1, + method: "initialize", + params: {}, + }); + + expect(res.status).toBe(200); + const body = res.body as Record; + expect(body.result).toBeDefined(); + }); + + it("handles multiple concurrent initialize requests generating distinct sessions", async () => { + await startServer(); + + const [r1, r2] = await Promise.all([ + httpPost(httpPort, { jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "a", version: "1" } } }), + httpPost(httpPort, { jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "b", version: "1" } } }), + ]); + + expect(r1.status).toBe(200); + expect(r2.status).toBe(200); + expect(r1.headers["mcp-session-id"]).toBeDefined(); + expect(r2.headers["mcp-session-id"]).toBeDefined(); + expect(r1.headers["mcp-session-id"]).not.toBe(r2.headers["mcp-session-id"]); + }); + }); + + // T011 + describe("tools/list over HTTP", () => { + it("returns tools list with correct count when AGENTMEMORY_TOOLS=all", async () => { + process.env["AGENTMEMORY_TOOLS"] = "all"; + await startServer(); + + const initRes = await httpPost(httpPort, { + jsonrpc: "2.0", + id: 1, + method: "initialize", + params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "test", version: "1.0" } }, + }); + const sessionId = initRes.headers["mcp-session-id"] as string; + expect(sessionId).toBeDefined(); + + const res = await httpPost( + httpPort, + { jsonrpc: "2.0", id: 2, method: "tools/list", params: {} }, + { "Mcp-Session-Id": sessionId }, + ); + + expect(res.status).toBe(200); + const body = res.body as Record; + expect(body.result).toBeDefined(); + const result = body.result as Record; + expect(result.tools).toBeDefined(); + expect(Array.isArray(result.tools)).toBe(true); + const tools = result.tools as unknown[]; + // In test mode (local fallback), IMPLEMENTED_TOOLS returns 7 tools + // (production connected to engine returns all 53) + expect(tools.length).toBeGreaterThanOrEqual(7); + }); + + it("returns reduced tool set with AGENTMEMORY_TOOLS=core", async () => { + process.env["AGENTMEMORY_TOOLS"] = "core"; + await startServer(); + + const initRes = await httpPost(httpPort, { + jsonrpc: "2.0", + id: 1, + method: "initialize", + params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "test", version: "1.0" } }, + }); + const sessionId = initRes.headers["mcp-session-id"] as string; + + const res = await httpPost( + httpPort, + { jsonrpc: "2.0", id: 2, method: "tools/list", params: {} }, + { "Mcp-Session-Id": sessionId }, + ); + + const body = res.body as Record; + const result = body.result as Record; + const tools = result.tools as unknown[]; + // In test mode, IMPLEMENTED_TOOLS filter applies (7 tools) + expect(tools.length).toBeGreaterThan(0); + for (const tool of tools) { + const t = tool as Record; + expect(t.name).toBeDefined(); + expect(t.description).toBeDefined(); + expect(t.inputSchema).toBeDefined(); + } + }); + }); + + // T012 + describe("tools/call over HTTP", () => { + it("forwards tool call and returns content array", async () => { + process.env["AGENTMEMORY_TOOLS"] = "all"; + await startServer(); + + const initRes = await httpPost(httpPort, { + jsonrpc: "2.0", + id: 1, + method: "initialize", + params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "test", version: "1.0" } }, + }); + const sessionId = initRes.headers["mcp-session-id"] as string; + + const res = await httpPost( + httpPort, + { + jsonrpc: "2.0", + id: 3, + method: "tools/call", + params: { name: "memory_export", arguments: {} }, + }, + { "Mcp-Session-Id": sessionId }, + ); + + expect(res.status).toBe(200); + const body = res.body as Record; + expect(body.result).toBeDefined(); + const result = body.result as Record; + expect(result.content).toBeDefined(); + expect(Array.isArray(result.content)).toBe(true); + const content = result.content as Array<{ type: string; text: string }>; + expect(content.length).toBeGreaterThan(0); + expect(content[0].type).toBe("text"); + expect(typeof content[0].text).toBe("string"); + }); + + it("returns error for unknown tool", async () => { + process.env["AGENTMEMORY_TOOLS"] = "all"; + await startServer(); + + const initRes = await httpPost(httpPort, { + jsonrpc: "2.0", + id: 1, + method: "initialize", + params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "test", version: "1.0" } }, + }); + const sessionId = initRes.headers["mcp-session-id"] as string; + + const res = await httpPost( + httpPort, + { + jsonrpc: "2.0", + id: 4, + method: "tools/call", + params: { name: "nonexistent_tool", arguments: {} }, + }, + { "Mcp-Session-Id": sessionId }, + ); + + expect(res.status).toBe(200); + const body = res.body as Record; + expect(body.error).toBeDefined(); + }); + + it("returns error for missing tool name", async () => { + process.env["AGENTMEMORY_TOOLS"] = "all"; + await startServer(); + + const initRes = await httpPost(httpPort, { + jsonrpc: "2.0", + id: 1, + method: "initialize", + params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "test", version: "1.0" } }, + }); + const sessionId = initRes.headers["mcp-session-id"] as string; + + const res = await httpPost( + httpPort, + { jsonrpc: "2.0", id: 5, method: "tools/call", params: {} }, + { "Mcp-Session-Id": sessionId }, + ); + + expect(res.status).toBe(200); + const body = res.body as Record; + expect(body.error).toBeDefined(); + }); + }); + + // T013 + describe("Bearer auth", () => { + it("returns 401 without token when secret is set", async () => { + await startServer("test-secret"); + const res = await httpPost(httpPort, { + jsonrpc: "2.0", + id: 1, + method: "initialize", + params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "test", version: "1.0" } }, + }); + + expect(res.status).toBe(401); + const body = res.body as Record; + expect(body.error).toBeDefined(); + }); + + it("returns 401 with wrong token", async () => { + await startServer("test-secret"); + const res = await httpPost( + httpPort, + { + jsonrpc: "2.0", + id: 1, + method: "initialize", + params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "test", version: "1.0" } }, + }, + { Authorization: "Bearer wrong-token" }, + ); + + expect(res.status).toBe(401); + }); + + it("returns 200 with correct token", async () => { + await startServer("test-secret"); + const res = await httpPost( + httpPort, + { + jsonrpc: "2.0", + id: 1, + method: "initialize", + params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "test", version: "1.0" } }, + }, + { Authorization: "Bearer test-secret" }, + ); + + expect(res.status).toBe(200); + const body = res.body as Record; + expect(body.result).toBeDefined(); + }); + + it("skips auth when secret is undefined", async () => { + await startServer(undefined); + const res = await httpPost(httpPort, { + jsonrpc: "2.0", + id: 1, + method: "initialize", + params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "test", version: "1.0" } }, + }); + + expect(res.status).toBe(200); + const body = res.body as Record; + expect(body.result).toBeDefined(); + }); + + it("skips auth when secret is empty string", async () => { + await startServer(""); + const res = await httpPost(httpPort, { + jsonrpc: "2.0", + id: 1, + method: "initialize", + params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "test", version: "1.0" } }, + }); + + expect(res.status).toBe(200); + }); + }); + + // T014 + describe("JSON-RPC errors", () => { + it("returns parse error (-32700) for invalid JSON", async () => { + await startServer(); + const bodyStr = "not-valid-json{{{"; + const res = await new Promise<{ status: number; body: unknown }>((resolve, reject) => { + const req = http.request( + { + hostname: "127.0.0.1", + port: httpPort, + method: "POST", + headers: { + "Content-Type": "application/json", + "Accept": MCP_ACCEPT, + "Content-Length": String(Buffer.byteLength(bodyStr)), + }, + }, + (res) => { + let data = ""; + res.on("data", (chunk) => (data += chunk)); + res.on("end", () => { + try { + resolve({ status: res.statusCode ?? 0, body: JSON.parse(data) }); + } catch { + resolve({ status: res.statusCode ?? 0, body: data }); + } + }); + }, + ); + req.on("error", reject); + req.write(bodyStr); + req.end(); + }); + + expect(res.status).toBe(400); + const body = res.body as Record; + expect(body.error).toBeDefined(); + expect((body.error as Record).code).toBe(-32700); + }); + + it("returns method not found (-32601) for unknown methods", async () => { + await startServer(); + + // Initialize first to get a session + const initRes = await httpPost(httpPort, { + jsonrpc: "2.0", + id: 1, + method: "initialize", + params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "test", version: "1.0" } }, + }); + const sessionId = initRes.headers["mcp-session-id"] as string; + + const res = await httpPost( + httpPort, + { + jsonrpc: "2.0", + id: 2, + method: "unknown/method", + params: {}, + }, + { "Mcp-Session-Id": sessionId }, + ); + + const body = res.body as Record; + expect(body.error).toBeDefined(); + expect((body.error as Record).code).toBe(-32601); + }); + + it("returns invalid params (-32602) for tools/call without params", async () => { + process.env["AGENTMEMORY_TOOLS"] = "all"; + await startServer(); + + const initRes = await httpPost(httpPort, { + jsonrpc: "2.0", + id: 1, + method: "initialize", + params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "test", version: "1.0" } }, + }); + const sessionId = initRes.headers["mcp-session-id"] as string; + + const res = await httpPost( + httpPort, + { jsonrpc: "2.0", id: 12, method: "tools/call" }, + { "Mcp-Session-Id": sessionId }, + ); + + const body = res.body as Record; + expect(body.error).toBeDefined(); + expect((body.error as Record).code).toBe(-32602); + }); + }); + + // T015 + describe("session management", () => { + it("initialize creates a session with Mcp-Session-Id header", async () => { + await startServer(); + + const res = await httpPost(httpPort, { + jsonrpc: "2.0", + id: 1, + method: "initialize", + params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "test", version: "1.0" } }, + }); + + expect(res.status).toBe(200); + expect(res.headers["mcp-session-id"]).toBeDefined(); + const sessionId = res.headers["mcp-session-id"] as string; + expect(typeof sessionId).toBe("string"); + expect(sessionId.length).toBeGreaterThan(0); + }); + + it("reuses session via Mcp-Session-Id header for tools/list", async () => { + await startServer(); + + const initRes = await httpPost(httpPort, { + jsonrpc: "2.0", + id: 1, + method: "initialize", + params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "test", version: "1.0" } }, + }); + const sessionId = initRes.headers["mcp-session-id"] as string; + + const toolsRes = await httpPost( + httpPort, + { jsonrpc: "2.0", id: 2, method: "tools/list", params: {} }, + { "Mcp-Session-Id": sessionId }, + ); + + expect(toolsRes.status).toBe(200); + const body = toolsRes.body as Record; + expect(body.result).toBeDefined(); + }); + + it("rejects invalid session ID with error code -32000", async () => { + await startServer(); + + const res = await httpPost( + httpPort, + { jsonrpc: "2.0", id: 1, method: "tools/list", params: {} }, + { "Mcp-Session-Id": "invalid-nonexistent-session-id" }, + ); + + expect([400, 404]).toContain(res.status); + const body = res.body as Record; + if (body.error) { + expect((body.error as Record).code).toBe(-32000); + } + }); + + it("returns 400 for non-initialize requests without session ID", async () => { + await startServer(); + + const res = await httpPost(httpPort, { + jsonrpc: "2.0", + id: 1, + method: "tools/list", + params: {}, + }); + + expect(res.status).toBe(400); + }); + + it("multiple initialize creates separate sessions", async () => { + await startServer(); + + const r1 = await httpPost(httpPort, { + jsonrpc: "2.0", id: 1, method: "initialize", + params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "a", version: "1" } }, + }); + const r2 = await httpPost(httpPort, { + jsonrpc: "2.0", id: 1, method: "initialize", + params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "b", version: "1" } }, + }); + + const s1 = r1.headers["mcp-session-id"] as string; + const s2 = r2.headers["mcp-session-id"] as string; + + expect(s1).toBeDefined(); + expect(s2).toBeDefined(); + expect(s1).not.toBe(s2); + + // Both sessions should work independently + const t1 = await httpPost( + httpPort, + { jsonrpc: "2.0", id: 2, method: "tools/list", params: {} }, + { "Mcp-Session-Id": s1 }, + ); + const t2 = await httpPost( + httpPort, + { jsonrpc: "2.0", id: 2, method: "tools/list", params: {} }, + { "Mcp-Session-Id": s2 }, + ); + + expect(t1.status).toBe(200); + expect(t2.status).toBe(200); + }); + }); + + // T017 + describe("notification handling (T017)", () => { + it("handles initialized notification without response", async () => { + await startServer(); + + const initRes = await httpPost(httpPort, { + jsonrpc: "2.0", + id: 1, + method: "initialize", + params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "test", version: "1.0" } }, + }); + const sessionId = initRes.headers["mcp-session-id"] as string; + + // Send initialized notification (no id field) + const notifRes = await httpPost( + httpPort, + { + jsonrpc: "2.0", + method: "notifications/initialized", + params: {}, + }, + { "Mcp-Session-Id": sessionId }, + ); + + // Notifications should be accepted (200 or 202) + expect([200, 202]).toContain(notifRes.status); + }); + }); + + // T019 — HTTP request validation + describe("HTTP method validation", () => { + it("returns 405 for GET requests with Allow header", async () => { + await startServer(); + const res = await new Promise<{ status: number; headers: http.IncomingHttpHeaders; body: string }>((resolve, reject) => { + const req = http.get(`http://127.0.0.1:${httpPort}/`, (res) => { + let data = ""; + res.on("data", (chunk) => (data += chunk)); + res.on("end", () => resolve({ status: res.statusCode ?? 0, headers: res.headers, body: data })); + }); + req.on("error", reject); + }); + expect(res.status).toBe(405); + expect(res.headers["allow"]).toBe("POST, DELETE"); + }); + + it("returns 405 for OPTIONS requests", async () => { + await startServer(); + const res = await new Promise<{ status: number; body: unknown }>((resolve, reject) => { + const req = http.request( + { hostname: "127.0.0.1", port: httpPort, method: "OPTIONS" }, + (res) => { + let data = ""; + res.on("data", (chunk) => (data += chunk)); + res.on("end", () => { + try { + resolve({ status: res.statusCode ?? 0, body: JSON.parse(data) }); + } catch { + resolve({ status: res.statusCode ?? 0, body: data }); + } + }); + }, + ); + req.on("error", reject); + req.end(); + }); + expect(res.status).toBe(405); + }); + + it("returns 405 for HEAD requests", async () => { + await startServer(); + const res = await new Promise<{ status: number }>((resolve, reject) => { + const req = http.request( + { hostname: "127.0.0.1", port: httpPort, method: "HEAD" }, + (res) => { + res.resume(); + resolve({ status: res.statusCode ?? 0 }); + }, + ); + req.on("error", reject); + req.end(); + }); + expect(res.status).toBe(405); + }); + }); + + describe("Content-Type validation", () => { + it("returns 415 for text/plain content type", async () => { + await startServer(); + const bodyStr = JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize", params: {} }); + const res = await new Promise<{ status: number; body: unknown }>((resolve, reject) => { + const req = http.request( + { + hostname: "127.0.0.1", + port: httpPort, + method: "POST", + headers: { + "Content-Type": "text/plain", + "Content-Length": String(Buffer.byteLength(bodyStr)), + }, + }, + (res) => { + let data = ""; + res.on("data", (chunk) => (data += chunk)); + res.on("end", () => { + try { + resolve({ status: res.statusCode ?? 0, body: JSON.parse(data) }); + } catch { + resolve({ status: res.statusCode ?? 0, body: data }); + } + }); + }, + ); + req.on("error", reject); + req.write(bodyStr); + req.end(); + }); + expect(res.status).toBe(415); + }); + + it("returns 415 for multipart/form-data content type", async () => { + await startServer(); + const res = await new Promise<{ status: number; body: unknown }>((resolve, reject) => { + const req = http.request( + { + hostname: "127.0.0.1", + port: httpPort, + method: "POST", + headers: { "Content-Type": "multipart/form-data", "Content-Length": "0" }, + }, + (res) => { + let data = ""; + res.on("data", (chunk) => (data += chunk)); + res.on("end", () => { + try { + resolve({ status: res.statusCode ?? 0, body: JSON.parse(data) }); + } catch { + resolve({ status: res.statusCode ?? 0, body: data }); + } + }); + }, + ); + req.on("error", reject); + req.end(); + }); + expect(res.status).toBe(415); + }); + + it("returns 415 for missing Content-Type", async () => { + await startServer(); + const bodyStr = JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize", params: {} }); + const res = await new Promise<{ status: number; body: unknown }>((resolve, reject) => { + const req = http.request( + { + hostname: "127.0.0.1", + port: httpPort, + method: "POST", + headers: { "Content-Length": String(Buffer.byteLength(bodyStr)) }, + }, + (res) => { + let data = ""; + res.on("data", (chunk) => (data += chunk)); + res.on("end", () => { + try { + resolve({ status: res.statusCode ?? 0, body: JSON.parse(data) }); + } catch { + resolve({ status: res.statusCode ?? 0, body: data }); + } + }); + }, + ); + req.on("error", reject); + req.write(bodyStr); + req.end(); + }); + expect(res.status).toBe(415); + }); + + it("accepts application/json with charset parameter", async () => { + await startServer(); + const res = await httpPost(httpPort, { + jsonrpc: "2.0", + id: 1, + method: "initialize", + params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "test", version: "1.0" } }, + }); + // httpPost helper always sets Content-Type: application/json + expect(res.status).toBe(200); + }); + }); + + describe("body size limit", () => { + it("returns 413 for payload exceeding 5MB", async () => { + await startServer(); + // Create a payload larger than 5MB + const largeStr = "x".repeat(6 * 1024 * 1024); // 6 MB + const bodyStr = JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize", params: { data: largeStr } }); + const res = await new Promise<{ status: number }>((resolve, reject) => { + const req = http.request( + { + hostname: "127.0.0.1", + port: httpPort, + method: "POST", + headers: { + "Content-Type": "application/json", + "Content-Length": String(Buffer.byteLength(bodyStr)), + }, + }, + (res) => { + res.resume(); + resolve({ status: res.statusCode ?? 0 }); + }, + ); + req.on("error", (err) => { + // The server may destroy the connection on oversize + resolve({ status: 413 }); + }); + req.write(bodyStr); + req.end(); + }); + expect(res.status).toBe(413); + }); + + it("accepts payload under 5MB", async () => { + await startServer(); + const res = await httpPost(httpPort, { + jsonrpc: "2.0", + id: 1, + method: "initialize", + params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "test", version: "1.0" } }, + }); + expect(res.status).toBe(200); + }); + }); + + describe("DELETE request handling", () => { + it("returns 200 for DELETE requests", async () => { + await startServer(); + const res = await new Promise<{ status: number }>((resolve, reject) => { + const req = http.request( + { hostname: "127.0.0.1", port: httpPort, method: "DELETE" }, + (res) => { + res.resume(); + resolve({ status: res.statusCode ?? 0 }); + }, + ); + req.on("error", reject); + req.end(); + }); + expect(res.status).toBe(200); + }); + }); + + describe("session lastUsedAt tracking", () => { + it("updates lastUsedAt on each request with valid session", async () => { + await startServer(); + + const initRes = await httpPost(httpPort, { + jsonrpc: "2.0", + id: 1, + method: "initialize", + params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "test", version: "1.0" } }, + }); + const sessionId = initRes.headers["mcp-session-id"] as string; + expect(sessionId).toBeDefined(); + + const entry1 = transports.get(sessionId) as { lastUsedAt: Date } | undefined; + expect(entry1).toBeDefined(); + const firstLastUsed = entry1!.lastUsedAt.getTime(); + + // Small delay then another request + await new Promise((r) => setTimeout(r, 50)); + + await httpPost( + httpPort, + { jsonrpc: "2.0", id: 2, method: "tools/list", params: {} }, + { "Mcp-Session-Id": sessionId }, + ); + + const entry2 = transports.get(sessionId) as { lastUsedAt: Date } | undefined; + expect(entry2).toBeDefined(); + expect(entry2!.lastUsedAt.getTime()).toBeGreaterThan(firstLastUsed); + }); + + it("evicts sessions with lastUsedAt older than 1 hour", async () => { + vi.useFakeTimers(); + try { + await startServer(); + + // Create a session normally + const initRes = await httpPost(httpPort, { + jsonrpc: "2.0", + id: 1, + method: "initialize", + params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "test", version: "1.0" } }, + }); + const sessionId = initRes.headers["mcp-session-id"] as string; + expect(sessionId).toBeDefined(); + expect(transports.has(sessionId)).toBe(true); + + // Manually age the session's lastUsedAt to 2 hours ago + const entry = transports.get(sessionId) as { lastUsedAt: Date } | undefined; + expect(entry).toBeDefined(); + entry!.lastUsedAt = new Date(Date.now() - 2 * 60 * 60 * 1000); + + // Advance time past the eviction interval (10 min + 1ms) + vi.advanceTimersByTime(10 * 60 * 1000 + 1); + + // Session should be evicted + expect(transports.has(sessionId)).toBe(false); + } finally { + vi.useRealTimers(); + } + }); + + it("does not evict recently used sessions", async () => { + vi.useFakeTimers(); + try { + await startServer(); + + const initRes = await httpPost(httpPort, { + jsonrpc: "2.0", + id: 1, + method: "initialize", + params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "test", version: "1.0" } }, + }); + const sessionId = initRes.headers["mcp-session-id"] as string; + + // Advance time but keep session recent (under 1 hour idle) + vi.advanceTimersByTime(10 * 60 * 1000 + 1); + + // Session should still be alive (lastUsedAt is current) + expect(transports.has(sessionId)).toBe(true); + } finally { + vi.useRealTimers(); + } + }); + }); +}); diff --git a/test/mcp-transport-coexistence.test.ts b/test/mcp-transport-coexistence.test.ts new file mode 100644 index 0000000000..869f3cabfe --- /dev/null +++ b/test/mcp-transport-coexistence.test.ts @@ -0,0 +1,250 @@ +import { describe, it, expect, beforeEach, afterEach, vi } from "vitest"; +import * as http from "node:http"; + +vi.mock("../src/mcp/rest-proxy.js", () => ({ + resolveHandle: vi.fn(async () => ({ mode: "local", kv: new (await import("../src/mcp/in-memory-kv.js")).InMemoryKV() })), + invalidateHandle: vi.fn(), + setLivezProbe: vi.fn(), + resetHandleForTests: vi.fn(), +})); + +vi.mock("../src/logger.js", () => ({ + logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() }, + bootLog: vi.fn(), +})); + +import { InMemoryKV } from "../src/mcp/in-memory-kv.js"; +import { startMcpStreamServer } from "../src/mcp/stream-http.js"; +import { handleToolsList } from "../src/mcp/handler.js"; +import type { Server } from "node:http"; + +const MCP_ACCEPT = "application/json, text/event-stream"; + +async function httpPost( + port: number, + body: unknown, + headers: Record = {}, +): Promise<{ status: number; headers: http.IncomingHttpHeaders; body: unknown }> { + return new Promise((resolve, reject) => { + const bodyStr = JSON.stringify(body); + const opts: http.RequestOptions = { + hostname: "127.0.0.1", + port, + method: "POST", + headers: { + "Content-Type": "application/json", + "Accept": MCP_ACCEPT, + "Content-Length": String(Buffer.byteLength(bodyStr)), + ...headers, + }, + }; + const req = http.request(opts, (res) => { + let data = ""; + res.on("data", (chunk) => (data += chunk)); + res.on("end", () => { + try { + resolve({ + status: res.statusCode ?? 0, + headers: res.headers, + body: JSON.parse(data), + }); + } catch { + resolve({ + status: res.statusCode ?? 0, + headers: res.headers, + body: data, + }); + } + }); + }); + req.on("error", reject); + req.write(bodyStr); + req.end(); + }); +} + +function freePort(): Promise { + return new Promise((resolve, reject) => { + const srv = http.createServer(); + srv.listen(0, "127.0.0.1", () => { + const addr = srv.address(); + const port = typeof addr === "object" && addr ? addr.port : 0; + srv.close(() => resolve(port)); + }); + srv.on("error", reject); + }); +} + +describe("MCP Transport Coexistence (T016-T017)", () => { + let server: Server; + let httpPort: number; + let kv: InMemoryKV; + let mockSdk: any; + + beforeEach(async () => { + vi.clearAllMocks(); + process.env["AGENTMEMORY_TOOLS"] = "all"; + kv = new InMemoryKV(); + httpPort = await freePort(); + mockSdk = { + trigger: vi.fn(async () => ({})), + registerFunction: vi.fn(), + registerTrigger: vi.fn(), + shutdown: vi.fn(), + }; + const result = await startMcpStreamServer(httpPort, mockSdk as any, kv as any, undefined); + server = result.server as unknown as Server; + }); + + afterEach(async () => { + if (server) { + await new Promise((resolve) => server.close(() => resolve())); + } + }); + + // T016 + describe("identical tool sets", () => { + it("returns the same tool names via HTTP transport as handleToolsList()", async () => { + const initRes = await httpPost(httpPort, { + jsonrpc: "2.0", + id: 1, + method: "initialize", + params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "test", version: "1.0" } }, + }); + const sessionId = initRes.headers["mcp-session-id"] as string; + + const toolsRes = await httpPost( + httpPort, + { jsonrpc: "2.0", id: 2, method: "tools/list", params: {} }, + { "Mcp-Session-Id": sessionId }, + ); + + const body = toolsRes.body as Record; + const result = body.result as Record; + const httpTools = (result.tools as Array<{ name: string }>).map((t) => t.name).sort(); + + // Compare against what handleToolsList returns directly + const handlerResult = await handleToolsList(mockSdk, kv); + const handlerTools = (handlerResult.tools as Array<{ name: string }>).map((t) => t.name).sort(); + + expect(httpTools).toEqual(handlerTools); + expect(httpTools.length).toBe(handlerTools.length); + expect(httpTools.length).toBeGreaterThan(0); + }); + + it("returns consistent tool schemas via HTTP matching handleToolsList()", async () => { + const initRes = await httpPost(httpPort, { + jsonrpc: "2.0", + id: 1, + method: "initialize", + params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "test", version: "1.0" } }, + }); + const sessionId = initRes.headers["mcp-session-id"] as string; + + const toolsRes = await httpPost( + httpPort, + { jsonrpc: "2.0", id: 2, method: "tools/list", params: {} }, + { "Mcp-Session-Id": sessionId }, + ); + + const body = toolsRes.body as Record; + const httpTools = (body.result as Record).tools as Array>; + + const handlerResult = await handleToolsList(mockSdk, kv); + const handlerTools = handlerResult.tools as Array>; + + expect(httpTools.length).toBe(handlerTools.length); + + for (let i = 0; i < handlerTools.length; i++) { + const httpTool = httpTools[i]; + const handlerTool = handlerTools[i]; + expect(httpTool.name).toBe(handlerTool.name); + expect(httpTool.description).toBe(handlerTool.description); + expect(httpTool.inputSchema).toEqual(handlerTool.inputSchema); + } + }); + + it("returns identical results for the same tool call via HTTP transport", async () => { + const initRes = await httpPost(httpPort, { + jsonrpc: "2.0", + id: 1, + method: "initialize", + params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "test", version: "1.0" } }, + }); + const sessionId = initRes.headers["mcp-session-id"] as string; + + const res = await httpPost( + httpPort, + { + jsonrpc: "2.0", + id: 3, + method: "tools/call", + params: { name: "memory_export", arguments: {} }, + }, + { "Mcp-Session-Id": sessionId }, + ); + + expect(res.status).toBe(200); + const body = res.body as Record; + expect(body.result).toBeDefined(); + const result = body.result as Record; + expect(result.content).toBeDefined(); + expect(Array.isArray(result.content)).toBe(true); + const content = result.content as Array<{ type: string; text: string }>; + expect(content[0].type).toBe("text"); + + const parsed = JSON.parse(content[0].text); + expect(parsed).toBeDefined(); + expect(parsed.version).toBeDefined(); + expect(Array.isArray(parsed.memories)).toBe(true); + expect(Array.isArray(parsed.sessions)).toBe(true); + }); + }); + + // T017 + describe("notification handling", () => { + it("notifications without id field produce no response body", async () => { + const initRes = await httpPost(httpPort, { + jsonrpc: "2.0", + id: 1, + method: "initialize", + params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "test", version: "1.0" } }, + }); + const sessionId = initRes.headers["mcp-session-id"] as string; + + const res = await httpPost( + httpPort, + { + jsonrpc: "2.0", + method: "notifications/initialized", + params: {}, + }, + { "Mcp-Session-Id": sessionId }, + ); + + expect([200, 202]).toContain(res.status); + }); + + it("server handles JSON-RPC without id field (notification)", async () => { + const initRes = await httpPost(httpPort, { + jsonrpc: "2.0", + id: 1, + method: "initialize", + params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "test", version: "1.0" } }, + }); + const sessionId = initRes.headers["mcp-session-id"] as string; + + const res = await httpPost( + httpPort, + { + jsonrpc: "2.0", + method: "notifications/cancelled", + params: { requestId: 1 }, + }, + { "Mcp-Session-Id": sessionId }, + ); + + expect([200, 202, 204]).toContain(res.status); + }); + }); +}); diff --git a/test/multi-instance-port.test.ts b/test/multi-instance-port.test.ts index 4343365b3e..a0c5e6e69a 100644 --- a/test/multi-instance-port.test.ts +++ b/test/multi-instance-port.test.ts @@ -7,6 +7,7 @@ const PORT_ENVS = [ "III_STREAMS_PORT", "III_ENGINE_PORT", "III_ENGINE_URL", + "AGENTMEMORY_MCP_PORT", ] as const; describe("multi-instance port auto-derive (#750)", () => { @@ -29,35 +30,49 @@ describe("multi-instance port auto-derive (#750)", () => { } }); - it("default REST anchor yields canonical 3111/3112/49134 quartet", () => { + it("default REST anchor yields canonical 3111/3112/3114/49134 family", () => { const cfg = loadConfig(); expect(cfg.restPort).toBe(3111); expect(cfg.streamsPort).toBe(3112); + expect(cfg.mcpPort).toBe(3114); expect(cfg.engineUrl).toBe("ws://localhost:49134"); }); - it("relocating REST drags streams + engine with it", () => { + it("relocating REST drags streams + MCP + engine with it", () => { process.env["III_REST_PORT"] = "3211"; const cfg = loadConfig(); expect(cfg.restPort).toBe(3211); expect(cfg.streamsPort).toBe(3212); + expect(cfg.mcpPort).toBe(3214); expect(cfg.engineUrl).toBe("ws://localhost:49234"); }); - it("instance N=2 block (3311) lands on 3312 + 49334", () => { + it("instance N=2 block (3311) lands on 3312 + 3314 + 49334", () => { process.env["III_REST_PORT"] = "3311"; const cfg = loadConfig(); expect(cfg.restPort).toBe(3311); expect(cfg.streamsPort).toBe(3312); + expect(cfg.mcpPort).toBe(3314); expect(cfg.engineUrl).toBe("ws://localhost:49334"); }); - it("explicit III_STREAM_PORT pins streams without affecting REST/engine", () => { + it("explicit III_STREAM_PORT pins streams without affecting REST/MCP/engine", () => { process.env["III_REST_PORT"] = "3211"; process.env["III_STREAM_PORT"] = "9999"; const cfg = loadConfig(); expect(cfg.restPort).toBe(3211); expect(cfg.streamsPort).toBe(9999); + expect(cfg.mcpPort).toBe(3214); + expect(cfg.engineUrl).toBe("ws://localhost:49234"); + }); + + it("explicit AGENTMEMORY_MCP_PORT pins MCP without affecting REST/streams/engine", () => { + process.env["III_REST_PORT"] = "3211"; + process.env["AGENTMEMORY_MCP_PORT"] = "8888"; + const cfg = loadConfig(); + expect(cfg.restPort).toBe(3211); + expect(cfg.streamsPort).toBe(3212); + expect(cfg.mcpPort).toBe(8888); expect(cfg.engineUrl).toBe("ws://localhost:49234"); });