@grafema/mcp 0.3.23 → 0.3.27

package/src/definitions/query-tools.ts

@@ -252,6 +252,44 @@ Returns: Indented call tree showing each hop with file:line location.`,
       required: ['source'],
     },
   },
+  {
+    name: 'trace_effects',
+    description: `Trace transitive side effects of a function through its call graph.
+
+For any function, traverses CALLS edges (DFS) and collects effects from leaf nodes
+using the effects-db (Node.js builtins, npm packages).
+
+Use this when you need to:
+- "What side effects does this function have?" → direct + transitive effects
+- "Does this handler do IO?" → trace shows IO:FILE:READ from fs.readFileSync at depth 3
+- "Where does the fetch() call come from?" → leaf_sources shows the origin at depth N
+- "What crosses module boundaries?" → boundary_crossings shows file-to-file effect flow
+
+Effect types: PURE, MUTATION, IO (with subtypes like IO:FILE:READ, IO:HTTP:REQUEST),
+THROW, ASYNC, NONDETERMINISTIC, UNKNOWN.
+
+UNKNOWN means: unresolved call, external package not in effects-db, or depth limit reached.
+
+Returns: direct effects, transitive effects, boundary crossings, leaf sources.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        node: {
+          type: 'string',
+          description: 'Function/method name or semantic ID',
+        },
+        file: {
+          type: 'string',
+          description: 'File path to disambiguate (optional)',
+        },
+        max_depth: {
+          type: 'number',
+          description: 'Maximum call graph traversal depth (default: 10)',
+        },
+      },
+      required: ['node'],
+    },
+  },
   {
     name: 'get_shape',
     description: `Get the shape (methods + properties) of a CLASS, INTERFACE, or typed variable.
@@ -351,4 +389,37 @@ Returns: List of nodes violating the rule, with file and line info.`,
       required: ['rule'],
     },
   },
