opencontext-mcp 1.2.1 → 1.3.0

package/dist/init/prompts.js

@@ -0,0 +1,17 @@
+/**
+ * Prompts the user for a yes/no answer.
+ * @param rl - Readline interface
+ * @param message - Prompt message
+ * @param defaultYes - Default answer when the user presses Enter
+ * @returns true if user confirms
+ */
+export async function promptForConfirm(rl, message, defaultYes = false) {
+    const hint = defaultYes ? "Y/n" : "y/N";
+    const answer = await rl.question(`${message} (${hint}): `);
+    const trimmed = answer.trim().toLowerCase();
+    if (trimmed === "") {
+        return defaultYes;
+    }
+    return trimmed === "y" || trimmed === "yes";
+}
+//# sourceMappingURL=prompts.js.map

package/dist/init/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../../src/init/prompts.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,EAAsB,EACtB,OAAe,EACf,UAAU,GAAG,KAAK;IAElB,MAAM,IAAI,GAAG,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;IACxC,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,GAAG,OAAO,KAAK,IAAI,KAAK,CAAC,CAAC;IAC3D,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC5C,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QACnB,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,OAAO,OAAO,KAAK,GAAG,IAAI,OAAO,KAAK,KAAK,CAAC;AAC9C,CAAC"}

package/dist/server/http.d.ts

@@ -0,0 +1,21 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export interface HttpServerOptions {
+    host: string;
+    port: number;
+    buildServer: () => Promise<McpServer>;
+}
+export interface HttpServerHandle {
+    /** Fully-qualified MCP endpoint URL, e.g. http://127.0.0.1:3001/mcp */
+    url: string;
+    close: () => Promise<void>;
+}
+/**
+ * Serves an MCP server over HTTP using the Streamable HTTP transport.
+ *
+ * Each request gets a fresh server instance and a stateless transport, matching
+ * the MCP Streamable HTTP reference pattern: no sessions are tracked in memory.
+ *
+ * @param options - Host, port, and a server factory
+ * @returns The endpoint URL and a close handle
+ */
+export declare function startHttpServer(options: HttpServerOptions): Promise<HttpServerHandle>;

package/dist/server/http.js

@@ -0,0 +1,63 @@
+import { createServer, } from "node:http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { SERVER_NAME, SERVER_VERSION } from "../shared/constants.js";
+import { getErrorMessage } from "../shared/errors.js";
+/**
+ * Serves an MCP server over HTTP using the Streamable HTTP transport.
+ *
+ * Each request gets a fresh server instance and a stateless transport, matching
+ * the MCP Streamable HTTP reference pattern: no sessions are tracked in memory.
+ *
+ * @param options - Host, port, and a server factory
+ * @returns The endpoint URL and a close handle
+ */
+export async function startHttpServer(options) {
+    const handleRequest = async (req, res) => {
+        if (req.method === "GET" && req.url === "/") {
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ name: SERVER_NAME, version: SERVER_VERSION }));
+            return;
+        }
+        try {
+            const mcpServer = await options.buildServer();
+            // Omitting sessionIdGenerator puts the transport in stateless mode.
+            const transport = new StreamableHTTPServerTransport();
+            await mcpServer.connect(transport);
+            try {
+                await transport.handleRequest(req, res);
+            }
+            finally {
+                await mcpServer.close();
+            }
+        }
+        catch (error) {
+            if (!res.headersSent) {
+                res.writeHead(500, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({
+                    jsonrpc: "2.0",
+                    error: { code: -32603, message: getErrorMessage(error) },
+                    id: null,
+                }));
+            }
+        }
+    };
+    const server = createServer(handleRequest);
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(options.port, options.host, () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    const address = server.address();
+    const boundPort = typeof address === "object" && address !== null ? address.port : options.port;
+    const displayHost = options.host === "0.0.0.0" || options.host === "::" ? "localhost" : options.host;
+    const url = `http://${displayHost}:${boundPort}/mcp`;
+    return {
+        url,
+        close: async () => {
+            await new Promise((resolve) => server.close(() => resolve()));
+        },
+    };
+}
+//# sourceMappingURL=http.js.map

package/dist/server/http.js.map

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

package/dist/{server.d.ts → server/index.d.ts}

