@context-os/mcp 1.0.0

package/dist/packages/core/src/index.js

@@ -0,0 +1,88 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { spawn } from 'node:child_process';
+/**
+ * Discovers the workspace root by looking for root/soul.md in parent directories.
+ */
+export function findWorkspaceRoot() {
+    let current = process.cwd();
+    const root = path.parse(current).root;
+    while (current !== root) {
+        if (fs.existsSync(path.join(current, "root", "soul.md"))) {
+            return fs.realpathSync(current);
+        }
+        current = path.dirname(current);
+    }
+    return fs.realpathSync(process.cwd()); // Fallback to CWD
+}
+export const workspaceRoot = findWorkspaceRoot();
+/**
+ * Standard ContextOS "Buckets" for security isolation.
+ */
+export const ALLOWED_BUCKETS = [
+    "projects",
+    "knowledge",
+    "schemas",
+    "archive",
+    "log",
+    "orgs",
+    "root"
+];
+/**
+ * Validates that a path is within the workspace root and inside an allowed bucket.
+ */
+export function validatePath(requestedPath) {
+    const resolvedPath = path.resolve(workspaceRoot, requestedPath);
+    let fullPath;
+    try {
+        fullPath = fs.realpathSync(resolvedPath);
+    }
+    catch (e) {
+        fullPath = resolvedPath;
+    }
+    const relativePath = path.relative(workspaceRoot, fullPath);
+    // Security check: must be within the workspace root
+    if (relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+        throw new Error(`Security violation: Path ${requestedPath} is outside the allowed ContextOS workspace root.`);
+    }
+    // Enterprise check: must be within an allowed bucket
+    const isAllowed = ALLOWED_BUCKETS.some(bucket => {
+        const bucketRoot = path.join(workspaceRoot, bucket);
+        const bucketRelative = path.relative(bucketRoot, fullPath);
+        return !bucketRelative.startsWith("..") && !path.isAbsolute(bucketRelative);
+    });
+    if (!isAllowed) {
+        throw new Error(`Security violation: Path ${requestedPath} is outside the allowed bucket (projects, orgs, knowledge, schemas, etc).`);
+    }
+    return { fullPath, relativePath };
+}
+/**
+ * Checks if a path is in a read-only bucket for agents.
+ */
+export function isReadOnly(filePath) {
+    const { fullPath } = validatePath(filePath);
+    const readOnlyBuckets = ["knowledge", "schemas", "root"];
+    return readOnlyBuckets.some(bucket => {
+        const bucketRoot = path.join(workspaceRoot, bucket);
+        const bucketRelative = path.relative(bucketRoot, fullPath);
+        return !bucketRelative.startsWith("..") && !path.isAbsolute(bucketRelative);
+    });
+}
+/**
+ * Executes an atomic git transaction (Add + Commit).
+ */
+export async function gitCommit(filePath, message) {
+    return new Promise((resolve, reject) => {
+        const add = spawn("git", ["add", filePath], { cwd: workspaceRoot });
+        add.on("close", (code) => {
+            if (code !== 0 && code !== null) {
+                return reject(new Error(`Git add failed with code ${code}`));
+            }
+            const commit = spawn("git", ["commit", "-m", message], { cwd: workspaceRoot });
+            commit.on("close", (code) => {
+                // If code is not 0, it might be "nothing to commit" which is fine for our tools
+                resolve();
+            });
+        });
+    });
+}

package/dist/workspace-mcp/src/index.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerReadTool } from "./tools/read.js";
+import { registerWriteTool } from "./tools/write.js";
+import { registerSearchTool } from "./tools/search.js";
+import { registerContextTool } from "./tools/context.js";
+import { registerDecisionTool } from "./tools/decision.js";
+import { registerMemoryTool } from "./tools/memory.js";
+import { registerDailyTool } from "./tools/daily.js";
+async function main() {
+    const server = new McpServer({
+        name: "workspace-mcp",
+        version: "0.1.0",
+    });
+    // Register all tools
+    registerReadTool(server);
+    registerWriteTool(server);
+    registerSearchTool(server);
+    registerContextTool(server);
+    registerDecisionTool(server);
+    registerMemoryTool(server);
+    registerDailyTool(server);
+    // Connect via stdio
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Workspace MCP Server running on stdio");
+}
+main().catch((error) => {
+    console.error("MCP Server Error:", error);
+    process.exit(1);
+});

package/dist/workspace-mcp/src/tests/isolation.test.js

