@dudamel/mcp-context 0.1.0

package/dist/context-client.d.ts

@@ -0,0 +1,70 @@
+import type { DirectoryCatalog, FileReadResponse, GrepHit, ReadCsvResponse, ReadSectionResponse, ReadYamlResponse, SearchResult, StatResponse, TailResponse, TreeResponse } from './types.js';
+export interface GrepRequest {
+    pattern: string;
+    path?: string;
+    maxResults?: number;
+    fixedString?: boolean;
+    ignoreCase?: boolean;
+}
+export interface FindRequest {
+    name: string;
+    path?: string;
+    maxResults?: number;
+    type?: 'f' | 'd';
+}
+/**
+ * HTTP client for the dudamel context-server. The context-server is the single
+ * source of truth for the VFS — directory layout, per-directory .index.yaml
+ * catalogs, and on-disk files. The MCP adapts those HTTP endpoints into tool
+ * calls for the LLM.
+ */
+export declare class ContextServerError extends Error {
+    readonly status: number;
+    readonly url: string;
+    constructor(message: string, status: number, url: string);
+}
+export interface ContextServerClientOptions {
+    /**
+     * Base URL for the HTTP backend.
+     *   - direct: the context-server itself (e.g. http://context-server:3001).
+     *   - proxy:  orchestrator base URL (we append /api/context to paths).
+     */
+    baseUrl: string;
+    /** When set, switches to proxy mode and adds Authorization: ApiKey <apiKey>. */
+    apiKey?: string;
+}
+export declare class ContextServerClient {
+    private readonly baseUrl;
+    private readonly apiKey?;
+    private readonly pathPrefix;
+    constructor(options: ContextServerClientOptions);
+    private url;
+    private headers;
+    private get;
+    private post;
+    grep(req: GrepRequest): Promise<SearchResult<GrepHit>>;
+    find(req: FindRequest): Promise<SearchResult<string>>;
+    stat(path: string): Promise<StatResponse>;
+    tree(path?: string, maxDepth?: number): Promise<TreeResponse>;
+    tail(path: string, lines?: number): Promise<TailResponse>;
+    readSection(path: string, heading?: string): Promise<ReadSectionResponse>;
+    readYaml(path: string, keyPath?: string): Promise<ReadYamlResponse>;
+    readCsv(path: string, opts?: {
+        filterColumn?: string;
+        filterValue?: string;
+        columns?: string[];
+        maxRows?: number;
+    }): Promise<ReadCsvResponse>;
+    /**
+     * Fetch a file's raw text from the VFS. Path is VFS-relative:
+     *   "AGENTS.md"  -> /data/context/AGENTS.md
+     *   "src/foo"    -> /data/context/src/foo
+     */
+    readFile(vfsPath: string): Promise<FileReadResponse>;
+    /**
+     * Parsed .index.yaml for a directory.
+     * `dirPath` is VFS-relative: "source" or "source/sub/dir".
+     */
+    readDirectoryCatalog(dirPath: string): Promise<DirectoryCatalog>;
+}
+//# sourceMappingURL=context-client.d.ts.map

package/dist/context-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-client.d.ts","sourceRoot":"","sources":["../src/context-client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,gBAAgB,EAChB,gBAAgB,EAChB,OAAO,EACP,eAAe,EACf,mBAAmB,EACnB,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,GAAG,GAAG,GAAG,CAAC;CAClB;AAED;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAGzC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM;gBAFpB,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM;CAKvB;AAED,MAAM,WAAW,0BAA0B;IACzC;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,OAAO,EAAE,0BAA0B;IAM/C,OAAO,CAAC,GAAG;IAKX,OAAO,CAAC,OAAO;YAMD,GAAG;YAcH,IAAI;IAkBlB,IAAI,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;IAItD,IAAI,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;IAIrD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAIzC,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAI7D,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAIzD,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAIzE,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAInE,OAAO,CACL,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAC3F,OAAO,CAAC,eAAe,CAAC;IAI3B;;;;OAIG;IACG,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAY1D;;;OAGG;IACG,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAMvE"}

package/dist/context-client.js