@@ -1,5 +1,5 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { type ResolvedConfig } from "./config.js";
+import { type ResolvedConfig } from "../config/index.js";
 /**
  * Creates and configures the OpenContext MCP server.
  * Registers all available tools (save_context, read_context).
@@ -7,3 +7,5 @@ import { type ResolvedConfig } from "./config.js";
  * @param config - Optional pre-loaded config (loads from disk if omitted)
  */
 export declare function createOpenContextServer(basePath?: string, config?: ResolvedConfig): Promise<McpServer>;
+export { startHttpServer } from "./http.js";
+export type { HttpServerOptions, HttpServerHandle } from "./http.js";

package/dist/{server.js → server/index.js}

@@ -1,8 +1,10 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { ContextStore } from "./context-store.js";
-import { SERVER_NAME, SERVER_VERSION, getErrorMessage, textResult } from "./types.js";
-import { loadConfig } from "./config.js";
+import { ContextStore } from "../store/context-store.js";
+import { SERVER_NAME, SERVER_VERSION } from "../shared/constants.js";
+import { getErrorMessage } from "../shared/errors.js";
+import { textResult } from "../shared/types.js";
+import { loadConfig } from "../config/index.js";
 /**
  * Creates and configures the OpenContext MCP server.
  * Registers all available tools (save_context, read_context).
@@ -89,4 +91,5 @@ export async function createOpenContextServer(basePath, config) {
     });
     return server;
 }
-//# sourceMappingURL=server.js.map
+export { startHttpServer } from "./http.js";
+//# sourceMappingURL=index.js.map

package/dist/server/index.js.map

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

package/dist/shared/constants.d.ts

@@ -0,0 +1,27 @@
+/** MCP server identifier used in protocol handshakes. */
+export declare const SERVER_NAME = "opencontext-mcp";
+/** Current server version for compatibility checks. */
+export declare const SERVER_VERSION = "1.2.1";
+/** Filename for the auto-generated context index. */
+export declare const INDEX_FILENAME = "index.md";
+/** Package name published on npm, launched via npx in generated configs. */
+export declare const OPENCONTEXT_MCP_PACKAGE = "opencontext-mcp";
+/** Default host the HTTP(S) server binds to. */
+export declare const DEFAULT_HTTP_HOST = "127.0.0.1";
+/** Default port the HTTP(S) server listens on. */
+export declare const DEFAULT_HTTP_PORT = 3032;
+/** Topic names reserved by the system — cannot be written by external agents. */
+export declare const RESERVED_TOPICS: ReadonlySet<string>;
+/**
+ * Allowed values for the topic status field in YAML frontmatter.
+ * Kept next to the badges so both stay in sync.
+ */
+export type TopicStatus = "active" | "deprecated" | "superseded";
+/** Badge prefix used in index.md for non-active topics. */
+export declare const STATUS_BADGES: ReadonlyMap<TopicStatus, string>;
+/**
+ * Regex pattern for validating topic names.
+ * Allows lowercase alphanumeric with single hyphens or underscores as separators.
+ * Examples: "api_contracts", "auth-rules", "migration-v2"
+ */
+export declare const TOPIC_PATTERN: RegExp;

package/dist/shared/constants.js

@@ -0,0 +1,26 @@
+/** MCP server identifier used in protocol handshakes. */
+export const SERVER_NAME = "opencontext-mcp";
+/** Current server version for compatibility checks. */
+export const SERVER_VERSION = "1.2.1";
+/** Filename for the auto-generated context index. */
+export const INDEX_FILENAME = "index.md";
+/** Package name published on npm, launched via npx in generated configs. */
+export const OPENCONTEXT_MCP_PACKAGE = "opencontext-mcp";
+/** Default host the HTTP(S) server binds to. */
+export const DEFAULT_HTTP_HOST = "127.0.0.1";
+/** Default port the HTTP(S) server listens on. */
+export const DEFAULT_HTTP_PORT = 3032;
+/** Topic names reserved by the system — cannot be written by external agents. */
+export const RESERVED_TOPICS = new Set(["index"]);
+/** Badge prefix used in index.md for non-active topics. */
+export const STATUS_BADGES = new Map([
+    ["deprecated", "[DEPRECATED]"],
+    ["superseded", "[SUPERSEDED]"],
+]);
+/**
+ * Regex pattern for validating topic names.
+ * Allows lowercase alphanumeric with single hyphens or underscores as separators.
+ * Examples: "api_contracts", "auth-rules", "migration-v2"
+ */
+export const TOPIC_PATTERN = /^[a-z0-9]+(?:[_-][a-z0-9]+)*$/;
+//# sourceMappingURL=constants.js.map

