feat(mcp): Phase 1 tools improvement — Parts 1.1–1.4

.changeset/mcp-phase1-tools-improvement.md

@@ -0,0 +1,13 @@
+---
+'@prosdevlab/dev-agent': patch
+---
+
+MCP tools improvement: faster pattern analysis, merged health into status, agent usability
+
+- `dev_patterns` is 10-30x faster — reads from Antfly index instead of re-scanning with ts-morph
+- `dev_health` merged into `dev_status` (use `section="health"`) — 6 tools reduced to 5
+- `dev_patterns` parameter renamed from `query` to `filePath` to prevent LLM misuse
+- New `format: "json"` option on `dev_patterns` for token-efficient agent workflows
+- All tools now return `suggestion` field on errors for agent recovery guidance
+- Removed stale GitHub code from health adapter
+- Extracted pure pattern analyzers for testability

.claude/scratchpad.md

@@ -0,0 +1,22 @@
+# Scratchpad
+
+## Known Limitations
+
+- **`getDocsByFilePath` fetches all docs client-side (capped at 5k).** Uses `getAll(limit: 5000)` + exact path filter. Fine for single repos (dev-agent has ~2,200 docs). Won't scale to monorepos with 50k+ files. Future fix: server-side path filter in Antfly SDK.
+
+## Open Questions
+
+- Can Antfly SDK support server-side path filtering? Would eliminate the 5k doc cap in `getDocsByFilePath`. Worth raising with Antfly team after MCP Phase 1 ships.
+
+## Future Work
+
+- Antfly SDK: server-side path filter for `getDocsByFilePath` (eliminates 5k cap)
+- `dev_patterns format: "json"` for token-efficient agent output (MCP Phase 1, Part 1.4)
+- ast-grep as optional dep for pattern analysis (MCP Phase 1, Part 1.5)
+- PageRank for `dev_map` hot paths (MCP Phase 1, Part 1.6)
+- E2E tests in CI — blocked on Antfly memory requirements vs GitHub runner limits (7GB)
+
+## Notes
+
+- Both pattern analysis paths (index vs scan) must use the same pure extractors from 1.1 to avoid drift. Test this explicitly.
+- Log which path is used (index vs scanner) at debug level so we can verify the fast path fires in production.

CLAUDE.md

@@ -23,7 +23,7 @@ Everything runs on your machine. No data leaves.
 packages/
   core/          # Scanner (ts-morph, tree-sitter), vector storage (Antfly), services
   cli/           # Commander.js CLI — dev index, dev mcp install, etc.
-  mcp-server/    # MCP server with 6 built-in adapters
+  mcp-server/    # MCP server with 5 built-in adapters
   subagents/     # Coordinator, explorer, planner, PR agents
   integrations/  # Claude Code, VS Code, Cursor
   logger/        # @prosdevlab/kero — centralized logging
@@ -139,16 +139,15 @@ See `.claude/da-plans/README.md` for status and format details.
 
 ---
 
-## MCP tools (6 adapters)
+## MCP tools (5 adapters)
 
 | Tool | Purpose |
 |------|---------|
 | `dev_search` | Hybrid code search — BM25 + vector + RRF (use FIRST for conceptual queries) |
 | `dev_refs` | Find callers/callees of functions |
 | `dev_map` | Codebase structure with change frequency |
-| `dev_patterns` | File pattern analysis (similar code, error handling, types) |
-| `dev_status` | Repository indexing status + Antfly stats + watcher status |
-| `dev_health` | Server health checks (Antfly connectivity) |
+| `dev_patterns` | File pattern analysis (similar code, error handling, types). Takes `filePath`, not `query`. |
+| `dev_status` | Repository indexing status + Antfly stats + health checks (`section="health"`) |
 
 ---
 

PLAN.md

@@ -47,7 +47,7 @@ Dev-agent provides semantic code search, codebase intelligence, and GitHub integ
 | `dev_patterns` - File analysis | ✅ Done | MCP adapter |
 | `dev_plan` - Issue planning | ✅ Done | MCP adapter |
 | `dev_gh` - GitHub search | ✅ Done | MCP adapter |