@@ -0,0 +1,118 @@
+import yaml from 'js-yaml';
+/**
+ * HTTP client for the dudamel context-server. The context-server is the single
+ * source of truth for the VFS — directory layout, per-directory .index.yaml
+ * catalogs, and on-disk files. The MCP adapts those HTTP endpoints into tool
+ * calls for the LLM.
+ */
+export class ContextServerError extends Error {
+    status;
+    url;
+    constructor(message, status, url) {
+        super(message);
+        this.status = status;
+        this.url = url;
+        this.name = 'ContextServerError';
+    }
+}
+export class ContextServerClient {
+    baseUrl;
+    apiKey;
+    pathPrefix;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, '');
+        this.apiKey = options.apiKey;
+        this.pathPrefix = this.apiKey ? '/api/context' : '';
+    }
+    url(path) {
+        if (!path.startsWith('/'))
+            throw new Error(`ContextServerClient path must start with "/", got "${path}"`);
+        return `${this.baseUrl}${this.pathPrefix}${path}`;
+    }
+    headers(extra) {
+        const out = { ...(extra ?? {}) };
+        if (this.apiKey)
+            out['Authorization'] = `ApiKey ${this.apiKey}`;
+        return out;
+    }
+    async get(path) {
+        const target = this.url(path);
+        const res = await fetch(target, { method: 'GET', headers: this.headers() });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            throw new ContextServerError(`GET ${path} -> ${res.status}${body ? `: ${body}` : ''}`, res.status, target);
+        }
+        return (await res.json());
+    }
+    async post(path, body) {
+        const target = this.url(path);
+        const res = await fetch(target, {
+            method: 'POST',
+            headers: this.headers({ 'Content-Type': 'application/json' }),
+            body: JSON.stringify(body ?? {}),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new ContextServerError(`POST ${path} -> ${res.status}${text ? `: ${text}` : ''}`, res.status, target);
+        }
+        return (await res.json());
+    }
+    grep(req) {
+        return this.post('/search/grep', req);
+    }
+    find(req) {
+        return this.post('/search/find', req);
+    }
+    stat(path) {
+        return this.post('/search/stat', { path });
+    }
+    tree(path, maxDepth) {
+        return this.post('/search/tree', { path, maxDepth });
+    }
+    tail(path, lines) {
+        return this.post('/search/tail', { path, lines });
+    }
+    readSection(path, heading) {
+        return this.post('/search/section', { path, heading });
+    }
+    readYaml(path, keyPath) {
+        return this.post('/search/yaml', { path, keyPath });
+    }
+    readCsv(path, opts) {
+        return this.post('/search/csv', { path, ...opts });
+    }
+    /**
+     * Fetch a file's raw text from the VFS. Path is VFS-relative:
+     *   "AGENTS.md"  -> /data/context/AGENTS.md
+     *   "src/foo"    -> /data/context/src/foo
+     */
+    async readFile(vfsPath) {
+        const segments = vfsPath.split('/').filter((s) => s.length > 0);
+        if (segments.length === 0)
+            throw new Error('Path cannot be empty');
+        const [sourceName, ...rest] = segments;
+        const encoded = encodeURIComponent(sourceName);
+        const url = rest.length === 0
+            ? `/read/${encoded}`
+            : `/read/${encoded}/${rest.map(encodeURIComponent).join('/')}`;
+        return this.get(url);
+    }
+    /**
+     * Parsed .index.yaml for a directory.
+     * `dirPath` is VFS-relative: "source" or "source/sub/dir".
+     */
+    async readDirectoryCatalog(dirPath) {
+        const trimmed = dirPath.replace(/\/$/, '');
+        const catalogPath = trimmed.length === 0 ? '.index.yaml' : `${trimmed}/.index.yaml`;
+        const raw = await this.readFile(catalogPath);
+        return parseCatalog(raw.content);
+    }
+}
+function parseCatalog(text) {
+    const parsed = yaml.load(text);
+    if (parsed == null || typeof parsed !== 'object') {
+        throw new Error(`Catalog YAML did not parse into an object: ${typeof parsed}`);
+    }
+    return parsed;
+}
+//# sourceMappingURL=context-client.js.map

package/dist/context-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-client.js","sourceRoot":"","sources":["../src/context-client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createContextServer } from './server.js';
+export { ContextServerClient, ContextServerError } from './context-client.js';
+export type { McpContextConfig, CatalogEntry, DirectoryCatalog, FileReadResponse } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9E,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createContextServer } from './server.js';
+export { ContextServerClient, ContextServerError } from './context-client.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { McpContextConfig } from './types.js';
+export declare function createContextServer(config: McpContextConfig): Promise<McpServer>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAMpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAiEnD,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,CAAC,CA8BtF"}

