@pharaoh-so/mcp 0.3.27 → 0.3.28

package/inspect-tools.json

@@ -155,8 +155,8 @@
       }
     },
     {
-      "name": "search_functions",
-      "description": "Check if functionality already exists BEFORE writing any new function, utility, or helper.\n\nCALL THIS WHEN:\n• You're about to create a new function — search first to prevent duplicates\n• You need to find where a concept is implemented (e.g., 'notify', 'validate', 'parse')\n• You're looking for the right function to import instead of reimplementing\n• A task says 'add X functionality' — verify X doesn't already exist\n\nRETURNS: Matching functions with file paths, line numbers, module, export status, async flag, complexity scores, and full signatures. Searches all functions across the entire codebase.\n\nEXAMPLES:\n• \"Is there already a function that sends Slack notifications?\"\n• \"What validation utilities exist?\"\n• \"Where is email formatting handled?\"\n• \"Does a retry wrapper already exist somewhere?\"\n\nWHY NOT JUST READ FILES: grep only finds exact string matches and misses re-exports, aliases, and barrel-file indirection. This searches the full resolved dependency graph — if it exists anywhere in the codebase, this finds it.",
+      "name": "get_blast_radius",
+      "description": "Check what breaks BEFORE refactoring, renaming, or deleting a function, file, or module.\n\nCALL THIS WHEN:\n• You're about to refactor or rename a function — see every caller that needs updating\n• You want to know if a change is safe — check if anything depends on this code\n• A PR modifies a shared utility — trace all downstream consumers\n• You need to assess risk level before a change (LOW/MEDIUM/HIGH)\n\nRETURNS: Risk assessment (LOW/MEDIUM/HIGH), all affected callers grouped by module with file paths, impacted HTTP endpoints, impacted cron jobs, and affected DB operations. Traces up to 5 hops deep through the call graph.\n\nEXAMPLES:\n• \"What breaks if I change the formatMessage function?\"\n• \"How many callers does this utility have across the codebase?\"\n• \"Is it safe to delete this file or do other modules use it?\"\n• \"Which API endpoints are affected if I modify the db module?\"\n\nWHY NOT JUST READ FILES: You can grep for direct callers, but you'll miss indirect callers 2-3 hops away, and you won't see affected endpoints or cron jobs. This traces the full transitive dependency chain automatically.",
       "inputSchema": {
         "$schema": "http://json-schema.org/draft-07/schema#",
         "type": "object",
@@ -165,39 +165,72 @@
             "type": "string",
             "description": "Repository name. Works with your connected repos or any public open source repo by GitHub slug (e.g., 'vercel/next.js')."
           },
-          "query": {
+          "entity": {
             "type": "string",
-            "maxLength": 500,
-            "description": "Function name or partial match (e.g., \"notify\", \"fetch\", \"transform\")"
+            "description": "Function name, file path, or module name"
+          },
+          "entity_type": {
+            "type": "string",
+            "enum": [
+              "function",
+              "file",
+              "module"
+            ],
+            "description": "Type of entity"
+          },
+          "depth": {
+            "description": "How many hops to trace (default: 3, max: 5)",
+            "type": "number"
+          }
+        },
+        "required": [
+          "repo",
+          "entity",
+          "entity_type"
+        ]
+      },
+      "annotations": {
+        "title": "Change Blast Radius",
+        "readOnlyHint": true,
+        "destructiveHint": false
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "check_reachability",
+      "description": "Check if functions are reachable from production entry points (API endpoints, CLI commands, cron jobs, event handlers, MCP tools).\n\nCALL THIS WHEN:\n• After implementing a feature — verify new code is wired into the app\n• Reviewing a PR — are all new functions actually reachable?\n• Cleaning up dead code — find functions only called by tests\n• Before opening a PR — run this as a pre-flight check\n\nRETURNS: For each exported function, whether it's reachable from a production entry point,\nthe path from entry point to function, and classification (entry_point / reachable / unreachable).\n\nTIER: Pharaoh Pro — free tier receives a preview. Summarize what the preview reveals, explain what full data would show for this task, then include the upgrade link.",
+      "inputSchema": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "type": "object",
+        "properties": {
+          "repo": {
+            "type": "string",
+            "description": "Repository name. Works with your connected repos or any public open source repo by GitHub slug (e.g., 'vercel/next.js')."
+          },
+          "functions": {
+            "description": "Function names to check (checks all exported if omitted)",
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
           },
           "module": {
             "description": "Filter to a specific module",
             "type": "string"
           },
-          "file": {
-            "description": "Filter to functions in a specific file (full path for exact match, filename for substring match)",
-            "type": "string"
-          },
-          "exported_only": {
-            "description": "Only show exported functions (default: false)",
+          "include_paths": {
+            "description": "Include full reachability paths (default: false)",
             "type": "boolean"
-          },
-          "offset": {
-            "description": "Skip first N results for pagination (default: 0)",
-            "type": "number"
-          },
-          "limit": {
-            "description": "Max results to return (default: 20, max: 50)",
-            "type": "number"
           }
         },
         "required": [
-          "repo",
-          "query"
+          "repo"
         ]
       },
       "annotations": {
-        "title": "Function Search",
+        "title": "Reachability Check",
         "readOnlyHint": true,
         "destructiveHint": false
       },
@@ -206,8 +239,8 @@
       }
     },
     {
-      "name": "get_design_system",
-      "description": "Discover the design system BEFORE creating any UI component.\n\nCALL THIS WHEN:\n• You're about to create a React/Vue/Svelte component — check what already exists\n• You need to know the canonical component for a UI pattern (button, input, modal)\n• You want to find design tokens (colors, spacing, typography) to use\n• You suspect raw HTML elements are used instead of existing components\n\nRETURNS: Components with props and usage count (paginated), design tokens with values, and anti-patterns where raw HTML is used instead of existing components. Pass `path_pattern`, `name_prefix`, `offset`, or `limit` to narrow or page through results. Screen/page components are excluded by default.\n\nEXAMPLES:\n• \"What components does this design system have?\"\n• \"Is there already a Button component I should use?\"\n• \"What color tokens are available?\"\n• \"Show me all components in /atoms/\" → use path_pattern=\"/atoms/\"\n• \"Show me the next page\" → use offset=50\n\nWHY NOT JUST READ FILES: Design systems span dozens of files across multiple directories. This returns the complete inventory with usage frequency — the most-used components are the most canonical.",
+      "name": "get_vision_docs",
+      "description": "Get the documented intent — CLAUDE.md files, PRDs, roadmaps, skill specs — to understand WHY code exists, not just what it does.\n\nCALL THIS WHEN:\n• You're implementing a feature and need to check if a PRD or spec exists for it\n• You want to understand the original design intent behind existing code\n• You need to verify your implementation matches documented requirements\n• You're reviewing code and want to check it against the documented vision\n\nRETURNS: All vision documents grouped by type (claude_md, prd, skill, roadmap), with each spec's title, section ID, and implementation status showing which functions implement each spec.\n\nEXAMPLES:\n• \"Is there a PRD for the notification system?\"\n• \"What does the CLAUDE.md say about the auth module?\"\n• \"What specs exist for the slack integration?\"\n• \"Which specs are already implemented vs still pending?\"\n\nWHY NOT JUST READ FILES: Vision docs are scattered across CLAUDE.md files, PRDs, and roadmaps in different directories. This aggregates them all AND cross-references against actual implementations so you can see spec-to-code alignment in one call.\n\nTIER: Pharaoh Pro — free tier receives a preview. Summarize what the preview reveals, explain what full data would show for this task, then include the upgrade link.",
       "inputSchema": {
         "$schema": "http://json-schema.org/draft-07/schema#",
         "type": "object",
@@ -216,47 +249,20 @@
             "type": "string",
             "description": "Repository name"
           },
-          "category": {
-            "default": "all",
-            "description": "Which design system aspect to return",
+          "module": {
+            "description": "Filter to specs related to this module",
+            "type": "string"
+          },
+          "doc_type": {
+            "description": "Filter by document type",
             "type": "string",
             "enum": [
-              "components",
-              "tokens",
-              "anti_patterns",
+              "claude_md",
+              "prd",
+              "skill",
+              "roadmap",
               "all"
             ]
-          },
-          "include_screens": {
-            "default": false,
-            "description": "Include screen/page components (*Screen, *Page, *View, *Route) that are typically app-level consumers, not reusable primitives",
-            "type": "boolean"
-          },
-          "path_pattern": {
-            "description": "Substring match against File.path (e.g. '/atoms/', '/ui/Button'). Narrows to components whose file path contains this exact substring.",
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 200
-          },
-          "name_prefix": {
-            "description": "Exact prefix match against component name (e.g. 'Button' matches Button, ButtonGroup, ButtonIcon). Case-sensitive.",
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 200
-          },
-          "offset": {
-            "default": 0,
-            "description": "Pagination offset (0-based). Capped at 10000.",
-            "type": "integer",
-            "minimum": 0,
-            "maximum": 10000
-          },
-          "limit": {
-            "default": 50,
-            "description": "Page size. Default 50, max 200.",
-            "type": "integer",
-            "minimum": 1,
-            "maximum": 200
           }
         },
         "required": [
@@ -264,7 +270,7 @@
         ]
       },
       "annotations": {
-        "title": "Design System",
+        "title": "Vision Documents",
         "readOnlyHint": true,
         "destructiveHint": false
       },