-| `dev_health` - Health checks | ✅ Done | MCP adapter |
+| `dev_health` - Health checks | ✅ Merged into `dev_status` | MCP adapter |
 | Cursor integration | ✅ Done | CLI command |
 | Claude Code integration | ✅ Done | CLI command |
 | Rate limiting (token bucket) | ✅ Done | MCP server |

README.md

@@ -10,14 +10,13 @@
 
 ## What it does
 
-dev-agent indexes your codebase and provides 6 MCP tools to AI assistants. Instead of grepping through files, they can ask conceptual questions like "where do we handle authentication?"
+dev-agent indexes your codebase and provides 5 MCP tools to AI assistants. Instead of grepping through files, they can ask conceptual questions like "where do we handle authentication?"
 
 - `dev_search` — Hybrid search (BM25 + vector + RRF) — returns code snippets, not just paths
 - `dev_refs` — Find callers/callees of any function
 - `dev_map` — Codebase structure with hot paths (most referenced files)
 - `dev_patterns` — Compare coding patterns against similar files
-- `dev_status` — Repository indexing status and health
-- `dev_health` — Server health checks
+- `dev_status` — Repository indexing status, health checks, and Antfly stats
 
 ## Quick Start
 
@@ -110,13 +109,9 @@ Compare a file's coding patterns (imports, error handling, type coverage, testin
 Analyze patterns in src/auth/middleware.ts
 ```
 
-### `dev_status` — Repository Status
+### `dev_status` — Repository Status & Health
 
-Indexing status, document counts, Antfly stats, and file watcher state.
-
-### `dev_health` — Health Checks
-
-Server health, Antfly connectivity, and repository access.
+Indexing status, document counts, Antfly stats, file watcher state, and health checks (`section="health"`).
 
 ## Supported Languages
 
@@ -155,7 +150,7 @@ pnpm lint
 packages/
   core/          # Scanner, vector storage, indexer, services
   cli/           # Commander.js CLI
-  mcp-server/    # MCP server with 6 tool adapters
+  mcp-server/    # MCP server with 5 tool adapters
   subagents/     # Explorer, planner, PR agents
   integrations/  # Claude Code, VS Code, Cursor
   logger/        # @prosdevlab/kero centralized logging

TROUBLESHOOTING.md

@@ -252,7 +252,7 @@ killall dev
 
 2. **Check health:**
    ```
-   Use dev_health tool to see rate limit status
+   Use dev_status section="health" tool to see rate limit status
    ```
 
 3. **If persistent:**
@@ -446,7 +446,7 @@ Failed to fetch issues: spawnSync /bin/sh ENOBUFS
 
 3. **Monitor health:**
    ```
-   dev_health --verbose
+   dev_status section="health" format="verbose"
    ```
 
 ---
@@ -466,7 +466,7 @@ Failed to fetch issues: spawnSync /bin/sh ENOBUFS
 
 **Diagnosis:**
 ```
-Use dev_health tool to check component status
+Use dev_status section="health" tool to check component status
 ```
 
 **Common causes:**
@@ -505,7 +505,7 @@ Check the tool's input schema:
 
 3. Check server health:
    ```
-   dev_health
+   dev_status section="health"
    ```
 
 ---
@@ -573,9 +573,9 @@ claude mcp add --env LOG_LEVEL=debug dev-agent -- dev mcp start
 ### Check component health
 
 ```
-Use dev_health tool with verbose flag:
+Use dev_status section="health" tool with verbose flag:
 
-dev_health --verbose
+dev_status section="health" format="verbose"
 
 Shows:
 - Vector storage status
@@ -596,7 +596,7 @@ dev mcp start --verbose
 # In another terminal, send test message
 echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | dev mcp start
 
-# Should list all 6 tools: dev_search, dev_refs, dev_map, dev_patterns, dev_status, dev_health
+# Should list all 5 tools: dev_search, dev_refs, dev_map, dev_patterns, dev_status
 ```
 
 ### Inspect storage
@@ -666,7 +666,7 @@ If you encounter a bug:
 
 2. **Get diagnostics:**
    ```
-   Use dev_health --verbose
+   Use dev_status section="health" format="verbose"
    ```
 
 3. **Enable debug logs:**
@@ -720,7 +720,7 @@ dev index
 dev_status
 
 # Verify health
-dev_health
+dev_status section="health"
 ```
 
 ### Debugging search quality