package/dist/server.js

@@ -0,0 +1,90 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ContextServerClient } from './context-client.js';
+import { registerInstructionsTool } from './tools/instructions.js';
+import { registerListSourcesTool, registerBrowseTool, registerTreeTool } from './tools/navigate.js';
+import { registerReadFileTool, registerStatTool, registerTailTool, registerReadSectionTool, registerReadYamlTool, registerReadCsvTool } from './tools/read.js';
+import { registerGrepTool, registerFindTool } from './tools/search.js';
+const BASE_INSTRUCTIONS = `
+Dudamel Context MCP — read-only access to the organization's knowledge base (the VFS).
+
+Call \`get_instructions\` on your first interaction for background on the .index.yaml
+catalog convention. Not required — the tools work without it, but it helps you
+understand the data model the first time.
+
+Typical workflow:
+  1. get_instructions          — understand the conventions
+  2. list_sources              — see what knowledge bases exist
+  3. browse <path>             — explore a source; read catalog descriptions
+  4. tree <path>               — compact recursive map of a subtree in one call
+  5. stat <path>               — check size / line count before reading large files
+  6. read_file <path>          — fetch actual content when it's relevant
+  7. read_section <path, h>    — pull one markdown section instead of the whole file
+  8. read_yaml <path, key>     — navigate a YAML file by dot-path key
+  9. read_csv <path, filter>   — query a CSV file with column filtering
+  10. tail <path>              — peek at the end of a file (logs, recent entries)
+  11. grep / find              — search content or filenames across the VFS
+
+Prefer reading catalog descriptions (via \`browse\`) over reading full files —
+catalogs are dense summaries. Use \`grep\`/\`find\` to locate things you don't
+already have a path for; scope them with \`path\` when you can.
+`.trim();
+/**
+ * Fetch the root catalog and render a "available sources" section the LLM can
+ * match against. Descriptions are generated by the indexer from actual source
+ * content, so this is how the server tells the model what topics it covers
+ * without anyone hardcoding "use this for Luna Lines" — the data is per-org.
+ * Falls back silently to the static base instructions if the catalog can't
+ * be reached (fresh deploy, network hiccup, etc.).
+ */
+async function buildInstructions(client) {
+    try {
+        const catalog = await client.readDirectoryCatalog('');
+        const entries = catalog.entries ?? [];
+        if (entries.length === 0)
+            return BASE_INSTRUCTIONS;
+        const sourceLines = entries
+            .map((e) => `- **${e.path}** — ${e.description || '(no description yet — call browse for details)'}`)
+            .join('\n');
+        const discovery = `
+## Available knowledge sources
+
+This server is the authoritative source for the topics below. **When the user
+asks about anything that overlaps with these descriptions, use this server's
+tools before answering from memory** — call \`browse\`/\`grep\`/\`read_file\`
+to confirm the current state rather than guessing.
+
+${sourceLines}
+`.trim();
+        return `${BASE_INSTRUCTIONS}\n\n${discovery}`;
+    }
+    catch {
+        // Best-effort — if we can't reach the context-server at init time, ship
+        // the static instructions. Subsequent tool calls will fail the same way
+        // and surface the real error to the LLM.
+        return BASE_INSTRUCTIONS;
+    }
+}
+export async function createContextServer(config) {
+    const client = config.mode === 'proxy'
+        ? new ContextServerClient({ baseUrl: config.baseUrl, apiKey: config.apiKey })
+        : new ContextServerClient({ baseUrl: config.baseUrl });
+    const instructions = await buildInstructions(client);
+    const server = new McpServer({ name: 'dudamel-context', version: '0.1.0' }, {
+        capabilities: { tools: {} },
+        instructions,
+    });
+    registerInstructionsTool(server, client);
+    registerListSourcesTool(server, client);
+    registerBrowseTool(server, client);
+    registerTreeTool(server, client);
+    registerReadFileTool(server, client);
+    registerReadSectionTool(server, client);
+    registerReadYamlTool(server, client);
+    registerReadCsvTool(server, client);
+    registerStatTool(server, client);
+    registerTailTool(server, client);
+    registerGrepTool(server, client);
+    registerFindTool(server, client);
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/stdio-server.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * stdio entry point for the Dudamel Context MCP.
+ *
+ * Two mutually-exclusive connection modes:
+ *
+ *   1. Remote (preferred for external clients: Claude Code, Cursor, …):
+ *        DUDAMEL_API_URL  — e.g. https://dudamel.example.com
+ *        DUDAMEL_API_KEY  — API key for authentication
+ *      Goes through the authenticated /api/context proxy on the orchestrator.
+ *
+ *   2. Direct (internal, inside the compose network):
+ *        DUDAMEL_CONTEXT_SERVER_URL — defaults to http://context-server:3001
+ */
+export {};
+//# sourceMappingURL=stdio-server.d.ts.map

package/dist/stdio-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio-server.d.ts","sourceRoot":"","sources":["../src/stdio-server.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;GAYG"}

package/dist/stdio-server.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * stdio entry point for the Dudamel Context MCP.
+ *
+ * Two mutually-exclusive connection modes:
+ *
+ *   1. Remote (preferred for external clients: Claude Code, Cursor, …):
+ *        DUDAMEL_API_URL  — e.g. https://dudamel.example.com
+ *        DUDAMEL_API_KEY  — API key for authentication
+ *      Goes through the authenticated /api/context proxy on the orchestrator.
+ *
+ *   2. Direct (internal, inside the compose network):
+ *        DUDAMEL_CONTEXT_SERVER_URL — defaults to http://context-server:3001
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createContextServer } from './server.js';
+function resolveConfig() {
+    const apiUrl = process.env.DUDAMEL_API_URL?.trim();
+    const apiKey = process.env.DUDAMEL_API_KEY?.trim();
+    if (apiUrl && apiKey) {
+        return { mode: 'proxy', baseUrl: apiUrl, apiKey };
+    }
+    if (apiUrl && !apiKey) {
+        process.stderr.write('[dudamel-mcp-context] DUDAMEL_API_URL is set but DUDAMEL_API_KEY is missing — refusing to connect without auth.\n');
+        process.exit(2);
+    }
+    const direct = process.env.DUDAMEL_CONTEXT_SERVER_URL?.trim() || 'http://context-server:3001';
+    return { mode: 'direct', baseUrl: direct };
+}
+async function main() {
+    const config = resolveConfig();
+    const server = await createContextServer(config);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // The SDK keeps the event loop alive while the transport is open; exit on
+    // stdin EOF so the process doesn't hang when the parent goes away.
+    process.stdin.on('end', () => process.exit(0));
+}
+void main().catch((error) => {
+    // Stdio MCPs must never write to stdout outside the protocol; stderr is safe.
+    process.stderr.write(`[dudamel-mcp-context] fatal: ${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=stdio-server.js.map

package/dist/stdio-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio-server.js","sourceRoot":"","sources":["../src/stdio-server.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAGlD,SAAS,aAAa;IACpB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,EAAE,CAAC;IACnD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,EAAE,CAAC;IAEnD,IAAI,MAAM,IAAI,MAAM,EAAE,CAAC;QACrB,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IACpD,CAAC;IACD,IAAI,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;QACtB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,mHAAmH,CAAC,CAAC;QAC1I,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,0BAA0B,EAAE,IAAI,EAAE,IAAI,4BAA4B,CAAC;IAC9F,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AAC7C,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,aAAa,EAAE,CAAC;IAC/B,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,MAAM,CAAC,CAAC;IACjD,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,0EAA0E;IAC1E,mEAAmE;IACnE,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,KAAK,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IAC1B,8EAA8E;IAC9E,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,gCAAgC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAC1G,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/tools/instructions.d.ts

@@ -0,0 +1,10 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ContextServerClient } from '../context-client.js';
+/**
+ * `get_instructions` — returns the AGENTS.md file at the VFS root, which
+ * teaches the agent the `.index.yaml` navigation pattern. Every other tool's
+ * description points here, and the server `instructions` field also tells the
+ * LLM to call this first.
+ */
+export declare function registerInstructionsTool(server: McpServer, client: ContextServerClient): void;
+//# sourceMappingURL=instructions.d.ts.map

package/dist/tools/instructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../../src/tools/instructions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAGhE;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAoC7F"}

package/dist/tools/instructions.js

@@ -0,0 +1,40 @@
+import { ContextServerError } from '../context-client.js';
+/**
+ * `get_instructions` — returns the AGENTS.md file at the VFS root, which
+ * teaches the agent the `.index.yaml` navigation pattern. Every other tool's
+ * description points here, and the server `instructions` field also tells the
+ * LLM to call this first.
+ */
+export function registerInstructionsTool(server, client) {
+    server.tool('get_instructions', 'Read the usage guide for this knowledge base (AGENTS.md). Recommended on your first interaction — it explains the .index.yaml catalog structure and navigation conventions. Not required: `list_sources` and `browse` work without it.', {}, async () => {
+        try {
+            const result = await client.readFile('AGENTS.md');
+            return {
+                content: [{ type: 'text', text: result.content }],
+            };
+        }
+        catch (error) {
+            if (error instanceof ContextServerError && error.status === 404) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'No AGENTS.md was found at the VFS root. The admin may not have seeded one yet. ' +
+                                'For reference, each directory should contain a .index.yaml like:\n\n' +
+                                '```yaml\n' +
+                                'description: "Summary of this directory"\n' +
+                                'entries:\n' +
+                                '  - path: file.md\n' +
+                                '    type: file\n' +
+                                '    description: "Summary of this file"\n' +
+                                '```\n\n' +
+                                'Start by calling `list_sources`, then `browse` to drill down, and `read_file` for actual content.',
+                        },
+                    ],
+                };
+            }
+            throw error;
+        }
+    });
+}
+//# sourceMappingURL=instructions.js.map

