@microtoll/mcp 0.1.0

package/src/docs.js

@@ -0,0 +1,78 @@
+/**
+ * The docs, as the package ships them: generated/docs.json is written by
+ * the repository's docs build (docs/build.mjs) from the same sources as
+ * microtoll.dev, so search here and the site never drift. No network: the
+ * pages are inside the package.
+ */
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+let cache = null;
+export function loadDocs(file = new URL('../generated/docs.json', import.meta.url)) {
+  if (!cache) cache = JSON.parse(fs.readFileSync(fileURLToPath(file), 'utf8'));
+  return cache;
+}
+
+const tokenize = (s) => String(s || '').toLowerCase().match(/[a-z0-9][a-z0-9-]*/g) || [];
+const stem = (t) => t.replace(/(ings?|ed|es|s)$/, '');
+
+/** The page a `path` names: "packages/access.html", "packages/access", or the full URL. */
+export function readDoc(path, docs = loadDocs()) {
+  if (typeof path !== 'string' || !path) return null;
+  let p = path.trim().replace(/^https?:\/\/microtoll\.dev\//, '').replace(/^\//, '');
+  if (!/\.html$/.test(p)) p += '.html';
+  const page = docs.find((d) => d.path === p);
+  return page ? { path: page.path, url: page.url, title: page.title, description: page.description, markdown: page.markdown } : null;
+}
+
+/** The guides and package pages outrank the project records (the decisions log, the policies), which mention everything. */
+const SECTION_WEIGHT = { Start: 1.3, Packages: 1.4, 'Examples and deployment': 1.2, 'The honest part': 1.1, 'For agents': 1.1, Project: 0.5 };
+
+/**
+ * Full-text search over every page's sections: a term in a heading counts
+ * five, in the page title three, each occurrence in the text one (capped),
+ * the whole phrase four more; every query term must appear somewhere in the
+ * page for it to count; the page's part of the site weights the result.
+ */
+export function searchDocs(query, { limit = 8, docs = loadDocs() } = {}) {
+  const phrase = String(query || '').toLowerCase().trim();
+  const terms = [...new Set(tokenize(query).map(stem))].filter((t) => t.length > 1);
+  if (terms.length === 0) return [];
+  const hits = [];
+  for (const page of docs) {
+    const pageText = page.markdown.toLowerCase();
+    if (!terms.every((t) => pageText.includes(t))) continue;
+    const titleTokens = tokenize(page.title).map(stem);
+    const weight = SECTION_WEIGHT[page.section] || 1;
+    for (const section of page.sections) {
+      const heading = section.heading || page.title;
+      const headingTokens = tokenize(heading).map(stem);
+      const text = section.text.toLowerCase();
+      let score = 0;
+      for (const t of terms) {
+        if (headingTokens.some((h) => h.startsWith(t))) score += 5;
+        if (titleTokens.some((h) => h.startsWith(t))) score += 3;
+        const n = text.split(t).length - 1;
+        score += Math.min(n, 4);
+      }
+      if (terms.length > 1 && (text.includes(phrase) || heading.toLowerCase().includes(phrase))) score += 4;
+      if (score === 0) continue;
+      hits.push({ path: page.path, url: page.url, title: page.title, heading, score: Math.round(score * weight * 10) / 10, excerpt: excerpt(section.text, terms) });
+    }
+  }
+  hits.sort((a, b) => b.score - a.score || a.path.localeCompare(b.path));
+  return hits.slice(0, limit);
+}
+
+function excerpt(text, terms) {
+  const lines = text.split('\n').filter((l) => l.trim() && !/^```/.test(l));
+  const line = lines.find((l) => terms.some((t) => l.toLowerCase().includes(t))) || lines[0] || '';
+  const clean = line.replace(/[#*`>]/g, '').trim();
+  return clean.length > 240 ? `${clean.slice(0, 237)}…` : clean;
+}
+
+/** The search result as the model reads it. */
+export function formatSearch(query, hits) {
+  if (hits.length === 0) return `No page mentions "${query}". Try other words, or read https://microtoll.dev/llms.txt for the index.`;
+  return hits.map((h, i) => `${i + 1}. ${h.title} — ${h.heading}\n   ${h.url}  (path: ${h.path})\n   ${h.excerpt}`).join('\n\n');
+}

