granite-mem 0.1.3 → 0.1.4

package/README.md

@@ -60,6 +60,7 @@ Granite is designed to be easy for agents to read and act on:
 - notes are plain files
 - metadata is explicit
 - commands support `--json`
+- Granite ships with an MCP server
 - vault structure is predictable
 - search, backlinks, and recommendations are available from the CLI
 
@@ -85,7 +86,13 @@ mem add "Talked to Alice about local-first sync tradeoffs"
 mem new "Local-first sync tradeoffs" --type permanent
 mem list
 mem search "sync"
-mem serve
+```
+
+Start one long-running interface when you need it:
+
+```bash
+mem serve   # local web UI
+mem mcp     # MCP server for agent clients
 ```
 
 `mem new` does more than create a file. It can immediately suggest related links, tags, and the next note to create, which is the core of Granite's value loop.
@@ -175,6 +182,37 @@ mem recommend sync-constraints --json
 
 That makes Granite a useful substrate for local workflows, scripts, and agent memory.
 
+## MCP Server
+
+Granite ships with an MCP server so LLM clients can control the vault directly through tools, resources, and prompts.
+
+Start it over stdio for local MCP clients:
+
+```bash
+mem mcp --vault /path/to/vault
+```
+
+Start it over Streamable HTTP:
+
+```bash
+mem mcp --transport http --host 127.0.0.1 --port 3321
+```
+
+The server exposes:
+
+- tools for vault overview, list/get/search, create/update, backlinks, link suggestions, recommendations, and doctor
+- resources for `granite.yml`, vault overview, note types, and individual notes via `granite://notes/{slug}`
+- prompts for refining notes and reviewing links/next steps
+
+Example stdio client configuration:
+
+```json
+{
+  "command": "mem",
+  "args": ["mcp", "--vault", "/path/to/vault"]
+}
+```
+
 ## Commands
 
 ```bash
@@ -192,6 +230,7 @@ mem recommend <slug> [--json]
 mem types
 mem doctor
 mem serve [-p <port>]
+mem mcp [--vault <path>] [--transport <stdio|http>]
 ```
 
 ## Development

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command } from "commander";
+import { Command, InvalidArgumentError } from "commander";
 
 // src/commands/init.ts
 import fs3 from "fs";
