docs: update all references for 5-tool MCP (dev_health → dev_status)

Sweep all docs for stale dev_health references and 6-tool counts:
- CLAUDE.md, README.md, PLAN.md, TROUBLESHOOTING.md, examples/README.md
- Website: homepage, tools index, dev-health (→ redirect), dev-patterns
  (query→filePath, add json format), troubleshooting
- CLI help text and CURSOR_SETUP.md
- packages/dev-agent/README.md
- Add changeset for v0.10.4, release notes, update latest-version.ts

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: prosdev

.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.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

@@ -48,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(
@@ -161,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)');

packages/dev-agent/README.md

@@ -39,8 +39,7 @@ When integrated with Cursor or Claude Code, you get 6 powerful tools:
 - `dev_refs` - Find callers/callees of functions
 - `dev_map` - Codebase structure with change frequency
 - `dev_patterns` - File analysis and pattern checking
-- `dev_status` - Repository status and health
-- `dev_health` - Component health checks
+- `dev_status` - Repository status, health checks, and Antfly stats
 
 ## Requirements
 
@@ -110,11 +109,11 @@ All processing happens on your machine:
 # Find authentication-related code
 dev_search: "JWT token validation middleware"
 
-# Find similar code patterns
-dev_patterns: { action: "compare", query: "src/auth/middleware.ts" }
+# Analyze coding patterns
+dev_patterns: { filePath: "src/auth/middleware.ts" }
 
 # Check system health
-dev_health: verbose
+dev_status: { section: "health" }
 ```
 
 ## Support

packages/mcp-server/CURSOR_SETUP.md

@@ -66,20 +66,17 @@ Compare src/auth/middleware.ts with similar implementations
 - `limit`: Number of results (default: 10, for compare action)
 - `format`: Output format (`compact` or `verbose`)
 
-### `dev_health` - Server Health Check
-Check the health of dev-agent MCP server and its components.
+### Health Checks (via `dev_status`)
+
+Use `dev_status` with `section="health"` for server diagnostics:
 
 ```
-Check server health
+Check server health status
 ```
 
-**Parameters:**
-- `verbose`: Include detailed diagnostics (default: false)
-
 **Checks:**
-- Vector storage (indexed code)
-- Repository accessibility
-- GitHub index status and age
+- Repository access
+- Antfly connectivity
 
 ## Management Commands