package/src/index.js

@@ -0,0 +1,61 @@
+/**
+ * @microtoll/mcp — public entry point (D-39). `createMicrotollServer`
+ * builds the three tools on the protocol in protocol.js; bin/microtoll-mcp.mjs
+ * starts it on stdio.
+ */
+import { createServer, PROTOCOL_VERSION } from './protocol.js';
+import { loadDocs, searchDocs, readDoc, formatSearch } from './docs.js';
+import { scaffold, renderScaffold } from './scaffold.js';
+
+export { createServer, PROTOCOL_VERSION, loadDocs, searchDocs, readDoc, formatSearch, scaffold, renderScaffold };
+
+export const VERSION = '0.0.0';
+
+export const INSTRUCTIONS = [
+  'Microtoll Engine: sign-in, key handling, access control and revocation for end-to-end-encrypted apps, as packages.',
+  'Search the docs before writing security code; never add cryptography beyond what the packages provide; keep the server storing only what it cannot read.',
+  'microtoll_scaffold writes the notes starter into an empty directory and runs nothing.',
+].join(' ');
+
+export function tools() {
+  return [
+    {
+      name: 'microtoll_search_docs',
+      description: 'Full-text search over the Microtoll Engine documentation (the same pages as microtoll.dev, shipped inside this package). Returns pages, sections and excerpts; read a page with microtoll_read_doc.',
+      inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'What to look for, in words.' }, limit: { type: 'integer', minimum: 1, maximum: 20, default: 8 } }, required: ['query'] },
+      handler: ({ query, limit }) => formatSearch(String(query || ''), searchDocs(String(query || ''), { limit: Number.isInteger(limit) ? Math.min(Math.max(limit, 1), 20) : 8 })),
+    },
+    {
+      name: 'microtoll_read_doc',
+      description: 'One documentation page as Markdown: the `path` from a search result (for example "packages/access.html") or from https://microtoll.dev/llms.txt.',
+      inputSchema: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
+      handler: ({ path }) => {
+        const page = readDoc(String(path || ''));
+        if (!page) return { text: `No page at "${path}". The index is https://microtoll.dev/llms.txt; paths look like "packages/access.html".`, isError: true };
+        return `# ${page.title}\n${page.url}\n\n${page.markdown}`;
+      },
+    },
+    {
+      name: 'microtoll_scaffold',
+      description: 'Writes the notes starter (an end-to-end-encrypted notes app on Microtoll Engine: client, page, Compose file, nginx, README) into an EMPTY directory, with the namespace and origin filled in. Writes files and nothing else: no commands run, no network. The next steps (npm install, docker compose up) are returned for the person to run.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          directory: { type: 'string', description: 'Where to write the app: an empty or not-yet-existing directory.' },
+          namespace: { type: 'string', description: 'The app\'s crypto namespace (a-z, 0-9, "-"); used by the client and the server alike. Default "myapp".' },
+          origin: { type: 'string', description: 'The web origin the app runs at, for example http://localhost:8088. Default http://localhost:8088.' },
+          name: { type: 'string', description: 'The app\'s name (a-z, 0-9, "-"); default: the namespace.' },
+        },
+        required: ['directory'],
+      },
+      handler: (args) => {
+        const r = scaffold({ directory: args.directory, namespace: args.namespace || 'myapp', origin: args.origin || 'http://localhost:8088', name: args.name || null });
+        return `Wrote ${r.files.length} files into ${r.directory}:\n${r.files.map((f) => `  ${f}`).join('\n')}\n\nNamespace ${r.namespace}, origin ${r.origin}.\n\nNext, for the person to run:\n${r.next.map((s) => `  ${s}`).join('\n')}`;
+      },
+    },
+  ];
+}
+
+export function createMicrotollServer() {
+  return createServer({ name: 'microtoll', version: VERSION, instructions: INSTRUCTIONS, tools: tools() });
+}

