@openparachute/vault 0.4.0 → 0.4.4-rc.11

package/src/mcp-tools.ts

@@ -7,6 +7,11 @@
 
 import { generateMcpTools } from "../core/src/mcp.ts";
 import type { McpToolDef } from "../core/src/mcp.ts";
+import {
+  buildVaultProjection,
+  projectionToMarkdown,
+  type VaultProjection,
+} from "../core/src/vault-projection.ts";
 import { readVaultConfig, writeVaultConfig } from "./config.ts";
 import { getVaultStore } from "./vault-store.ts";
 import { hasScopeForVault } from "./scopes.ts";
@@ -18,22 +23,72 @@ import {
 } from "./tag-scope.ts";
 import { findTokensReferencingTag } from "./token-store.ts";
 
+/**
+ * Filter a vault projection to entries an in-scope tag contributes to.
+ *
+ * Mirrors the JSON `vault-info` wrapper exactly so the connect-time
+ * markdown brief and the JSON tool surface identical scope shapes:
+ *
+ *   - `tags` array → drop entries whose name isn't in `allowed`.
+ *   - `indexed_fields` array → for each entry, intersect `tags` (the
+ *     declarer list) with `allowed`. Drop the entry entirely when no
+ *     declarer survives.
+ *
+ * Aggregate stats and the static `query_hints` catalog pass through
+ * unchanged — counts are aggregate (already pre-#271 behavior) and hints
+ * are pure documentation.
+ */
+function filterProjectionByScope(
+  projection: VaultProjection,
+  allowed: Set<string>,
+): VaultProjection {
+  return {
+    ...projection,
+    tags: projection.tags.filter((t) => allowed.has(t.name)),
+    indexed_fields: projection.indexed_fields
+      .map((f) => ({ ...f, tags: f.tags.filter((t) => allowed.has(t)) }))
+      .filter((f) => f.tags.length > 0),
+  };
+}
+
 /**
  * Get the MCP server instruction for a vault.
- * Sent once at session init — not per tool.
+ *
+ * Sent once at session init via the MCP `initialize` response — not per
+ * tool. The body is a markdown brief composed from the same vault projection
+ * `vault-info` returns, so an agent has everything it needs to orient
+ * itself before issuing a single query. Stats are included so the count
+ * line ("N notes, M tags") is always populated.
+ *
+ * When `auth` carries `scoped_tags`, the projection is filtered to those
+ * tags + descendants before rendering — symmetric with the JSON
+ * `vault-info` wrapper, so a tag-scoped token never learns about
+ * out-of-scope tags via the connect-time brief either. Aggregate counts
+ * pass through unchanged (they were pre-existing leak surface; not new).
+ *
+ * Async because expanding the tag-scope allowlist hits the store's
+ * hierarchy resolver. Returns the orientation block even when the vault
+ * has no description or schemas — empty vaults still get the query-hint
+ * catalog and refresh pointers.
  */