package/dist/tools/instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../src/tools/instructions.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CAAC,MAAiB,EAAE,MAA2B;IACrF,MAAM,CAAC,IAAI,CACT,kBAAkB,EAClB,wOAAwO,EACxO,EAAE,EACF,KAAK,IAAI,EAAE;QACT,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;YAClD,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;aAClD,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,kBAAkB,IAAI,KAAK,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;gBAChE,OAAO;oBACL,OAAO,EAAE;wBACP;4BACE,IAAI,EAAE,MAAM;4BACZ,IAAI,EACF,iFAAiF;gCACjF,sEAAsE;gCACtE,WAAW;gCACX,4CAA4C;gCAC5C,YAAY;gCACZ,qBAAqB;gCACrB,kBAAkB;gCAClB,2CAA2C;gCAC3C,SAAS;gCACT,mGAAmG;yBACtG;qBACF;iBACF,CAAC;YACJ,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/navigate.d.ts

@@ -0,0 +1,22 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ContextServerClient } from '../context-client.js';
+/**
+ * `list_sources` — top-level entry point. Returns the source catalog
+ * generated from /data/context/.index.yaml, where each source is a
+ * directory with its own subtree and `.index.yaml`.
+ */
+export declare function registerListSourcesTool(server: McpServer, client: ContextServerClient): void;
+/**
+ * `browse` — the ls-with-descriptions primitive. Returns the description of
+ * the directory itself plus the entries inside (files and subdirectories),
+ * each with their own description. One tool call per directory is enough to
+ * decide what to drill into next.
+ */
+export declare function registerBrowseTool(server: McpServer, client: ContextServerClient): void;
+/**
+ * `tree` — a compact recursive listing of a VFS subtree. One call gives a
+ * full picture of everything available under `path`, up to `maxDepth` levels.
+ * Rendered as an indented outline so the LLM can scan it line-by-line.
+ */
+export declare function registerTreeTool(server: McpServer, client: ContextServerClient): void;
+//# sourceMappingURL=navigate.d.ts.map