+  {
+    name: 'find_shared_behaviors',
+    description: `List clusters of FEATUREs whose entry-points share an identical BEHAVIOR (same forward-slice hash).
+
+Surfaces cross-modality duplication — e.g. "this CLI command is a thin wrapper around the
+same library function as that HTTP endpoint" or "this MCP tool and that VS Code command
+delegate to identical logic".
+
+Each cluster contains:
+  - hash:           sha256 of the shared transitive call set (BEHAVIOR.metadata.hash)
+  - effects:        transitive effects (IO, MUTATION, …) attributed to the shared behavior
+  - coreNodeCount:  size of the shared forward slice
+  - features:       array of { id, type, name, file } — the FEATUREs that share this behavior
+
+Cluster types are FEATURE node types: cli:command, mcp:tool, vscode:command (and any future
+domain types created by enrichers).
+
+Returns clusters ordered by size (largest first), then hash (deterministic tie-break).
+Empty result means every FEATURE has a unique implementation.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        minClusterSize: {
+          type: 'number',
+          description: 'Minimum FEATUREs per cluster (default: 2). Values below 2 are clamped to 2.',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum clusters to return (default: 100).',
+        },
+      },
+    },
+  },
 ];

package/src/handlers/analysis-handlers.ts

@@ -2,7 +2,7 @@
  * MCP Analysis Handlers
  */
 
-import { ensureAnalyzed } from '../analysis.js';
+import { ensureAnalyzed, discoverServices } from '../analysis.js';
 import { getAnalysisStatus, isAnalysisRunning } from '../state.js';
 import {
   textResult,
@@ -17,6 +17,11 @@ import type { ServerStats } from '@grafema/types';
 
 // === ANALYSIS HANDLERS ===
 
+export async function handleDiscoverServices(): Promise<ToolResult> {
+  const services = await discoverServices();
+  return textResult(`Found ${services.length} service(s):\n${JSON.stringify(services, null, 2)}`);
+}
+
 export async function handleAnalyzeProject(args: AnalyzeProjectArgs): Promise<ToolResult> {
   const { service, force } = args;
 

package/src/handlers/behavior-handlers.ts

@@ -0,0 +1,174 @@
+/**
+ * Behavior handlers — surface cross-modality FEATURE duplication.
+ *
+ * `find_shared_behaviors` lists clusters of FEATUREs (cli:command, mcp:tool,
+ * vscode:command, …) whose entry-point forward-slice hashes match. Mirrors the
+ * `grafema features --duplicates` CLI subcommand — same algorithm, same
+ * cluster shape — so the two channels return symmetric data.
+ *
+ * REG-1119.
+ */
+
+import { ensureAnalyzed } from '../analysis.js';
+import { textResult, errorResult } from '../utils.js';
+import type { ToolResult, FindSharedBehaviorsArgs } from '../types.js';
+import type { EdgeType, EdgeRecord } from '@grafema/types';
+
+/**
+ * Minimal backend interface used by the logic function. Allows testing with
+ * a simple mock without importing the full GraphBackend. Matches the subset
+ * of RFDBServerBackend that we need.
+ */
+interface BehaviorBackendLike {
+  getNode(id: string): Promise<Record<string, unknown> | null>;
+  queryNodes(query: { type?: string; nodeType?: string }): AsyncIterable<Record<string, unknown>>;
+  getIncomingEdges(nodeId: string, edgeTypes?: EdgeType[] | null): Promise<EdgeRecord[]>;
+}
+
+interface SharedFeatureRef {
+  id: string;
+  type: string;
+  name: string;
+  file: string;
+}
+
+interface SharedBehaviorCluster {
+  hash: string;
+  effects: string[];
+  coreNodeCount: number;
+  features: SharedFeatureRef[];
+}
+
+const DEFAULT_MIN_CLUSTER_SIZE = 2;
+const DEFAULT_LIMIT = 100;
+const MAX_LIMIT = 10_000;
+
+// === Logic function (testable, accepts backend directly) ===
+
+export async function findSharedBehaviorsLogic(
+  db: BehaviorBackendLike,
+  args: FindSharedBehaviorsArgs,
+): Promise<ToolResult> {
+  const { minClusterSize: rawMin, limit: rawLimit } = args ?? {};
+
+  if (rawMin !== undefined && (!Number.isFinite(rawMin) || rawMin < 0)) {
+    return errorResult('minClusterSize must be a non-negative number');
+  }
+  if (rawLimit !== undefined && (!Number.isFinite(rawLimit) || rawLimit <= 0)) {
+    return errorResult('limit must be a positive number');
+  }
+  if (rawLimit !== undefined && rawLimit > MAX_LIMIT) {
+    return errorResult(`limit must be <= ${MAX_LIMIT}`);
+  }
+
+  const minClusterSize = Math.max(2, rawMin ?? DEFAULT_MIN_CLUSTER_SIZE);
+  const limit = rawLimit ?? DEFAULT_LIMIT;
+
+  // 1. Collect all BEHAVIOR nodes.
+  interface BehaviorRow {
+    id: string;
+    hash: string;
+    effects: string[];
+    coreNodeCount: number;
+  }
+  const behaviors: BehaviorRow[] = [];
+  for await (const node of db.queryNodes({ type: 'BEHAVIOR' })) {
+    const id = String(node.id ?? '');
+    if (!id) continue;
+    const hash = readString(node.hash);
+    if (!hash) continue;
+    behaviors.push({
+      id,
+      hash,
+      effects: readStringArray(node.effects),
+      coreNodeCount: readNumber(node.coreNodeCount) ?? 0,
+    });
+  }
+
+  // 2. Bucket by hash.
+  const byHash = new Map<string, BehaviorRow[]>();
+  for (const b of behaviors) {
+    let bucket = byHash.get(b.hash);
+    if (!bucket) {
+      bucket = [];
+      byHash.set(b.hash, bucket);
+    }
+    bucket.push(b);
+  }
+
+  // 3. Resolve features (incoming IMPLEMENTED_BY) for clusters.
+  const clusters: SharedBehaviorCluster[] = [];
+  for (const [hash, bucket] of byHash) {
+    if (bucket.length < minClusterSize) continue;
+
+    const features: SharedFeatureRef[] = [];
+    const seen = new Set<string>();
+    for (const beh of bucket) {
+      const edges = await db.getIncomingEdges(beh.id, ['IMPLEMENTED_BY'] as EdgeType[]);
+      for (const edge of edges) {
+        const featureId = String(edge.src);
+        if (!featureId || seen.has(featureId)) continue;
+        seen.add(featureId);
+        const node = await db.getNode(featureId);
+        if (!node) continue;
+        features.push({
+          id: featureId,
+          type: readString(node.type) ?? 'UNKNOWN',
+          name: readString(node.name) ?? '',
+          file: readString(node.file) ?? '',
+        });
+      }
+    }
+
+    if (features.length < minClusterSize) continue;
+
+    features.sort((a, b) => (a.type === b.type ? a.name.localeCompare(b.name) : a.type.localeCompare(b.type)));
+    clusters.push({
+      hash,
+      effects: bucket[0].effects,
+      coreNodeCount: bucket[0].coreNodeCount,
+      features,
+    });
+  }
+
+  clusters.sort((a, b) => (b.features.length - a.features.length) || a.hash.localeCompare(b.hash));
+  const truncated = clusters.length > limit;
+  const limited = clusters.slice(0, limit);
+
+  return textResult(JSON.stringify({
+    count: limited.length,
+    truncated,
+    minClusterSize,
+    clusters: limited,
+  }, null, 2));
+}
+
+// === Public handler (calls ensureAnalyzed, used by MCP routing) ===
+
+export async function handleFindSharedBehaviors(args: FindSharedBehaviorsArgs): Promise<ToolResult> {
+  const db = await ensureAnalyzed();
+  return findSharedBehaviorsLogic(db as unknown as BehaviorBackendLike, args);
+}
+
+// === Internal helpers ===
+
+function readString(v: unknown): string | undefined {
+  return typeof v === 'string' ? v : undefined;
+}
+
+function readNumber(v: unknown): number | undefined {
+  return typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+}
+
+function readStringArray(v: unknown): string[] {
+  if (Array.isArray(v)) return v.filter((x): x is string => typeof x === 'string');
+  if (typeof v === 'string') {
+    try {
+      const parsed = JSON.parse(v);
+      if (Array.isArray(parsed)) return parsed.filter((x): x is string => typeof x === 'string');
+    } catch {
+      // not JSON
+    }
+  }
+  return [];
+}

package/src/handlers/dataflow-handlers.ts

@@ -4,6 +4,8 @@
  * Delegates BFS tracing to @grafema/util's shared traceDataflow module.
  */
 
+import { join } from 'path';
+import { existsSync } from 'fs';
 import { ensureAnalyzed } from '../analysis.js';
 import { getProjectPath } from '../state.js';
 import {
@@ -17,6 +19,7 @@ import type {
   TraceAliasArgs,
   TraceDataFlowArgs,
   TraceCallChainArgs,
+  TraceEffectsArgs,
   CheckInvariantArgs,
   GraphNode,
 } from '../types.js';
@@ -24,6 +27,8 @@ import {
   traceDataflow,
   renderTraceNarrative,
   traceCallChain,
+  traceEffects,
+  EffectsLookup,
   type DataflowBackend,
   type TraceDetail,
 } from '@grafema/util';
@@ -103,7 +108,7 @@ export async function handleTraceAlias(args: TraceAliasArgs): Promise<ToolResult
 
 // === TRACE DATAFLOW ===
 
-export async function handleTraceDataFlow(args: TraceDataFlowArgs): Promise<ToolResult> {
+export async function handleTraceDataflow(args: TraceDataFlowArgs): Promise<ToolResult> {
   const db = await ensureAnalyzed();
   const { source, file, direction = 'forward', max_depth = 10, limit = 50, detail } = args;
 
@@ -159,7 +164,7 @@ export async function handleTraceDataFlow(args: TraceDataFlowArgs): Promise<Tool
 
 // === TRACE CALL CHAIN ===
 
-export async function handleTraceCallChain(args: TraceCallChainArgs): Promise<ToolResult> {
+export async function handleTraceCalls(args: TraceCallChainArgs): Promise<ToolResult> {
   const db = await ensureAnalyzed();
   const { source, file, direction = 'forward', max_depth = 10 } = args;
 
@@ -373,3 +378,106 @@ export async function handleCheckInvariant(args: CheckInvariantArgs): Promise<To
     return errorResult(message);
   }
 }
+
+// === TRACE EFFECTS ===
+
+let _effectsLookup: EffectsLookup | null = null;
+
+function getEffectsLookup(): EffectsLookup {
+  if (!_effectsLookup) {
+    // Find effects-db directory relative to the project
+    // The effects-db is at the project root: <repo>/effects-db/
+    // Also check node_modules for installed packages
+    const candidates = [
+      join(getProjectPath(), 'effects-db'),
+      join(getProjectPath(), 'node_modules', '@grafema', 'effects-db'),
+    ];
+
+    for (const candidate of candidates) {
+      if (existsSync(candidate)) {
+        _effectsLookup = EffectsLookup.load(candidate);
+        break;
+      }
+    }
+
+    if (!_effectsLookup) {
+      _effectsLookup = EffectsLookup.empty();
+    }
+  }
+  return _effectsLookup;
+}
+
+export async function handleTraceEffects(args: TraceEffectsArgs): Promise<ToolResult> {
+  const db = await ensureAnalyzed();
+  const { node, file, max_depth = 10 } = args;
+
+  // Find source node (same pattern as handleTraceCalls)
+  let sourceNode: GraphNode | null = await db.getNode(node);
+  if (!sourceNode) {
+    let fallbackNode: GraphNode | null = null;
+    for (const type of ['FUNCTION', 'METHOD', 'CONSTRUCTOR']) {
+      for await (const n of db.queryNodes({ type, name: node })) {
+        if (file && !n.file?.includes(file)) {
+          if (!fallbackNode) fallbackNode = n;
+          continue;
+        }
+        sourceNode = n;
+        break;
+      }
+      if (sourceNode) break;
+    }
+    if (!sourceNode && fallbackNode) {
+      sourceNode = fallbackNode;
+    }
+  }
+  if (!sourceNode) {
+    const displaySource = isGrafemaUri(node) ? toCompactSemanticId(node) : node;
+    return errorResult(`Source "${displaySource}" not found. Provide a FUNCTION or METHOD name.`);
+  }
+
+  const effectsLookup = getEffectsLookup();
+  const dfDb = db as unknown as DataflowBackend;
+
+  const result = await traceEffects(dfDb, sourceNode.id, effectsLookup, { maxDepth: max_depth });
+
+  if (!result) {
+    return errorResult(`Could not trace effects for "${sourceNode.name || node}"`);
+  }
+
+  // Format as readable text
+  const lines: string[] = [];
+  const name = result.node.name;
+  const fileShort = result.node.file ? result.node.file.split('/').pop() : '?';
+
+  lines.push(`## Effects of ${name} (${fileShort}:${result.node.line ?? '?'})`);
+  lines.push('');
+
+  lines.push(`**Direct effects:** ${result.direct.join(', ') || 'PURE'}`);
+  lines.push(`**Transitive effects:** ${result.transitive.join(', ')}`);
+  lines.push('');
+
+  if (result.leaf_sources.length > 0) {
+    lines.push(`### Leaf sources (${result.leaf_sources.length})`);
+    for (const leaf of result.leaf_sources) {
+      const leafFile = leaf.file ? leaf.file.split('/').pop() : '';
+      const loc = leafFile ? ` (${leafFile})` : '';
+      lines.push(`  depth ${leaf.depth}: ${leaf.node}${loc} → ${leaf.effects.join(', ')}`);
+    }
+    lines.push('');
+  }
+
+  if (result.boundary_crossings.length > 0) {
+    lines.push(`### Boundary crossings (${result.boundary_crossings.length})`);
+    for (const bc of result.boundary_crossings) {
+      const fromShort = bc.from_file.split('/').pop();
+      const toShort = bc.to_file.split('/').pop();
+      lines.push(`  ${bc.caller} (${fromShort}) → ${bc.callee} (${toShort}): ${bc.effects.join(', ')}`);
+    }
+    lines.push('');
+  }
+
+  lines.push(`---`);
+  lines.push(`Nodes visited: ${result.nodes_visited}, max depth: ${result.max_depth}${result.max_depth_reached ? ' (TRUNCATED — some paths marked UNKNOWN)' : ''}`);
+
+  return textResult(lines.join('\n'));
+}