-export function getServerInstruction(vaultName: string): string {
+export async function getServerInstruction(
+  vaultName: string,
+  auth?: AuthResult,
+): Promise<string> {
   const config = readVaultConfig(vaultName);
+  const store = getVaultStore(vaultName);
+  let projection = buildVaultProjection(store.db, { includeStats: true });
 
-  const parts: string[] = [
-    `You are connected to Parachute Vault "${vaultName}".`,
-  ];
-
-  if (config?.description) {
-    parts.push("", config.description);
+  if (auth?.scoped_tags && auth.scoped_tags.length > 0) {
+    const allowed = await expandTokenTagScope(store, auth.scoped_tags);
+    if (allowed) projection = filterProjectionByScope(projection, allowed);
   }
 
-  return parts.join("\n");
+  return projectionToMarkdown({
+    vaultName,
+    description: config?.description ?? null,
+    projection,
+  });
 }
 
 /**
@@ -92,10 +147,11 @@ function applyTagDependencyGuards(tools: McpToolDef[], vaultName: string): void
  * unscoped sessions retain identical pre-tag-scope behavior.
  *
  * Read tools handled here:
- *   - query-notes:      filter single-note returns + result lists
- *   - list-tags:        filter to allowlisted tags + descendants
- *   - find-path:        require both endpoints (and every hop) in scope
- *   - synthesize-notes: anchor + neighbors all gated by scope
+ *   - query-notes: filter single-note returns + result lists
+ *   - list-tags:   filter to allowlisted tags + descendants
+ *   - find-path:   require both endpoints (and every hop) in scope
+ *   - vault-info:  filter projection.tags + projection.indexed_fields
+ *                  to entries an in-scope tag contributes to
  *
  * Write-tool gating happens in handleScopedMcp at the verb-scope layer
  * AND inside each tool's wrapper here (so a tag-scoped `vault:write`
@@ -155,28 +211,30 @@ function applyTagScopeWrappers(
     return result;
   });
 
-  wrapReadTool(tools, "synthesize-notes", async (orig, params) => {
+  // vault-info projection (#271): filter the tags catalog to in-scope tags
+  // and the indexed_fields catalog to fields with at least one in-scope
+  // declarer. Within each surviving indexed_fields entry, also drop
+  // out-of-scope declarer names from the `tags` array — a token scoped to
+  // `task` shouldn't learn that `project` declares `status` too. Other
+  // top-level keys (name, description, query_hints, stats) pass through:
+  // counts are aggregate and existing pre-#271 behavior already returned
+  // them to scoped tokens. The same `filterProjectionByScope` helper backs
+  // `getServerInstruction` so the JSON tool and the connect-time markdown
+  // brief stay in lockstep.
+  wrapReadTool(tools, "vault-info", async (orig, params) => {
     const allowed = await getAllowed();
-    if (!allowed) return await orig(params);
-    // Verify the anchor is in scope first — out-of-scope anchor 404s as if
-    // the note doesn't exist, mirroring the REST find-path semantics.
-    const anchorId = (params as any).id ?? (params as any).note_id;
-    if (anchorId) {
-      const anchor = await store.getNote(anchorId as string);
-      if (!anchor || !noteWithinTagScope(anchor, allowed, rawTags)) {
-        return { error: "Note not found", id: anchorId };
-      }
-    }
     const result = await orig(params);
-    // Filter neighbors to those in scope. The synthesize-notes shape exposes
-    // `neighbors` (array of note objects with tags) — mirror the query-notes
-    // filter pattern here.
-    if (result && typeof result === "object" && Array.isArray((result as any).neighbors)) {
-      (result as any).neighbors = (result as any).neighbors.filter((n: any) =>
-        noteWithinTagScope(n, allowed, rawTags),
-      );
-    }
-    return result;
+    if (!allowed || !result || typeof result !== "object") return result;
+    const r = result as Record<string, unknown> & Partial<VaultProjection>;
+    const partial: VaultProjection = {
+      tags: Array.isArray(r.tags) ? r.tags : [],
+      indexed_fields: Array.isArray(r.indexed_fields) ? r.indexed_fields : [],
+      query_hints: Array.isArray(r.query_hints) ? r.query_hints : [],
+    };
+    const filtered = filterProjectionByScope(partial, allowed);
+    r.tags = filtered.tags;
+    r.indexed_fields = filtered.indexed_fields;
+    return r;
   });
 
   // ---- Write-side guards ----
@@ -266,59 +324,6 @@ function applyTagScopeWrappers(
     return await orig(params);
   });
 
-  // Note-schemas mappings — same auth boundary as REST `handleNoteSchemas`.
-  // `tag`-kind mappings are tag-scoped data; `path_prefix`-kind mappings carry
-  // no tag-axis information and stay visible/writable. The single-tag check
-  // delegates to `tagsWithinScope` so the string-form fallback is honored.
-
-  wrapReadTool(tools, "list-note-schemas", async (orig, params) => {
-    const allowed = await getAllowed();
-    if (!allowed) return await orig(params);
-    const result = await orig(params);
-    const filterMappings = (mappings: any[]): any[] =>
-      mappings.filter(
-        (m: any) => m.match_kind !== "tag" || tagsWithinScope([m.match_value], allowed, rawTags),
-      );
-    if (Array.isArray(result)) {
-      return result.map((s: any) =>
-        Array.isArray(s.mappings) ? { ...s, mappings: filterMappings(s.mappings) } : s,
-      );
-    }
-    if (result && typeof result === "object" && Array.isArray((result as any).mappings)) {
-      return { ...(result as any), mappings: filterMappings((result as any).mappings) };
-    }
-    return result;
-  });
-
-  wrapReadTool(tools, "set-schema-mapping", async (orig, params) => {
-    const allowed = await getAllowed();
-    if (!allowed) return await orig(params);
-    const match_kind = (params as any).match_kind;
-    const match_value = (params as any).match_value;
-    if (
-      match_kind === "tag" &&
-      typeof match_value === "string" &&
-      !tagsWithinScope([match_value], allowed, rawTags)
-    ) {
-      return forbidden(`set-schema-mapping: tag "${match_value}" is outside the token's allowlist`);
-    }
-    return await orig(params);
-  });
-
-  wrapReadTool(tools, "delete-schema-mapping", async (orig, params) => {
-    const allowed = await getAllowed();
-    if (!allowed) return await orig(params);
-    const match_kind = (params as any).match_kind;
-    const match_value = (params as any).match_value;
-    if (
-      match_kind === "tag" &&
-      typeof match_value === "string" &&
-      !tagsWithinScope([match_value], allowed, rawTags)
-    ) {
-      return forbidden(`delete-schema-mapping: tag "${match_value}" is outside the token's allowlist`);
-    }
-    return await orig(params);
-  });
 }
 
 function wrapReadTool(
@@ -364,14 +369,20 @@ function overrideVaultInfo(
       writeVaultConfig(config);
     }
 
-    const result: any = {
+    const store = getVaultStore(vaultName);
+    const includeStats = Boolean(params.include_stats);
+    const projection = buildVaultProjection(store.db, { includeStats });
+
+    const result: Record<string, unknown> = {
       name: config.name,
       description: config.description ?? null,
+      tags: projection.tags,
+      indexed_fields: projection.indexed_fields,
+      query_hints: projection.query_hints,
     };
 
-    if (params.include_stats) {
-      const store = getVaultStore(vaultName);
-      result.stats = await store.getVaultStats();
+    if (projection.stats) {
+      result.stats = projection.stats;
     }
 
     return result;