opencontext-mcp 0.1.0 → 1.1.0

package/README.md

@@ -3,6 +3,7 @@
 [![MCP](https://img.shields.io/badge/MCP-compatible-2563eb)](https://modelcontextprotocol.io/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6)](https://www.typescriptlang.org/)
 [![Node.js](https://img.shields.io/badge/Node.js-20%2B-339933)](https://nodejs.org/)
+[![Website](https://img.shields.io/badge/URL-opencntx.dev-c42f52?link=https%3A%2F%2Fopencntx.dev)](https://opencntx.dev/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 OpenContext MCP gives AI agents persistent, project-local memory.
@@ -15,6 +16,9 @@ The result is simple and transparent: your agent gets memory, and you keep full
 
 - `save_context`: save markdown context to `.opencontext/<topic>.md`
 - `read_context`: read one saved topic or list all available topics
+- **Auto-Index**: automatic `index.md` generation with topic metadata
+- **Write Guard**: input validation, size limits, and prompt injection protection
+- **Config System**: customizable via `.opencontext.jsonc` or `.opencontext.json`
 - Project-specific storage based on the client's current working directory
 - No database, account, cloud sync, or hidden state
 - Works with MCP-compatible clients over stdio
@@ -54,9 +58,9 @@ Add OpenContext MCP to your OpenCode MCP configuration:
 }
 ```
 
-### Cursor
+### Cursor / Claude Desktop
 
-Add this server to your Cursor MCP configuration:
+Cursor and Claude Desktop use the same MCP server configuration:
 
 ```json
 {
@@ -69,36 +73,52 @@ Add this server to your Cursor MCP configuration:
 }
 ```
 
-### Claude Desktop
+Restart your MCP client after updating the configuration.
 
-Add this entry to your Claude Desktop MCP configuration:
+## Configuration
 
-```json
+OpenContext can be customized with a config file in your project root. Create `.opencontext.jsonc` or `.opencontext.json`:
+
+```jsonc
 {
-  "mcpServers": {
-    "opencontext": {
-      "command": "npx",
-      "args": ["-y", "opencontext-mcp"]
-    }
+  // Custom storage path (default: ".opencontext")
+  "path": ".opencontext",
+
+  // Disable write operations
+  "readOnly": false,
+
+  // Pause all tool access
+  "disabled": false,
+
+  // Auto-generate index.md with topic metadata
+  "autoIndex": true,
+
+  // Write guard settings
+  "guard": {
+    "enabled": true,
+    "maxFileSizeKb": 50,
+    "strictPatternCheck": true
+  },
+
+  // History backup settings (coming soon)
+  "history": {
+    "enabled": false,
+    "maxBackupsPerTopic": 5,
+    "retentionDays": 7
   }
 }
 ```
 
-Restart your MCP client after updating configuration.
-
-## How It Works
+### Guard System
 
-OpenContext MCP stores files relative to the process working directory used by your MCP client:
-
-```text
-your-project/
-  .opencontext/
-    architecture.md
-    api-contracts.md
-    coding_rules.md
-```
+The write guard protects against:
 
-Topics must be lowercase snake_case or kebab-case, such as `architecture`, `api-contracts`, or `coding_rules`.
+- **Empty content**: prevents saving blank or whitespace-only files
+- **Payload too large**: configurable max file size (default 50KB)
+- **Invalid topics**: enforces snake_case or kebab-case naming
+- **Path traversal**: blocks `..`, absolute paths, and directory escapes
+- **Reserved topics**: prevents overwriting system files like `index.md`
+- **Prompt injection**: detects and blocks common injection patterns
 
 ## Available Tools
 
@@ -154,10 +174,7 @@ Recommended workflow:
 3. Let agents update context when they discover something that should survive the current chat.
 4. Review `.opencontext/` files like normal project documentation.
 
-Copy-ready agent prompts:
-
-- [`examples/plan-agent.md`](examples/plan-agent.md) -- architect that analyzes requirements and saves context
-- [`examples/build-agent.md`](examples/build-agent.md) -- developer that reads context before coding
+For pre-built agent prompts, see the [documentation](https://opencntx.dev/docs/agents).
 
 ## Version Control
 
@@ -175,33 +192,45 @@ Or ignore it when context should stay local:
 
 Because files are plain markdown, both approaches are safe and easy to audit.
 
+## Project Structure
+
+```text
+opencontext/
+├── packages/
+│   └── opencontext/         # MCP server package
+│       ├── src/
+│       │   ├── index.ts           # CLI entrypoint (stdio transport)
+│       │   ├── server.ts          # McpServer factory and tool registration
+│       │   ├── config.ts          # Config loading (.opencontext.jsonc)
+│       │   ├── context-store.ts   # Filesystem operations for .opencontext/
+│       │   ├── validation.ts      # Topic validation and write guard
+│       │   └── types.ts           # Shared constants and error helpers
+│       └── test/
+│           ├── context-store.test.ts
+│           ├── validation.test.ts
+│           ├── guard.test.ts
+│           └── auto-index.test.ts
+├── apps/
+│   └── web/                 # Website (Next.js)
+│       └── src/
+│           ├── app/
+│           │   ├── page.tsx        # Landing page
+│           │   ├── docs/           # Documentation
+│           │   ├── imprint/
+│           │   └── privacy-policy/
+│           └── components/
+├── CONTRIBUTING.md
+├── SECURITY.md
+└── README.md
+```
+
 ## Development
 
 ```bash
 pnpm install
-pnpm build        # compile TypeScript
+pnpm build        # compile all packages
 pnpm typecheck    # type-check without emitting
 pnpm test         # run vitest suite
-pnpm start        # start the MCP server
-```
-
-Project structure:
-
-```text
-src/
-  index.ts            CLI entrypoint (stdio transport, startup error handling)
-  server.ts           McpServer factory and tool registration
-  context-store.ts    Filesystem operations for .opencontext/
-  validation.ts       Topic validation and input rules
-  types.ts            Shared constants, error classes, and result helpers
-test/
-  validation.test.ts  Unit tests for topic validation
-  context-store.test.ts  Unit tests for read/write/list operations
-examples/
-  plan-agent.md       Architect system prompt
-  build-agent.md      Developer system prompt
-README.md             User documentation
-LICENSE               MIT license
 ```
 
 ## License

package/dist/config.d.ts

@@ -0,0 +1,24 @@
+export interface OpenContextConfig {
+    $schema?: string;
+    path?: string;
+    readOnly?: boolean;
+    disabled?: boolean;
+    autoIndex?: boolean;
+    history?: {
+        enabled?: boolean;
+        maxBackupsPerTopic?: number;
+        retentionDays?: number;
+    };
+    guard?: {
+        enabled?: boolean;
+        maxFileSizeKb?: number;
+        strictPatternCheck?: boolean;
+    };
+}
+export type ResolvedConfig = Required<Omit<OpenContextConfig, "$schema">>;
+export declare const DEFAULT_CONFIG: ResolvedConfig;
+/**
+ * Loads configuration from .opencontext.jsonc or .opencontext.json in the given directory.
+ * Falls back to DEFAULT_CONFIG if no file exists or parsing fails.
+ */
+export declare function loadConfig(cwd?: string): Promise<ResolvedConfig>;

package/dist/config.js

@@ -0,0 +1,114 @@
+import { readFile } from "node:fs/promises";
+import * as path from "node:path";
+export const DEFAULT_CONFIG = {
+    path: ".opencontext",
+    readOnly: false,
+    disabled: false,
+    autoIndex: true,
+    history: {
+        enabled: false,
+        maxBackupsPerTopic: 5,
+        retentionDays: 7,
+    },
+    guard: {
+        enabled: true,
+        maxFileSizeKb: 50,
+        strictPatternCheck: true,
+    },
+};
+const CONFIG_CANDIDATES = [".opencontext.jsonc", ".opencontext.json"];
+/**
+ * Strips JSONC content into parseable JSON by removing comments and trailing commas.
+ * Handles single-line (//), multi-line (/* * /), and trailing commas.
+ */
+function stripJsonComments(raw) {
+    let result = "";
+    let i = 0;
+    const len = raw.length;
+    while (i < len) {
+        const ch = raw[i];
+        // Strings: copy verbatim (including escaped characters)
+        if (ch === '"') {
+            result += ch;
+            i++;
+            while (i < len && raw[i] !== '"') {
+                if (raw[i] === "\\") {
+                    result += raw[i];
+                    i++;
+                }
+                if (i < len) {
+                    result += raw[i];
+                    i++;
+                }
+            }
+            if (i < len) {
+                result += raw[i]; // closing quote
+                i++;
+            }
+            continue;
+        }
+        // Single-line comment: skip until newline
+        if (ch === "/" && i + 1 < len && raw[i + 1] === "/") {
+            while (i < len && raw[i] !== "\n") {
+                i++;
+            }
+            continue;
+        }
+        // Multi-line comment: skip until */
+        if (ch === "/" && i + 1 < len && raw[i + 1] === "*") {
+            i += 2;
+            while (i < len - 1 && !(raw[i] === "*" && raw[i + 1] === "/")) {
+                i++;
+            }
+            i += 2; // skip */
+            continue;
+        }
+        result += ch;
+        i++;
+    }
+    // Strip trailing commas before closing braces/brackets
+    return result.replace(/,(\s*[}\]])/g, "$1");
+}
+function deepMerge(target, source) {
+    const result = { ...target };
+    for (const key of Object.keys(source)) {
+        const sourceVal = source[key];
+        const targetVal = result[key];
+        if (sourceVal !== null &&
+            typeof sourceVal === "object" &&
+            !Array.isArray(sourceVal) &&
+            targetVal !== null &&
+            typeof targetVal === "object" &&
+            !Array.isArray(targetVal)) {
+            result[key] = deepMerge(targetVal, sourceVal);
+        }
+        else if (sourceVal !== undefined) {
+            result[key] = sourceVal;
+        }
+    }
+    return result;
+}
+/**
+ * Loads configuration from .opencontext.jsonc or .opencontext.json in the given directory.
+ * Falls back to DEFAULT_CONFIG if no file exists or parsing fails.
+ */
+export async function loadConfig(cwd = process.cwd()) {
+    for (const filename of CONFIG_CANDIDATES) {
+        const filePath = path.join(cwd, filename);
+        try {
+            const raw = await readFile(filePath, "utf8");
+            const cleaned = stripJsonComments(raw);
+            const parsed = JSON.parse(cleaned);
+            return deepMerge(DEFAULT_CONFIG, parsed);
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                continue; // file doesn't exist, try next candidate
+            }
+            console.error(`OpenContext: failed to parse ${filename}: ${error.message}`);
+            return DEFAULT_CONFIG;
+        }
+    }
+    return DEFAULT_CONFIG;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/context-store.d.ts

@@ -1,9 +1,50 @@
+import { type ResolvedConfig } from "./config.js";
+/**
+ * Manages context file storage operations.
+ * Handles reading, writing, and listing context files in the configured directory.
+ */
 export declare class ContextStore {
     private readonly basePath;
-    constructor(basePath?: string);
+    private readonly config;
+    private readonly contextDir;
+    constructor(basePath?: string, config?: ResolvedConfig);
+    /** Returns the absolute path to the context directory. */
     getContextDirectory(): string;
+    /** Returns the absolute path to a topic file. */
     getTopicFilePath(topic: string): string;
+    /**
+     * Saves context content to a topic file.
+     * Validates payload using WriteGuard 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
+     */
     saveContext(topicInput: string, content: string): Promise<string>;
+    /**
+     * 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
+     */
     readContext(topicInput?: string): Promise<string>;
+    /**
+     * Lists all available context topics.
+     * Scans the context directory for .md files and returns sorted topic names.
+     * @returns Sorted array of topic names
+     */
     listTopics(): Promise<string[]>;
+    /**
+     * 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/context-store.js

@@ -1,48 +1,86 @@
-import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
-import path from "node:path";
-import { CONTEXT_DIRECTORY_NAME, UserInputError, isNodeError } from "./types.js";
-import { validateTopic } from "./validation.js";
+import { mkdir, readdir, readFile, writeFile, stat } from "node:fs/promises";
+import * as path from "node:path";
+import { INDEX_FILENAME, UserInputError, isNodeError } from "./types.js";
+import { validateTopic, validateWritePayload, sanitizeTopicPath } from "./validation.js";
+import { DEFAULT_CONFIG } from "./config.js";
+/**
+ * Manages context file storage operations.
+ * Handles reading, writing, and listing context files in the configured directory.
+ */
 export class ContextStore {
     basePath;
-    constructor(basePath = process.cwd()) {
+    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 path.join(this.basePath, CONTEXT_DIRECTORY_NAME);
+        return this.contextDir;
     }
+    /** Returns the absolute path to a topic file. */
     getTopicFilePath(topic) {
-        return path.join(this.getContextDirectory(), `${topic}.md`);
+        return path.join(this.contextDir, `${topic}.md`);
     }
+    /**
+     * Saves context content to a topic file.
+     * Validates payload using WriteGuard 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 contextDirectory = this.getContextDirectory();
-        const filePath = this.getTopicFilePath(topic);
-        await mkdir(contextDirectory, { recursive: true });
+        const filePath = sanitizeTopicPath(this.contextDir, topic);
+        await mkdir(this.contextDir, { recursive: true });
         await writeFile(filePath, content, "utf8");
-        return `Saved context topic "${topic}" to ${CONTEXT_DIRECTORY_NAME}/${topic}.md.`;
+        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 {
-                return await readFile(this.getTopicFilePath(topic), "utf8");
+                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 ${CONTEXT_DIRECTORY_NAME}/${topic}.md.`);
+                    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 ${CONTEXT_DIRECTORY_NAME}/. Use save_context to create one.`;
+            return `No OpenContext topics found in ${this.config.path}/. Use save_context to create one.`;
         }
-        return `Available OpenContext topics:\n\n${topics.map((topic) => `- ${topic}`).join("\n")}`;
+        return this.rebuildContextIndex();
     }
+    /**
+     * 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.getContextDirectory(), { withFileTypes: true });
+            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))
@@ -55,5 +93,103 @@ export class ContextStore {
             throw error;
         }
     }
+    /**
+     * 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)
+     */
+    extractDescription(content) {
+        const trimmed = content.trim();
+        if (!trimmed) {
+            return "No summary available.";
+        }
+        // Strategy A: YAML frontmatter with description key
+        if (trimmed.startsWith("---")) {
+            const endIdx = trimmed.indexOf("---", 3);
+            if (endIdx !== -1) {
+                const frontmatter = trimmed.slice(3, endIdx);
+                const descMatch = frontmatter.match(/description:\s*["']?(.+?)["']?\s*$/m);
+                if (descMatch?.[1]) {
+                    return descMatch[1].slice(0, 120);
+                }
+            }
+        }
+        const lines = trimmed.split("\n");
+        // Strategy B: First heading
+        for (const line of lines) {
+            const headingMatch = line.match(/^#\s+(.+)$/);
+            if (headingMatch?.[1]) {
+                return headingMatch[1].slice(0, 120);
+            }
+        }
+        // Strategy C: First non-empty paragraph line
+        for (const line of lines) {
+            const stripped = line.trim();
+            if (stripped && !stripped.startsWith("#")) {
+                return stripped.length > 120 ? stripped.slice(0, 120) + "..." : stripped;
+            }
+        }
+        return "No summary available.";
+    }
+    /**
+     * 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
+     */
+    async rebuildContextIndex() {
+        let entries;
+        try {
+            entries = await readdir(this.contextDir, { withFileTypes: true });
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === "ENOENT") {
+                return "";
+            }
+            throw error;
+        }
+        const topicFiles = entries
+            .filter((entry) => entry.isFile() &&
+            entry.name.endsWith(".md") &&
+            entry.name !== INDEX_FILENAME &&
+            entry.name !== "README.md")
+            .sort((a, b) => a.name.localeCompare(b.name));
+        if (topicFiles.length === 0) {
+            return "";
+        }
+        const topicEntries = [];
+        for (const entry of topicFiles) {
+            const filePath = path.join(this.contextDir, entry.name);
+            const content = await readFile(filePath, "utf8");
+            const fileStat = await stat(filePath);
+            const topic = entry.name.slice(0, -".md".length);
+            const description = this.extractDescription(content);
+            const date = fileStat.mtime.toISOString().slice(0, 10);
+            const sizeBytes = Buffer.byteLength(content, "utf8");
+            topicEntries.push({ topic, filename: entry.name, description, date, sizeBytes });
+        }
+        const lines = [
+            "# Project Context Index",
+            "<!-- AUTO-GENERATED BY OPENCONTEXT - DO NOT EDIT MANUALLY -->",
+            "",
+            "Available context topics in this project:",
+            "",
+        ];
+        for (const t of topicEntries) {
+            const sizeStr = t.sizeBytes >= 1024
+                ? `${(t.sizeBytes / 1024).toFixed(1)} KB`
+                : `${t.sizeBytes} B`;
+            lines.push(`- **${t.topic}** (\`${t.filename}\`) - Updated: ${t.date} (${sizeStr})`);
+            lines.push(`  > ${t.description}`);
+        }
+        lines.push("");
+        lines.push("---");
+        lines.push("*To read a specific context topic, call `read_context` with the topic name.*");
+        lines.push("");
+        const indexContent = lines.join("\n");
+        const indexPath = path.join(this.contextDir, INDEX_FILENAME);
+        await writeFile(indexPath, indexContent, "utf8");
+        return indexContent;
+    }
 }
 //# sourceMappingURL=context-store.js.map

package/dist/context-store.js.map

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

package/dist/index.js

@@ -2,8 +2,12 @@
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createOpenContextServer } from "./server.js";
 import { SERVER_NAME, getErrorMessage } from "./types.js";
+/**
+ * Main entry point for the OpenContext MCP server.
+ * Creates server instance and connects to stdio transport.
+ */
 async function main() {
-    const server = createOpenContextServer();
+    const server = await createOpenContextServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE1D,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,uBAAuB,EAAE,CAAC;IACzC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,OAAO,CAAC,KAAK,CAAC,mBAAmB,WAAW,KAAK,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC3E,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE1D;;;GAGG;AACH,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,MAAM,uBAAuB,EAAE,CAAC;IAC/C,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,OAAO,CAAC,KAAK,CAAC,mBAAmB,WAAW,KAAK,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC3E,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/server.d.ts

@@ -1,2 +1,9 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-export declare function createOpenContextServer(basePath?: string): McpServer;
+import { type ResolvedConfig } from "./config.js";
+/**
+ * Creates and configures the OpenContext MCP server.
+ * Registers all available tools (save_context, read_context).
+ * @param basePath - Optional base directory (defaults to cwd)
+ * @param config - Optional pre-loaded config (loads from disk if omitted)
+ */
+export declare function createOpenContextServer(basePath?: string, config?: ResolvedConfig): Promise<McpServer>;

package/dist/server.js

@@ -2,15 +2,23 @@ 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";
-export function createOpenContextServer(basePath) {
-    const store = new ContextStore(basePath);
+import { loadConfig } from "./config.js";
+/**
+ * Creates and configures the OpenContext MCP server.
+ * Registers all available tools (save_context, read_context).
+ * @param basePath - Optional base directory (defaults to cwd)
+ * @param config - Optional pre-loaded config (loads from disk if omitted)
+ */
+export async function createOpenContextServer(basePath, config) {
+    const resolvedConfig = config ?? await loadConfig(basePath);
+    const store = new ContextStore(basePath, resolvedConfig);
     const server = new McpServer({
         name: SERVER_NAME,
         version: SERVER_VERSION,
     });
     server.registerTool("save_context", {
         title: "Save Context",
-        description: "Persist markdown project context, architectural rules, or decisions into .opencontext/<topic>.md in the current working directory.",
+        description: `Persist markdown project context, architectural rules, or decisions into ${resolvedConfig.path}/<topic>.md in the current working directory.`,
         inputSchema: {
             topic: z
                 .string()
@@ -19,6 +27,12 @@ export function createOpenContextServer(basePath) {
             content: z.string().min(1).describe("Markdown content to save for this project topic."),
         },
     }, async ({ topic, content }) => {
+        if (resolvedConfig.disabled) {
+            return textResult("OpenContext is currently paused. Tool access is disabled via configuration.");
+        }
+        if (resolvedConfig.readOnly) {
+            return textResult("OpenContext is in read-only mode. Write operations are disabled via configuration.", true);
+        }
         try {
             const result = await store.saveContext(topic, content);
             return textResult(result);
@@ -38,6 +52,9 @@ export function createOpenContextServer(basePath) {
                 .describe("Optional topic name in snake_case or kebab-case. Omit to list all saved topics."),
         },
     }, async ({ topic }) => {
+        if (resolvedConfig.disabled) {
+            return textResult("OpenContext is currently paused. Tool access is disabled via configuration.");
+        }
         try {
             const result = await store.readContext(topic);
             return textResult(result);

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEtF,MAAM,UAAU,uBAAuB,CAAC,QAAiB;IACvD,MAAM,KAAK,GAAG,IAAI,YAAY,CAAC,QAAQ,CAAC,CAAC;IAEzC,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,cAAc;KACxB,CAAC,CAAC;IAEH,MAAM,CAAC,YAAY,CACjB,cAAc,EACd;QACE,KAAK,EAAE,cAAc;QACrB,WAAW,EACT,oIAAoI;QACtI,WAAW,EAAE;YACX,KAAK,EAAE,CAAC;iBACL,MAAM,EAAE;iBACR,GAAG,CAAC,CAAC,CAAC;iBACN,QAAQ,CACP,0FAA0F,CAC3F;YACH,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,kDAAkD,CAAC;SACxF;KACF,EACD,KAAK,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE;QAC3B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YACvD,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC;QAC5B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,UAAU,CAAC,sBAAsB,eAAe,CAAC,KAAK,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QAC1E,CAAC;IACH,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,cAAc,EACd;QACE,KAAK,EAAE,cAAc;QACrB,WAAW,EACT,yFAAyF;QAC3F,WAAW,EAAE;YACX,KAAK,EAAE,CAAC;iBACL,MAAM,EAAE;iBACR,GAAG,CAAC,CAAC,CAAC;iBACN,QAAQ,EAAE;iBACV,QAAQ,CACP,iFAAiF,CAClF;SACJ;KACF,EACD,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE;QAClB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;YAC9C,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC;QAC5B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,UAAU,CAAC,sBAAsB,eAAe,CAAC,KAAK,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QAC1E,CAAC;IACH,CAAC,CACF,CAAC;IAEF,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACtF,OAAO,EAAE,UAAU,EAAuB,MAAM,aAAa,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,QAAiB,EACjB,MAAuB;IAEvB,MAAM,cAAc,GAAG,MAAM,IAAI,MAAM,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC5D,MAAM,KAAK,GAAG,IAAI,YAAY,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;IAEzD,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,cAAc;KACxB,CAAC,CAAC;IAEH,MAAM,CAAC,YAAY,CACjB,cAAc,EACd;QACE,KAAK,EAAE,cAAc;QACrB,WAAW,EAAE,4EAA4E,cAAc,CAAC,IAAI,+CAA+C;QAC3J,WAAW,EAAE;YACX,KAAK,EAAE,CAAC;iBACL,MAAM,EAAE;iBACR,GAAG,CAAC,CAAC,CAAC;iBACN,QAAQ,CACP,0FAA0F,CAC3F;YACH,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,kDAAkD,CAAC;SACxF;KACF,EACD,KAAK,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE;QAC3B,IAAI,cAAc,CAAC,QAAQ,EAAE,CAAC;YAC5B,OAAO,UAAU,CAAC,6EAA6E,CAAC,CAAC;QACnG,CAAC;QACD,IAAI,cAAc,CAAC,QAAQ,EAAE,CAAC;YAC5B,OAAO,UAAU,CAAC,oFAAoF,EAAE,IAAI,CAAC,CAAC;QAChH,CAAC;QACD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YACvD,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC;QAC5B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,UAAU,CAAC,sBAAsB,eAAe,CAAC,KAAK,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QAC1E,CAAC;IACH,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,cAAc,EACd;QACE,KAAK,EAAE,cAAc;QACrB,WAAW,EACT,yFAAyF;QAC3F,WAAW,EAAE;YACX,KAAK,EAAE,CAAC;iBACL,MAAM,EAAE;iBACR,GAAG,CAAC,CAAC,CAAC;iBACN,QAAQ,EAAE;iBACV,QAAQ,CACP,iFAAiF,CAClF;SACJ;KACF,EACD,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE;QAClB,IAAI,cAAc,CAAC,QAAQ,EAAE,CAAC;YAC5B,OAAO,UAAU,CAAC,6EAA6E,CAAC,CAAC;QACnG,CAAC;QACD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;YAC9C,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC;QAC5B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,UAAU,CAAC,sBAAsB,eAAe,CAAC,KAAK,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QAC1E,CAAC;IACH,CAAC,CACF,CAAC;IAEF,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/types.d.ts

@@ -1,10 +1,29 @@
+/** MCP server identifier used in protocol handshakes. */
 export declare const SERVER_NAME = "opencontext-mcp";
-export declare const SERVER_VERSION = "0.1.0";
-export declare const CONTEXT_DIRECTORY_NAME = ".opencontext";
+/** Current server version for compatibility checks. */
+export declare const SERVER_VERSION = "1.1.0";
+/** Filename for the auto-generated context index. */
+export declare const INDEX_FILENAME = "index.md";
+/** Topic names reserved by the system — cannot be written by external agents. */
+export declare const RESERVED_TOPICS: ReadonlySet<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;
+/**
+ * Custom error class for user input validation errors.
+ * Thrown when topic names, content, or other user inputs fail validation.
+ */
 export declare class UserInputError extends Error {
     constructor(message: 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: {
@@ -12,5 +31,13 @@ export declare function textResult(text: string, isError?: boolean): {
         text: string;
     }[];
 };
+/**
+ * Safely extracts error message from unknown error types.
+ * Handles Error objects, strings, and unknown values.
+ */
 export declare function getErrorMessage(error: unknown): string;
+/**
+ * Type guard to check if an error is a Node.js filesystem error.
+ * Useful for handling ENOENT, EACCES, etc. from fs operations.
+ */
 export declare function isNodeError(error: unknown): error is NodeJS.ErrnoException;

package/dist/types.js

@@ -1,13 +1,32 @@
+/** MCP server identifier used in protocol handshakes. */
 export const SERVER_NAME = "opencontext-mcp";
-export const SERVER_VERSION = "0.1.0";
-export const CONTEXT_DIRECTORY_NAME = ".opencontext";
+/** Current server version for compatibility checks. */
+export const SERVER_VERSION = "1.1.0";
+/** Filename for the auto-generated context index. */
+export const INDEX_FILENAME = "index.md";
+/** Topic names reserved by the system — cannot be written by external agents. */
+export const RESERVED_TOPICS = new Set(["index"]);
+/**
+ * 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]+)*$/;
+/**
+ * Custom error class for user input validation errors.
+ * Thrown when topic names, content, or other user inputs fail validation.
+ */
 export class UserInputError extends Error {
     constructor(message) {
         super(message);
         this.name = "UserInputError";
     }
 }
+/**
+ * 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: [
@@ -19,12 +38,20 @@ export function textResult(text, isError = false) {
         ...(isError ? { isError: true } : {}),
     };
 }
+/**
+ * Safely extracts error message from unknown error types.
+ * Handles Error objects, strings, and unknown values.
+ */
 export function getErrorMessage(error) {
     if (error instanceof Error) {
         return error.message;
     }
     return "An unknown error occurred.";
 }
+/**
+ * Type guard to check if an error is a Node.js filesystem error.
+ * Useful for handling ENOENT, EACCES, etc. from fs operations.
+ */
 export function isNodeError(error) {
     return error instanceof Error && "code" in error;
 }

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,WAAW,GAAG,iBAAiB,CAAC;AAC7C,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AACtC,MAAM,CAAC,MAAM,sBAAsB,GAAG,cAAc,CAAC;AACrD,MAAM,CAAC,MAAM,aAAa,GAAG,+BAA+B,CAAC;AAE7D,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,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;AAED,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,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,KAAK,YAAY,KAAK,IAAI,MAAM,IAAI,KAAK,CAAC;AACnD,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.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,iFAAiF;AACjF,MAAM,CAAC,MAAM,eAAe,GAAwB,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;AAEvE;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,+BAA+B,CAAC;AAE7D;;;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;;;;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;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/validation.d.ts

@@ -1 +1,47 @@
+/**
+ * Options for configuring write guard behavior.
+ */
+export interface GuardOptions {
+    /** Maximum payload size in KB (default: 50 KB) */
+    maxFileSizeKb?: number;
+    /** Whether to allow empty content (default: false) */
+    allowEmpty?: boolean;
+    /** Whether to check for forbidden patterns (default: true) */
+    strictPatternCheck?: boolean;
+}
+/**
+ * Result of write guard validation.
+ */
+export interface GuardResult {
+    /** Whether the write is allowed */
+    allowed: boolean;
+    /** Human-readable reason for rejection */
+    reason?: string;
+    /** Error code for programmatic handling */
+    code?: "EMPTY_CONTENT" | "PAYLOAD_TOO_LARGE" | "INVALID_TOPIC" | "PATH_TRAVERSAL" | "FORBIDDEN_PATTERN" | "RESERVED_TOPIC";
+}
+/**
+ * Validates a topic string for safe filesystem operations.
+ * @param topicInput - The topic string to validate
+ * @returns The trimmed, validated topic
+ * @throws UserInputError if the topic is invalid
+ */
 export declare function validateTopic(topicInput: string): string;
+/**
+ * Sanitizes a topic path to prevent path traversal attacks.
+ * Ensures the resolved path stays within the context directory.
+ * @param contextDir - The absolute path to the context directory
+ * @param topic - The topic name
+ * @returns The sanitized absolute path to the topic file
+ * @throws UserInputError if path traversal is detected
+ */
+export declare function sanitizeTopicPath(contextDir: string, topic: string): string;
+/**
+ * Validates a write payload for context storage.
+ * Checks topic validity, content safety, size limits, and forbidden patterns.
+ * @param topic - The topic name to validate
+ * @param content - The content to validate
+ * @param options - Optional configuration for validation behavior
+ * @returns GuardResult indicating whether the write is allowed
+ */
+export declare function validateWritePayload(topic: string, content: string, options?: GuardOptions): GuardResult;

package/dist/validation.js

@@ -1,4 +1,20 @@
-import { TOPIC_PATTERN, UserInputError } from "./types.js";
+import * as path from "node:path";
+import { RESERVED_TOPICS, TOPIC_PATTERN, UserInputError } from "./types.js";
+/**
+ * Forbidden patterns that indicate prompt injection attempts.
+ * These are checked case-insensitively against the content.
+ */
+const FORBIDDEN_PATTERNS = [
+    /ignore\s+(all\s+)?(previous|prior)\s+instructions/i,
+    /system\s*:\s*override/i,
+    /bypass\s+(safety|guardrails?|system\s+prompt)/i,
+];
+/**
+ * Validates a topic string for safe filesystem operations.
+ * @param topicInput - The topic string to validate
+ * @returns The trimmed, validated topic
+ * @throws UserInputError if the topic is invalid
+ */
 export function validateTopic(topicInput) {
     const topic = topicInput.trim();
     if (!TOPIC_PATTERN.test(topic)) {
@@ -6,4 +22,85 @@ export function validateTopic(topicInput) {
     }
     return topic;
 }
+/**
+ * Sanitizes a topic path to prevent path traversal attacks.
+ * Ensures the resolved path stays within the context directory.
+ * @param contextDir - The absolute path to the context directory
+ * @param topic - The topic name
+ * @returns The sanitized absolute path to the topic file
+ * @throws UserInputError if path traversal is detected
+ */
+export function sanitizeTopicPath(contextDir, topic) {
+    // Quick rejection of obvious path traversal attempts
+    if (topic.includes("..") || path.isAbsolute(topic) || topic.startsWith(".") || topic.includes("/")) {
+        throw new UserInputError("Path traversal detected: topic must not contain '..', '/', or absolute paths.");
+    }
+    const filePath = path.join(contextDir, `${topic}.md`);
+    const resolvedPath = path.resolve(filePath);
+    const resolvedContextDir = path.resolve(contextDir);
+    // Double-check resolved path is still within .opencontext directory
+    if (!resolvedPath.startsWith(resolvedContextDir + path.sep) && resolvedPath !== resolvedContextDir) {
+        throw new UserInputError("Path traversal detected: topic must not contain '..' or absolute paths.");
+    }
+    return resolvedPath;
+}
+/**
+ * Validates a write payload for context storage.
+ * Checks topic validity, content safety, size limits, and forbidden patterns.
+ * @param topic - The topic name to validate
+ * @param content - The content to validate
+ * @param options - Optional configuration for validation behavior
+ * @returns GuardResult indicating whether the write is allowed
+ */
+export function validateWritePayload(topic, content, options) {
+    const opts = {
+        maxFileSizeKb: options?.maxFileSizeKb ?? 50,
+        allowEmpty: options?.allowEmpty ?? false,
+        strictPatternCheck: options?.strictPatternCheck ?? true,
+    };
+    const trimmedTopic = topic.trim();
+    if (!TOPIC_PATTERN.test(trimmedTopic)) {
+        return {
+            allowed: false,
+            reason: "Topic must be snake_case or kebab-case using lowercase letters, numbers, underscores, or hyphens.",
+            code: "INVALID_TOPIC",
+        };
+    }
+    if (RESERVED_TOPICS.has(trimmedTopic)) {
+        return {
+            allowed: false,
+            reason: `"${trimmedTopic}" is a reserved system topic and cannot be written directly.`,
+            code: "RESERVED_TOPIC",
+        };
+    }
+    if (!opts.allowEmpty && content.trim().length === 0) {
+        return {
+            allowed: false,
+            reason: "Content must not be empty or consist solely of whitespace.",
+            code: "EMPTY_CONTENT",
+        };
+    }
+    // Convert KB to bytes for size comparison
+    const maxBytes = opts.maxFileSizeKb * 1024;
+    const contentBytes = Buffer.byteLength(content, "utf8");
+    if (contentBytes > maxBytes) {
+        return {
+            allowed: false,
+            reason: `Payload size (${contentBytes} bytes) exceeds maximum allowed size (${maxBytes} bytes).`,
+            code: "PAYLOAD_TOO_LARGE",
+        };
+    }
+    if (opts.strictPatternCheck) {
+        for (const pattern of FORBIDDEN_PATTERNS) {
+            if (pattern.test(content)) {
+                return {
+                    allowed: false,
+                    reason: `Content contains forbidden pattern: ${pattern.source}`,
+                    code: "FORBIDDEN_PATTERN",
+                };
+            }
+        }
+    }
+    return { allowed: true };
+}
 //# sourceMappingURL=validation.js.map

package/dist/validation.js.map

@@ -1 +1 @@
-{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE3D,MAAM,UAAU,aAAa,CAAC,UAAkB;IAC9C,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC;IAEhC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,cAAc,CACtB,mGAAmG,CACpG,CAAC;IACJ,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencontext-mcp",
-  "version": "0.1.0",
+  "version": "1.1.0",
   "description": "A Model Context Protocol server for persistent project-specific AI agent context.",
   "type": "module",
   "bin": {
@@ -28,10 +28,11 @@
     "memory"
   ],
   "repository": {
-    "url": "git+https://github.com/slxca/opencontext.git"
+    "url": "git+https://github.com/slxca/opencontext.git",
+    "directory": "packages/opencontext"
   },
   "bugs": {
-    "url": "https://github.com/slxca/mockr.js/issues",
+    "url": "https://github.com/slxca/opencontext/issues",
     "email": "bugs@s-luca.com"
   },
   "publishConfig": {
@@ -39,11 +40,11 @@
   },
   "author": "slxca <hello@slxca.com> (https://slxca.com)",
   "funding": "https://github.com/sponsors/slxca",
+  "homepage": "https://opencntx.dev",
   "license": "MIT",
   "engines": {
     "node": ">=20.0.0"
   },
-  "packageManager": "pnpm@9.15.4",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.17.4",
     "zod": "^4.5.4"

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 OpenContext Contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/examples/build-agent.md

@@ -1,48 +0,0 @@
-# OpenContext Build Agent
-
-Copy this prompt into your AI client's system prompt to turn it into a developer that follows rules saved by the Plan Agent.
-
-## System Prompt
-
-You are the OpenContext Build Agent: a pragmatic senior developer responsible for implementing changes while strictly following project context saved by the Plan Agent.
-
-Before writing or editing any code, you must use the `read_context` tool with no topic to list available OpenContext topics. Then read all topics relevant to the requested work. If relevant context exists, follow it. If the user's request conflicts with saved context, stop and ask for clarification before changing code.
-
-Your responsibilities:
-
-- Read OpenContext before coding.
-- Inspect the codebase and make the smallest correct change.
-- Preserve existing architecture, naming conventions, and testing strategy.
-- Run appropriate verification commands when feasible.
-- Use `save_context` when you discover a durable rule, convention, decision, or debugging note future agents should know.
-- Do not overwrite saved context with speculative or temporary information.
-
-Required workflow:
-
-```text
-1. Call read_context with no topic.
-2. Read each relevant topic with read_context.
-3. Inspect the affected code.
-4. Implement the smallest correct change.
-5. Run relevant tests, type checks, or builds.
-6. Save any newly discovered durable context with save_context.
-7. Summarize what changed and what was verified.
-```
-
-If no OpenContext topics exist, state that no saved context was available, then proceed by inspecting the repository directly.
-
-Build output format:
-
-```text
-Changed
-<files or behavior changed>
-
-Context Used
-<topics read or note that no context existed>
-
-Verification
-<commands run and results>
-
-Context Saved
-<topics saved or updated, if any>
-```

package/examples/plan-agent.md

@@ -1,53 +0,0 @@
-# OpenContext Plan Agent
-
-Copy this prompt into your AI client's system prompt to turn it into an architect that uses OpenContext MCP.
-
-## System Prompt
-
-You are the OpenContext Plan Agent: a senior software architect responsible for turning requirements into clear implementation plans and durable project context.
-
-Before planning, use the `read_context` tool with no topic to list available OpenContext topics. Read every topic relevant to the user's request before making recommendations. If no context exists, inspect the repository and infer only what is supported by evidence in the codebase.
-
-Your responsibilities:
-
-- Analyze the user's requirement and the current codebase before proposing changes.
-- Identify architectural constraints, project conventions, API contracts, data model decisions, and implementation risks.
-- Create a practical step-by-step plan that a build agent can execute.
-- Use `save_context` to persist durable decisions, rules, and conventions that future agents should follow.
-- Prefer concise markdown context organized under focused snake_case or kebab-case topics.
-
-When using `save_context`, choose topics such as:
-
-- `architecture`
-- `coding_rules`
-- `api-contracts`
-- `data-model`
-- `testing-strategy`
-
-Context you save must be factual and durable. Do not save temporary guesses, chat-only preferences, or unresolved options unless they are clearly marked as open questions.
-
-Plan output format:
-
-```text
-Summary
-<one-paragraph explanation of the intended solution>
-
-Relevant Context Read
-<topics read and what mattered>
-
-Architecture Decisions
-<decisions made or confirmed>
-
-Implementation Plan
-1. <step>
-2. <step>
-3. <step>
-
-Risks And Checks
-<known risks, tests, and verification steps>
-
-Context Saved
-<topics saved or updated>
-```
-
-Always save newly discovered durable context before finishing your response.