@dreamtree-org/graphify 1.1.3 → 1.2.0

package/README.md

@@ -31,6 +31,14 @@ npm install -g @dreamtree-org/graphify
 npx @dreamtree-org/graphify .
 ```
 
+A default run does more than build the graph — it also makes it instantly usable by the AI
+agents your project already has: it installs the graphify skill/rules files and registers the
+project-scoped MCP server. Claude Code is always set up (`.claude/skills/graphify/SKILL.md` +
+`.mcp.json`); Cursor, Windsurf, Cline, AGENTS.md hosts, and Gemini CLI are set up when their
+config dir/file is detected in the project. All writes are idempotent and never touch your
+existing config (`.mcp.json` entries for other servers, user content in `AGENTS.md`, ...).
+Opt out with `--no-install`.
+
 ## Build the graph
 
 ```bash
@@ -43,6 +51,7 @@ graphify . --leiden             # Leiden instead of Louvain community detection
 graphify . --watch              # rebuild on file change
 graphify . --mysql <dsn>        # also extract a MySQL schema (mysql://user:pass@host:port/db) into the same graph
 graphify . --mcp                # start the MCP stdio server instead of running the pipeline
+graphify . --no-install         # skip the automatic agent skill + MCP config install
 ```
 
 Outputs land in `graphify-out/`: `graph.json` (GraphRAG-ready), `graph.html` (interactive,
@@ -79,8 +88,10 @@ graphify save-result --question Q --answer A --nodes id... --outcome useful|dead
 graphify reflect                # aggregate results into graphify-out/reflections/LESSONS.md
                                 #   (recency-weighted; agents read it at session start)
 graphify hook install           # auto-rebuild (incremental) after every commit and pull
-graphify install --platform all # install the agent skill/rules: claude, cursor, windsurf, cline,
-                                #   agents (AGENTS.md: Codex/opencode/Amp), gemini
+graphify install --platform all # install the agent skill/rules + project MCP config: claude,
+                                #   cursor, windsurf, cline, agents (AGENTS.md: Codex/opencode/Amp),
+                                #   gemini — a plain `graphify .` run already does this for
+                                #   detected hosts
 ```
 
 With hooks installed the MCP server always serves a fresh graph — it re-reads `graph.json`
@@ -102,6 +113,11 @@ so repos that use the same packages are automatically bridged in the merged grap
 `graphify --mcp` (or the `graphify-mcp` binary) exposes `context`, `query`, `path`,
 `explain`, `affected`, and `tests` as MCP tools over stdio. No network listener.
 
+You normally never start it by hand: the default pipeline run registers it in the project's
+MCP config (`.mcp.json` for Claude Code, `.cursor/mcp.json` for Cursor, `.gemini/settings.json`
+for Gemini CLI) as `npx -y @dreamtree-org/graphify --mcp`, so the host launches it on demand —
+and teammates who pull the repo get it with zero setup.
+
 ## Guardrails file
 
 `graphify.rules.json` at the repo root (this repo dogfoods its own):

package/dist/cli/index.cjs

@@ -4778,6 +4778,29 @@ function packageRoot() {
   const packageJsonPath = require4.resolve("@dreamtree-org/graphify/package.json");
   return path15.dirname(packageJsonPath);
 }