package/src/handlers/graphql-handlers.ts

@@ -29,7 +29,7 @@ async function getYoga(backend: RFDBServerBackend) {
   return yogaInstance;
 }
 
-export async function handleGraphQLQuery(args: GraphQLQueryArgs): Promise<ToolResult> {
+export async function handleQueryGraphql(args: GraphQLQueryArgs): Promise<ToolResult> {
   const { query, variables, operationName } = args;
 
   if (!query || query.trim() === '') {

package/src/handlers/index.ts

@@ -3,9 +3,9 @@
  */
 
 export { handleQueryGraph, handleFindCalls, handleFindNodes } from './query-handlers.js';
-export { handleTraceAlias, handleTraceDataFlow, handleTraceCallChain, handleCheckInvariant, handleExplain } from './dataflow-handlers.js';
+export { handleTraceAlias, handleTraceDataflow, handleTraceCalls, handleCheckInvariant, handleExplain, handleTraceEffects } from './dataflow-handlers.js';
 export type { ExplainArgs } from './dataflow-handlers.js';
-export { handleAnalyzeProject, handleGetAnalysisStatus, handleGetStats, handleGetSchema } from './analysis-handlers.js';
+export { handleDiscoverServices, handleAnalyzeProject, handleGetAnalysisStatus, handleGetStats, handleGetSchema } from './analysis-handlers.js';
 export { handleCreateGuarantee, handleListGuarantees, handleCheckGuarantees, handleDeleteGuarantee } from './guarantee-handlers.js';
 export { handleGetFunctionDetails, handleGetContext, handleGetFileOverview, handleGetShape } from './context-handlers.js';
 export { handleReadProjectStructure, handleWriteConfig } from './project-handlers.js';
@@ -18,5 +18,6 @@ export { handleAddKnowledge, handleQueryKnowledge, handleQueryDecisions, handleS
 // Disabled: requires git-ingest (US-17). See US-17 in AI-AGENT-STORIES.md
 // export { handleGitChurn, handleGitCoChange, handleGitOwnership, handleGitArchaeology } from './knowledge-handlers.js';
 export { handleDescribe } from './notation-handlers.js';
-export { handleGraphQLQuery } from './graphql-handlers.js';
+export { handleQueryGraphql } from './graphql-handlers.js';
 export { handleQueryRegistry } from './registry-handlers.js';
+export { handleFindSharedBehaviors } from './behavior-handlers.js';

package/src/handlers/query-handlers.ts

@@ -436,7 +436,7 @@ export async function handleFindNodes(args: FindNodesArgs): Promise<ToolResult>
   // === Rich context enrichment ===
   // For each found node, add structural context (methods, calls, imports)
   // Only enrich when result set is small enough (≤10 nodes) to avoid latency
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+   
   const enriched = nodes.length <= 10
     ? await enrichNodes(db as any, nodes)
     : nodes;

package/src/server.ts

@@ -35,17 +35,17 @@ import { PROMPTS, getPrompt } from './prompts.js';
 
 import { TOOLS } from './definitions/index.js';
 import { initializeFromArgs, setupLogging, getProjectPath } from './state.js';
-import { textResult, errorResult, log } from './utils.js';
+import { errorResult, log } from './utils.js';
 import { getSocketPathOverride } from './state.js';
-import { discoverServices } from './analysis.js';
 import {
   handleQueryGraph,
   handleFindCalls,
   handleFindNodes,
   handleTraceAlias,
-  handleTraceDataFlow,
-  handleTraceCallChain,
+  handleTraceDataflow,
+  handleTraceCalls,
   handleCheckInvariant,
+  handleDiscoverServices,
   handleAnalyzeProject,
   handleGetAnalysisStatus,
   handleGetStats,
@@ -78,9 +78,11 @@ import {
   // handleGitOwnership,
   // handleGitArchaeology,
   handleDescribe,
-  handleGraphQLQuery,
+  handleQueryGraphql,
   handleQueryRegistry,
   handleExplain,
+  handleTraceEffects,
+  handleFindSharedBehaviors,
 } from './handlers/index.js';
 import type { ExplainArgs } from './handlers/index.js';
 import type {
@@ -119,9 +121,11 @@ import type {
   // GitCoChangeArgs,
   // GitOwnershipArgs,
   // GitArchaeologyArgs,
+  TraceEffectsArgs,
   DescribeArgs,
   GraphQLQueryArgs,
   QueryRegistryArgs,
+  FindSharedBehaviorsArgs,
 } from './types.js';
 
 /**
@@ -247,24 +251,27 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
         break;
 
       case 'trace_dataflow':
-        result = await handleTraceDataFlow(asArgs<TraceDataFlowArgs>(args));
+        result = await handleTraceDataflow(asArgs<TraceDataFlowArgs>(args));
         break;
 
       case 'trace_calls':
-        result = await handleTraceCallChain(asArgs<TraceCallChainArgs>(args));
+        result = await handleTraceCalls(asArgs<TraceCallChainArgs>(args));
         break;
 
       case 'explain':
         result = await handleExplain(asArgs<ExplainArgs>(args));
         break;
 
+      case 'trace_effects':
+        result = await handleTraceEffects(asArgs<TraceEffectsArgs>(args));
+        break;
+
       case 'check_invariant':
         result = await handleCheckInvariant(asArgs<CheckInvariantArgs>(args));
         break;
 
       case 'discover_services':
-        const services = await discoverServices();
-        result = textResult(`Found ${services.length} service(s):\n${JSON.stringify(services, null, 2)}`);
+        result = await handleDiscoverServices();
         break;
 
       case 'analyze_project':
@@ -393,13 +400,17 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
         break;
 
       case 'query_graphql':
-        result = await handleGraphQLQuery(asArgs<GraphQLQueryArgs>(args));
+        result = await handleQueryGraphql(asArgs<GraphQLQueryArgs>(args));
         break;
 
       case 'query_registry':
         result = await handleQueryRegistry(asArgs<QueryRegistryArgs>(args));
         break;
 
+      case 'find_shared_behaviors':
+        result = await handleFindSharedBehaviors(asArgs<FindSharedBehaviorsArgs>(args));
+        break;
+
       default:
         result = errorResult(`Unknown tool: ${name}`);
     }

package/src/types.ts

@@ -81,6 +81,12 @@ export interface TraceCallChainArgs {
   max_depth?: number;
 }
 
+export interface TraceEffectsArgs {
+  node: string;
+  file?: string;
+  max_depth?: number;
+}
+
 export interface GetShapeArgs {
   target: string;
   file?: string;
@@ -108,6 +114,13 @@ export interface FindNodesArgs {
   offset?: number;
 }
 
+export interface FindSharedBehaviorsArgs {
+  /** Minimum cluster size to include. Default 2. */
+  minClusterSize?: number;
+  /** Maximum number of clusters to return. Default 100. */
+  limit?: number;
+}
+
 export interface AnalyzeProjectArgs {
   service?: string;
   force?: boolean;