package/dist/shared/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/shared/constants.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,MAAM,CAAC,MAAM,WAAW,GAAG,iBAAiB,CAAC;AAE7C,uDAAuD;AACvD,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AAEtC,qDAAqD;AACrD,MAAM,CAAC,MAAM,cAAc,GAAG,UAAU,CAAC;AAEzC,4EAA4E;AAC5E,MAAM,CAAC,MAAM,uBAAuB,GAAG,iBAAiB,CAAC;AAEzD,gDAAgD;AAChD,MAAM,CAAC,MAAM,iBAAiB,GAAG,WAAW,CAAC;AAE7C,kDAAkD;AAClD,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAEtC,iFAAiF;AACjF,MAAM,CAAC,MAAM,eAAe,GAAwB,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;AAQvE,2DAA2D;AAC3D,MAAM,CAAC,MAAM,aAAa,GAAqC,IAAI,GAAG,CAAC;IACrE,CAAC,YAAY,EAAE,cAAc,CAAC;IAC9B,CAAC,YAAY,EAAE,cAAc,CAAC;CAC/B,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,+BAA+B,CAAC"}

package/dist/shared/errors.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Custom error for user input validation problems.
+ * Thrown when topic names, content, or other user inputs fail validation.
+ */
+export declare class UserInputError extends Error {
+    constructor(message: string);
+}
+/**
+ * Safely extracts an error message from unknown error types.
+ * Handles Error objects, strings, and any other unexpected value.
+ */
+export declare function getErrorMessage(error: unknown): string;
+/**
+ * Type guard for Node.js filesystem errors.
+ * Lets callers distinguish ENOENT, EACCES, etc. from other failures.
+ */
+export declare function isNodeError(error: unknown): error is NodeJS.ErrnoException;

package/dist/shared/errors.js

@@ -0,0 +1,28 @@
+/**
+ * Custom error for user input validation problems.
+ * Thrown when topic names, content, or other user inputs fail validation.
+ */
+export class UserInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UserInputError";
+    }
+}
+/**
+ * Safely extracts an error message from unknown error types.
+ * Handles Error objects, strings, and any other unexpected value.
+ */
+export function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return "An unknown error occurred.";
+}
+/**
+ * Type guard for Node.js filesystem errors.
+ * Lets callers distinguish ENOENT, EACCES, etc. from other failures.
+ */
+export function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}
+//# sourceMappingURL=errors.js.map

package/dist/shared/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/shared/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC,OAAO,CAAC;IACvB,CAAC;IAED,OAAO,4BAA4B,CAAC;AACtC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,KAAK,YAAY,KAAK,IAAI,MAAM,IAAI,KAAK,CAAC;AACnD,CAAC"}

package/dist/shared/types.d.ts

@@ -0,0 +1,29 @@
+import type { TopicStatus } from "./constants.js";
+/** Outcome of a config/file upsert, used for user-facing status output. */
+export type ConfigStatus = "created" | "updated" | "unchanged" | "skipped";
+/** Result of writing or updating an agent integration config file. */
+export interface ConfigWriteResult {
+    status: ConfigStatus;
+    message: string;
+}
+/** Parsed YAML frontmatter from a topic file. All fields optional. */
+export interface TopicFrontmatter {
+    description?: string;
+    status?: TopicStatus;
+    /** The topic this one replaces (used by the newer topic). */
+    supersedes?: string;
+    /** The topic that replaced this one (used by the older topic). */
+    superseded_by?: string;
+}
+/**
+ * Creates a standardized MCP tool response object.
+ * @param text - Response message
+ * @param isError - Whether this is an error response (default: false)
+ */
+export declare function textResult(text: string, isError?: boolean): {
+    isError?: boolean;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};

package/dist/shared/types.js

