feat(mcp): add prompts, token footers, and fix GitHub indexing

## Features

### 1. Prompts System (MCP Protocol)
- Implement prompts/list and prompts/get handlers
- Add 8 guided workflow prompts:
  - analyze-issue: Full issue analysis with implementation plan
  - find-pattern: Search codebase for patterns
  - repo-overview: Comprehensive repository health dashboard
  - find-similar: Find code similar to a file
  - search-github: Search issues/PRs by topic
  - explore-relationships: Analyze file dependencies
  - create-plan: Generate detailed task breakdown
  - quick-search: Fast semantic code search
- Enable prompts capability in server initialization
- Create PromptRegistry with argument validation

### 2. Token Cost Visibility
- Add 🪙 coin emoji footers to all tool outputs
- Display accurate token estimates at end of responses
- Helps users make informed decisions about format choices
- Shows ~36 tokens (compact) vs ~462 tokens (verbose) examples

### 3. Calibrated Token Estimation
- Improve accuracy from 12.9% error to 0.6% error
- Change formula: 4 chars/token → 4.5 chars/token
- Adjust word estimate: 1.3 → 1.25 tokens/word
- Validated against actual Cursor usage (178 tokens)
- Add comprehensive accuracy tests

## Bug Fixes

### GitHub Indexing Status
- Fix path mismatch: use consistent vectorStorePath-github pattern
- Load repository name from state file to avoid gh CLI calls
- Enable offline operation with cached GitHub data
- Fix GitHubAdapter and StatusAdapter initialization
- Now correctly shows: ✅ GitHub (40 items) instead of ⚠️ not indexed

### CLI Stats Command
- Add GitHub integration section to 'dev stats' output
- Display issues, PRs, and sync status
- Load GitHubIndexer with repository from state file
- Show comprehensive repository and GitHub metrics

## Tests
- Update all formatter tests for token footers
- Add token footer validation tests
- Fix status adapter test expectations (debug → warn)
- Add calibrated token estimation accuracy tests
- All 246 tests passing

## Documentation
- Update token estimation comments with calibration details
- Add prompt definitions with descriptions and arguments
- Document offline GitHub operation capability

Closes #26 (MCP Integration improvements)

Author: prosdev

packages/cli/src/commands/stats.ts

@@ -1,4 +1,7 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
 import { RepositoryIndexer } from '@lytics/dev-agent-core';
+import { GitHubIndexer } from '@lytics/dev-agent-subagents';
 import chalk from 'chalk';
 import { Command } from 'commander';
 import ora from 'ora';
@@ -25,6 +28,36 @@ export const statsCommand = new Command('stats')
       await indexer.initialize();
 
       const stats = await indexer.getStats();
+
+      // Try to load GitHub stats
+      let githubStats = null;
+      try {
+        // Try to load repository from state file
+        let repository: string | undefined;
+        const statePath = path.join(config.repositoryPath, '.dev-agent/github-state.json');
+        try {
+          const stateContent = await fs.readFile(statePath, 'utf-8');
+          const state = JSON.parse(stateContent);
+          repository = state.repository;
+        } catch {
+          // State file doesn't exist
+        }
+
+        const githubIndexer = new GitHubIndexer(
+          {
+            vectorStorePath: `${config.vectorStorePath}-github`,
+            statePath,
+            autoUpdate: false,
+          },
+          repository
+        );
+        await githubIndexer.initialize();
+        githubStats = githubIndexer.getStats();
+        await githubIndexer.close();
+      } catch {
+        // GitHub not indexed, ignore
+      }
+
       await indexer.close();
 
       spinner.stop();
@@ -66,6 +99,36 @@ export const statsCommand = new Command('stats')
         logger.warn(`${stats.errors.length} error(s) during last indexing`);
       }
 