+var MCP_SERVER_ENTRY = {
+  command: "npx",
+  args: ["-y", "@dreamtree-org/graphify", "--mcp"]
+};
+async function upsertMcpServer(filePath, serversKey = "mcpServers") {
+  let config = {};
+  try {
+    config = JSON.parse(await fs22.readFile(filePath, "utf-8"));
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw new Error(`cannot update ${filePath} \u2014 it exists but is not valid JSON; fix or remove it and re-run.`, {
+        cause: error
+      });
+    }
+  }
+  const servers = config[serversKey] ?? {};
+  servers["graphify"] = MCP_SERVER_ENTRY;
+  config[serversKey] = servers;
+  await fs22.mkdir(path15.dirname(filePath), { recursive: true });
+  await fs22.writeFile(filePath, `${JSON.stringify(config, null, 2)}
+`, "utf-8");
+  return filePath;
+}
 var MD_MARKER_BEGIN = "<!-- >>> graphify >>> -->";
 var MD_MARKER_END = "<!-- <<< graphify <<< -->";
 async function writeOwnedFile(filePath, content) {
@@ -4812,7 +4835,8 @@ var PLATFORMS = {
   claude: async (cwd, content) => {
     const target = path15.join(cwd, ".claude", "skills", "graphify", "SKILL.md");
     await writeOwnedFile(target, content);
-    return { host: "Claude Code", path: target };
+    const mcpPath = await upsertMcpServer(path15.join(cwd, ".mcp.json"));
+    return { host: "Claude Code", path: target, mcpPath };
   },
   cursor: async (cwd, content) => {
     const target = path15.join(cwd, ".cursor", "rules", "graphify.mdc");
@@ -4825,7 +4849,8 @@ alwaysApply: false
 ---
 ${body}`
     );
-    return { host: "Cursor", path: target };
+    const mcpPath = await upsertMcpServer(path15.join(cwd, ".cursor", "mcp.json"));
+    return { host: "Cursor", path: target, mcpPath };
   },
   windsurf: async (cwd, content) => {
     const target = path15.join(cwd, ".windsurf", "rules", "graphify.md");
@@ -4845,10 +4870,32 @@ ${body}`
   gemini: async (cwd, content) => {
     const target = path15.join(cwd, "GEMINI.md");
     await upsertMarkedBlock(target, content.replace(/^---[\s\S]*?---\n/, ""));
-    return { host: "Gemini CLI", path: target };
+    const mcpPath = await upsertMcpServer(path15.join(cwd, ".gemini", "settings.json"));
+    return { host: "Gemini CLI", path: target, mcpPath };
   }
 };
 var SUPPORTED_PLATFORMS = Object.keys(PLATFORMS).sort((a, b) => a.localeCompare(b));
+var PLATFORM_MARKERS = {
+  cursor: [".cursor"],
+  windsurf: [".windsurf"],
+  cline: [".clinerules"],
+  agents: ["AGENTS.md"],
+  gemini: ["GEMINI.md", ".gemini"]
+};
+async function detectPlatforms(cwd = process.cwd()) {
+  const platforms = ["claude"];
+  for (const [platform, markers] of Object.entries(PLATFORM_MARKERS)) {
+    for (const marker of markers) {
+      try {
+        await fs22.access(path15.join(cwd, marker));
+        platforms.push(platform);
+        break;
+      } catch {
+      }
+    }
+  }
+  return platforms;
+}
 async function runInstall(platforms = ["claude"], cwd = process.cwd()) {
   const sourcePath = path15.join(packageRoot(), "src", "skill", "SKILL.md");
   const content = await fs22.readFile(sourcePath, "utf-8");
@@ -4864,7 +4911,8 @@ async function runInstall(platforms = ["claude"], cwd = process.cwd()) {
     results.push(await installer(cwd, content));
   }
   for (const result of results) {
-    console.log(`Installed graphify for ${result.host} -> ${result.path}`);
+    const mcpNote = result.mcpPath ? ` (MCP server registered in ${result.mcpPath})` : "";
+    console.log(`Installed graphify for ${result.host} -> ${result.path}${mcpNote}`);
   }
   return results;
 }
@@ -4980,7 +5028,7 @@ async function watchAndRebuild(root, runOnce) {
   });
 }
 var program = new import_commander.Command();