@@ -533,8 +533,8 @@ function countNoteFiles(vaultRoot, config) {
 }
 function upsertNoteAndLinks(db, note) {
   const upsertNote = db.prepare(`
-    INSERT INTO notes (slug, id, title, type, created, modified, tags, aliases, body, filepath)
-    VALUES (@slug, @id, @title, @type, @created, @modified, @tags, @aliases, @body, @filepath)
+    INSERT INTO notes (slug, id, title, type, created, modified, tags, aliases, body, filepath, status, source)
+    VALUES (@slug, @id, @title, @type, @created, @modified, @tags, @aliases, @body, @filepath, @status, @source)
     ON CONFLICT(slug) DO UPDATE SET
       id = excluded.id,
       title = excluded.title,
@@ -544,7 +544,9 @@ function upsertNoteAndLinks(db, note) {
       tags = excluded.tags,
       aliases = excluded.aliases,
       body = excluded.body,
-      filepath = excluded.filepath
+      filepath = excluded.filepath,
+      status = excluded.status,
+      source = excluded.source
   `);
   const deleteLinks = db.prepare("DELETE FROM links WHERE source_slug = ?");
   const insertLink = db.prepare(`
@@ -562,7 +564,9 @@ function upsertNoteAndLinks(db, note) {
       tags: JSON.stringify(note.frontmatter.tags),
       aliases: JSON.stringify(note.frontmatter.aliases),
       body: note.body,
-      filepath: note.filepath
+      filepath: note.filepath,
+      status: note.frontmatter.status ?? "active",
+      source: note.frontmatter.source ?? "human"
     });
     deleteLinks.run(note.slug);
     const links = parseWikilinks(note.body);
@@ -1354,7 +1358,8 @@ function showCommand(slug, options) {
 }
 
 // src/core/search.ts
-function searchNotes(db, query) {
+function searchNotes(db, query, limit = 20) {
+  const cappedLimit = Math.max(1, Math.min(limit, 100));
   const stmt = db.prepare(`
     SELECT
       n.slug,
@@ -1365,9 +1370,9 @@ function searchNotes(db, query) {
     JOIN notes n ON n.rowid = notes_fts.rowid
     WHERE notes_fts MATCH ?
     ORDER BY rank
-    LIMIT 20
+    LIMIT ?
   `);
-  const rows = stmt.all(query);
+  const rows = stmt.all(query, cappedLimit);
   return rows.map((r) => ({
     slug: r.slug,
     title: r.title,
@@ -1959,9 +1964,1109 @@ function printRecommendations(vaultRoot, config, filepath, strategy) {
   }
 }
 
+// src/commands/mcp.ts
+import path9 from "path";
+
+// src/mcp/server.ts
+import { serve as serve2 } from "@hono/node-server";
+import { Hono as Hono2 } from "hono";
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import * as z from "zod/v4";
+
+// src/version.ts
+var GRANITE_VERSION = "0.1.2";
+
+// src/mcp/server.ts
+var readOnlyAnnotations = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false
+};
+var writeAnnotations = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: false,
+  openWorldHint: false
+};
+var fieldDefinitionSchema = z.object({
+  type: z.enum(["text", "date", "number", "boolean", "wikilink", "list", "enum"]),
+  of: z.string().optional(),
+  options: z.array(z.string()).optional(),
+  required: z.boolean().optional(),
+  default: z.string().optional(),
+  description: z.string().optional()
+});
+var noteTypeInfoSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  folder: z.string(),
+  line_limit: z.number(),
+  warn_only: z.boolean(),
+  slug_format: z.enum(["title", "date"]),
+  instructions: z.string().optional(),
+  fields: z.record(z.string(), fieldDefinitionSchema).optional()
+});
+var noteSummarySchema = z.object({
+  slug: z.string(),
+  title: z.string(),
+  type: z.string(),
+  created: z.string(),
+  modified: z.string(),
+  tags: z.array(z.string()),
+  aliases: z.array(z.string()),
+  status: z.enum(["inbox", "active", "archived"]),
+  source: z.enum(["human", "agent", "extraction"]),
+  filepath: z.string(),
+  resource_uri: z.string()
+});
+var wikiLinkSchema = z.object({
+  raw: z.string(),
+  target: z.string(),
+  display: z.string(),
+  resolved: z.boolean(),
+  resolved_slug: z.string().optional()
+});
+var noteDetailsSchema = noteSummarySchema.extend({
+  body: z.string(),
+  frontmatter: z.record(z.string(), z.unknown()),
+  outgoing_links: z.array(wikiLinkSchema)
+});
+var searchResultSchema = z.object({
+  slug: z.string(),
+  title: z.string(),
+  snippet: z.string(),
+  score: z.number()
+});
+var backlinkSchema = z.object({
+  source_slug: z.string(),
+  source_title: z.string(),
+  context: z.string()
+});
+var linkSuggestionSchema = z.object({
+  target_slug: z.string(),
+  target_title: z.string(),
+  mentions: z.number()
+});
+var recommendationSchema = z.object({
+  additions: z.array(z.object({ text: z.string() })),
+  links: z.array(z.object({
+    slug: z.string(),
+    title: z.string(),
+    type: z.string(),
+    reason: z.string(),
+    source: z.enum(["mention", "search"])
+  })),
+  tags: z.array(z.object({
+    tag: z.string(),
+    weight: z.number(),
+    source_slugs: z.array(z.string())
+  })),
+  next_steps: z.array(z.object({
+    type: z.string(),
+    title_hint: z.string().optional(),
+    reason: z.string()
+  }))
+});
+var doctorIssueSchema = z.object({
+  level: z.enum(["error", "warning", "info"]),
+  file: z.string(),
+  message: z.string()
+});
+var vaultOverviewSchema = z.object({
+  vault_root: z.string(),
+  vault_name: z.string(),
+  default_type: z.string(),
+  auto_rebuild: z.boolean(),
+  index_last_rebuild: z.string().optional(),
+  note_count: z.number(),
+  notes_by_type: z.record(z.string(), z.number()),
+  recent_notes: z.array(noteSummarySchema)
+});
+function createGraniteMcpServer(runtime) {
+  const server = new McpServer(
+    {
+      name: "granite",
+      version: GRANITE_VERSION,
+      title: "Granite MCP Server"
+    },
+    {
+      capabilities: { logging: {} },
+      instructions: [
+        "Granite exposes a local-first markdown vault.",
+        "Prefer read tools and resources first, then write with granite_create_note or granite_update_note.",
+        "Resources are read-only views; notes live on disk and the SQLite index is derived state.",
+        "Use granite_recommend_note_actions to preserve Granite\u2019s capture -> link -> recommend loop."
+      ].join(" ")
+    }
+  );
+  registerTools(server, runtime);
+  registerResources(server, runtime);
+  registerPrompts(server, runtime);
+  return server;
+}
+async function startGraniteMcpStdioServer(runtime) {
+  const server = createGraniteMcpServer(runtime);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(`Granite MCP server listening on stdio for ${runtime.vaultRoot}`);
+}
+function startGraniteMcpHttpServer(runtime, options) {
+  const app = createGraniteMcpHttpApp(runtime, options);
+  console.error(`Granite MCP server listening on http://${options.host}:${options.port}/mcp`);
+  console.error(`Health check: http://${options.host}:${options.port}/health`);
+  console.error(`Vault: ${runtime.vaultRoot}`);
+  serve2({
+    fetch: app.fetch,
+    hostname: options.host,
+    port: options.port
+  });
+}
+async function withResponseCleanup(response, cleanup) {
+  let cleanedUp = false;
+  const cleanupOnce = async () => {
+    if (cleanedUp) {
+      return;
+    }
+    cleanedUp = true;
+    await cleanup();
+  };
+  if (!response.body) {
+    await cleanupOnce();
+    return response;
+  }
+  const reader = response.body.getReader();
+  const wrappedBody = new ReadableStream({
+    async pull(controller) {
+      try {
+        const { done, value } = await reader.read();
+        if (done) {
+          controller.close();
+          await cleanupOnce();
+          return;
+        }
+        controller.enqueue(value);
+      } catch (error) {
+        controller.error(error);
+        await cleanupOnce();
+      }
+    },
+    async cancel(reason) {
+      try {
+        await reader.cancel(reason);
+      } finally {
+        await cleanupOnce();
+      }
+    }
+  });
+  return new Response(wrappedBody, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers
+  });
+}
+function registerTools(server, runtime) {
+  server.registerTool("granite_get_vault_overview", {
+    title: "Granite Vault Overview",
+    description: "Summarize the current Granite vault, including counts by type and recent notes.",
+    inputSchema: {
+      recent_limit: z.number().int().min(1).max(20).optional().describe("How many recent notes to include. Defaults to 10.")
+    },
+    outputSchema: vaultOverviewSchema,
+    annotations: readOnlyAnnotations
+  }, async ({ recent_limit }) => {
+    const overview = runtime.getVaultOverview(recent_limit ?? 10);
+    return toolResult(
+      overview,
+      `Vault "${overview.vault_name}" with ${overview.note_count} notes.`
+    );
+  });
+  server.registerTool("granite_list_note_types", {
+    title: "Granite Note Types",
+    description: "List the note types configured in the vault.",
+    outputSchema: z.object({
+      default_type: z.string(),
+      note_types: z.array(noteTypeInfoSchema)
+    }),
+    annotations: readOnlyAnnotations
+  }, async () => {
+    const noteTypes = runtime.listNoteTypes();
+    return toolResult({
+      default_type: runtime.getDefaultNoteType(),
+      note_types: noteTypes
+    }, `Loaded ${noteTypes.length} Granite note types.`);
+  });
+  server.registerTool("granite_list_notes", {
+    title: "List Granite Notes",
+    description: "List notes from the Granite vault with optional filters.",
+    inputSchema: {
+      type: z.string().optional().describe("Filter by note type."),
+      status: z.enum(["inbox", "active", "archived"]).optional().describe("Filter by note status."),
+      source: z.enum(["human", "agent", "extraction"]).optional().describe("Filter by note source."),
+      since: z.string().optional().describe("Only notes modified on or after this ISO or YYYY-MM-DD value."),
+      limit: z.number().int().min(1).max(200).optional().describe("Maximum number of notes to return. Defaults to 25.")
+    },
+    outputSchema: z.object({
+      notes: z.array(noteSummarySchema),
+      total: z.number()
+    }),
+    annotations: readOnlyAnnotations
+  }, async (args) => {
+    const notes = runtime.listNotes(args);
+    return toolResult({
+      notes,
+      total: notes.length
+    }, `Returned ${notes.length} note(s).`);
+  });
+  server.registerTool("granite_get_note", {
+    title: "Get Granite Note",
+    description: "Read a Granite note by slug, including frontmatter, body, and resolved outgoing links.",
+    inputSchema: {
+      slug: z.string().describe("The note slug.")
+    },
+    outputSchema: noteDetailsSchema,
+    annotations: readOnlyAnnotations
+  }, async ({ slug }) => {
+    const note = runtime.getNote(slug);
+    return {
+      ...toolResult(note, `Loaded "${note.title}" (${note.slug}).`),
+      content: [
+        { type: "text", text: `Loaded "${note.title}" (${note.slug}).` },
+        createNoteResourceLink(note.title, note.resource_uri)
+      ]
+    };
+  });
+  server.registerTool("granite_search_notes", {
+    title: "Search Granite Notes",
+    description: "Run full-text search against the Granite index.",
+    inputSchema: {
+      query: z.string().describe("Full-text query for the SQLite FTS index."),
+      limit: z.number().int().min(1).max(50).optional().describe("Maximum number of search results. Defaults to 10.")
+    },
+    outputSchema: z.object({
+      query: z.string(),
+      results: z.array(searchResultSchema)
+    }),
+    annotations: readOnlyAnnotations
+  }, async ({ query, limit }) => {
+    const results = runtime.search(query, limit ?? 10);
+    return toolResult({
+      query,
+      results
+    }, `Found ${results.length} result(s) for "${query}".`);
+  });
+  server.registerTool("granite_create_note", {
+    title: "Create Granite Note",
+    description: "Create a new note in the Granite vault.",
+    inputSchema: {
+      title: z.string().describe("Note title."),
+      type: z.string().optional().describe("Note type. Defaults to the vault default type."),
+      body: z.string().optional().describe("Optional note body. If omitted, Granite uses the type template."),
+      tags: z.array(z.string()).optional().describe("Tags to add immediately."),
+      aliases: z.array(z.string()).optional().describe("Aliases to add immediately."),
+      status: z.enum(["inbox", "active", "archived"]).optional().describe("Initial note status."),
+      source: z.enum(["human", "agent", "extraction"]).optional().describe("Initial note source.")
+    },
+    outputSchema: z.object({
+      note: noteDetailsSchema,
+      recommendations: recommendationSchema
+    }),
+    annotations: writeAnnotations
+  }, async (args) => {
+    const result = runtime.createNote(args);
+    return toolResult(result, `Created "${result.note.title}" (${result.note.slug}).`);
+  });
+  server.registerTool("granite_capture_note", {
+    title: "Capture Granite Note",
+    description: "Quick-capture a note from free-form text, similar to mem add.",
+    inputSchema: {
+      text: z.string().describe("Raw capture text."),
+      type: z.string().optional().describe("Optional note type override. Defaults to the vault default type."),
+      tags: z.array(z.string()).optional().describe("Tags to add immediately."),
+      aliases: z.array(z.string()).optional().describe("Aliases to add immediately."),
+      status: z.enum(["inbox", "active", "archived"]).optional().describe("Initial note status."),
+      source: z.enum(["human", "agent", "extraction"]).optional().describe("Initial note source.")
+    },
+    outputSchema: z.object({
+      note: noteDetailsSchema,
+      recommendations: recommendationSchema
+    }),
+    annotations: writeAnnotations
+  }, async (args) => {
+    const result = runtime.captureNote(args);
+    return toolResult(result, `Captured "${result.note.title}" (${result.note.slug}).`);
+  });
+  server.registerTool("granite_update_note", {
+    title: "Update Granite Note",
+    description: "Update frontmatter or body fields for an existing Granite note.",
+    inputSchema: {
+      slug: z.string().describe("Slug of the note to update."),
+      title: z.string().optional().describe("Replace the note title."),
+      body: z.string().optional().describe("Replace the entire note body."),
+      append: z.string().optional().describe("Append text to the existing note body."),
+      tags: z.array(z.string()).optional().describe("Tags to add."),
+      aliases: z.array(z.string()).optional().describe("Aliases to add."),
+      status: z.enum(["inbox", "active", "archived"]).optional().describe("New note status."),
+      source: z.enum(["human", "agent", "extraction"]).optional().describe("New note source.")
+    },
+    outputSchema: z.object({
+      note: noteDetailsSchema,
+      recommendations: recommendationSchema
+    }),
+    annotations: writeAnnotations
+  }, async ({ slug, ...updates }) => {
+    const result = runtime.updateNote(slug, updates);
+    return toolResult(result, `Updated "${result.note.title}" (${result.note.slug}).`);
+  });
+  server.registerTool("granite_get_backlinks", {
+    title: "Granite Backlinks",
+    description: "List notes that link to a given Granite note.",
+    inputSchema: {
+      slug: z.string().describe("Slug of the target note.")
+    },
+    outputSchema: z.object({
+      slug: z.string(),
+      backlinks: z.array(backlinkSchema)
+    }),
+    annotations: readOnlyAnnotations
+  }, async ({ slug }) => {
+    const backlinks = runtime.getBacklinks(slug);
+    return toolResult({
+      slug,
+      backlinks
+    }, `Found ${backlinks.length} backlink(s) for "${slug}".`);
+  });
+  server.registerTool("granite_suggest_links", {
+    title: "Suggest Granite Links",
+    description: "Suggest missing wikilinks for a Granite note based on mentions.",
+    inputSchema: {
+      slug: z.string().describe("Slug of the note to inspect.")
+    },
+    outputSchema: z.object({
+      slug: z.string(),
+      suggestions: z.array(linkSuggestionSchema)
+    }),
+    annotations: readOnlyAnnotations
+  }, async ({ slug }) => {
+    const suggestions = runtime.suggestLinks(slug);
+    return toolResult({
+      slug,
+      suggestions
+    }, `Found ${suggestions.length} suggested link(s) for "${slug}".`);
+  });
+  server.registerTool("granite_recommend_note_actions", {
+    title: "Recommend Granite Actions",
+    description: "Recommend follow-up links, tags, additions, and next notes for a Granite note.",
+    inputSchema: {
+      slug: z.string().describe("Slug of the note to analyze.")
+    },
+    outputSchema: z.object({
+      slug: z.string(),
+      recommendations: recommendationSchema
+    }),
+    annotations: readOnlyAnnotations
+  }, async ({ slug }) => {
+    const recommendations = runtime.recommend(slug);
+    return toolResult({
+      slug,
+      recommendations
+    }, recommendationSummary(recommendations));
+  });
+  server.registerTool("granite_run_doctor", {
+    title: "Run Granite Doctor",
+    description: "Validate vault health and report structural issues.",
+    outputSchema: z.object({
+      issues: z.array(doctorIssueSchema),
+      counts: z.object({
+        errors: z.number(),
+        warnings: z.number(),
+        info: z.number()
+      })
+    }),
+    annotations: readOnlyAnnotations
+  }, async () => {
+    const result = runtime.runDoctor();
+    return toolResult(
+      result,
+      `${result.counts.errors} error(s), ${result.counts.warnings} warning(s), ${result.counts.info} info item(s).`
+    );
+  });
+}
+function registerResources(server, runtime) {
+  server.registerResource("granite-vault-config", "granite://vault/config", {
+    title: "Granite Config",
+    description: "Raw granite.yml configuration for the current vault.",
+    mimeType: "text/yaml"
+  }, async () => ({
+    contents: [{
+      uri: "granite://vault/config",
+      text: runtime.readVaultConfigRaw(),
+      mimeType: "text/yaml"
+    }]
+  }));
+  server.registerResource("granite-vault-overview", "granite://vault/overview", {
+    title: "Granite Vault Overview",
+    description: "Structured summary of the current vault.",
+    mimeType: "application/json"
+  }, async () => ({
+    contents: [{
+      uri: "granite://vault/overview",
+      text: runtime.readVaultOverviewJson(),
+      mimeType: "application/json"
+    }]
+  }));
+  server.registerResource("granite-note-types", "granite://vault/types", {
+    title: "Granite Note Types",
+    description: "Structured list of the note types configured in the current vault.",
+    mimeType: "application/json"
+  }, async () => ({
+    contents: [{
+      uri: "granite://vault/types",
+      text: runtime.readVaultTypesJson(),
+      mimeType: "application/json"
+    }]
+  }));
+  const noteTemplate = new ResourceTemplate("granite://notes/{slug}", {
+    list: void 0,
+    complete: {
+      slug: async (value) => runtime.completeSlugs(value)
+    }
+  });
+  server.registerResource("granite-note", noteTemplate, {
+    title: "Granite Note",
+    description: "Read a Granite note as markdown with YAML frontmatter.",
+    mimeType: "text/markdown"
+  }, async (uri, variables) => {
+    const variable = variables.slug;
+    const slug = Array.isArray(variable) ? variable[0] : variable;
+    if (!slug) {
+      throw new Error("Resource URI is missing the note slug.");
+    }
+    return {
+      contents: [{
+        uri: uri.toString(),
+        text: runtime.readNoteMarkdown(decodeURIComponent(slug)),
+        mimeType: "text/markdown"
+      }]
+    };
+  });
+}
+function registerPrompts(server, runtime) {
+  server.registerPrompt("granite_refine_note", {
+    title: "Refine Granite Note",
+    description: "Create a prompt for turning a note into a cleaner permanent note draft.",
+    argsSchema: {
+      slug: z.string().describe("Slug of the note to refine.")
+    }
+  }, async ({ slug }) => {
+    const note = runtime.getNote(slug);
+    return {
+      description: `Refine ${note.slug} into a durable Granite note.`,
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              "Refine the attached Granite note into a durable, well-structured permanent note.",
+              "Keep the meaning intact, avoid inventing facts, preserve useful wikilinks, and use Granite-style headings when appropriate."
+            ].join(" ")
+          }
+        },
+        {
+          role: "user",
+          content: {
+            type: "resource",
+            resource: {
+              uri: note.resource_uri,
+              text: runtime.readNoteMarkdown(slug),
+              mimeType: "text/markdown"
+            }
+          }
+        }
+      ]
+    };
+  });
+  server.registerPrompt("granite_review_connections", {
+    title: "Review Granite Connections",
+    description: "Create a prompt for improving note links, tags, and next steps.",
+    argsSchema: {
+      slug: z.string().describe("Slug of the note to inspect.")
+    }
+  }, async ({ slug }) => {
+    const note = runtime.getNote(slug);
+    const backlinks = runtime.getBacklinks(slug);
+    const recommendations = runtime.recommend(slug);
+    return {
+      description: `Review the connections around ${note.slug}.`,
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              "Review this Granite note and propose better links, tags, and the most useful follow-up note.",
+              "Prefer concrete suggestions grounded in the vault context below."
+            ].join(" ")
+          }
+        },
+        {
+          role: "user",
+          content: {
+            type: "resource",
+            resource: {
+              uri: note.resource_uri,
+              text: runtime.readNoteMarkdown(slug),
+              mimeType: "text/markdown"
+            }
+          }
+        },
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: JSON.stringify({ backlinks, recommendations }, null, 2)
+          }
+        }
+      ]
+    };
+  });
+}
+function toolResult(structuredContent, summary) {
+  return {
+    content: [{ type: "text", text: summary }],
+    structuredContent: asStructuredContent(structuredContent)
+  };
+}
+function createNoteResourceLink(name, uri) {
+  return {
+    type: "resource_link",
+    name,
+    uri,
+    mimeType: "text/markdown",
+    description: "Read the markdown resource for this note."
+  };
+}
+function recommendationSummary(recommendations) {
+  return [
+    `${recommendations.links.length} link suggestion(s)`,
+    `${recommendations.tags.length} tag suggestion(s)`,
+    `${recommendations.next_steps.length} next-step suggestion(s)`
+  ].join(", ");
+}
+function asStructuredContent(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+function createGraniteMcpHttpApp(runtime, options) {
+  const app = new Hono2();
+  const allowedHosts = buildAllowedHosts(options.host, options.port);
+  const allowedOrigins = buildAllowedOrigins(options.host, options.port, options.allowedOrigins ?? []);
+  app.use("/mcp", async (c, next) => {
+    const requestHost = (c.req.header("host") ?? "").toLowerCase();
+    if (allowedHosts.size > 0 && !allowedHosts.has(requestHost)) {
+      return c.json({
+        jsonrpc: "2.0",
+        error: { code: -32e3, message: "Forbidden host header." },
+        id: null
+      }, 403);
+    }
+    const origin = c.req.header("origin");
+    if (origin && !allowedOrigins.has(origin)) {
+      return c.json({
+        jsonrpc: "2.0",
+        error: { code: -32e3, message: "Forbidden origin." },
+        id: null
+      }, 403);
+    }
+    if (c.req.method === "OPTIONS") {
+      return new Response(null, {
+        status: 204,
+        headers: corsHeaders(origin, allowedOrigins)
+      });
+    }
+    await next();
+  });
+  app.get("/health", (c) => c.json({ status: "ok", name: "granite-mcp", version: GRANITE_VERSION }));
+  app.all("/mcp", async (c) => {
+    const origin = c.req.header("origin");
+    const server = createGraniteMcpServer(runtime);
+    const transport = new WebStandardStreamableHTTPServerTransport({
+      sessionIdGenerator: void 0,
+      enableJsonResponse: options.jsonResponse ?? false
+    });
+    try {
+      await server.connect(transport);
+      const response = await transport.handleRequest(c.req.raw);
+      const managedResponse = await withResponseCleanup(response, async () => {
+        await server.close();
+      });
+      return withCors(managedResponse, origin, allowedOrigins);
+    } catch (error) {
+      await server.close();
+      throw error;
+    }
+  });
+  return app;
+}
+function buildAllowedHosts(host, port) {
+  const normalizedHost = host.toLowerCase();
+  if (normalizedHost === "0.0.0.0" || normalizedHost === "::" || normalizedHost === "[::]") {
+    return /* @__PURE__ */ new Set();
+  }
+  const allowed = /* @__PURE__ */ new Set([`${normalizedHost}:${port}`]);
+  if (normalizedHost === "127.0.0.1" || normalizedHost === "localhost") {
+    allowed.add(`127.0.0.1:${port}`);
+    allowed.add(`localhost:${port}`);
+  }
+  if (normalizedHost === "::1" || normalizedHost === "[::1]") {
+    allowed.add(`[::1]:${port}`);
+  }
+  return allowed;
+}
+function buildAllowedOrigins(host, port, extraOrigins) {
+  const allowed = new Set(extraOrigins);
+  const normalizedHost = host.toLowerCase();
+  if (normalizedHost === "::1" || normalizedHost === "[::1]") {
+    allowed.add(`http://[::1]:${port}`);
+  } else if (normalizedHost !== "0.0.0.0" && normalizedHost !== "::" && normalizedHost !== "[::]") {
+    allowed.add(`http://${normalizedHost}:${port}`);
+  }
+  if (normalizedHost === "127.0.0.1" || normalizedHost === "localhost") {
+    allowed.add(`http://127.0.0.1:${port}`);
+    allowed.add(`http://localhost:${port}`);
+  }
+  return allowed;
+}
+function withCors(response, origin, allowedOrigins) {
+  const headers = new Headers(response.headers);
+  for (const [key, value] of corsHeaders(origin, allowedOrigins)) {
+    headers.set(key, value);
+  }
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers
+  });
+}
+function corsHeaders(origin, allowedOrigins) {
+  const headers = new Headers();
+  if (origin && allowedOrigins.has(origin)) {
+    headers.set("Access-Control-Allow-Origin", origin);
+    headers.set("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+    headers.set("Access-Control-Allow-Headers", "Content-Type, MCP-Protocol-Version, Last-Event-ID");
+    headers.set("Access-Control-Expose-Headers", "MCP-Session-Id, MCP-Protocol-Version");
+    headers.set("Vary", "Origin");
+  }
+  return headers;
+}
+
+// src/mcp/runtime.ts
+import fs12 from "fs";
+import path8 from "path";
+var GraniteMcpRuntime = class {
+  vaultRoot;
+  config;
+  db;
+  indexCheckIntervalMs;
+  lastSignature;
+  lastIndexCheckAt = 0;
+  constructor(vaultRoot, options = {}) {
+    this.vaultRoot = path8.resolve(vaultRoot);
+    this.config = loadConfig(this.vaultRoot);
+    this.db = openDatabase(this.vaultRoot);
+    this.indexCheckIntervalMs = options.indexCheckIntervalMs ?? 1500;
+  }
+  close() {
+    this.db.close();
+  }
+  getVaultOverview(recentLimit = 10) {
+    const notes = this.readAllNotes().sort((a, b) => b.frontmatter.modified.localeCompare(a.frontmatter.modified));
+    const byType = {};
+    for (const note of notes) {
+      byType[note.frontmatter.type] = (byType[note.frontmatter.type] ?? 0) + 1;
+    }
+    return {
+      vault_root: this.vaultRoot,
+      vault_name: this.config.vault_name,
+      default_type: this.config.defaults.note_type,
+      auto_rebuild: this.config.index.auto_rebuild,
+      index_last_rebuild: this.getMetaValue("last_rebuild"),
+      note_count: notes.length,
+      notes_by_type: byType,
+      recent_notes: notes.slice(0, clampLimit(recentLimit, 20)).map((note) => this.toNoteSummary(note))
+    };
+  }
+  listNoteTypes() {
+    return Object.entries(this.config.note_types).map(([name, typeConfig]) => ({
+      name,
+      description: typeConfig.description,
+      folder: typeConfig.folder,
+      line_limit: typeConfig.line_limit,
+      warn_only: typeConfig.warn_only,
+      slug_format: typeConfig.slug_format ?? "title",
+      instructions: typeConfig.instructions,
+      fields: typeConfig.fields
+    }));
+  }
+  getDefaultNoteType() {
+    return this.config.defaults.note_type;
+  }
+  listNotes(input = {}) {
+    let notes = this.readAllNotes();
+    if (input.type) {
+      notes = notes.filter((note) => note.frontmatter.type === input.type);
+    }
+    if (input.status) {
+      notes = notes.filter((note) => note.frontmatter.status === input.status);
+    }
+    if (input.source) {
+      notes = notes.filter((note) => note.frontmatter.source === input.source);
+    }
+    if (input.since) {
+      const since = input.since;
+      notes = notes.filter((note) => note.frontmatter.modified >= since);
+    }
+    notes.sort((a, b) => b.frontmatter.modified.localeCompare(a.frontmatter.modified));
+    return notes.slice(0, clampLimit(input.limit ?? 25, 200)).map((note) => this.toNoteSummary(note));
+  }
+  getNote(slug) {
+    const note = this.requireNote(slug);
+    const allNotes = this.readAllNotes();
+    const outgoingLinks = resolveWikilinks(parseWikilinks(note.body), allNotes);
+    return {
+      ...this.toNoteSummary(note),
+      body: note.body,
+      frontmatter: note.frontmatter,
+      outgoing_links: outgoingLinks
+    };
+  }
+  search(query, limit = 10) {
+    this.refreshIndex();
+    return searchNotes(this.db, query, clampLimit(limit, 50));
+  }
+  getBacklinks(slug) {
+    this.requireNote(slug);
+    this.refreshIndex();
+    return getBacklinks(this.db, slug);
+  }
+  suggestLinks(slug) {
+    const note = this.requireNote(slug);
+    this.refreshIndex();
+    return suggestLinks(this.db, note);
+  }
+  recommend(slug) {
+    const note = this.requireNote(slug);
+    this.refreshIndex();
+    return getRecommendations(this.db, note, this.config);
+  }
+  runDoctor() {
+    this.refreshIndex();
+    const issues = runDoctor(this.vaultRoot, this.config, this.db);
+    return {
+      counts: {
+        errors: issues.filter((issue) => issue.level === "error").length,
+        warnings: issues.filter((issue) => issue.level === "warning").length,
+        info: issues.filter((issue) => issue.level === "info").length
+      },
+      issues
+    };
+  }
+  createNote(input) {
+    const resolvedType = input.type ?? this.config.defaults.note_type;
+    const typeConfig = this.config.note_types[resolvedType];
+    if (!typeConfig) {
+      throw new Error(`Unknown note type: "${resolvedType}"`);
+    }
+    const bodyOverride = input.body !== void 0 ? ensureTrailingNewline(input.body) : typeConfig.slug_format === "date" ? ensureTrailingNewline(input.title) : void 0;
+    const created = createNote(this.vaultRoot, this.config, resolvedType, input.title, bodyOverride);
+    const metadataMutations = {
+      tags: input.tags,
+      aliases: input.aliases,
+      status: input.status,
+      source: input.source
+    };
+    if (hasMetadataMutations(metadataMutations)) {
+      this.applyMutations(created.filepath, metadataMutations);
+    }
+    return this.afterWrite(created.slug, true);
+  }
+  captureNote(input) {
+    const content = input.text.trim();
+    if (!content) {
+      throw new Error("Capture text cannot be empty.");
+    }
+    const firstLine = content.split("\n")[0] ?? "Untitled";
+    const title = firstLine.length > 60 ? `${firstLine.slice(0, 60).trim()}...` : firstLine;
+    return this.createNote({
+      title,
+      type: input.type,
+      body: ensureTrailingNewline(content),
+      tags: input.tags,
+      aliases: input.aliases,
+      status: input.status,
+      source: input.source
+    });
+  }
+  updateNote(slug, input) {
+    const note = this.requireNote(slug);
+    const needsFullRebuild = input.title !== void 0 || (input.aliases?.length ?? 0) > 0;
+    this.applyMutations(note.filepath, input);
+    if (needsFullRebuild) {
+      return this.afterWrite(slug, true);
+    }
+    this.refreshIndex();
+    const updated = readNote(note.filepath);
+    syncNoteInIndex(this.vaultRoot, this.config, this.db, updated);
+    this.captureSignature();
+    return {
+      note: this.getNote(updated.slug),
+      recommendations: getRecommendations(this.db, updated, this.config)
+    };
+  }
+  readVaultConfigRaw() {
+    return fs12.readFileSync(path8.join(this.vaultRoot, CONFIG_FILENAME), "utf-8");
+  }
+  readVaultTypesJson() {
+    return JSON.stringify({
+      default_type: this.config.defaults.note_type,
+      note_types: this.listNoteTypes()
+    }, null, 2);
+  }
+  readVaultOverviewJson() {
+    return JSON.stringify(this.getVaultOverview(), null, 2);
+  }
+  readNoteMarkdown(slug) {
+    const note = this.requireNote(slug);
+    return fs12.readFileSync(note.filepath, "utf-8");
+  }
+  completeSlugs(prefix = "") {
+    const normalizedPrefix = prefix.toLowerCase();
+    return this.readAllNotes().sort((a, b) => b.frontmatter.modified.localeCompare(a.frontmatter.modified)).map((note) => note.slug).filter((slug) => slug.toLowerCase().startsWith(normalizedPrefix)).slice(0, 25);
+  }
+  noteResourceUri(slug) {
+    return `granite://notes/${encodeURIComponent(slug)}`;
+  }
+  refreshIndex(force = false) {
+    const now = Date.now();
+    if (!force && now - this.lastIndexCheckAt < this.indexCheckIntervalMs) {
+      return;
+    }
+    const currentConfigMtimeMs = this.getConfigMtimeMs();
+    if (!this.lastSignature || currentConfigMtimeMs !== this.lastSignature.configMtimeMs) {
+      this.config = loadConfig(this.vaultRoot);
+    }
+    const signature = this.computeSignature();
+    let shouldRebuild = false;
+    if (force) {
+      shouldRebuild = true;
+    } else if (this.config.index.auto_rebuild) {
+      if (!this.lastSignature) {
+        shouldRebuild = signature.noteCount !== this.getIndexedNoteCount() || signature.latestMutationMs > this.getLastRebuildMs();
+      } else {
+        shouldRebuild = signature.noteCount !== this.lastSignature.noteCount || signature.latestMutationMs !== this.lastSignature.latestMutationMs || signature.configMtimeMs !== this.lastSignature.configMtimeMs;
+      }
+    }
+    if (shouldRebuild) {
+      rebuildIndex(this.vaultRoot, this.config, this.db);
+    }
+    this.lastSignature = signature;
+    this.lastIndexCheckAt = now;
+  }
+  readAllNotes() {
+    return listNotes(this.vaultRoot, this.config);
+  }
+  requireNote(slug) {
+    const note = findNoteBySlug(this.vaultRoot, this.config, slug);
+    if (!note) {
+      throw new Error(`Note not found: ${slug}`);
+    }
+    return note;
+  }
+  toNoteSummary(note) {
+    return {
+      slug: note.slug,
+      title: note.frontmatter.title,
+      type: note.frontmatter.type,
+      created: note.frontmatter.created,
+      modified: note.frontmatter.modified,
+      tags: note.frontmatter.tags,
+      aliases: note.frontmatter.aliases,
+      status: note.frontmatter.status,
+      source: note.frontmatter.source,
+      filepath: note.filepath,
+      resource_uri: this.noteResourceUri(note.slug)
+    };
+  }
+  applyMutations(filepath, input) {
+    const raw = fs12.readFileSync(filepath, "utf-8");
+    const { frontmatter, body: existingBody } = parseFrontmatter(raw);
+    let body = existingBody;
+    if (input.title !== void 0) {
+      frontmatter.title = input.title;
+    }
+    if (input.tags && input.tags.length > 0) {
+      frontmatter.tags = mergeUnique(frontmatter.tags, input.tags);
+    }
+    if (input.aliases && input.aliases.length > 0) {
+      frontmatter.aliases = mergeUnique(frontmatter.aliases, input.aliases);
+    }
+    if (input.status !== void 0) {
+      validateStatus(input.status);
+      frontmatter.status = input.status;
+    }
+    if (input.source !== void 0) {
+      validateSource(input.source);
+      frontmatter.source = input.source;
+    }
+    if (input.body !== void 0) {
+      body = ensureTrailingNewline(input.body);
+    }
+    if (input.append !== void 0) {
+      body = `${body.trimEnd()}
+${input.append}
+`;
+    }
+    frontmatter.modified = (/* @__PURE__ */ new Date()).toISOString();
+    fs12.writeFileSync(filepath, serializeFrontmatter(frontmatter, body), "utf-8");
+  }
+  afterWrite(slug, fullRebuild) {
+    if (fullRebuild) {
+      this.refreshIndex(true);
+    } else {
+      this.refreshIndex();
+      const note2 = this.requireNote(slug);
+      syncNoteInIndex(this.vaultRoot, this.config, this.db, note2);
+      this.captureSignature();
+    }
+    const note = this.requireNote(slug);
+    return {
+      note: this.getNote(note.slug),
+      recommendations: getRecommendations(this.db, note, this.config)
+    };
+  }
+  captureSignature() {
+    this.lastSignature = this.computeSignature();
+    this.lastIndexCheckAt = Date.now();
+  }
+  computeSignature() {
+    let noteCount = 0;
+    let latestNoteMtimeMs = 0;
+    for (const typeConfig of Object.values(this.config.note_types)) {
+      const folder = path8.join(this.vaultRoot, typeConfig.folder);
+      if (!fs12.existsSync(folder)) {
+        continue;
+      }
+      for (const entry of fs12.readdirSync(folder)) {
+        if (!entry.endsWith(".md")) {
+          continue;
+        }
+        noteCount += 1;
+        const stat = fs12.statSync(path8.join(folder, entry));
+        latestNoteMtimeMs = Math.max(latestNoteMtimeMs, stat.mtimeMs);
+      }
+    }
+    const configMtimeMs = this.getConfigMtimeMs();
+    return {
+      noteCount,
+      latestMutationMs: Math.max(latestNoteMtimeMs, configMtimeMs),
+      configMtimeMs
+    };
+  }
+  getConfigMtimeMs() {
+    const configPath = path8.join(this.vaultRoot, CONFIG_FILENAME);
+    return fs12.existsSync(configPath) ? fs12.statSync(configPath).mtimeMs : 0;
+  }
+  getLastRebuildMs() {
+    const value = this.getMetaValue("last_rebuild");
+    return value ? Date.parse(value) || 0 : 0;
+  }
+  getMetaValue(key) {
+    const row = this.db.prepare("SELECT value FROM meta WHERE key = ?").get(key);
+    return row?.value;
+  }
+  getIndexedNoteCount() {
+    const row = this.db.prepare("SELECT COUNT(*) as count FROM notes").get();
+    return row.count;
+  }
+};
+function ensureTrailingNewline(value) {
+  return value.endsWith("\n") ? value : `${value}
+`;
+}
+function clampLimit(value, max) {
+  return Math.max(1, Math.min(value, max));
+}
+function mergeUnique(existing, incoming) {
+  const merged = new Set(existing);
+  for (const value of incoming) {
+    const trimmed = value.trim();
+    if (trimmed) {
+      merged.add(trimmed);
+    }
+  }
+  return [...merged];
+}
+function hasMetadataMutations(input) {
+  return (input.tags?.length ?? 0) > 0 || (input.aliases?.length ?? 0) > 0 || input.status !== void 0 || input.source !== void 0;
+}
+
+// src/commands/mcp.ts
+async function mcpCommand(options) {
+  const transport = parseTransport(options.transport);
+  const vaultRoot = resolveVaultRoot(options.vault);
+  const runtime = new GraniteMcpRuntime(vaultRoot);
+  const shutdown = () => {
+    runtime.close();
+    process.exit(0);
+  };
+  process.once("SIGINT", shutdown);
+  process.once("SIGTERM", shutdown);
+  if (transport === "http") {
+    const port = parsePort(options.port);
+    startGraniteMcpHttpServer(runtime, {
+      host: options.host ?? "127.0.0.1",
+      port,
+      allowedOrigins: options.allowOrigin ?? [],
+      jsonResponse: options.jsonResponse ?? false
+    });
+    return;
+  }
+  await startGraniteMcpStdioServer(runtime);
+}
+function resolveVaultRoot(explicitVault) {
+  const fromEnv = process.env.GRANITE_VAULT;
+  if (explicitVault) {
+    return path9.resolve(explicitVault);
+  }
+  if (fromEnv) {
+    return path9.resolve(fromEnv);
+  }
+  return requireVaultRoot();
+}
+function parseTransport(value) {
+  const transport = value ?? "stdio";
+  if (transport !== "stdio" && transport !== "http") {
+    throw new Error(`Invalid MCP transport: ${transport}. Expected "stdio" or "http".`);
+  }
+  return transport;
+}
+function parsePort(value) {
+  const raw = (value ?? process.env.MCP_PORT ?? "3321").trim();
+  if (!/^\d+$/.test(raw)) {
+    throw new Error(`Invalid MCP port: ${raw}`);
+  }
+  const parsed = Number.parseInt(raw, 10);
+  if (parsed <= 0) {
+    throw new Error(`Invalid MCP port: ${raw}`);
+  }
+  return parsed;
+}
+
 // src/index.ts
 var program = new Command();
-program.name("mem").description("Granite \u2014 a local-first markdown memory system").version("0.1.0");
+program.name("mem").description("Granite \u2014 a local-first markdown memory system").version(GRANITE_VERSION);
 program.command("init").description("Initialize the default vault in ~/.granite").action(() => {
   initVault();
 });
@@ -2004,4 +3109,17 @@ program.command("doctor").description("Validate vault health").action(() => {
 program.command("serve").description("Start the local web UI").option("-p, --port <port>", "Port number", "4321").action((options) => {
   serveCommand(options);
 });
-program.parse();
+program.command("mcp").description("Start Granite as an MCP server").option("--vault <path>", "Vault root. Defaults to the current Granite vault or $GRANITE_VAULT").option("--transport <transport>", "Transport to use: stdio or http", parseTransportOption, "stdio").option("--host <host>", "Host for HTTP transport", "127.0.0.1").option("--port <port>", "Port for HTTP transport", "3321").option("--allow-origin <origin>", "Allow an HTTP Origin for browser-based HTTP clients", collectValues, []).option("--json-response", "Prefer JSON HTTP responses instead of SSE streams").action(async (options) => {
+  await mcpCommand(options);
+});
+await program.parseAsync();
+function collectValues(value, previous) {
+  return [...previous, value];
+}
+function parseTransportOption(value) {
+  try {
+    return parseTransport(value);
+  } catch (error) {
+    throw new InvalidArgumentError(error instanceof Error ? error.message : String(error));
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "granite-mem",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "A local-first markdown memory system for humans and agents",
   "type": "module",
   "bin": {
@@ -27,18 +27,21 @@
     "build": "tsup && rm -rf dist/public && cp -r src/web/public dist/public",
     "dev": "tsx src/index.ts",
     "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
     "lint": "tsc --noEmit",
     "prepare": "husky"
   },
   "dependencies": {
+    "@hono/node-server": "^1.13.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "better-sqlite3": "^11.0.0",
     "commander": "^13.0.0",
     "gray-matter": "^4.0.3",
     "hono": "^4.0.0",
-    "@hono/node-server": "^1.13.0",
     "js-yaml": "^4.1.0",
-    "uuid": "^11.0.0"
+    "uuid": "^11.0.0",
+    "zod": "^3.25.76"
   },
   "devDependencies": {
     "@commitlint/cli": "^20.0.0",
@@ -47,6 +50,7 @@
     "@types/js-yaml": "^4.0.0",
     "@types/node": "^22.0.0",
     "@types/uuid": "^10.0.0",
+    "@vitest/coverage-v8": "^3.2.4",
     "commitizen": "^4.3.1",
     "cz-conventional-changelog": "^3.3.0",
     "husky": "^9.1.7",