+      // Display GitHub stats if available
+      if (githubStats) {
+        logger.log('');
+        logger.log(chalk.bold.cyan('🔗 GitHub Integration'));
+        logger.log('');
+        logger.log(`${chalk.cyan('Repository:')}        ${githubStats.repository}`);
+        logger.log(`${chalk.cyan('Total Documents:')}   ${githubStats.totalDocuments}`);
+        logger.log(`${chalk.cyan('Issues:')}            ${githubStats.byType.issue || 0}`);
+        logger.log(`${chalk.cyan('Pull Requests:')}     ${githubStats.byType.pull_request || 0}`);
+        logger.log('');
+        logger.log(`${chalk.cyan('Open:')}              ${githubStats.byState.open || 0}`);
+        logger.log(`${chalk.cyan('Closed:')}            ${githubStats.byState.closed || 0}`);
+        if (githubStats.byState.merged) {
+          logger.log(`${chalk.cyan('Merged:')}            ${githubStats.byState.merged}`);
+        }
+        logger.log('');
+        logger.log(
+          `${chalk.cyan('Last Synced:')}       ${new Date(githubStats.lastIndexed).toLocaleString()}`
+        );
+      } else {
+        logger.log('');
+        logger.log(chalk.bold.cyan('🔗 GitHub Integration'));
+        logger.log('');
+        logger.log(
+          chalk.gray('Not indexed. Run') +
+            chalk.yellow(' dev gh index ') +
+            chalk.gray('to sync GitHub data.')
+        );
+      }
+
       logger.log('');
     } catch (error) {
       spinner.fail('Failed to load statistics');

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

@@ -62,7 +62,7 @@ async function main() {
     const githubAdapter = new GitHubAdapter({
       repositoryPath,
       // GitHubIndexer will be lazily initialized on first use
-      vectorStorePath: `${repositoryPath}/.dev-agent/github-vectors.lance`,
+      vectorStorePath: `${vectorStorePath}-github`,
       statePath: `${repositoryPath}/.dev-agent/github-state.json`,
       defaultLimit: 10,
       defaultFormat: 'compact',

packages/mcp-server/src/adapters/__tests__/github-adapter.test.ts

@@ -231,6 +231,32 @@ describe('GitHubAdapter', () => {
         'No matching issues or PRs found'
       );
     });
+
+    it('should include token footer in search results', async () => {
+      const mockResults: GitHubSearchResult[] = [
+        {
+          document: mockIssue,
+          score: 0.9,
+          matchedFields: ['title'],
+        },
+      ];
+
+      vi.mocked(mockGitHubIndexer.search).mockResolvedValue(mockResults);
+
+      const result = await adapter.execute(
+        {
+          action: 'search',
+          query: 'test',
+          format: 'compact',
+        },
+        mockContext
+      );
+
+      expect(result.success).toBe(true);
+      const content = (result.data as { content: string })?.content;
+      expect(content).toContain('🪙');
+      expect(content).toMatch(/~\d+ tokens$/);
+    });
   });
 
   describe('Context Action', () => {

packages/mcp-server/src/adapters/__tests__/status-adapter.test.ts

@@ -106,8 +106,8 @@ describe('StatusAdapter', () => {
       });
 
       await adapter.initialize(mockContext);
-      expect(mockContext.logger.debug).toHaveBeenCalledWith(
-        'GitHub indexer not available',
+      expect(mockContext.logger.warn).toHaveBeenCalledWith(
+        'GitHub indexer initialization failed',
         expect.any(Object)
       );
     });

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

@@ -9,6 +9,7 @@ import type {
   GitHubSearchOptions,
   GitHubSearchResult,
 } from '@lytics/dev-agent-subagents';
+import { estimateTokensForText } from '../../formatters/utils';
 import { ToolAdapter } from '../tool-adapter';
 import type { AdapterContext, ToolDefinition, ToolExecutionContext, ToolResult } from '../types';
 
@@ -85,11 +86,26 @@ export class GitHubAdapter extends ToolAdapter {
     // Lazy initialization
     const { GitHubIndexer: GitHubIndexerClass } = await import('@lytics/dev-agent-subagents');
 
-    this.githubIndexer = new GitHubIndexerClass({
-      vectorStorePath: this.vectorStorePath,
-      statePath: this.statePath,
-      autoUpdate: false,
-    });
+    // Try to load repository from state file to avoid gh CLI call
+    let repository: string | undefined;
+    try {
+      const fs = await import('node:fs/promises');
+      const stateContent = await fs.readFile(this.statePath, 'utf-8');
+      const state = JSON.parse(stateContent);
+      repository = state.repository;
+    } catch {
+      // State file doesn't exist or can't be read
+      // GitHubIndexer will try gh CLI as fallback
+    }
+
+    this.githubIndexer = new GitHubIndexerClass(
+      {
+        vectorStorePath: this.vectorStorePath,
+        statePath: this.statePath,
+        autoUpdate: false,
+      },
+      repository // Pass repository to avoid gh CLI call
+    );
 
     await this.githubIndexer.initialize();
     return this.githubIndexer;
@@ -306,7 +322,10 @@ export class GitHubAdapter extends ToolAdapter {
     const results = await indexer.search(query, options);
 
     if (results.length === 0) {
-      return '## GitHub Search Results\n\nNo matching issues or PRs found. Try:\n- Using different keywords\n- Removing filters (type, state, labels)\n- Re-indexing GitHub data with "dev gh index"';
+      const noResultsMsg =
+        '## GitHub Search Results\n\nNo matching issues or PRs found. Try:\n- Using different keywords\n- Removing filters (type, state, labels)\n- Re-indexing GitHub data with "dev gh index"';
+      const tokens = estimateTokensForText(noResultsMsg);
+      return `${noResultsMsg}\n\n🪙 ~${tokens} tokens`;
     }
 
     if (format === 'verbose') {
@@ -403,7 +422,9 @@ export class GitHubAdapter extends ToolAdapter {
       lines.push('', `_...and ${results.length - 5} more results_`);
     }
 
-    return lines.join('\n');
+    const content = lines.join('\n');
+    const tokens = estimateTokensForText(content);
+    return `${content}\n\n🪙 ~${tokens} tokens`;
   }
 
   /**
@@ -447,7 +468,9 @@ export class GitHubAdapter extends ToolAdapter {
       lines.push('');
     }
 
-    return lines.join('\n');
+    const content = lines.join('\n');
+    const tokens = estimateTokensForText(content);
+    return `${content}\n\n🪙 ~${tokens} tokens`;
   }
 
   /**
@@ -474,7 +497,9 @@ export class GitHubAdapter extends ToolAdapter {
       `**URL:** ${doc.url}`,
     ].filter(Boolean) as string[];
 
-    return lines.join('\n');
+    const content = lines.join('\n');
+    const tokens = estimateTokensForText(content);
+    return `${content}\n\n🪙 ~${tokens} tokens`;
   }
 
   /**
@@ -518,7 +543,9 @@ export class GitHubAdapter extends ToolAdapter {
       `**URL:** ${doc.url}`,
     ].filter(Boolean) as string[];
 
-    return lines.join('\n');
+    const content = lines.join('\n');
+    const tokens = estimateTokensForText(content);
+    return `${content}\n\n🪙 ~${tokens} tokens`;
   }
 
   /**

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

@@ -74,15 +74,29 @@ export class StatusAdapter extends ToolAdapter {
 
     // Initialize GitHub indexer lazily
     try {
-      this.githubIndexer = new GitHubIndexer({
-        vectorStorePath: `${this.vectorStorePath}-github`,
-        statePath: '.dev-agent/github-state.json',
-        autoUpdate: true,
-        staleThreshold: 15 * 60 * 1000,
-      });
+      // Try to load repository from state file
+      let repository: string | undefined;
+      const statePath = path.join(this.repositoryPath, '.dev-agent/github-state.json');
+      try {
+        const stateContent = await fs.promises.readFile(statePath, 'utf-8');
+        const state = JSON.parse(stateContent);
+        repository = state.repository;
+      } catch {
+        // State file doesn't exist, will try gh CLI
+      }
+
+      this.githubIndexer = new GitHubIndexer(
+        {
+          vectorStorePath: `${this.vectorStorePath}-github`,
+          statePath, // Use absolute path
+          autoUpdate: true,
+          staleThreshold: 15 * 60 * 1000,
+        },
+        repository
+      );
       await this.githubIndexer.initialize();
     } catch (error) {
-      context.logger.debug('GitHub indexer not available', { error });
+      context.logger.warn('GitHub indexer initialization failed', { error });
       // Not fatal, GitHub section will show "not indexed"
     }
   }

packages/mcp-server/src/formatters/__tests__/formatters.test.ts

@@ -70,14 +70,17 @@ describe('Formatters', () => {
       expect(result.content).toContain('2. [84%]');
       expect(result.content).toContain('3. [72%]');
       expect(result.tokenEstimate).toBeGreaterThan(0);
+      // Should include token footer
+      expect(result.content).toMatch(/🪙 ~\d+ tokens$/);
     });
 
     it('should respect maxResults option', () => {
       const formatter = new CompactFormatter({ maxResults: 2 });
       const result = formatter.formatResults(mockResults);
 
-      const lines = result.content.split('\n');
-      expect(lines).toHaveLength(2); // Only 2 results
+      // Count actual result lines (numbered lines)
+      const resultLines = result.content.split('\n').filter((l) => /^\d+\./.test(l));
+      expect(resultLines).toHaveLength(2); // Only 2 results
     });
 
     it('should exclude signatures by default', () => {
@@ -139,6 +142,9 @@ describe('Formatters', () => {
 
       // Should have double newlines between results
       expect(result.content).toContain('\n\n');
+
+      // Should include token footer
+      expect(result.content).toMatch(/🪙 ~\d+ tokens$/);
     });
 
     it('should include signatures by default', () => {
@@ -215,4 +221,34 @@ describe('Formatters', () => {
       expect(threeResults.tokenEstimate).toBeGreaterThan(oneResult.tokenEstimate * 2);
     });
   });
+
+  describe('Token Footer', () => {
+    it('compact formatter should include coin emoji footer', () => {
+      const formatter = new CompactFormatter();
+      const result = formatter.formatResults(mockResults);
+
+      expect(result.content).toContain('🪙');
+      expect(result.content).toMatch(/~\d+ tokens$/);
+    });
+
+    it('verbose formatter should include coin emoji footer', () => {
+      const formatter = new VerboseFormatter();
+      const result = formatter.formatResults(mockResults);
+
+      expect(result.content).toContain('🪙');
+      expect(result.content).toMatch(/~\d+ tokens$/);
+    });
+
+    it('token footer should match tokenEstimate property', () => {
+      const formatter = new CompactFormatter();
+      const result = formatter.formatResults(mockResults);
+
+      // Extract token count from footer
+      const footerMatch = result.content.match(/🪙 ~(\d+) tokens$/);
+      expect(footerMatch).toBeTruthy();
+
+      const footerTokens = Number.parseInt(footerMatch![1], 10);
+      expect(footerTokens).toBe(result.tokenEstimate);
+    });
+  });
 });

packages/mcp-server/src/formatters/__tests__/utils.test.ts

@@ -155,5 +155,47 @@ describe('Formatter Utils', () => {
         expect(ratio).toBeLessThan(2);
       }
     });
+
+    it('should use calibrated 4.5 chars per token formula', () => {
+      // Test the calibrated formula matches actual usage
+      // Known: 803 chars normalized = 178 tokens actual
+      const testText = '## GitHub Search Results\n'.repeat(20); // ~520 chars
+      const normalized = testText.trim().replace(/\s+/g, ' ');
+      const estimate = estimateTokensForText(testText);
+      const expectedFromFormula = Math.ceil(normalized.length / 4.5);
+
+      // Should use the calibrated 4.5 ratio
+      expect(estimate).toBeGreaterThanOrEqual(expectedFromFormula - 5);
+      expect(estimate).toBeLessThanOrEqual(expectedFromFormula + 5);
+    });
+
+    it('should estimate within 5% for technical content', () => {
+      // Real test case from actual usage (full text)
+      const technicalText = `## GitHub Search Results
+**Query:** "token estimation and cost tracking"
+**Total Found:** 3
+
+1. [Score: 29.6%] function: estimateTokensForText
+  Location: packages/mcp-server/src/formatters/utils.ts:15
+  Signature: export function estimateTokensForText(text: string): number
+  Metadata: language: typescript, exported: true, lines: 19
+
+2. [Score: 21.0%] function: estimateTokensForJSON
+  Location: packages/mcp-server/src/formatters/utils.ts:63
+  Signature: export function estimateTokensForJSON(obj: unknown): number
+  Metadata: language: typescript, exported: true, lines: 4
+
+3. [Score: 19.7%] method: VerboseFormatter.estimateTokens
+  Location: packages/mcp-server/src/formatters/verbose-formatter.ts:114
+  Signature: estimateTokens(result: SearchResult): number
+  Metadata: language: typescript, exported: true, lines: 3`;
+
+      const estimate = estimateTokensForText(technicalText);
+      const actualTokens = 178; // Verified from Cursor
+
+      // Should be within 5% of actual (calibrated at 0.6%)
+      const errorPercent = Math.abs((estimate - actualTokens) / actualTokens) * 100;
+      expect(errorPercent).toBeLessThan(5);
+    });
   });
 });

packages/mcp-server/src/formatters/compact-formatter.ts

@@ -72,8 +72,11 @@ export class CompactFormatter implements ResultFormatter {
     });
 
     // Calculate total tokens
-    const content = formatted.join('\n');
-    const tokenEstimate = estimateTokensForText(content);
+    const contentLines = formatted.join('\n');
+    const tokenEstimate = estimateTokensForText(contentLines);
+
+    // Add token footer
+    const content = `${contentLines}\n\n🪙 ~${tokenEstimate} tokens`;
 
     return {
       content,