Skip to content

Self-hosted MCP server + dashboard giving Claude Code, Cursor & Hermes agents shared long-term memory over a git-backed markdown vault. Agent-native, Obsidian-compatible second brain — markdown RAG, no vector DB.

feat(mcp): standalone stdio server + Dockerfile.mcp (local mode)

Ronalds Palacisfbac66a151a2
diff --git a/Dockerfile.mcp b/Dockerfile.mcp
new file mode 100644
index 0000000..087ff10
--- /dev/null
+++ b/Dockerfile.mcp
@@ -0,0 +1,30 @@
+# Engram — standalone stdio MCP server.
+#
+# This is the "local mode" image: it serves the brain_* tools over stdio against a folder of
+# markdown, with no HTTP, no auth, no git. It's what registries (Glama, Smithery) run to
+# introspect the tools, and what Claude Desktop / Cursor run over stdio.
+#
+# The full dashboard + HTTP MCP server for a self-hosted team is the root `Dockerfile`.
+#
+# By default it serves the bundled sample-vault. Mount your own and point VAULT_DIR at it:
+# docker run -i -v /path/to/vault:/vault -e VAULT_DIR=/vault <image>
+
+FROM oven/bun:1
+
+WORKDIR /app
+
+# git + certs: only used if you point it at a git-backed vault; harmless otherwise.
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends git ca-certificates \
+ && rm -rf /var/lib/apt/lists/*
+
+COPY package.json bun.lock* ./
+RUN bun install --frozen-lockfile
+
+COPY . .
+
+ENV NODE_ENV=production \
+ GIT_SYNC_ENABLED=false
+
+# stdio MCP server: JSON-RPC on stdin/stdout. Nothing here may write to stdout.
+CMD ["bun", "scripts/mcp-stdio.ts"]
diff --git a/README.md b/README.md
index 09439d4..3a0942b 100644
--- a/README.md
+++ b/README.md
@@ -126,6 +126,19 @@ Point it at your own vault:
VAULT_DIR=/path/to/your/obsidian-or-markdown/vault bun dev
```
+### Two ways to run it
+
+- **Hosted mode (team):** the dashboard + HTTP MCP server above — self-host it once, many agents and
+ teammates connect over `POST /api/mcp`. This is the main mode.
+- **Local mode (stdio):** a plain stdio MCP server over a folder, no HTTP/auth/git — for a single
+ machine, Claude Desktop / Cursor, or a registry's Docker introspection:
+
+ ```bash
+ bun run mcp:stdio /path/to/your/vault # defaults to ./sample-vault
+ ```
+
+ Same `brain_*` tools. Image: `Dockerfile.mcp` (`CMD ["bun", "scripts/mcp-stdio.ts"]`).
+
## MCP tools
Agents only ever see the active vault — no repo, workspace, or GitHub tools are exposed.
diff --git a/package.json b/package.json
index adb1cb7..858fbca 100644
--- a/package.json
+++ b/package.json
@@ -30,6 +30,7 @@
"dev": "next dev",
"build": "next build",
"start": "next start",
+ "mcp:stdio": "bun scripts/mcp-stdio.ts",
"lint": "eslint",
"gen:secrets": "tsx scripts/gen-secrets.ts"
},
diff --git a/scripts/mcp-stdio.ts b/scripts/mcp-stdio.ts
new file mode 100644
index 0000000..b2b7a22
--- /dev/null
+++ b/scripts/mcp-stdio.ts
@@ -0,0 +1,45 @@
+#!/usr/bin/env bun
+/**
+ * Engram — standalone stdio MCP server (local mode).
+ *
+ * The dashboard serves MCP over HTTP for a self-hosted, multi-agent team. This is the other mode:
+ * a plain stdio MCP server over a local folder of markdown, for a single machine — Claude Desktop,
+ * Cursor, `npx`, or a registry's Docker introspection (Glama/Smithery only need it to start and
+ * answer tools/list). Same brain_* tools; no HTTP, no auth, no git.
+ *
+ * bun scripts/mcp-stdio.ts [vault-dir]
+ *
+ * Defaults to the bundled sample-vault when no dir is given. VAULT_DIR env also works.
+ * The vault dir MUST be resolved into env BEFORE the tools module loads (config reads it at
+ * import time), so the tool imports are dynamic and happen after this block.
+ */
+const vaultArg = process.argv[2];
+if (vaultArg) process.env.VAULT_DIR = vaultArg;
+// Local mode: never touch git, never require an Anthropic key for introspection.
+process.env.GIT_SYNC_ENABLED = "false";
+
+const { TOOLS, TOOL_MAP } = await import("@/lib/mcp/tools");
+const { Server } = await import("@modelcontextprotocol/sdk/server/index.js");
+const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
+const { ListToolsRequestSchema, CallToolRequestSchema } = await import("@modelcontextprotocol/sdk/types.js");
+
+const server = new Server({ name: "engram", version: "0.1.0" }, { capabilities: { tools: {} } });
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+ tools: TOOLS.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })),
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+ const tool = TOOL_MAP.get(req.params.name);
+ if (!tool) throw new Error(`unknown tool: ${req.params.name}`);
+ const out = await tool.handler(req.params.arguments ?? {});
+ const text = typeof out === "string" ? out : JSON.stringify(out, null, 2);
+ return { content: [{ type: "text", text }] };
+});
+
+// stderr only — stdout is the JSON-RPC channel and must stay clean.
+console.error(`[engram] stdio MCP server ready · vault: ${process.env.VAULT_DIR ?? "(bundled sample-vault)"}`);
+
+await server.connect(new StdioServerTransport());
+
+export {};