package/dist/tools/navigate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigate.d.ts","sourceRoot":"","sources":["../../src/tools/navigate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAIhE;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAsB5F;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAkDvF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAmCrF"}

package/dist/tools/navigate.js

@@ -0,0 +1,121 @@
+import { z } from 'zod';
+import { ContextServerError } from '../context-client.js';
+/**
+ * `list_sources` — top-level entry point. Returns the source catalog
+ * generated from /data/context/.index.yaml, where each source is a
+ * directory with its own subtree and `.index.yaml`.
+ */
+export function registerListSourcesTool(server, client) {
+    server.tool('list_sources', 'List the top-level knowledge sources in this VFS. Each source is a directory at the VFS root with its own documentation tree. Use this to discover what is available, then call `browse` on a source to explore it. If you have not read the usage guide yet, call `get_instructions` first.', {}, async () => {
+        const catalog = await client.readDirectoryCatalog('');
+        const entries = catalog.entries ?? [];
+        if (entries.length === 0) {
+            return {
+                content: [{ type: 'text', text: 'No sources are configured in the VFS yet.' }],
+            };
+        }
+        const text = entries
+            .map((e) => `- **${e.path}** — ${e.description || '(no description)'}`)
+            .join('\n');
+        return { content: [{ type: 'text', text }] };
+    });
+}
+/**
+ * `browse` — the ls-with-descriptions primitive. Returns the description of
+ * the directory itself plus the entries inside (files and subdirectories),
+ * each with their own description. One tool call per directory is enough to
+ * decide what to drill into next.
+ */
+export function registerBrowseTool(server, client) {
+    server.tool('browse', 'List the contents of a directory in the VFS with a description for each entry. Path is VFS-relative, e.g. "my-source" or "my-source/subdir". Omit `path` to browse the root. Prefer this over `read_file` for navigation — reading catalog descriptions is much cheaper than reading every file.', {
+        path: z
+            .string()
+            .optional()
+            .describe('VFS path to the directory. Examples: "my-source", "my-source/tech", "". Leave empty for the root.'),
+    }, async ({ path }) => {
+        const normalised = (path ?? '').replace(/\/$/, '');
+        try {
+            const catalog = await client.readDirectoryCatalog(normalised);
+            const lines = [
+                normalised === '' ? '# / (root)' : `# /${normalised}`,
+                '',
+                catalog.description ? catalog.description : '(no directory description)',
+                '',
+                '## Entries',
+            ];
+            if (!catalog.entries || catalog.entries.length === 0) {
+                lines.push('_(empty)_');
+            }
+            else {
+                for (const entry of catalog.entries) {
+                    lines.push(`- **${entry.path}** (${entry.type}) — ${entry.description || '(no description)'}`);
+                }
+            }
+            return { content: [{ type: 'text', text: lines.join('\n') }] };
+        }
+        catch (error) {
+            if (error instanceof ContextServerError && error.status === 404) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `No directory catalog found at "${normalised}". The path may not exist or may not have been indexed yet. Try \`list_sources\` to see what's available.`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            throw error;
+        }
+    });
+}
+/**
+ * `tree` — a compact recursive listing of a VFS subtree. One call gives a
+ * full picture of everything available under `path`, up to `maxDepth` levels.
+ * Rendered as an indented outline so the LLM can scan it line-by-line.
+ */
+export function registerTreeTool(server, client) {
+    server.tool('tree', 'Recursively list directories + files under a VFS path, with depth information. Returns a compact outline — much cheaper than chained `browse` calls when you want a broad map. Defaults to depth 3; max 10.', {
+        path: z
+            .string()
+            .optional()
+            .describe('VFS path to the subtree root. Examples: "my-source", "my-source/tech". Omit for the whole VFS.'),
+        maxDepth: z
+            .number()
+            .int()
+            .min(1)
+            .max(10)
+            .optional()
+            .describe('How many levels deep to descend (default 3, hard cap 10).'),
+    }, async ({ path, maxDepth }) => {
+        const result = await client.tree(path, maxDepth);
+        if (result.entries.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `No entries under ${result.root ? `"${result.root}"` : 'the VFS root'} (or it doesn't exist).`,
+                    },
+                ],
+            };
+        }
+        const lines = formatTree(result.entries);
+        const footer = result.truncated ? '\n\n(truncated — pass a more specific `path` or a smaller `maxDepth`)' : '';
+        const header = result.root ? `# /${result.root}\n` : '# / (root)\n';
+        return { content: [{ type: 'text', text: header + lines + footer }] };
+    });
+}
+function formatTree(entries) {
+    return entries
+        .map((e) => {
+        const indent = '  '.repeat(Math.max(0, e.depth - 1));
+        const suffix = e.type === 'directory' ? '/' : '';
+        // Show only the leaf name so the indent carries hierarchy; keep full path
+        // available for follow-up tool calls via the leading `  ` (agents can
+        // reconstruct it or we can be explicit). Being explicit is cheaper to
+        // read — emit the full path.
+        return `${indent}- ${e.path}${suffix}`;
+    })
+        .join('\n');
+}
+//# sourceMappingURL=navigate.js.map

package/dist/tools/navigate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigate.js","sourceRoot":"","sources":["../../src/tools/navigate.ts"],"names":[],"mappings":"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"}