package/src/protocol.js

@@ -0,0 +1,93 @@
+/**
+ * The Model Context Protocol over standard input and output, the subset a
+ * tools-only server needs (D-39): JSON-RPC 2.0 messages, one per line, on
+ * stdin and stdout; `initialize`, `ping`, `tools/list`, `tools/call`;
+ * notifications acknowledged by silence; errors as JSON-RPC errors; logs on
+ * stderr, never stdout (stdout is the protocol). Written in rather than
+ * taken from the SDK so the whole package can be read in one sitting and
+ * carries no dependency tree.
+ *
+ * Protocol version 2025-06-18. A host offers its version in `initialize`;
+ * this server answers with the one it speaks, and a host that cannot speak
+ * it disconnects -- the negotiation the specification describes.
+ */
+export const PROTOCOL_VERSION = '2025-06-18';
+
+const PARSE_ERROR = -32700;
+const INVALID_REQUEST = -32600;
+const METHOD_NOT_FOUND = -32601;
+const INVALID_PARAMS = -32602;
+
+/**
+ * createServer({ name, version, instructions, tools })
+ *   tools: [{ name, description, inputSchema, handler(args) -> string | { text, isError } }]
+ * Returns { handle(message) -> Promise<reply | null>, listen({ input, output, log }) }.
+ * `handle` is the protocol; `listen` wires it to streams.
+ */
+export function createServer({ name, version, instructions = '', tools = [] }) {
+  for (const t of tools) {
+    if (!/^[a-zA-Z0-9_-]{1,64}$/.test(t.name)) throw new Error(`tool name not allowed: ${t.name}`);
+    if (typeof t.handler !== 'function') throw new Error(`tool ${t.name} needs a handler`);
+  }
+  const byName = new Map(tools.map((t) => [t.name, t]));
+  const ok = (id, result) => ({ jsonrpc: '2.0', id, result });
+  const error = (id, code, message, data) => ({ jsonrpc: '2.0', id, error: { code, message, ...(data !== undefined ? { data } : {}) } });
+
+  /** One message in, one reply out (or null for a notification). Never throws. */
+  async function handle(msg) {
+    if (!msg || typeof msg !== 'object' || Array.isArray(msg)) return error(null, INVALID_REQUEST, 'a JSON-RPC request object was expected');
+    const { id, method, params } = msg;
+    const isNotification = id === undefined || id === null;
+    if (msg.jsonrpc !== '2.0' || typeof method !== 'string') return isNotification ? null : error(id, INVALID_REQUEST, 'invalid request');
+    if (method.startsWith('notifications/')) return null;   // initialized, cancelled, progress: nothing to do
+    if (isNotification) return null;                        // any other notification is ignored, as the specification allows
+    switch (method) {
+      case 'initialize':
+        return ok(id, { protocolVersion: PROTOCOL_VERSION, capabilities: { tools: { listChanged: false } }, serverInfo: { name, version }, ...(instructions ? { instructions } : {}) });
+      case 'ping':
+        return ok(id, {});
+      case 'tools/list':
+        return ok(id, { tools: tools.map(({ name: n, description, inputSchema }) => ({ name: n, description, inputSchema })) });
+      case 'tools/call': {
+        const wanted = params && typeof params === 'object' ? params.name : undefined;
+        const tool = byName.get(wanted);
+        if (!tool) return error(id, INVALID_PARAMS, `unknown tool: ${String(wanted)}`);
+        const args = params && params.arguments && typeof params.arguments === 'object' ? params.arguments : {};
+        try {
+          const r = await tool.handler(args);
+          const text = typeof r === 'string' ? r : String(r && r.text);
+          return ok(id, { content: [{ type: 'text', text }], isError: Boolean(r && typeof r === 'object' && r.isError) });
+        } catch (e) {
+          // A tool's failure is a tool result, not a protocol error: the host shows it to the model.
+          return ok(id, { content: [{ type: 'text', text: e.message }], isError: true });
+        }
+      }
+      default:
+        return error(id, METHOD_NOT_FOUND, `method not found: ${method}`);
+    }
+  }
+
+  /** Reads newline-delimited JSON from `input`, answers on `output`, in order. */
+  function listen({ input = process.stdin, output = process.stdout, log = (line) => process.stderr.write(`${line}\n`) } = {}) {
+    let buffer = '';
+    let queue = Promise.resolve();
+    const write = (reply) => { if (reply) output.write(`${JSON.stringify(reply)}\n`); };
+    input.setEncoding('utf8');
+    input.on('data', (chunk) => {
+      buffer += chunk;
+      let nl;
+      while ((nl = buffer.indexOf('\n')) >= 0) {
+        const line = buffer.slice(0, nl).trim();
+        buffer = buffer.slice(nl + 1);
+        if (!line) continue;
+        let msg;
+        try { msg = JSON.parse(line); } catch { write(error(null, PARSE_ERROR, 'parse error')); continue; }
+        queue = queue.then(() => handle(msg)).then(write).catch((e) => log(`microtoll-mcp: ${e.message}`));
+      }
+    });
+    input.on('end', () => { queue.then(() => { if (typeof output.end === 'function' && output !== process.stdout) output.end(); }); });
+    return { stop: () => input.removeAllListeners('data') };
+  }
+
+  return { handle, listen, tools };
+}