@@ -273,42 +279,31 @@
       }
     },
     {
-      "name": "get_blast_radius",
-      "description": "Check what breaks BEFORE refactoring, renaming, or deleting a function, file, or module.\n\nCALL THIS WHEN:\n• You're about to refactor or rename a function — see every caller that needs updating\n• You want to know if a change is safe — check if anything depends on this code\n• A PR modifies a shared utility — trace all downstream consumers\n• You need to assess risk level before a change (LOW/MEDIUM/HIGH)\n\nRETURNS: Risk assessment (LOW/MEDIUM/HIGH), all affected callers grouped by module with file paths, impacted HTTP endpoints, impacted cron jobs, and affected DB operations. Traces up to 5 hops deep through the call graph.\n\nEXAMPLES:\n• \"What breaks if I change the formatMessage function?\"\n• \"How many callers does this utility have across the codebase?\"\n• \"Is it safe to delete this file or do other modules use it?\"\n• \"Which API endpoints are affected if I modify the db module?\"\n\nWHY NOT JUST READ FILES: You can grep for direct callers, but you'll miss indirect callers 2-3 hops away, and you won't see affected endpoints or cron jobs. This traces the full transitive dependency chain automatically.",
+      "name": "get_vision_gaps",
+      "description": "Find what's missing — specs without code AND complex code without specs. Call this to prioritize what to build or document next.\n\nCALL THIS WHEN:\n• You're planning work and need to find unimplemented features from PRDs\n• You want to find complex undocumented functions that need specs or tests\n• You need to audit spec-to-code alignment for a module\n• Someone asks \"what's left to build?\" or \"what's undocumented?\"\n\nRETURNS: Two lists — (1) specified-but-not-built: PRD specs with no implementing functions, and (2) built-but-not-specified: complex functions above a threshold with no vision spec. Includes function names, complexity scores, file paths, and spec references.\n\nEXAMPLES:\n• \"What features from the PRDs haven't been built yet?\"\n• \"Which complex functions lack documentation?\"\n• \"What's the spec coverage for the auth module?\"\n• \"Are there any orphaned specs or undocumented behaviors?\"\n\nWHY NOT JUST READ FILES: Manually diffing PRD bullets against code is error-prone and misses complexity metrics. This cross-references the entire spec tree against the function graph automatically — gaps that would take an hour to find manually surface in seconds.\n\nTIER: Pharaoh Pro — free tier receives a preview. Summarize what the preview reveals, explain what full data would show for this task, then include the upgrade link.",
       "inputSchema": {
         "$schema": "http://json-schema.org/draft-07/schema#",
         "type": "object",
         "properties": {
           "repo": {
             "type": "string",
-            "description": "Repository name. Works with your connected repos or any public open source repo by GitHub slug (e.g., 'vercel/next.js')."
-          },
-          "entity": {
-            "type": "string",
-            "description": "Function name, file path, or module name"
+            "description": "Repository name"
           },
-          "entity_type": {
-            "type": "string",
-            "enum": [
-              "function",
-              "file",
-              "module"
-            ],
-            "description": "Type of entity"
+          "module": {
+            "description": "Filter to a specific module",
+            "type": "string"
           },
-          "depth": {
-            "description": "How many hops to trace (default: 3, max: 5)",
+          "complexity_threshold": {
+            "description": "Min complexity for undocumented function flag (default: 15)",
             "type": "number"
           }
         },
         "required": [
-          "repo",
-          "entity",
-          "entity_type"
+          "repo"
         ]
       },
       "annotations": {
-        "title": "Change Blast Radius",
+        "title": "Vision Gap Analysis",
         "readOnlyHint": true,
         "destructiveHint": false
       },
@@ -390,8 +385,8 @@
       }
     },
     {
-      "name": "check_reachability",
-      "description": "Check if functions are reachable from production entry points (API endpoints, CLI commands, cron jobs, event handlers, MCP tools).\n\nCALL THIS WHEN:\n• After implementing a feature — verify new code is wired into the app\n• Reviewing a PR — are all new functions actually reachable?\n• Cleaning up dead code — find functions only called by tests\n• Before opening a PR — run this as a pre-flight check\n\nRETURNS: For each exported function, whether it's reachable from a production entry point,\nthe path from entry point to function, and classification (entry_point / reachable / unreachable).\n\nTIER: Pharaoh Pro — free tier receives a preview. Summarize what the preview reveals, explain what full data would show for this task, then include the upgrade link.",
+      "name": "search_functions",
+      "description": "Check if functionality already exists BEFORE writing any new function, utility, or helper.\n\nCALL THIS WHEN:\n• You're about to create a new function — search first to prevent duplicates\n• You need to find where a concept is implemented (e.g., 'notify', 'validate', 'parse')\n• You're looking for the right function to import instead of reimplementing\n• A task says 'add X functionality' — verify X doesn't already exist\n\nRETURNS: Matching functions with file paths, line numbers, module, export status, async flag, complexity scores, and full signatures. Searches all functions across the entire codebase.\n\nEXAMPLES:\n• \"Is there already a function that sends Slack notifications?\"\n• \"What validation utilities exist?\"\n• \"Where is email formatting handled?\"\n• \"Does a retry wrapper already exist somewhere?\"\n\nWHY NOT JUST READ FILES: grep only finds exact string matches and misses re-exports, aliases, and barrel-file indirection. This searches the full resolved dependency graph — if it exists anywhere in the codebase, this finds it.",
       "inputSchema": {
         "$schema": "http://json-schema.org/draft-07/schema#",
         "type": "object",
@@ -400,101 +395,39 @@
             "type": "string",
             "description": "Repository name. Works with your connected repos or any public open source repo by GitHub slug (e.g., 'vercel/next.js')."
           },
-          "functions": {
-            "description": "Function names to check (checks all exported if omitted)",
-            "type": "array",
-            "items": {
-              "type": "string"
-            }
+          "query": {
+            "type": "string",
+            "maxLength": 500,
+            "description": "Function name or partial match (e.g., \"notify\", \"fetch\", \"transform\")"
           },
           "module": {
             "description": "Filter to a specific module",
             "type": "string"
           },
-          "include_paths": {
-            "description": "Include full reachability paths (default: false)",
-            "type": "boolean"
-          }
-        },
-        "required": [
-          "repo"
-        ]
-      },
-      "annotations": {
-        "title": "Reachability Check",
-        "readOnlyHint": true,
-        "destructiveHint": false
-      },
-      "execution": {
-        "taskSupport": "forbidden"
-      }
-    },
-    {
-      "name": "get_vision_docs",
-      "description": "Get the documented intent — CLAUDE.md files, PRDs, roadmaps, skill specs — to understand WHY code exists, not just what it does.\n\nCALL THIS WHEN:\n• You're implementing a feature and need to check if a PRD or spec exists for it\n• You want to understand the original design intent behind existing code\n• You need to verify your implementation matches documented requirements\n• You're reviewing code and want to check it against the documented vision\n\nRETURNS: All vision documents grouped by type (claude_md, prd, skill, roadmap), with each spec's title, section ID, and implementation status showing which functions implement each spec.\n\nEXAMPLES:\n• \"Is there a PRD for the notification system?\"\n• \"What does the CLAUDE.md say about the auth module?\"\n• \"What specs exist for the slack integration?\"\n• \"Which specs are already implemented vs still pending?\"\n\nWHY NOT JUST READ FILES: Vision docs are scattered across CLAUDE.md files, PRDs, and roadmaps in different directories. This aggregates them all AND cross-references against actual implementations so you can see spec-to-code alignment in one call.\n\nTIER: Pharaoh Pro — free tier receives a preview. Summarize what the preview reveals, explain what full data would show for this task, then include the upgrade link.",
-      "inputSchema": {
-        "$schema": "http://json-schema.org/draft-07/schema#",
-        "type": "object",
-        "properties": {
-          "repo": {
-            "type": "string",
-            "description": "Repository name"
-          },
-          "module": {
-            "description": "Filter to specs related to this module",
+          "file": {
+            "description": "Filter to functions in a specific file (full path for exact match, filename for substring match)",
             "type": "string"
           },
-          "doc_type": {
-            "description": "Filter by document type",
-            "type": "string",
-            "enum": [
-              "claude_md",
-              "prd",
-              "skill",
-              "roadmap",
-              "all"
-            ]
-          }
-        },
-        "required": [
-          "repo"
-        ]
-      },
-      "annotations": {
-        "title": "Vision Documents",
-        "readOnlyHint": true,
-        "destructiveHint": false
-      },
-      "execution": {
-        "taskSupport": "forbidden"
-      }
-    },
-    {
-      "name": "get_vision_gaps",
-      "description": "Find what's missing — specs without code AND complex code without specs. Call this to prioritize what to build or document next.\n\nCALL THIS WHEN:\n• You're planning work and need to find unimplemented features from PRDs\n• You want to find complex undocumented functions that need specs or tests\n• You need to audit spec-to-code alignment for a module\n• Someone asks \"what's left to build?\" or \"what's undocumented?\"\n\nRETURNS: Two lists — (1) specified-but-not-built: PRD specs with no implementing functions, and (2) built-but-not-specified: complex functions above a threshold with no vision spec. Includes function names, complexity scores, file paths, and spec references.\n\nEXAMPLES:\n• \"What features from the PRDs haven't been built yet?\"\n• \"Which complex functions lack documentation?\"\n• \"What's the spec coverage for the auth module?\"\n• \"Are there any orphaned specs or undocumented behaviors?\"\n\nWHY NOT JUST READ FILES: Manually diffing PRD bullets against code is error-prone and misses complexity metrics. This cross-references the entire spec tree against the function graph automatically — gaps that would take an hour to find manually surface in seconds.\n\nTIER: Pharaoh Pro — free tier receives a preview. Summarize what the preview reveals, explain what full data would show for this task, then include the upgrade link.",
-      "inputSchema": {
-        "$schema": "http://json-schema.org/draft-07/schema#",
-        "type": "object",
-        "properties": {
-          "repo": {
-            "type": "string",
-            "description": "Repository name"
+          "exported_only": {
+            "description": "Only show exported functions (default: false)",
+            "type": "boolean"
           },
-          "module": {
-            "description": "Filter to a specific module",
-            "type": "string"
+          "offset": {
+            "description": "Skip first N results for pagination (default: 0)",
+            "type": "number"
           },
-          "complexity_threshold": {
-            "description": "Min complexity for undocumented function flag (default: 15)",
+          "limit": {
+            "description": "Max results to return (default: 20, max: 50)",
             "type": "number"
           }
         },
         "required": [
-          "repo"
+          "repo",
+          "query"
         ]
       },
       "annotations": {
-        "title": "Vision Gap Analysis",
+        "title": "Function Search",
         "readOnlyHint": true,
         "destructiveHint": false
       },
@@ -691,6 +624,73 @@
         "taskSupport": "forbidden"
       }
     },
+    {
+      "name": "get_design_system",
+      "description": "Discover the design system BEFORE creating any UI component.\n\nCALL THIS WHEN:\n• You're about to create a React/Vue/Svelte component — check what already exists\n• You need to know the canonical component for a UI pattern (button, input, modal)\n• You want to find design tokens (colors, spacing, typography) to use\n• You suspect raw HTML elements are used instead of existing components\n\nRETURNS: Components with props and usage count (paginated), design tokens with values, and anti-patterns where raw HTML is used instead of existing components. Pass `path_pattern`, `name_prefix`, `offset`, or `limit` to narrow or page through results. Screen/page components are excluded by default.\n\nEXAMPLES:\n• \"What components does this design system have?\"\n• \"Is there already a Button component I should use?\"\n• \"What color tokens are available?\"\n• \"Show me all components in /atoms/\" → use path_pattern=\"/atoms/\"\n• \"Show me the next page\" → use offset=50\n\nWHY NOT JUST READ FILES: Design systems span dozens of files across multiple directories. This returns the complete inventory with usage frequency — the most-used components are the most canonical.",
+      "inputSchema": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "type": "object",
+        "properties": {
+          "repo": {
+            "type": "string",
+            "description": "Repository name"
+          },
+          "category": {
+            "default": "all",
+            "description": "Which design system aspect to return",
+            "type": "string",
+            "enum": [
+              "components",
+              "tokens",
+              "anti_patterns",
+              "all"
+            ]
+          },
+          "include_screens": {
+            "default": false,
+            "description": "Include screen/page components (*Screen, *Page, *View, *Route) that are typically app-level consumers, not reusable primitives",
+            "type": "boolean"
+          },
+          "path_pattern": {
+            "description": "Substring match against File.path (e.g. '/atoms/', '/ui/Button'). Narrows to components whose file path contains this exact substring.",
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200
+          },
+          "name_prefix": {
+            "description": "Exact prefix match against component name (e.g. 'Button' matches Button, ButtonGroup, ButtonIcon). Case-sensitive.",
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200
+          },
+          "offset": {
+            "default": 0,
+            "description": "Pagination offset (0-based). Capped at 10000.",
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 10000
+          },
+          "limit": {
+            "default": 50,
+            "description": "Page size. Default 50, max 200.",
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 200
+          }
+        },
+        "required": [
+          "repo"
+        ]
+      },
+      "annotations": {
+        "title": "Design System",
+        "readOnlyHint": true,
+        "destructiveHint": false
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
     {
       "name": "setup_environment",
       "description": "Set up the optimal development environment for this codebase — install Pharaoh's curated plugin bundle.\n\nCALL THIS WHEN:\n• The user says \"set up my environment\", \"install plugins\", or \"optimize my setup\"\n• You want to proactively improve the development experience with proven plugins\n• After noticing the user could benefit from LSP, security scanning, or code review tools\n• The user is on OpenClaw or Cursor and wants to install Pharaoh skills/prompts\n\nRETURNS: A curated list of recommended plugins and install instructions, tailored to the client platform (claude-code, openclaw, or cursor) and languages in this codebase.\n\nThis is a one-time setup. Once installed, plugins persist across sessions.",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pharaoh-so/mcp",
   "mcpName": "so.pharaoh/pharaoh",
-  "version": "0.3.27",
+  "version": "0.3.28",
   "description": "MCP proxy for Pharaoh — maps codebases into queryable knowledge graphs for AI agents. Enables Claude Code in headless environments (VPS, SSH, CI) via device flow auth.",
   "type": "module",
   "main": "dist/index.js",