@@ -0,0 +1,22 @@
+import assert from "node:assert";
+import { validatePath, findWorkspaceRoot } from "../utils.js";
+import path from "node:path";
+describe("Security Isolation Tests", () => {
+    const workspaceRoot = findWorkspaceRoot();
+    it("should allow paths within projects directory", () => {
+        const validPath = path.join(workspaceRoot, "projects", "ContextOS", "memory.md");
+        assert.doesNotThrow(() => validatePath(validPath));
+    });
+    it("should block directory traversal attacks (..)", () => {
+        const maliciousPath = path.join(workspaceRoot, "projects", "ContextOS", "..", "..", "package.json");
+        assert.throws(() => validatePath(maliciousPath), /Security violation/);
+    });
+    it("should block access to root config files when in project context", () => {
+        const rootConfig = path.join(workspaceRoot, "package.json");
+        assert.throws(() => validatePath(rootConfig), /Security violation/);
+    });
+    it("should allow access to specific allowed root files (knowledge, schemas)", () => {
+        const knowledgePath = path.join(workspaceRoot, "knowledge", "domains", "ai-agents.md");
+        assert.doesNotThrow(() => validatePath(knowledgePath));
+    });
+});

package/dist/workspace-mcp/src/tools/context.js

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import fs from "fs/promises";
+import path from "path";
+import { validatePath, handleToolError } from "../utils.js";
+export function registerContextTool(server) {
+    server.tool("workspace_context", {
+        project: z.string().describe("The project name (e.g., ContextOS)")
+    }, async ({ project }) => {
+        try {
+            const { fullPath: projectDir } = validatePath(`projects/${project}`);
+            const filesToLoad = ["CONTEXT.md", "memory.md", "decisions.md", "tasks/active.md"];
+            let content = `# Context for Project: ${project}\n\n`;
+            for (const file of filesToLoad) {
+                const filePath = path.join(projectDir, file);
+                try {
+                    const data = await fs.readFile(filePath, "utf-8");
+                    content += `## ${file}\n\n${data}\n---\n\n`;
+                }
+                catch (fileError) {
+                    content += `## ${file}\n\n(File not found)\n---\n\n`;
+                }
+            }
+            return {
+                content: [{ type: "text", text: content }],
+                isError: false
+            };
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+}

package/dist/workspace-mcp/src/tools/daily.js

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import fs from "fs/promises";
+import path from "path";
+import { validatePath, gitCommit, handleToolError } from "../utils.js";
+export function registerDailyTool(server) {
+    server.tool("workspace_daily_update", {
+        project: z.string().describe("Project name"),
+        content: z.string().describe("Content to append to today's daily log")
+    }, async ({ project, content }) => {
+        try {
+            const { fullPath: dailyDir } = validatePath(`projects/${project}/daily`);
+            const date = new Date().toISOString().split("T")[0];
+            const dailyLogPath = path.join(dailyDir, `${date}.md`);
+            // Ensure daily directory exists
+            await fs.mkdir(dailyDir, { recursive: true });
+            const timestamp = new Date().toLocaleTimeString();
+            const entry = `\n### [${timestamp}]\n\n${content}\n`;
+            await fs.appendFile(dailyLogPath, entry, "utf-8");
+            await gitCommit(dailyLogPath, `feat(mcp): daily log entry for ${date}`);
+            return {
+                content: [{ type: "text", text: `Updated today's daily log: ${date}.md` }],
+                isError: false
+            };
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+}

package/dist/workspace-mcp/src/tools/decision.js

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import fs from "fs/promises";
+import { validatePath, gitCommit, handleToolError } from "../utils.js";
+export function registerDecisionTool(server) {
+    server.tool("workspace_log_decision", {
+        project: z.string().describe("Project name"),
+        title: z.string().describe("Decision title"),
+        context: z.string().describe("Context of the decision"),
+        decision: z.string().describe("The decision made"),
+        rationale: z.string().describe("Rationale for the decision")
+    }, async ({ project, title, context, decision, rationale }) => {
+        try {
+            const { fullPath: projectDir } = validatePath(`projects/${project}`);
+            const decisionsPath = `${projectDir}/decisions.md`;
+            const date = new Date().toISOString().split("T")[0];
+            const adrId = `ADR-${Math.floor(Math.random() * 10000).toString().padStart(4, "0")}`;
+            const adrContent = `
+## [${adrId}] ${title}
+
+- **Date**: ${date}
+- **Status**: Accepted
+- **Context**: ${context}
+- **Decision**: ${decision}
+- **Rationale**: ${rationale}
+\n---\n`;
+            await fs.appendFile(decisionsPath, adrContent, "utf-8");
+            await gitCommit(decisionsPath, `feat(mcp): log decision ${adrId}: ${title}`);
+            return {
+                content: [{ type: "text", text: `Logged decision ${adrId} in ${project}/decisions.md` }],
+                isError: false
+            };
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+}

package/dist/workspace-mcp/src/tools/memory.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import fs from "fs/promises";
+import { validatePath, gitCommit, handleToolError } from "../utils.js";
+export function registerMemoryTool(server) {
+    server.tool("workspace_memory_update", {
+        project: z.string().describe("Project name"),
+        content: z.string().describe("Updated memory content (Markdown format)")
+    }, async ({ project, content }) => {
+        try {
+            const { fullPath: memoryPath } = validatePath(`projects/${project}/memory.md`);
+            const date = new Date().toISOString().split("T")[0];
+            const fullMemoryContent = `# Project Memory: ${project}\n\nLast Updated: ${date}\n\n${content}\n`;
+            await fs.writeFile(memoryPath, fullMemoryContent, "utf-8");
+            await gitCommit(memoryPath, `feat(mcp): update context memory for ${project}`);
+            return {
+                content: [{ type: "text", text: `Updated memory for ${project}` }],
+                isError: false
+            };
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+}

package/dist/workspace-mcp/src/tools/read.js

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import fs from "fs/promises";
+import { validatePath, handleToolError } from "../utils.js";
+export function registerReadTool(server) {
+    server.tool("workspace_read", {
+        path: z.string().describe("Relative path to the file"),
+        scope: z.enum(["root", "org", "project"]).describe("Access scope for protection")
+    }, async ({ path: filePath, scope }) => {
+        try {
+            const { fullPath } = validatePath(`${scope}/${filePath}`);
+            const data = await fs.readFile(fullPath, "utf-8");
+            return {
+                content: [{ type: "text", text: data }],
+                isError: false
+            };
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+}

package/dist/workspace-mcp/src/tools/search.js

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { validatePath, handleToolError } from "../utils.js";
+const execFileAsync = promisify(execFile);
+export function registerSearchTool(server) {
+    server.tool("workspace_search", {
+        query: z.string().describe("Search query string"),
+        scope: z.string().optional().describe("Search scope (e.g., projects, knowledge, or specific project name)")
+    }, async ({ query, scope }) => {
+        try {
+            const target = scope === "root" ? "." : scope || "projects";
+            const { fullPath: baseDir } = validatePath(target);
+            // Use grep -rnI via execFile (no shell interpolation)
+            const { stdout } = await execFileAsync("grep", ["-rnIE", query, "."], { cwd: baseDir });
+            const results = stdout.split("\n").slice(0, 50).join("\n");
+            return {
+                content: [{ type: "text", text: results || "No results found." }],
+                isError: false
+            };
+        }
+        catch (error) {
+            // If grep fails (no results), return a friendly message
+            if (error.code === 1) {
+                return {
+                    content: [{ type: "text", text: "No results found." }],
+                    isError: false
+                };
+            }
+            return handleToolError(error);
+        }
+    });
+}

package/dist/workspace-mcp/src/tools/write.js

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import fs from "fs/promises";
+import { validatePath, gitCommit, handleToolError } from "../utils.js";
+export function registerWriteTool(server) {
+    server.tool("workspace_write", {
+        path: z.string().describe("Relative path to the file"),
+        content: z.string().describe("Content to write"),
+        mode: z.enum(["append", "replace"]).describe("Write mode")
+    }, async ({ path: filePath, content, mode }) => {
+        try {
+            const { fullPath, relativePath } = validatePath(filePath);
+            const { isReadOnly } = await import("../utils.js");
+            if (isReadOnly(fullPath)) {
+                throw new Error(`Path ${filePath} is in a read-only bucket (knowledge/schemas). Use specific extraction tools to update knowledge.`);
+            }
+            if (mode === "append") {
+                await fs.appendFile(fullPath, "\n" + content, "utf-8");
+            }
+            else {
+                await fs.writeFile(fullPath, content, "utf-8");
+            }
+            // Secure auto-commit via GitQueue
+            await gitCommit(fullPath, `chore(mcp): update ${relativePath}`);
+            return {
+                content: [{ type: "text", text: `Successfully ${mode}d to ${filePath}` }],
+                isError: false
+            };
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+}

package/dist/workspace-mcp/src/utils.js

@@ -0,0 +1,7 @@
+export { findWorkspaceRoot, workspaceRoot, ALLOWED_BUCKETS, validatePath, isReadOnly, gitCommit } from "@context-os/core";
+export function handleToolError(error) {
+    return {
+        content: [{ type: "text", text: `Error: ${error.message}` }],
+        isError: true
+    };
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@context-os/mcp",
+  "version": "1.0.0",
+  "description": "Model Context Protocol server for ContextOS integration",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "bin": {
+    "context-os-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc -w",
+    "start": "node dist/index.js",
+    "test": "npm run build && PATH=/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin npx mocha dist/tests/**/*.test.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.0",
+    "@context-os/core": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/chai": "^5.2.3",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^22.13.10",
+    "chai": "^6.2.2",
+    "mocha": "^11.7.5",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.8.2"
+  }
+}