package/src/scaffold.js

@@ -0,0 +1,60 @@
+/**
+ * The scaffold: writes the notes starter (the engine's notes example with
+ * the namespace and origin filled in) into an EMPTY directory the host
+ * names, and does nothing else -- no command runs, nothing is fetched, no
+ * telemetry. The templates are generated/scaffold/notes/, produced by the
+ * repository's docs build from examples/notes-app and docs/scaffold/notes.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const NAMESPACE_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+export const TEMPLATES_DIR = fileURLToPath(new URL('../generated/scaffold/notes/', import.meta.url));
+
+/** Everything the scaffold would write, without writing it: [{ name, text }]. */
+export function renderScaffold({ namespace = 'myapp', origin = 'http://localhost:8088', name = null } = {}, templatesDir = TEMPLATES_DIR) {
+  if (!NAMESPACE_RE.test(namespace)) throw new Error('namespace: 1-64 characters of a-z, 0-9 and "-", starting with a letter or digit (the same string createCryptoCore takes)');
+  let url;
+  try { url = new URL(origin); } catch { throw new Error('origin: a web origin such as http://localhost:8088 or https://app.example'); }
+  if (!/^https?:$/.test(url.protocol) || url.pathname !== '/' || url.search || url.hash) throw new Error('origin: scheme and host only, no path');
+  const appName = name || namespace;
+  if (!NAME_RE.test(appName)) throw new Error('name: 1-64 characters of a-z, 0-9 and "-"');
+  const port = url.port || (url.protocol === 'https:' ? '443' : '80');
+  const wsOrigin = `${url.protocol === 'https:' ? 'wss' : 'ws'}://${url.host}`;
+  const fill = (text) => text
+    .replace(/__NAMESPACE__/g, namespace).replace(/__ORIGIN__/g, url.origin).replace(/__WS_ORIGIN__/g, wsOrigin)
+    .replace(/__PORT__/g, port).replace(/__NAME__/g, appName);
+  const out = [];
+  for (const file of fs.readdirSync(templatesDir).sort()) {
+    let text = fs.readFileSync(path.join(templatesDir, file), 'utf8');
+    if (file === 'page.js') {
+      // The example's own namespace and passkey name become the app's.
+      text = text.replace("namespace: 'notes-example'", `namespace: '${namespace}'`).replace("rpName: 'Microtoll notes'", `rpName: '${appName}'`);
+    }
+    out.push({ name: file, text: fill(text) });
+  }
+  return { files: out, namespace, origin: url.origin, name: appName };
+}
+
+/** Writes the scaffold. Refuses a directory that exists and is not empty. Returns { directory, files, next }. */
+export function scaffold(options = {}) {
+  const directory = options.directory;
+  if (typeof directory !== 'string' || !directory.trim()) throw new Error('directory: where to write the app (an absolute path, or one relative to the host\'s working directory)');
+  const target = path.resolve(directory);
+  if (fs.existsSync(target)) {
+    if (!fs.statSync(target).isDirectory()) throw new Error(`${target} exists and is not a directory`);
+    if (fs.readdirSync(target).length > 0) throw new Error(`${target} is not empty: the scaffold writes only into an empty directory, and never overwrites`);
+  }
+  const rendered = renderScaffold(options);
+  fs.mkdirSync(target, { recursive: true });
+  for (const f of rendered.files) fs.writeFileSync(path.join(target, f.name), f.text, { flag: 'wx' });
+  return {
+    directory: target,
+    files: rendered.files.map((f) => f.name),
+    namespace: rendered.namespace,
+    origin: rendered.origin,
+    next: [`cd ${target}`, 'npm install', 'docker compose up', `open ${rendered.origin}`, 'read notes.js, then README.md'],
+  };
+}

