@blockrun/franklin 3.23.1 → 3.24.0

package/dist/commands/start.js

@@ -15,7 +15,8 @@ import { validateToolDescriptions } from '../tools/validate.js';
 import { launchInkUI } from '../ui/app.js';
 import { pickModel, resolveModel } from '../ui/model-picker.js';
 import { loadMcpConfig } from '../mcp/config.js';
-import { connectMcpServers, disconnectMcpServers } from '../mcp/client.js';
+import { connectMcpServers, disconnectMcpServers, getMcpServerInstructions } from '../mcp/client.js';
+import { ensureCodegraphIndex } from '../mcp/codegraph.js';
 export async function startCommand(options) {
     const version = options.version ?? '1.0.0';
     // Early-validate explicit resume ID so a typo fails fast — before wallet
@@ -282,6 +283,10 @@ export async function startCommand(options) {
     const systemInstructions = assembleInstructions(workDir, model);
     // Connect MCP servers (non-blocking — add tools if servers are available)
     const mcpConfig = loadMcpConfig(workDir);
+    // Kick off the CodeGraph index build (no-op if disabled/absent/already built).
+    // Runs in the background so it never blocks startup; the agent falls back to
+    // grep/read until the index is ready.
+    ensureCodegraphIndex(workDir);
     let mcpTools = [];
     const mcpServerCount = Object.keys(mcpConfig.mcpServers).filter(k => !mcpConfig.mcpServers[k].disabled).length;
     if (mcpServerCount > 0) {
@@ -290,6 +295,13 @@ export async function startCommand(options) {
             if (mcpTools.length > 0) {
                 console.log(chalk.dim(`  MCP:    ${mcpTools.length} tools from ${mcpServerCount} server(s)`));
             }
+            // Fold each connected server's playbook (from its initialize response)
+            // into the system prompt. For CodeGraph this is what drives the agent to
+            // query the index instead of looping grep — the bulk of the savings.
+            const mcpInstructions = getMcpServerInstructions();
+            if (mcpInstructions) {
+                systemInstructions.push(mcpInstructions);
+            }
         }
         catch (err) {
             if (options.debug) {

package/dist/mcp/client.d.ts

@@ -34,6 +34,17 @@ export declare function connectMcpServers(config: McpConfig, debug?: boolean): P
  * Disconnect all MCP servers.
  */
 export declare function disconnectMcpServers(): Promise<void>;
+/**
+ * Aggregate server-level instructions from all connected MCP servers into a
+ * single system-prompt section, or '' if no server supplied any.
+ *
+ * These come from the `initialize` response of servers Franklin chose to
+ * connect (built-in, or user-configured + trusted), so they're treated as
+ * trusted guidance rather than untrusted data. The agent reads this once per
+ * session to learn each toolset's playbook (which tool for which question,
+ * common chains, anti-patterns) instead of rediscovering it by trial.
+ */
+export declare function getMcpServerInstructions(): string;
 /**
  * List connected MCP servers and their tools.
  */

package/dist/mcp/client.js

@@ -151,7 +151,12 @@ async function connectStdio(name, config) {
     catch {
         // Server doesn't support resources — that's fine, tools-only mode
     }
-    const connected = { name, client, transport, tools: capabilities };
+    // Server-level instructions from the initialize response. MCP servers use
+    // this to tell the agent HOW to use their tools (selection-by-intent, common
+    // chains, anti-patterns) — e.g. CodeGraph's "answer directly, don't grep to
+    // re-verify" playbook, which is where most of its tool-call savings come from.
+    const instructions = (client.getInstructions() || '').trim() || undefined;
+    const connected = { name, client, transport, tools: capabilities, instructions };
     connections.set(name, connected);
     return connected;
 }
@@ -210,6 +215,32 @@ export async function disconnectMcpServers() {
         connections.delete(name);
     }
 }
+/**
+ * Aggregate server-level instructions from all connected MCP servers into a
+ * single system-prompt section, or '' if no server supplied any.
+ *
+ * These come from the `initialize` response of servers Franklin chose to
+ * connect (built-in, or user-configured + trusted), so they're treated as
+ * trusted guidance rather than untrusted data. The agent reads this once per
+ * session to learn each toolset's playbook (which tool for which question,
+ * common chains, anti-patterns) instead of rediscovering it by trial.
+ */
+export function getMcpServerInstructions() {
+    const blocks = [];
+    for (const [name, conn] of connections) {
+        if (conn.instructions) {
+            blocks.push(`### MCP server: ${name}\n${conn.instructions}`);
+        }
+    }
+    if (blocks.length === 0)
+        return '';
+    return [
+        '## Connected MCP tool playbooks',
+        'Each connected MCP server below provides guidance on how to use its tools effectively. Follow these playbooks when those tools are relevant.',
+        '',
+        blocks.join('\n\n'),
+    ].join('\n');
+}
 /**
  * List connected MCP servers and their tools.
  */

package/dist/mcp/codegraph.d.ts

@@ -0,0 +1,45 @@
+/**
+ * CodeGraph built-in MCP server integration.
+ *
+ * CodeGraph (https://github.com/colbymchenry/codegraph, MIT) builds a local
+ * SQLite knowledge graph of a repo's symbols, call edges, and files via
+ * tree-sitter, then serves it over MCP. For Franklin this is a direct USDC win:
+ * agents answer "how does X work / what calls Y / trace this flow" from the
+ * pre-built index instead of looping grep + read, which cuts tool calls (and
+ * therefore paid LLM round-trips) sharply on real codebases.
+ *
+ * Shipped as a dependency, so `franklin` users get it with no extra install.
+ * The npm package is a thin shim (`npm-shim.js`) that locates a per-platform
+ * bundle (vendored Node 24 + app) and execs it — so we always launch it via
+ * the user's own node against the shim, never a global `codegraph` on PATH.
+ *
+ * Opt out with FRANKLIN_CODEGRAPH=0 (or "false").
+ */
+import type { McpServerConfig } from './client.js';
+/**
+ * Resolve the CodeGraph npm shim entry point, or null if the dependency
+ * isn't installed / resolvable. The shim is plain JS runnable by any node.
+ */
+export declare function resolveCodegraphShim(): string | null;
+/** Whether CodeGraph is available and not disabled. */
+export declare function isCodegraphEnabled(): boolean;
+/**
+ * Build the built-in MCP server config for CodeGraph, pinned to `workDir`.
+ *
+ * We launch via the user's node + the shim (the shim re-execs the bundled
+ * Node 24 runtime internally). `--path` is required because Franklin's MCP
+ * client doesn't advertise a `roots` capability, so the server can't infer
+ * the project from a rootUri — without it CodeGraph wouldn't know which repo
+ * to index. Returns null when CodeGraph is unavailable or disabled.
+ */
+export declare function getCodegraphServerConfig(workDir: string): McpServerConfig | null;
+/**
+ * Build the initial index for `workDir` if it has no `.codegraph/` yet.
+ *
+ * Non-blocking: spawns `codegraph init <workDir> -i` detached and returns
+ * immediately. The serving MCP process watches the project, so it picks up
+ * the freshly built index; until it's ready, codegraph tools report
+ * "not initialized" and the agent falls back to grep/read (no regression).
+ * No-op when CodeGraph is disabled, unavailable, or already initialized.
+ */
+export declare function ensureCodegraphIndex(workDir: string): void;

package/dist/mcp/codegraph.js

@@ -0,0 +1,105 @@
+/**
+ * CodeGraph built-in MCP server integration.
+ *
+ * CodeGraph (https://github.com/colbymchenry/codegraph, MIT) builds a local
+ * SQLite knowledge graph of a repo's symbols, call edges, and files via
+ * tree-sitter, then serves it over MCP. For Franklin this is a direct USDC win:
+ * agents answer "how does X work / what calls Y / trace this flow" from the
+ * pre-built index instead of looping grep + read, which cuts tool calls (and
+ * therefore paid LLM round-trips) sharply on real codebases.
+ *
+ * Shipped as a dependency, so `franklin` users get it with no extra install.
+ * The npm package is a thin shim (`npm-shim.js`) that locates a per-platform
+ * bundle (vendored Node 24 + app) and execs it — so we always launch it via
+ * the user's own node against the shim, never a global `codegraph` on PATH.
+ *
+ * Opt out with FRANKLIN_CODEGRAPH=0 (or "false").
+ */
+import { createRequire } from 'node:module';
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { logger } from '../logger.js';
+const require = createRequire(import.meta.url);
+/** True unless the user explicitly disabled CodeGraph via env. */
+function userEnabled() {
+    const v = (process.env.FRANKLIN_CODEGRAPH || '').toLowerCase();
+    return v !== '0' && v !== 'false' && v !== 'off';
+}
+/**
+ * Resolve the CodeGraph npm shim entry point, or null if the dependency
+ * isn't installed / resolvable. The shim is plain JS runnable by any node.
+ */
+export function resolveCodegraphShim() {
+    try {
+        const shim = require.resolve('@colbymchenry/codegraph/npm-shim.js');
+        return fs.existsSync(shim) ? shim : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Whether CodeGraph is available and not disabled. */
+export function isCodegraphEnabled() {
+    return userEnabled() && resolveCodegraphShim() !== null;
+}
+/**
+ * Build the built-in MCP server config for CodeGraph, pinned to `workDir`.
+ *
+ * We launch via the user's node + the shim (the shim re-execs the bundled
+ * Node 24 runtime internally). `--path` is required because Franklin's MCP
+ * client doesn't advertise a `roots` capability, so the server can't infer
+ * the project from a rootUri — without it CodeGraph wouldn't know which repo
+ * to index. Returns null when CodeGraph is unavailable or disabled.
+ */
+export function getCodegraphServerConfig(workDir) {
+    if (!userEnabled())
+        return null;
+    const shim = resolveCodegraphShim();
+    if (!shim)
+        return null;
+    return {
+        transport: 'stdio',
+        command: process.execPath,
+        args: [shim, 'serve', '--mcp', '--path', workDir],
+        label: 'CodeGraph (built-in)',
+    };
+}
+/**
+ * Build the initial index for `workDir` if it has no `.codegraph/` yet.
+ *
+ * Non-blocking: spawns `codegraph init <workDir> -i` detached and returns
+ * immediately. The serving MCP process watches the project, so it picks up
+ * the freshly built index; until it's ready, codegraph tools report
+ * "not initialized" and the agent falls back to grep/read (no regression).
+ * No-op when CodeGraph is disabled, unavailable, or already initialized.
+ */
+export function ensureCodegraphIndex(workDir) {
+    if (!isCodegraphEnabled())
+        return;
+    const indexDir = path.join(workDir, '.codegraph');
+    if (fs.existsSync(indexDir))
+        return; // already initialized — watcher keeps it fresh
+    const shim = resolveCodegraphShim();
+    if (!shim)
+        return;
+    try {
+        const child = spawn(process.execPath, [shim, 'init', workDir, '-i'], {
+            cwd: workDir,
+            // Discard output: this is best-effort background indexing. Failures are
+            // non-fatal — the agent simply keeps using grep/read until (and if) the
+            // index appears. Surfacing a stack trace here would just be noise.
+            stdio: 'ignore',
+            detached: true,
+        });
+        child.on('error', (err) => {
+            logger.debug(`[franklin] codegraph index build failed: ${err.message}`);
+        });
+        // Don't keep the event loop alive waiting on the indexer.
+        child.unref();
+        logger.info(`[franklin] CodeGraph: building initial index for ${workDir}`);
+    }
+    catch (err) {
+        logger.debug(`[franklin] codegraph index spawn error: ${err.message}`);
+    }
+}

package/dist/mcp/config.js

@@ -8,6 +8,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { execSync } from 'node:child_process';
 import { BLOCKRUN_DIR } from '../config.js';
+import { getCodegraphServerConfig } from './codegraph.js';
 const GLOBAL_MCP_FILE = path.join(BLOCKRUN_DIR, 'mcp.json');
 /**
  * Load MCP server configurations from global + project files.
@@ -46,6 +47,13 @@ export function loadMcpConfig(workDir) {
             servers[name] = config;
         }
     }
+    // Built-in CodeGraph: shipped as a dependency (not on PATH), so it's
+    // resolved + pinned to this workDir rather than probed via `which`.
+    // User config below can still override or disable it.
+    const codegraph = getCodegraphServerConfig(workDir);
+    if (codegraph) {
+        servers.codegraph = codegraph;
+    }
     // 1. Global config
     try {
         if (fs.existsSync(GLOBAL_MCP_FILE)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/franklin",
-  "version": "3.23.1",
+  "version": "3.24.0",
   "description": "Franklin Agent — The AI agent with a wallet. Spends USDC autonomously to get real work done. Pay per action, no subscriptions.",
   "type": "module",
   "exports": {
@@ -67,6 +67,7 @@
   },
   "dependencies": {
     "@blockrun/llm": "^2.0.0",
+    "@colbymchenry/codegraph": "^0.9.7",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@solana/spl-token": "^0.4.14",
     "@solana/web3.js": "^1.98.4",