@@ -0,0 +1,17 @@
+/**
+ * Creates a standardized MCP tool response object.
+ * @param text - Response message
+ * @param isError - Whether this is an error response (default: false)
+ */
+export function textResult(text, isError = false) {
+    return {
+        content: [
+            {
+                type: "text",
+                text,
+            },
+        ],
+        ...(isError ? { isError: true } : {}),
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/shared/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/shared/types.ts"],"names":[],"mappings":"AAqBA;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,OAAO,GAAG,KAAK;IACtD,OAAO;QACL,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAe;gBACrB,IAAI;aACL;SACF;QACD,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACtC,CAAC;AACJ,CAAC"}

package/dist/{context-store.d.ts → store/context-store.d.ts}

@@ -1,4 +1,4 @@
-import { type ResolvedConfig } from "./config.js";
+import { type ResolvedConfig } from "../config/index.js";
 /**
  * Manages context file storage operations.
  * Handles reading, writing, and listing context files in the configured directory.
@@ -14,7 +14,7 @@ export declare class ContextStore {
     getTopicFilePath(topic: string): string;
     /**
      * Saves context content to a topic file.
-     * Validates payload using WriteGuard before writing.
+     * Validates the payload using the write guard before writing.
      * @param topicInput - Topic name (will be validated and trimmed)
      * @param content - Markdown content to save
      * @returns Success message with file location
@@ -41,22 +41,8 @@ export declare class ContextStore {
      * @returns Sorted array of topic names
      */
     listTopics(): Promise<string[]>;
-    /**
-     * Parses YAML frontmatter from markdown content.
-     * Returns extracted fields or empty object if no frontmatter found.
-     * Uses simple line-by-line parsing — no external YAML dependency.
-     */
-    private parseFrontmatter;
-    /**
-     * Extracts a short description from markdown content.
-     * Strategy: frontmatter description → first heading → first paragraph → fallback.
-     * @param content - Raw markdown content
-     * @returns Truncated description (max 120 chars)
-     */
-    private extractDescription;
     /**
      * Rebuilds the auto-generated index.md file in the context directory.
-     * Scans all topic files, extracts metadata, and writes a compact index.
      * @returns The generated index markdown content
      */
     rebuildContextIndex(): Promise<string>;

package/dist/store/context-store.js

@@ -0,0 +1,147 @@
+import { mkdir, readdir, readFile, writeFile, lstat, unlink } from "node:fs/promises";
+import * as path from "node:path";
+import { UserInputError, isNodeError } from "../shared/errors.js";
+import { validateTopic, sanitizeTopicPath } from "../validation/index.js";
+import { validateWritePayload } from "../validation/write-guard.js";
+import { buildContextIndex } from "./index-builder.js";
+import { DEFAULT_CONFIG } from "../config/index.js";
+/**
+ * Manages context file storage operations.
+ * Handles reading, writing, and listing context files in the configured directory.
+ */
+export class ContextStore {
+    basePath;
+    config;
+    contextDir;
+    constructor(basePath = process.cwd(), config = DEFAULT_CONFIG) {
+        this.basePath = basePath;
+        this.config = config;
+        this.contextDir = path.join(this.basePath, this.config.path);
+    }
+    /** Returns the absolute path to the context directory. */
+    getContextDirectory() {
+        return this.contextDir;
+    }
+    /** Returns the absolute path to a topic file. */
+    getTopicFilePath(topic) {
+        return path.join(this.contextDir, `${topic}.md`);
+    }
+    /**
+     * Saves context content to a topic file.
+     * Validates the payload using the write guard before writing.
+     * @param topicInput - Topic name (will be validated and trimmed)
+     * @param content - Markdown content to save
+     * @returns Success message with file location
+     * @throws UserInputError if validation fails
+     */
+    async saveContext(topicInput, content) {
+        const guardResult = validateWritePayload(topicInput, content, {
+            maxFileSizeKb: this.config.guard.maxFileSizeKb,
+            strictPatternCheck: this.config.guard.strictPatternCheck,
+        });
+        if (!guardResult.allowed) {
+            console.error(`WriteGuard Rejected: ${guardResult.reason} (Code: ${guardResult.code})`);
+            throw new UserInputError(`WriteGuard Rejected: ${guardResult.reason} (Code: ${guardResult.code})`);
+        }
+        const topic = validateTopic(topicInput);
+        const filePath = sanitizeTopicPath(this.contextDir, topic);
+        // Reject writes to existing symlinks — prevents symlink traversal attacks
+        try {
+            const fileStat = await lstat(filePath);
+            if (fileStat.isSymbolicLink()) {
+                throw new UserInputError(`Refusing to overwrite symlink at ${this.config.path}/${topic}.md. Delete the symlink first.`);
+            }
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === "ENOENT") {
+                // File does not exist yet — normal case, continue
+            }
+            else {
+                throw error;
+            }
+        }
+        await mkdir(this.contextDir, { recursive: true });
+        await writeFile(filePath, content, "utf8");
+        return `Saved context topic "${topic}" to ${this.config.path}/${topic}.md.`;
+    }
+    /**
+     * Reads context content from a topic file, or lists all topics if none specified.
+     * @param topicInput - Optional topic name to read
+     * @returns Topic content or list of available topics
+     * @throws UserInputError if topic doesn't exist or is invalid
+     */
+    async readContext(topicInput) {
+        if (topicInput !== undefined) {
+            const topic = validateTopic(topicInput);
+            try {
+                const filePath = sanitizeTopicPath(this.contextDir, topic);
+                return await readFile(filePath, "utf8");
+            }
+            catch (error) {
+                if (isNodeError(error) && error.code === "ENOENT") {
+                    throw new UserInputError(`No context found for topic "${topic}" at ${this.config.path}/${topic}.md.`);
+                }
+                throw error;
+            }
+        }
+        const topics = await this.listTopics();
+        if (topics.length === 0) {
+            return `No OpenContext topics found in ${this.config.path}/. Use save_context to create one.`;
+        }
+        if (!this.config.autoIndex) {
+            return topics.map((t) => `- ${t}`).join("\n");
+        }
+        return this.rebuildContextIndex();
+    }
+    /**
+     * Deletes a context topic file from the context directory.
+     * @param topicInput - Topic name to delete
+     * @returns Success message with confirmation
+     * @throws UserInputError if topic doesn't exist or is invalid
+     */
+    async deleteContext(topicInput) {
+        const topic = validateTopic(topicInput);
+        const filePath = sanitizeTopicPath(this.contextDir, topic);
+        try {
+            await unlink(filePath);
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === "ENOENT") {
+                throw new UserInputError(`No context found for topic "${topic}" at ${this.config.path}/${topic}.md.`);
+            }
+            throw error;
+        }
+        if (this.config.autoIndex) {
+            await this.rebuildContextIndex();
+        }
+        return `Deleted context topic "${topic}" from ${this.config.path}/${topic}.md.`;
+    }
+    /**
+     * Lists all available context topics.
+     * Scans the context directory for .md files and returns sorted topic names.
+     * @returns Sorted array of topic names
+     */
+    async listTopics() {
+        try {
+            const entries = await readdir(this.contextDir, { withFileTypes: true });
+            return entries
+                .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+                .map((entry) => entry.name.slice(0, -".md".length))
+                .sort((a, b) => a.localeCompare(b));
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === "ENOENT") {
+                return [];
+            }
+            throw error;
+        }
+    }
+    /**
+     * Rebuilds the auto-generated index.md file in the context directory.
+     * @returns The generated index markdown content
+     */
+    async rebuildContextIndex() {
+        return buildContextIndex(this.contextDir);
+    }
+}
+//# sourceMappingURL=context-store.js.map