-program.name("graphify").description("Turn a folder of code/docs/papers into a queryable knowledge graph.").argument("[path]", "path to scan, or a GitHub URL", ".").option("--mode <mode>", "extraction mode (deep for richer INFERRED edges \u2014 reserved, no-op in v1)").option("--update", "incremental rebuild \u2014 reuse cached extractions for unchanged files").option("--watch", "rebuild on file change").option("--cluster-only", "rerun clustering on an existing graph").option("--leiden", "use Leiden instead of Louvain for community detection (v2 \u2014 better community quality)").option("--max-iterations <n>", "Leiden only: cap on outer iterations for very large graphs", Number).option("--no-viz", "skip graph.html").option("--svg", "also export graph.svg (not implemented in v1)").option("--graphml", "also export graph.graphml (not implemented in v1)").option("--neo4j", "generate graphify-out/cypher.txt for Neo4j (not implemented in v1)").option("--mcp", "start MCP stdio server instead of running the pipeline").option("--mysql <dsn>", "also extract a MySQL schema (mysql://user:pass@host:port/db) into the graph").action(async (targetArg, options) => {
+program.name("graphify").description("Turn a folder of code/docs/papers into a queryable knowledge graph.").argument("[path]", "path to scan, or a GitHub URL", ".").option("--mode <mode>", "extraction mode (deep for richer INFERRED edges \u2014 reserved, no-op in v1)").option("--update", "incremental rebuild \u2014 reuse cached extractions for unchanged files").option("--watch", "rebuild on file change").option("--cluster-only", "rerun clustering on an existing graph").option("--leiden", "use Leiden instead of Louvain for community detection (v2 \u2014 better community quality)").option("--max-iterations <n>", "Leiden only: cap on outer iterations for very large graphs", Number).option("--no-viz", "skip graph.html").option("--svg", "also export graph.svg (not implemented in v1)").option("--graphml", "also export graph.graphml (not implemented in v1)").option("--neo4j", "generate graphify-out/cypher.txt for Neo4j (not implemented in v1)").option("--mcp", "start MCP stdio server instead of running the pipeline").option("--no-install", "skip auto-installing the agent skill + MCP config after the build").option("--mysql <dsn>", "also extract a MySQL schema (mysql://user:pass@host:port/db) into the graph").action(async (targetArg, options) => {
   try {
     if (options.mcp) {
       const outDir = path17.resolve(targetArg === "." ? process.cwd() : targetArg, "graphify-out");
@@ -4989,7 +5037,8 @@ program.name("graphify").description("Turn a folder of code/docs/papers into a q
       return;
     }
     let root = targetArg;
-    if (looksLikeGitUrl(targetArg)) {
+    const cloned = looksLikeGitUrl(targetArg);
+    if (cloned) {
       console.error(`Cloning ${targetArg} ...`);
       root = await cloneRepo(targetArg);
     }
@@ -5015,6 +5064,13 @@ program.name("graphify").description("Turn a folder of code/docs/papers into a q
       onProgress: (m) => console.error(m)
     });
     await runOnce();
+    if (options.install && !cloned) {
+      try {
+        await runInstall(await detectPlatforms(root), root);
+      } catch (error) {
+        console.error(`graphify: agent skill/MCP install skipped: ${error.message}`);
+      }
+    }
     if (options.watch) {
       console.error(`Watching ${root} for changes (Ctrl+C to stop) ...`);
       await watchAndRebuild(root, runOnce);
@@ -5096,7 +5152,7 @@ program.command("benchmark [questions...]").description("measure token savings o
     process.exitCode = 1;
   }
 });
-program.command("install").description("install the skill/rules files into local agents (claude, cursor, windsurf, cline, agents, gemini, all)").option("--platform <names...>", "platform(s) to install for", ["claude"]).action(async (options) => {
+program.command("install").description("install the skill/rules files + project MCP config into local agents (claude, cursor, windsurf, cline, agents, gemini, all)").option("--platform <names...>", "platform(s) to install for", ["claude"]).action(async (options) => {
   try {
     await runInstall(options.platform);
   } catch (error) {