@geminilight/mindos 0.1.0

package/mcp/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "mindos-mcp",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "npx tsx src/index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^25.4.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5"
+  }
+}

package/mcp/src/index.ts

@@ -0,0 +1,494 @@
+/**
+ * MindOS MCP Server — HTTP client wrapper
+ *
+ * Pure protocol adapter: maps MCP tools to App REST API calls via fetch.
+ * Zero business logic — all operations delegated to the App.
+ *
+ * Transport modes:
+ *   Streamable HTTP (default):
+ *     mindos mcp
+ *
+ *   stdio:
+ *     MCP_TRANSPORT=stdio mindos mcp
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
+import { randomUUID } from "node:crypto";
+import { createServer } from "node:http";
+import { z } from "zod";
+
+// ─── Config ──────────────────────────────────────────────────────────────────
+
+const BASE_URL       = process.env.MINDOS_URL      ?? "http://localhost:3000";
+const AUTH_TOKEN     = process.env.AUTH_TOKEN;
+const MCP_TRANSPORT  = process.env.MCP_TRANSPORT   ?? "http";    // "http" | "stdio"
+const MCP_HOST       = process.env.MCP_HOST        ?? "127.0.0.1";
+const MCP_PORT       = parseInt(process.env.MCP_PORT ?? "8787", 10);
+const MCP_ENDPOINT   = process.env.MCP_ENDPOINT    ?? "/mcp";
+const CHARACTER_LIMIT = 25_000;
+
+function headers(): Record<string, string> {
+  const h: Record<string, string> = { "Content-Type": "application/json" };
+  if (AUTH_TOKEN) h["Authorization"] = `Bearer ${AUTH_TOKEN}`;
+  return h;
+}
+
+// ─── HTTP helpers ────────────────────────────────────────────────────────────
+
+async function get(path: string, params?: Record<string, string>): Promise<Record<string, unknown>> {
+  const url = new URL(path, BASE_URL);
+  if (params) {
+    for (const [k, v] of Object.entries(params)) {
+      if (v !== undefined && v !== null) url.searchParams.set(k, v);
+    }
+  }
+  const res = await fetch(url.toString(), { headers: headers() });
+  const json = await res.json() as Record<string, unknown>;
+  if (!res.ok) throw new Error((json.error as string) ?? `HTTP ${res.status}`);
+  return json;
+}
+
+async function post(path: string, body: Record<string, unknown>): Promise<Record<string, unknown>> {
+  const res = await fetch(new URL(path, BASE_URL).toString(), {
+    method: "POST",
+    headers: headers(),
+    body: JSON.stringify(body),
+  });
+  const json = await res.json() as Record<string, unknown>;
+  if (!res.ok) throw new Error((json.error as string) ?? `HTTP ${res.status}`);
+  return json;
+}
+
+function ok(text: string) {
+  return { content: [{ type: "text" as const, text }] };
+}
+
+function error(msg: string) {
+  return { isError: true, content: [{ type: "text" as const, text: `Error: ${msg}` }] };
+}
+
+function truncate(text: string, limit = CHARACTER_LIMIT): string {
+  if (text.length <= limit) return text;
+  return text.slice(0, limit) + `\n\n[... truncated at ${limit} characters. Use offset/limit params for paginated access.]`;
+}
+
+// ─── MCP Server ──────────────────────────────────────────────────────────────
+
+const server = new McpServer({ name: "mindos-mcp-server", version: "1.0.0" });
+
+// ── mindos_list_files ───────────────────────────────────────────────────────
+
+server.registerTool("mindos_list_files", {
+  title: "List Knowledge Base Files",
+  description: "Return the full file tree of the MindOS knowledge base as a directory tree.",
+  inputSchema: z.object({
+    response_format: z.enum(["markdown", "json"]).default("markdown"),
+  }),
+  annotations: { readOnlyHint: true },
+}, async ({ response_format }) => {
+  try {
+    const json = await get("/api/files", { format: response_format });
+    return ok(typeof json.tree === "string" ? json.tree : JSON.stringify(json.tree ?? json, null, 2));
+  } catch (e) { return error(String(e)); }
+});
+
+// ── mindos_read_file ────────────────────────────────────────────────────────
+
+server.registerTool("mindos_read_file", {
+  title: "Read File Content",
+  description: "Read the full content of a file in the MindOS knowledge base.",
+  inputSchema: z.object({
+    path: z.string().min(1),
+    offset: z.number().int().min(0).default(0),
+    limit: z.number().int().min(1).max(CHARACTER_LIMIT).default(CHARACTER_LIMIT),
+  }),
+  annotations: { readOnlyHint: true },
+}, async ({ path, offset, limit }) => {
+  try {
+    const json = await get("/api/file", { path, op: "read_file" });
+    const content = json.content as string;
+    const slice = content.slice(offset, offset + limit);
+    const hasMore = offset + limit < content.length;
+    const header = hasMore
+      ? `[Showing characters ${offset}–${offset + slice.length} of ${content.length}. Use offset=${offset + limit} for next page.]\n\n`
+      : offset > 0 ? `[Showing characters ${offset}–${offset + slice.length} of ${content.length}]\n\n` : "";
+    return ok(header + slice);
+  } catch (e) { return error(String(e)); }
+});
+
+// ── mindos_write_file ───────────────────────────────────────────────────────
+
+server.registerTool("mindos_write_file", {
+  title: "Write File Content",
+  description: "Overwrite the entire content of an existing file.",
+  inputSchema: z.object({
+    path: z.string().min(1),
+    content: z.string(),
+  }),
+}, async ({ path, content }) => {
+  try {
+    await post("/api/file", { op: "save_file", path, content });
+    return ok(`Successfully wrote ${content.length} characters to "${path}"`);
+  } catch (e) { return error(String(e)); }
+});
+
+// ── mindos_create_file ──────────────────────────────────────────────────────
+
+server.registerTool("mindos_create_file", {
+  title: "Create New File",
+  description: "Create a new file in the knowledge base. Only .md and .csv files allowed.",
+  inputSchema: z.object({
+    path: z.string().min(1).regex(/\.(md|csv)$/),
+    content: z.string().default(""),
+  }),
+}, async ({ path, content }) => {
+  try {
+    await post("/api/file", { op: "create_file", path, content });
+    return ok(`Created "${path}" (${content.length} characters)`);
+  } catch (e) { return error(String(e)); }
+});
+
+// ── mindos_delete_file ──────────────────────────────────────────────────────
+
+server.registerTool("mindos_delete_file", {
+  title: "Delete File",
+  description: "Permanently delete a file from the knowledge base.",
+  inputSchema: z.object({
+    path: z.string().min(1),
+  }),
+  annotations: { destructiveHint: true },
+}, async ({ path }) => {
+  try {
+    await post("/api/file", { op: "delete_file", path });
+    return ok(`Deleted "${path}"`);
+  } catch (e) { return error(String(e)); }
+});
+
+// ── mindos_rename_file ──────────────────────────────────────────────────────
+
+server.registerTool("mindos_rename_file", {
+  title: "Rename File",
+  description: "Rename a file within its current directory.",
+  inputSchema: z.object({
+    path: z.string().min(1),
+    new_name: z.string().min(1),
+  }),
+}, async ({ path, new_name }) => {
+  try {
+    const json = await post("/api/file", { op: "rename_file", path, new_name });
+    return ok(`Renamed "${path}" → "${json.newPath}"`);
+  } catch (e) { return error(String(e)); }
+});
+
+// ── mindos_move_file ────────────────────────────────────────────────────────
+
+server.registerTool("mindos_move_file", {
+  title: "Move File",
+  description: "Move a file to a new path. Returns affected backlinks.",
+  inputSchema: z.object({
+    from_path: z.string().min(1),
+    to_path: z.string().min(1),
+  }),
+}, async ({ from_path, to_path }) => {
+  try {
+    const json = await post("/api/file", { op: "move_file", path: from_path, to_path });
+    const affected = json.affectedFiles as string[] ?? [];
+    const lines = [`Moved "${from_path}" → "${json.newPath}"`];
+    if (affected.length > 0) {
+      lines.push("", `${affected.length} file(s) reference the old path:`);
+      for (const f of affected) lines.push(`  - ${f}`);
+    }
+    return ok(lines.join("\n"));
+  } catch (e) { return error(String(e)); }
+});
+
+// ── mindos_search_notes ─────────────────────────────────────────────────────
+
+server.registerTool("mindos_search_notes", {
+  title: "Search Knowledge Base",
+  description: "Full-text search across all .md and .csv files.",
+  inputSchema: z.object({
+    query: z.string().min(1).max(200),
+    limit: z.number().int().min(1).max(50).default(20),
+    scope: z.string().optional(),
+    file_type: z.enum(["md", "csv", "all"]).default("all"),
+    modified_after: z.string().optional(),
+    response_format: z.enum(["markdown", "json"]).default("markdown"),
+  }),
+  annotations: { readOnlyHint: true },
+}, async ({ query, limit, scope, file_type, modified_after, response_format }) => {
+  try {
+    const params: Record<string, string> = { q: query, limit: String(limit) };
+    if (scope) params.scope = scope;
+    if (file_type !== "all") params.file_type = file_type;
+    if (modified_after) params.modified_after = modified_after;
+    if (response_format) params.format = response_format;
+    const json = await get("/api/search", params);
+    return ok(truncate(JSON.stringify(json, null, 2)));
+  } catch (e) { return error(String(e)); }
+});
+
+// ── mindos_get_recent ───────────────────────────────────────────────────────
+
+server.registerTool("mindos_get_recent", {
+  title: "Get Recently Modified Files",
+  description: "Return recently modified files sorted by modification time.",
+  inputSchema: z.object({
+    limit: z.number().int().min(1).max(50).default(10),
+    response_format: z.enum(["markdown", "json"]).default("markdown"),
+  }),
+  annotations: { readOnlyHint: true },
+}, async ({ limit, response_format }) => {
+  try {
+    const json = await get("/api/recent-files", { limit: String(limit), format: response_format });
+    return ok(JSON.stringify(json, null, 2));
+  } catch (e) { return error(String(e)); }
+});
+
+// ── mindos_read_lines ───────────────────────────────────────────────────────
+
+server.registerTool("mindos_read_lines", {
+  title: "Read File as Lines",
+  description: "Read file content as a numbered array of lines (0-indexed).",
+  inputSchema: z.object({
+    path: z.string().min(1),
+  }),
+  annotations: { readOnlyHint: true },
+}, async ({ path }) => {
+  try {
+    const json = await get("/api/file", { path, op: "read_lines" });
+    const lines = json.lines as string[];
+    const numbered = lines.map((l, i) => `${i}: ${l}`).join("\n");
+    return ok(`${lines.length} lines total:\n\n${numbered}`);
+  } catch (e) { return error(String(e)); }
+});
+
+// ── mindos_insert_lines ─────────────────────────────────────────────────────
+
+server.registerTool("mindos_insert_lines", {
+  title: "Insert Lines into File",
+  description: "Insert lines at a specific position (0-based, -1 to prepend).",
+  inputSchema: z.object({
+    path: z.string().min(1),
+    after_index: z.number().int(),
+    lines: z.array(z.string()).min(1),
+  }),
+}, async ({ path, after_index, lines }) => {
+  try {
+    await post("/api/file", { op: "insert_lines", path, after_index, lines });
+    return ok(`Inserted ${lines.length} line(s) after index ${after_index} in "${path}"`);
+  } catch (e) { return error(String(e)); }
+});
+
+// ── mindos_update_lines ─────────────────────────────────────────────────────
+
+server.registerTool("mindos_update_lines", {
+  title: "Replace Lines in File",
+  description: "Replace a range of lines (inclusive, 0-based).",
+  inputSchema: z.object({
+    path: z.string().min(1),
+    start: z.number().int().min(0),
+    end: z.number().int().min(0),
+    lines: z.array(z.string()).min(1),
+  }),
+}, async ({ path, start, end, lines }) => {
+  try {
+    await post("/api/file", { op: "update_lines", path, start, end, lines });
+    return ok(`Replaced lines ${start}–${end} in "${path}" with ${lines.length} new line(s)`);
+  } catch (e) { return error(String(e)); }
+});
+
+// ── mindos_append_to_file ───────────────────────────────────────────────────
+
+server.registerTool("mindos_append_to_file", {
+  title: "Append Content to File",
+  description: "Append text to the end of an existing file.",
+  inputSchema: z.object({
+    path: z.string().min(1),
+    content: z.string().min(1),
+  }),
+}, async ({ path, content }) => {
+  try {
+    await post("/api/file", { op: "append_to_file", path, content });
+    return ok(`Appended ${content.length} character(s) to "${path}"`);
+  } catch (e) { return error(String(e)); }
+});
+
+// ── mindos_insert_after_heading ─────────────────────────────────────────────
+
+server.registerTool("mindos_insert_after_heading", {
+  title: "Insert Content After Heading",
+  description: "Insert content after a Markdown heading.",
+  inputSchema: z.object({
+    path: z.string().min(1),
+    heading: z.string().min(1),
+    content: z.string().min(1),
+  }),
+}, async ({ path, heading, content }) => {
+  try {
+    await post("/api/file", { op: "insert_after_heading", path, heading, content });
+    return ok(`Inserted content after heading "${heading}" in "${path}"`);
+  } catch (e) { return error(String(e)); }
+});
+
+// ── mindos_update_section ───────────────────────────────────────────────────
+
+server.registerTool("mindos_update_section", {
+  title: "Replace Markdown Section Content",
+  description: "Replace the content of a Markdown section identified by heading.",
+  inputSchema: z.object({
+    path: z.string().min(1),
+    heading: z.string().min(1),
+    content: z.string(),
+  }),
+}, async ({ path, heading, content }) => {
+  try {
+    await post("/api/file", { op: "update_section", path, heading, content });
+    return ok(`Updated section "${heading}" in "${path}"`);
+  } catch (e) { return error(String(e)); }
+});
+
+// ── mindos_append_csv ───────────────────────────────────────────────────────
+
+server.registerTool("mindos_append_csv", {
+  title: "Append Row to CSV",
+  description: "Append a row to a CSV file with RFC 4180 escaping.",
+  inputSchema: z.object({
+    path: z.string().min(1).regex(/\.csv$/),
+    row: z.array(z.string()).min(1),
+  }),
+}, async ({ path, row }) => {
+  try {
+    const json = await post("/api/file", { op: "append_csv", path, row });
+    return ok(`Appended row to "${path}". File now has ${json.newRowCount} rows.`);
+  } catch (e) { return error(String(e)); }
+});
+
+// ── mindos_get_backlinks ────────────────────────────────────────────────────
+
+server.registerTool("mindos_get_backlinks", {
+  title: "Find Backlinks to File",
+  description: "Find all files that reference a given file path.",
+  inputSchema: z.object({
+    path: z.string().min(1),
+  }),
+  annotations: { readOnlyHint: true },
+}, async ({ path }) => {
+  try {
+    const json = await get("/api/backlinks", { path });
+    return ok(JSON.stringify(json, null, 2));
+  } catch (e) { return error(String(e)); }
+});
+
+// ── mindos_bootstrap ────────────────────────────────────────────────────────
+
+server.registerTool("mindos_bootstrap", {
+  title: "Bootstrap Agent Context",
+  description: "Load MindOS startup context: INSTRUCTION.md, README.md, CONFIG files, and optional target directory context.",
+  inputSchema: z.object({
+    target_dir: z.string().optional(),
+  }),
+  annotations: { readOnlyHint: true },
+}, async ({ target_dir }) => {
+  try {
+    const params: Record<string, string> = {};
+    if (target_dir) params.target_dir = target_dir;
+    const json = await get("/api/bootstrap", params);
+    const sections = Object.entries(json)
+      .filter(([, v]) => v !== undefined && v !== null)
+      .map(([key, val]) => `--- ${key} ---\n\n${val}`)
+      .join("\n\n");
+    return ok(truncate(sections));
+  } catch (e) { return error(String(e)); }
+});
+
+// ── mindos_get_history ──────────────────────────────────────────────────────
+
+server.registerTool("mindos_get_history", {
+  title: "Get File Git History",
+  description: "Get git commit history for a file.",
+  inputSchema: z.object({
+    path: z.string().min(1),
+    limit: z.number().int().min(1).max(50).default(10),
+  }),
+  annotations: { readOnlyHint: true },
+}, async ({ path, limit }) => {
+  try {
+    const json = await get("/api/git", { op: "history", path, limit: String(limit) });
+    const entries = json.entries as Array<{ hash: string; date: string; message: string; author: string }>;
+    if (entries.length === 0) return ok(`No git history found for "${path}"`);
+    const lines = [`# Git History: ${path}`, "", `${entries.length} commit(s):`, ""];
+    for (const h of entries) {
+      lines.push(`- **${h.date}** \`${h.hash.slice(0, 8)}\` — ${h.message} (${h.author})`);
+    }
+    return ok(lines.join("\n"));
+  } catch (e) { return error(String(e)); }
+});
+
+// ── mindos_get_file_at_version ──────────────────────────────────────────────
+
+server.registerTool("mindos_get_file_at_version", {
+  title: "Read File at Git Version",
+  description: "Read file content at a specific git commit.",
+  inputSchema: z.object({
+    path: z.string().min(1),
+    commit: z.string().min(4),
+  }),
+  annotations: { readOnlyHint: true },
+}, async ({ path, commit }) => {
+  try {
+    const json = await get("/api/git", { op: "show", path, commit });
+    const content = json.content as string;
+    return ok(truncate(`# ${path} @ ${commit.slice(0, 8)}\n\n${content}`));
+  } catch (e) { return error(String(e)); }
+});
+
+// ─── Start ───────────────────────────────────────────────────────────────────
+
+async function main() {
+  if (MCP_TRANSPORT === "http") {
+    // ── Streamable HTTP mode ──────────────────────────────────────────────
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => randomUUID(),
+    });
+
+    const expressApp = createMcpExpressApp({ host: MCP_HOST });
+
+    // Auth middleware
+    if (AUTH_TOKEN) {
+      expressApp.use(MCP_ENDPOINT, (req, res, next) => {
+        const bearer = req.headers.authorization?.replace("Bearer ", "");
+        if (bearer !== AUTH_TOKEN) {
+          res.status(401).json({ error: "Unauthorized" });
+          return;
+        }
+        next();
+      });
+    }
+
+    expressApp.all(MCP_ENDPOINT, async (req, res) => {
+      await transport.handleRequest(req, res);
+    });
+
+    await server.connect(transport);
+
+    const httpServer = createServer(expressApp as Parameters<typeof createServer>[1]);
+    httpServer.listen(MCP_PORT, MCP_HOST, () => {
+      console.error(`MindOS MCP server (HTTP) listening on http://${MCP_HOST}:${MCP_PORT}${MCP_ENDPOINT}`);
+      console.error(`API backend: ${BASE_URL}`);
+    });
+  } else {
+    // ── stdio mode (default) ──────────────────────────────────────────────
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`MindOS MCP server started (stdio, API: ${BASE_URL})`);
+  }
+}
+
+main().catch((e) => {
+  console.error("Fatal:", e);
+  process.exit(1);
+});

package/mcp/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@geminilight/mindos",
+  "version": "0.1.0",
+  "description": "MindOS — Human-Agent Collaborative Mind System. Local-first knowledge base that syncs your mind to all AI Agents via MCP.",
+  "keywords": ["mindos", "mcp", "knowledge-base", "ai-agent", "local-first", "second-brain"],
+  "type": "module",
+  "license": "MIT",
+  "author": "GeminiLight",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GeminiLight/MindOS"
+  },
+  "bin": {
+    "mindos": "bin/cli.js"
+  },
+  "workspaces": ["app", "mcp"],
+  "files": [
+    "app/",
+    "mcp/",
+    "templates/",
+    "skills/",
+    "bin/",
+    "scripts/",
+    "assets/",
+    "README.md",
+    "README_zh.md",
+    "LICENSE",
+    ".env.local.example",
+    "!app/node_modules",
+    "!app/.next",
+    "!app/.env.local",
+    "!app/.claude",
+    "!app/__tests__",
+    "!app/**/*.bak",
+    "!mcp/node_modules",
+    "!mcp/dist"
+  ],
+  "scripts": {
+    "setup": "node scripts/setup.js",
+    "dev": "mindos dev",
+    "build": "mindos build",
+    "start": "mindos start",
+    "mcp": "mindos mcp",
+    "test": "cd app && npx vitest run"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}