feat(mcp): add dev_refs tool for call graph queries

Create RefsAdapter that provides the dev_refs MCP tool:
- Query callees (what a function calls)
- Query callers (what calls a function)
- Query both directions at once
- Format output as readable markdown
- Find best match for function name via semantic search
- Compute callers by reverse lookup through indexed callees

Also adds:
- startTimer() utility for measuring operation duration
- Uses estimateTokensForText for accurate token counting

Registered in MCP server alongside existing adapters.

Part of #80

Author: prosdev

packages/mcp-server/bin/dev-agent-mcp.ts

@@ -22,6 +22,7 @@ import {
   GitHubAdapter,
   HealthAdapter,
   PlanAdapter,
+  RefsAdapter,
   SearchAdapter,
   StatusAdapter,
 } from '../src/adapters/built-in';
@@ -180,6 +181,11 @@ async function main() {
       githubStatePath: filePaths.githubState,
     });
 
+    const refsAdapter = new RefsAdapter({
+      repositoryIndexer: indexer,
+      defaultLimit: 20,
+    });
+
     // Create MCP server with coordinator
     const server = new MCPServer({
       serverInfo: {
@@ -198,6 +204,7 @@ async function main() {
         exploreAdapter,
         githubAdapter,
         healthAdapter,
+        refsAdapter,
       ],
       coordinator,
     });

packages/mcp-server/src/adapters/built-in/index.ts

@@ -7,5 +7,6 @@ export { ExploreAdapter, type ExploreAdapterConfig } from './explore-adapter';
 export { GitHubAdapter, type GitHubAdapterConfig } from './github-adapter';
 export { HealthAdapter, type HealthCheckConfig } from './health-adapter';
 export { PlanAdapter, type PlanAdapterConfig } from './plan-adapter';
+export { RefsAdapter, type RefsAdapterConfig } from './refs-adapter';
 export { SearchAdapter, type SearchAdapterConfig } from './search-adapter';
 export { StatusAdapter, type StatusAdapterConfig } from './status-adapter';

packages/mcp-server/src/adapters/built-in/refs-adapter.ts

@@ -0,0 +1,362 @@
+/**
+ * Refs Adapter
+ * Provides call graph queries via the dev_refs tool
+ */
+
+import type { CalleeInfo, RepositoryIndexer, SearchResult } from '@lytics/dev-agent-core';
+import { estimateTokensForText, startTimer } from '../../formatters/utils';
+import { ToolAdapter } from '../tool-adapter';
+import type { AdapterContext, ToolDefinition, ToolExecutionContext, ToolResult } from '../types';
+
+/**
+ * Direction of relationship query
+ */
+export type RefDirection = 'callees' | 'callers' | 'both';
+
+/**
+ * Refs adapter configuration
+ */
+export interface RefsAdapterConfig {
+  /**
+   * Repository indexer instance
+   */
+  repositoryIndexer: RepositoryIndexer;
+
+  /**
+   * Default result limit
+   */
+  defaultLimit?: number;
+}
+
+/**
+ * Reference result for output
+ */
+interface RefResult {
+  name: string;
+  file?: string;
+  line: number;
+  type?: string;
+  snippet?: string;
+}
+
+/**
+ * Refs Adapter
+ * Implements the dev_refs tool for querying call relationships
+ */
+export class RefsAdapter extends ToolAdapter {
+  readonly metadata = {
+    name: 'refs-adapter',
+    version: '1.0.0',
+    description: 'Call graph relationship adapter',
+    author: 'Dev-Agent Team',
+  };
+
+  private indexer: RepositoryIndexer;
+  private config: Required<RefsAdapterConfig>;
+
+  constructor(config: RefsAdapterConfig) {
+    super();
+    this.indexer = config.repositoryIndexer;
+    this.config = {
+      repositoryIndexer: config.repositoryIndexer,
+      defaultLimit: config.defaultLimit ?? 20,
+    };
+  }
+
+  async initialize(context: AdapterContext): Promise<void> {
+    context.logger.info('RefsAdapter initialized', {
+      defaultLimit: this.config.defaultLimit,
+    });
+  }
+
+  getToolDefinition(): ToolDefinition {
+    return {
+      name: 'dev_refs',
+      description:
+        'Find call relationships for a function or method. Shows what calls it (callers) and what it calls (callees).',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          name: {
+            type: 'string',
+            description:
+              'Name of the function or method to query (e.g., "createPlan", "SearchAdapter.execute")',
+          },
+          direction: {
+            type: 'string',
+            enum: ['callees', 'callers', 'both'],
+            description:
+              'Direction of query: "callees" (what this calls), "callers" (what calls this), or "both" (default)',
+            default: 'both',
+          },
+          limit: {
+            type: 'number',
+            description: `Maximum number of results per direction (default: ${this.config.defaultLimit})`,
+            minimum: 1,
+            maximum: 50,
+            default: this.config.defaultLimit,
+          },
+        },
+        required: ['name'],
+      },
+    };
+  }
+
+  async execute(args: Record<string, unknown>, context: ToolExecutionContext): Promise<ToolResult> {
+    const {
+      name,
+      direction = 'both',
+      limit = this.config.defaultLimit,
+    } = args as {
+      name: string;
+      direction?: RefDirection;
+      limit?: number;
+    };
+
+    // Validate name
+    if (typeof name !== 'string' || name.trim().length === 0) {
+      return {
+        success: false,
+        error: {
+          code: 'INVALID_NAME',
+          message: 'Name must be a non-empty string',
+        },
+      };
+    }
+
+    // Validate direction
+    if (!['callees', 'callers', 'both'].includes(direction)) {
+      return {
+        success: false,
+        error: {
+          code: 'INVALID_DIRECTION',
+          message: 'Direction must be "callees", "callers", or "both"',
+        },
+      };
+    }
+
+    // Validate limit
+    if (typeof limit !== 'number' || limit < 1 || limit > 50) {
+      return {
+        success: false,
+        error: {
+          code: 'INVALID_LIMIT',
+          message: 'Limit must be a number between 1 and 50',
+        },
+      };
+    }
+
+    try {
+      const timer = startTimer();
+      context.logger.debug('Executing refs query', { name, direction, limit });
+
+      // First, find the target component
+      const searchResults = await this.indexer.search(name, { limit: 10 });
+      const target = this.findBestMatch(searchResults, name);
+
+      if (!target) {
+        return {
+          success: false,
+          error: {
+            code: 'NOT_FOUND',
+            message: `Could not find function or method named "${name}"`,
+          },
+        };
+      }
+
+      const result: {
+        target: {
+          name: string;
+          file: string;
+          line: number;
+          type: string;
+        };
+        callees?: RefResult[];
+        callers?: RefResult[];
+      } = {
+        target: {
+          name: target.metadata.name || name,
+          file: target.metadata.path || '',
+          line: target.metadata.startLine || 0,
+          type: (target.metadata.type as string) || 'unknown',
+        },
+      };
+
+      // Get callees if requested
+      if (direction === 'callees' || direction === 'both') {
+        result.callees = this.getCallees(target, limit);
+      }
+
+      // Get callers if requested
+      if (direction === 'callers' || direction === 'both') {
+        result.callers = await this.getCallers(target, limit);
+      }
+
+      const content = this.formatOutput(result, direction);
+      const duration_ms = timer.elapsed();
+
+      context.logger.info('Refs query completed', {
+        name,
+        direction,
+        calleesCount: result.callees?.length ?? 0,
+        callersCount: result.callers?.length ?? 0,
+        duration_ms,
+      });
+
+      const tokens = estimateTokensForText(content);
+
+      return {
+        success: true,
+        data: {
+          name,
+          direction,
+          content,
+          ...result,
+        },
+        metadata: {
+          tokens,
+          duration_ms,
+          timestamp: new Date().toISOString(),
+          cached: false,
+        },
+      };
+    } catch (error) {
+      context.logger.error('Refs query failed', { error });
+      return {
+        success: false,
+        error: {
+          code: 'REFS_FAILED',
+          message: error instanceof Error ? error.message : 'Unknown error',
+          details: error,
+        },
+      };
+    }
+  }
+
+  /**
+   * Find the best matching result for a name query
+   */
+  private findBestMatch(results: SearchResult[], name: string): SearchResult | null {
+    if (results.length === 0) return null;
+
+    // Exact name match takes priority
+    const exactMatch = results.find(
+      (r) => r.metadata.name === name || r.metadata.name?.endsWith(`.${name}`)
+    );
+    if (exactMatch) return exactMatch;
+
+    // Otherwise return the highest scoring result
+    return results[0];
+  }
+
+  /**
+   * Get callees from the target's metadata
+   */
+  private getCallees(target: SearchResult, limit: number): RefResult[] {
+    const callees = target.metadata.callees as CalleeInfo[] | undefined;
+    if (!callees || callees.length === 0) return [];
+
+    return callees.slice(0, limit).map((c) => ({
+      name: c.name,
+      file: c.file,
+      line: c.line,
+    }));
+  }
+
+  /**
+   * Find callers by searching all indexed components for callees that reference the target
+   */
+  private async getCallers(target: SearchResult, limit: number): Promise<RefResult[]> {
+    const targetName = target.metadata.name;
+    if (!targetName) return [];
+
+    // Search for components that might call this target
+    // We search broadly and then filter by callees
+    const candidates = await this.indexer.search(targetName, { limit: 100 });
+
+    const callers: RefResult[] = [];
+
+    for (const candidate of candidates) {
+      // Skip the target itself
+      if (candidate.id === target.id) continue;
+
+      const callees = candidate.metadata.callees as CalleeInfo[] | undefined;
+      if (!callees) continue;
+
+      // Check if any callee matches our target
+      const callsTarget = callees.some(
+        (c) =>
+          c.name === targetName ||
+          c.name.endsWith(`.${targetName}`) ||
+          targetName.endsWith(`.${c.name}`)
+      );
+
+      if (callsTarget) {
+        callers.push({
+          name: candidate.metadata.name || 'unknown',
+          file: candidate.metadata.path,
+          line: candidate.metadata.startLine || 0,
+          type: candidate.metadata.type as string,
+          snippet: candidate.metadata.signature as string | undefined,
+        });
+
+        if (callers.length >= limit) break;
+      }
+    }
+
+    return callers;
+  }
+
+  /**
+   * Format the output as readable text
+   */
+  private formatOutput(
+    result: {
+      target: { name: string; file: string; line: number; type: string };
+      callees?: RefResult[];
+      callers?: RefResult[];
+    },
+    direction: RefDirection
+  ): string {
+    const lines: string[] = [];
+
+    lines.push(`# References for ${result.target.name}`);
+    lines.push(`**Location:** ${result.target.file}:${result.target.line}`);
+    lines.push(`**Type:** ${result.target.type}`);
+    lines.push('');
+
+    if (direction === 'callees' || direction === 'both') {
+      lines.push('## Callees (what this calls)');
+      if (result.callees && result.callees.length > 0) {
+        for (const callee of result.callees) {
+          const location = callee.file ? `${callee.file}:${callee.line}` : `line ${callee.line}`;
+          lines.push(`- \`${callee.name}\` at ${location}`);
+        }
+      } else {
+        lines.push('*No callees found*');
+      }
+      lines.push('');
+    }
+
+    if (direction === 'callers' || direction === 'both') {
+      lines.push('## Callers (what calls this)');
+      if (result.callers && result.callers.length > 0) {
+        for (const caller of result.callers) {
+          const location = caller.file ? `${caller.file}:${caller.line}` : `line ${caller.line}`;
+          lines.push(`- \`${caller.name}\` (${caller.type}) at ${location}`);
+        }
+      } else {
+        lines.push('*No callers found in indexed code*');
+      }
+      lines.push('');
+    }
+
+    return lines.join('\n');
+  }
+
+  estimateTokens(args: Record<string, unknown>): number {
+    const { limit = this.config.defaultLimit, direction = 'both' } = args;
+    const multiplier = direction === 'both' ? 2 : 1;
+    return (limit as number) * 15 * multiplier + 50;
+  }
+}