package/types/index.d.ts

@@ -0,0 +1,35 @@
+// Hand-written declarations for @microtoll/mcp (M5).
+export const PROTOCOL_VERSION: '2025-06-18';
+export const VERSION: string;
+export const INSTRUCTIONS: string;
+
+export interface ToolResult { text: string; isError?: boolean; }
+export interface Tool {
+  name: string;
+  description: string;
+  inputSchema: object;
+  handler(args: Record<string, unknown>): string | ToolResult | Promise<string | ToolResult>;
+}
+export interface JsonRpcMessage { jsonrpc?: string; id?: string | number | null; method?: string; params?: unknown; }
+export interface JsonRpcReply { jsonrpc: '2.0'; id: string | number | null; result?: unknown; error?: { code: number; message: string; data?: unknown }; }
+export interface ReadableLike { setEncoding(enc: string): unknown; on(event: string, listener: (...args: any[]) => void): unknown; removeAllListeners(event: string): unknown; }
+export interface WritableLike { write(text: string): unknown; end?(): unknown; }
+export interface McpServer {
+  handle(message: unknown): Promise<JsonRpcReply | null>;
+  listen(options?: { input?: ReadableLike; output?: WritableLike; log?: (line: string) => void }): { stop(): void };
+  tools: Tool[];
+}
+export function createServer(options: { name: string; version: string; instructions?: string; tools?: Tool[] }): McpServer;
+export function createMicrotollServer(): McpServer;
+export function tools(): Tool[];
+
+export interface DocPage { path: string; url: string; title: string; description: string; section: string; markdown: string; sections: Array<{ heading: string | null; level: number; text: string }>; }
+export function loadDocs(file?: URL): DocPage[];
+export function readDoc(path: string, docs?: DocPage[]): { path: string; url: string; title: string; description: string; markdown: string } | null;
+export interface SearchHit { path: string; url: string; title: string; heading: string; score: number; excerpt: string; }
+export function searchDocs(query: string, options?: { limit?: number; docs?: DocPage[] }): SearchHit[];
+export function formatSearch(query: string, hits: SearchHit[]): string;
+
+export interface ScaffoldOptions { directory: string; namespace?: string; origin?: string; name?: string | null; }
+export function renderScaffold(options?: Omit<ScaffoldOptions, 'directory'>, templatesDir?: string): { files: Array<{ name: string; text: string }>; namespace: string; origin: string; name: string };
+export function scaffold(options: ScaffoldOptions): { directory: string; files: string[]; namespace: string; origin: string; next: string[] };