@@ -855,7 +855,7 @@ dev index
 
 ## Health Check Guide
 
-The `dev_health` tool provides comprehensive diagnostics:
+The `dev_status section="health"` tool provides comprehensive diagnostics:
 
 ### Interpreting Health Status
 
@@ -919,7 +919,7 @@ du -sh ~/.dev-agent/indexes/
 - After major code changes (adding features, refactoring)
 - Weekly for active projects
 - Monthly for stable projects
-- Use `dev_health` to check if index is stale
+- Use `dev_status section="health"` to check if index is stale
 
 ### Q: Can multiple AI tools use dev-agent simultaneously?
 
@@ -942,7 +942,7 @@ du -sh ~/.dev-agent/indexes/
 
 2. **Use health check:**
    ```
-   dev_health --verbose
+   dev_status section="health" format="verbose"
    ```
 
 3. **Enable debug logging:**
@@ -953,7 +953,7 @@ du -sh ~/.dev-agent/indexes/
 
 Include:
 - `dev --version`
-- `dev_health --verbose` output
+- `dev_status section="health" format="verbose"` output
 - Steps to reproduce
 - Expected vs actual behavior
 - Debug logs (if applicable)

examples/README.md

@@ -150,16 +150,18 @@ dev_status:
 
 ---
 
-### `dev_health` - Health Check
+### Health Check (via `dev_status`)
 
 Diagnose issues:
 
 ```
-dev_health
+dev_status:
+  section: health
 
 # Verbose output
-dev_health:
-  verbose: true
+dev_status:
+  section: health
+  format: verbose
 ```
 
 ---
@@ -230,7 +232,7 @@ dev_health:
 dev index
 
 # Check health
-dev_health
+dev_status section="health"
 ```
 
 ---
@@ -292,7 +294,7 @@ dev mcp install --cursor
 
 - Reduce `limit`
 - Use `compact` format
-- Check `dev_health`
+- Check `dev_status section="health"`
 
 ---
 

packages/cli/src/commands/mcp.ts

@@ -13,7 +13,6 @@ import {
   SearchService,
 } from '@prosdevlab/dev-agent-core';
 import {
-  HealthAdapter,
   InspectAdapter,
   MapAdapter,
   MCPServer,
@@ -49,9 +48,9 @@ Setup:
   2. Install MCP integration: dev mcp install --cursor
   3. Restart Cursor to activate
 
-Available Tools (6):
+Available Tools (5):
   dev_search, dev_status, dev_patterns,
-  dev_health, dev_refs, dev_map
+  dev_refs, dev_map
 `
   )
   .addCommand(
@@ -121,11 +120,6 @@ Available Tools (6):
             defaultFormat: 'compact',
           });
 
-          const healthAdapter = new HealthAdapter({
-            repositoryPath,
-            vectorStorePath: vectors,
-          });
-
           const refsAdapter = new RefsAdapter({
             searchService,
             defaultLimit: 20,
@@ -138,7 +132,7 @@ Available Tools (6):
             defaultTokenBudget: 2000,
           });
 
-          // Create MCP server with 6 adapters
+          // Create MCP server with 5 adapters (health merged into status)
           const server = new MCPServer({
             serverInfo: {
               name: 'dev-agent',
@@ -149,14 +143,7 @@ Available Tools (6):
               logLevel: logLevel as 'debug' | 'info' | 'warn' | 'error',
             },
             transport: options.transport === 'stdio' ? 'stdio' : undefined,
-            adapters: [
-              searchAdapter,
-              statusAdapter,
-              inspectAdapter,
-              healthAdapter,
-              refsAdapter,
-              mapAdapter,
-            ],
+            adapters: [searchAdapter, statusAdapter, inspectAdapter, refsAdapter, mapAdapter],
           });
 
           // Handle graceful shutdown
@@ -174,9 +161,7 @@ Available Tools (6):
           await server.start();
 
           logger.info(chalk.green('MCP server started successfully!'));
-          logger.info(
-            'Available tools: dev_search, dev_status, dev_patterns, dev_health, dev_refs, dev_map'
-          );
+          logger.info('Available tools: dev_search, dev_status, dev_patterns, dev_refs, dev_map');
 
           if (options.transport === 'stdio') {
             logger.info('Server running on stdio transport (for AI tools)');