package/dist/store/context-store.js.map

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

package/dist/store/index-builder.d.ts

@@ -0,0 +1,32 @@
+import { type TopicStatus } from "../shared/constants.js";
+import type { TopicFrontmatter } from "../shared/types.js";
+export interface TopicIndexEntry {
+    topic: string;
+    filename: string;
+    description: string;
+    date: string;
+    sizeBytes: number;
+    status: TopicStatus | undefined;
+    supersedes: string | undefined;
+    superseded_by: string | undefined;
+}
+/**
+ * Parses YAML frontmatter from markdown content.
+ * Returns extracted fields or an empty object when no frontmatter is present.
+ * Uses simple line-by-line parsing — no external YAML dependency.
+ */
+export declare function parseFrontmatter(content: string): TopicFrontmatter;
+/**
+ * Extracts a short description from markdown content.
+ * Strategy: frontmatter description → first heading → first paragraph → fallback.
+ * @param content - Raw markdown content
+ * @returns Truncated description (max 120 chars)
+ */
+export declare function extractDescription(content: string): string;
+/**
+ * Rebuilds the auto-generated index.md file in the context directory.
+ * Scans all topic files, extracts metadata, and writes a compact index.
+ * @param contextDir - Absolute path to the .opencontext directory
+ * @returns The generated index markdown content ("" when no topics exist)
+ */
+export declare function buildContextIndex(contextDir: string): Promise<string>;