searchsocket 0.6.3 → 0.7.0

package/dist/cli.js

@@ -12,7 +12,7 @@ import { Command, Option } from "commander";
 // package.json
 var package_default = {
   name: "searchsocket",
-  version: "0.6.3",
+  version: "0.7.0",
   description: "Semantic site search and MCP retrieval for SvelteKit static sites",
   license: "MIT",
   author: "Greg Priday <greg@siteorigin.com>",
@@ -4494,45 +4494,20 @@ var SearchEngine = class _SearchEngine {
 function createServer(engine) {
   const server = new McpServer({
     name: "searchsocket-mcp",
-    version: "0.1.0"
+    version: "0.2.0"
   });
   server.registerTool(
     "search",
     {
-      description: `Semantic site search powered by Upstash Search. Returns url, title, snippet, chunkText, score, and routeFile per result. chunkText contains the full raw chunk markdown. When groupBy is 'page' (default), each result includes a chunks array with section-level sub-results containing sectionTitle, headingPath, snippet, and score. Supports optional filters for structured metadata (e.g. {"version": 2, "deprecated": false}).`,
+      description: "Searches indexed site content using semantic similarity. Returns ranked results with url, title, snippet, chunkText (full section markdown), score, and routeFile (source file path for editing). Each result includes the best-matching section; set groupBy to 'page' (default) for additional chunk sub-results per page. Use routeFile to locate the source file when editing content. If snippets lack detail, call get_page with the result URL to retrieve the full page markdown.",
       inputSchema: {
-        query: z3.string().min(1),
-        scope: z3.string().optional(),
-        topK: z3.number().int().positive().max(100).optional(),
-        pathPrefix: z3.string().optional(),
-        tags: z3.array(z3.string()).optional(),
-        filters: z3.record(z3.string(), z3.union([z3.string(), z3.number(), z3.boolean()])).optional(),
-        groupBy: z3.enum(["page", "chunk"]).optional(),
-        maxSubResults: z3.number().int().positive().max(20).optional()
-      },
-      outputSchema: {
-        q: z3.string(),
-        scope: z3.string(),
-        results: z3.array(z3.object({
-          url: z3.string(),
-          title: z3.string(),
-          sectionTitle: z3.string().optional(),
-          snippet: z3.string(),
-          score: z3.number(),
-          routeFile: z3.string(),
-          chunks: z3.array(z3.object({
-            sectionTitle: z3.string().optional(),
-            snippet: z3.string(),
-            headingPath: z3.array(z3.string()),
-            score: z3.number()
-          })).optional()
-        })),
-        meta: z3.object({
-          timingsMs: z3.object({
-            search: z3.number(),
-            total: z3.number()
-          })
-        })
+        query: z3.string().min(1).describe("Search query. Use keywords or natural language, not full sentences."),
+        topK: z3.number().int().positive().max(100).optional().describe("Number of results to return (default: 10, max: 100)"),
+        pathPrefix: z3.string().optional().describe("Filter results to URLs starting with this prefix (e.g. '/docs')"),
+        tags: z3.array(z3.string()).optional().describe("Filter results to pages matching all specified tags"),
+        filters: z3.record(z3.string(), z3.union([z3.string(), z3.number(), z3.boolean()])).optional().describe('Filter by structured page metadata (e.g. {"version": 2})'),
+        groupBy: z3.enum(["page", "chunk"]).optional().describe("'page' (default) groups chunks by page with sub-results; 'chunk' returns individual chunks"),
+        scope: z3.string().optional()
       }
     },
     async (input) => {
@@ -4543,85 +4518,18 @@ function createServer(engine) {
         pathPrefix: input.pathPrefix,
         tags: input.tags,
         filters: input.filters,
-        groupBy: input.groupBy,
-        maxSubResults: input.maxSubResults
-      });
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(result, null, 2)
-          }
-        ],
-        structuredContent: result
-      };
-    }
-  );
-  server.registerTool(
-    "get_page",
-    {
-      description: "Fetch indexed markdown for a specific path or URL, including frontmatter and routeFile mapping.",
-      inputSchema: {
-        pathOrUrl: z3.string().min(1),
-        scope: z3.string().optional()
-      }
-    },
-    async (input) => {
-      const page = await engine.getPage(input.pathOrUrl, input.scope);
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(page, null, 2)
-          }
-        ]
-      };
-    }
-  );
-  server.registerTool(
-    "list_pages",
-    {
-      description: "List indexed pages with optional path prefix filtering and cursor-based pagination. Returns url, title, description, and routeFile for each page. Use nextCursor to fetch subsequent pages.",
-      inputSchema: {
-        pathPrefix: z3.string().optional(),
-        cursor: z3.string().optional(),
-        limit: z3.number().int().positive().max(200).optional(),
-        scope: z3.string().optional()
-      }
-    },
-    async (input) => {
-      const result = await engine.listPages({
-        pathPrefix: input.pathPrefix,
-        cursor: input.cursor,
-        limit: input.limit,
-        scope: input.scope
+        groupBy: input.groupBy
       });
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(result, null, 2)
-          }
-        ]
-      };
-    }
-  );
-  server.registerTool(
-    "get_site_structure",
-    {
-      description: "Returns the hierarchical page tree derived from URL paths. Use this to understand site navigation structure, find where pages belong, or scope further operations to a section. Nodes with isIndexed: false are implicit structural parents not directly in the index. Large sites (>2000 pages) return truncated: true.",
-      inputSchema: {
-        pathPrefix: z3.string().optional(),
-        scope: z3.string().optional(),
-        maxPages: z3.number().int().positive().max(2e3).optional()
+      if (result.results.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No results found for "${input.query}". Try broader keywords or remove filters.`
+            }
+          ]
+        };
       }
-    },
-    async (input) => {
-      const result = await engine.getSiteStructure({
-        pathPrefix: input.pathPrefix,
-        scope: input.scope,
-        maxPages: input.maxPages
-      });
       return {
         content: [
           {
@@ -4633,56 +4541,51 @@ function createServer(engine) {
     }
   );
   server.registerTool(
-    "find_source_file",
+    "get_page",
     {
-      description: "Find the SvelteKit source file for a piece of site content. Use this when you need to locate and edit content on the site. Returns the URL, route file path, section title, and a content snippet.",
+      description: "Retrieves the full markdown content and metadata for a specific page by its URL path. Use this after search when snippets lack the detail needed to answer a question. Returns reconstructed page markdown, frontmatter (title, routeFile, tags, link counts, indexedAt), and the source file path. Do NOT use this for discovery \u2014 use search first to find relevant pages.",
       inputSchema: {
-        query: z3.string().min(1),
+        path: z3.string().min(1).describe("URL path of the page (e.g. '/docs/auth'). Use a URL from search results."),
         scope: z3.string().optional()
       }
     },
     async (input) => {
-      const result = await engine.search({
-        q: input.query,
-        topK: 1,
-        scope: input.scope
-      });
-      if (result.results.length === 0) {
+      try {
+        const page = await engine.getPage(input.path, input.scope);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(page, null, 2)
+            }
+          ]
+        };
+      } catch {
+        const suggestions = await engine.search({ q: input.path, topK: 3, scope: input.scope });
+        const similar = suggestions.results.map((r) => r.url);
         return {
           content: [
             {
               type: "text",
-              text: JSON.stringify({
-                error: "No matching content found for the given query."
-              })
+              text: similar.length > 0 ? `Page '${input.path}' not found. Similar pages: ${similar.join(", ")}` : `Page '${input.path}' not found. Use search to find the correct URL.`
             }
           ]
         };
       }
-      const match = result.results[0];
-      const { url, routeFile, sectionTitle, snippet } = match;
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify({ url, routeFile, sectionTitle, snippet })
-          }
-        ]
-      };
     }
   );
   server.registerTool(
     "get_related_pages",
     {
-      description: "Find pages related to a given URL using link graph, semantic similarity, and structural proximity. Returns related pages ranked by a composite relatedness score. Use this to discover content connected to a known page.",
+      description: "Finds pages related to a specific page using link graph analysis, semantic similarity, and URL structure. Returns related pages with relationship type (outgoing_link, incoming_link, sibling, semantic) and relevance score. Do NOT use this for general search \u2014 use search instead. Use this only when you already have a specific page URL and need to discover connected content.",
       inputSchema: {
-        pathOrUrl: z3.string().min(1),
-        scope: z3.string().optional(),
-        topK: z3.number().int().positive().max(25).optional()
+        path: z3.string().min(1).describe("URL path of the source page (e.g. '/docs/auth'). Use a URL from search results."),
+        topK: z3.number().int().positive().max(25).optional().describe("Number of related pages to return (default: 10, max: 25)"),
+        scope: z3.string().optional()
       }
     },
     async (input) => {
-      const result = await engine.getRelatedPages(input.pathOrUrl, {
+      const result = await engine.getRelatedPages(input.path, {
         topK: input.topK,
         scope: input.scope
       });

package/dist/index.cjs

@@ -21739,45 +21739,20 @@ var SearchEngine = class _SearchEngine {
 function createServer(engine) {
   const server = new mcp_js.McpServer({
     name: "searchsocket-mcp",
-    version: "0.1.0"
+    version: "0.2.0"
   });
   server.registerTool(
     "search",
     {
-      description: `Semantic site search powered by Upstash Search. Returns url, title, snippet, chunkText, score, and routeFile per result. chunkText contains the full raw chunk markdown. When groupBy is 'page' (default), each result includes a chunks array with section-level sub-results containing sectionTitle, headingPath, snippet, and score. Supports optional filters for structured metadata (e.g. {"version": 2, "deprecated": false}).`,
+      description: "Searches indexed site content using semantic similarity. Returns ranked results with url, title, snippet, chunkText (full section markdown), score, and routeFile (source file path for editing). Each result includes the best-matching section; set groupBy to 'page' (default) for additional chunk sub-results per page. Use routeFile to locate the source file when editing content. If snippets lack detail, call get_page with the result URL to retrieve the full page markdown.",
       inputSchema: {
-        query: zod.z.string().min(1),
-        scope: zod.z.string().optional(),
-        topK: zod.z.number().int().positive().max(100).optional(),
-        pathPrefix: zod.z.string().optional(),
-        tags: zod.z.array(zod.z.string()).optional(),
-        filters: zod.z.record(zod.z.string(), zod.z.union([zod.z.string(), zod.z.number(), zod.z.boolean()])).optional(),
-        groupBy: zod.z.enum(["page", "chunk"]).optional(),
-        maxSubResults: zod.z.number().int().positive().max(20).optional()
-      },
-      outputSchema: {
-        q: zod.z.string(),
-        scope: zod.z.string(),
-        results: zod.z.array(zod.z.object({
-          url: zod.z.string(),
-          title: zod.z.string(),
-          sectionTitle: zod.z.string().optional(),
-          snippet: zod.z.string(),
-          score: zod.z.number(),
-          routeFile: zod.z.string(),
-          chunks: zod.z.array(zod.z.object({
-            sectionTitle: zod.z.string().optional(),
-            snippet: zod.z.string(),
-            headingPath: zod.z.array(zod.z.string()),
-            score: zod.z.number()
-          })).optional()
-        })),
-        meta: zod.z.object({
-          timingsMs: zod.z.object({
-            search: zod.z.number(),
-            total: zod.z.number()
-          })
-        })
+        query: zod.z.string().min(1).describe("Search query. Use keywords or natural language, not full sentences."),
+        topK: zod.z.number().int().positive().max(100).optional().describe("Number of results to return (default: 10, max: 100)"),
+        pathPrefix: zod.z.string().optional().describe("Filter results to URLs starting with this prefix (e.g. '/docs')"),
+        tags: zod.z.array(zod.z.string()).optional().describe("Filter results to pages matching all specified tags"),
+        filters: zod.z.record(zod.z.string(), zod.z.union([zod.z.string(), zod.z.number(), zod.z.boolean()])).optional().describe('Filter by structured page metadata (e.g. {"version": 2})'),
+        groupBy: zod.z.enum(["page", "chunk"]).optional().describe("'page' (default) groups chunks by page with sub-results; 'chunk' returns individual chunks"),
+        scope: zod.z.string().optional()
       }
     },
     async (input) => {
@@ -21788,85 +21763,18 @@ function createServer(engine) {
         pathPrefix: input.pathPrefix,
         tags: input.tags,
         filters: input.filters,
-        groupBy: input.groupBy,
-        maxSubResults: input.maxSubResults
-      });
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(result, null, 2)
-          }
-        ],
-        structuredContent: result
-      };
-    }
-  );
-  server.registerTool(
-    "get_page",
-    {
-      description: "Fetch indexed markdown for a specific path or URL, including frontmatter and routeFile mapping.",
-      inputSchema: {
-        pathOrUrl: zod.z.string().min(1),
-        scope: zod.z.string().optional()
-      }
-    },
-    async (input) => {
-      const page = await engine.getPage(input.pathOrUrl, input.scope);
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(page, null, 2)
-          }
-        ]
-      };
-    }
-  );
-  server.registerTool(
-    "list_pages",
-    {
-      description: "List indexed pages with optional path prefix filtering and cursor-based pagination. Returns url, title, description, and routeFile for each page. Use nextCursor to fetch subsequent pages.",
-      inputSchema: {
-        pathPrefix: zod.z.string().optional(),
-        cursor: zod.z.string().optional(),
-        limit: zod.z.number().int().positive().max(200).optional(),
-        scope: zod.z.string().optional()
-      }
-    },
-    async (input) => {
-      const result = await engine.listPages({
-        pathPrefix: input.pathPrefix,
-        cursor: input.cursor,
-        limit: input.limit,
-        scope: input.scope
+        groupBy: input.groupBy
       });
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(result, null, 2)
-          }
-        ]
-      };
-    }
-  );
-  server.registerTool(
-    "get_site_structure",
-    {
-      description: "Returns the hierarchical page tree derived from URL paths. Use this to understand site navigation structure, find where pages belong, or scope further operations to a section. Nodes with isIndexed: false are implicit structural parents not directly in the index. Large sites (>2000 pages) return truncated: true.",
-      inputSchema: {
-        pathPrefix: zod.z.string().optional(),
-        scope: zod.z.string().optional(),
-        maxPages: zod.z.number().int().positive().max(2e3).optional()
+      if (result.results.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No results found for "${input.query}". Try broader keywords or remove filters.`
+            }
+          ]
+        };
       }
-    },
-    async (input) => {
-      const result = await engine.getSiteStructure({
-        pathPrefix: input.pathPrefix,
-        scope: input.scope,
-        maxPages: input.maxPages
-      });
       return {
         content: [
           {
@@ -21878,56 +21786,51 @@ function createServer(engine) {
     }
   );
   server.registerTool(
-    "find_source_file",
+    "get_page",
     {
-      description: "Find the SvelteKit source file for a piece of site content. Use this when you need to locate and edit content on the site. Returns the URL, route file path, section title, and a content snippet.",
+      description: "Retrieves the full markdown content and metadata for a specific page by its URL path. Use this after search when snippets lack the detail needed to answer a question. Returns reconstructed page markdown, frontmatter (title, routeFile, tags, link counts, indexedAt), and the source file path. Do NOT use this for discovery \u2014 use search first to find relevant pages.",
       inputSchema: {
-        query: zod.z.string().min(1),
+        path: zod.z.string().min(1).describe("URL path of the page (e.g. '/docs/auth'). Use a URL from search results."),
         scope: zod.z.string().optional()
       }
     },
     async (input) => {
-      const result = await engine.search({
-        q: input.query,
-        topK: 1,
-        scope: input.scope
-      });
-      if (result.results.length === 0) {
+      try {
+        const page = await engine.getPage(input.path, input.scope);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(page, null, 2)
+            }
+          ]
+        };
+      } catch {
+        const suggestions = await engine.search({ q: input.path, topK: 3, scope: input.scope });
+        const similar = suggestions.results.map((r) => r.url);
         return {
           content: [
             {
               type: "text",
-              text: JSON.stringify({
-                error: "No matching content found for the given query."
-              })
+              text: similar.length > 0 ? `Page '${input.path}' not found. Similar pages: ${similar.join(", ")}` : `Page '${input.path}' not found. Use search to find the correct URL.`
             }
           ]
         };
       }
-      const match = result.results[0];
-      const { url, routeFile, sectionTitle, snippet } = match;
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify({ url, routeFile, sectionTitle, snippet })
-          }
-        ]
-      };
     }
   );
   server.registerTool(
     "get_related_pages",
     {
-      description: "Find pages related to a given URL using link graph, semantic similarity, and structural proximity. Returns related pages ranked by a composite relatedness score. Use this to discover content connected to a known page.",
+      description: "Finds pages related to a specific page using link graph analysis, semantic similarity, and URL structure. Returns related pages with relationship type (outgoing_link, incoming_link, sibling, semantic) and relevance score. Do NOT use this for general search \u2014 use search instead. Use this only when you already have a specific page URL and need to discover connected content.",
       inputSchema: {
-        pathOrUrl: zod.z.string().min(1),
-        scope: zod.z.string().optional(),
-        topK: zod.z.number().int().positive().max(25).optional()
+        path: zod.z.string().min(1).describe("URL path of the source page (e.g. '/docs/auth'). Use a URL from search results."),
+        topK: zod.z.number().int().positive().max(25).optional().describe("Number of related pages to return (default: 10, max: 25)"),
+        scope: zod.z.string().optional()
       }
     },
     async (input) => {
-      const result = await engine.getRelatedPages(input.pathOrUrl, {
+      const result = await engine.getRelatedPages(input.path, {
         topK: input.topK,
         scope: input.scope
       });

package/dist/index.js

@@ -21727,45 +21727,20 @@ var SearchEngine = class _SearchEngine {
 function createServer(engine) {
   const server = new McpServer({
     name: "searchsocket-mcp",
-    version: "0.1.0"
+    version: "0.2.0"
   });
   server.registerTool(
     "search",
     {
-      description: `Semantic site search powered by Upstash Search. Returns url, title, snippet, chunkText, score, and routeFile per result. chunkText contains the full raw chunk markdown. When groupBy is 'page' (default), each result includes a chunks array with section-level sub-results containing sectionTitle, headingPath, snippet, and score. Supports optional filters for structured metadata (e.g. {"version": 2, "deprecated": false}).`,
+      description: "Searches indexed site content using semantic similarity. Returns ranked results with url, title, snippet, chunkText (full section markdown), score, and routeFile (source file path for editing). Each result includes the best-matching section; set groupBy to 'page' (default) for additional chunk sub-results per page. Use routeFile to locate the source file when editing content. If snippets lack detail, call get_page with the result URL to retrieve the full page markdown.",
       inputSchema: {
-        query: z.string().min(1),
-        scope: z.string().optional(),
-        topK: z.number().int().positive().max(100).optional(),
-        pathPrefix: z.string().optional(),
-        tags: z.array(z.string()).optional(),
-        filters: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
-        groupBy: z.enum(["page", "chunk"]).optional(),
-        maxSubResults: z.number().int().positive().max(20).optional()
-      },
-      outputSchema: {
-        q: z.string(),
-        scope: z.string(),
-        results: z.array(z.object({
-          url: z.string(),
-          title: z.string(),
-          sectionTitle: z.string().optional(),
-          snippet: z.string(),
-          score: z.number(),
-          routeFile: z.string(),
-          chunks: z.array(z.object({
-            sectionTitle: z.string().optional(),
-            snippet: z.string(),
-            headingPath: z.array(z.string()),
-            score: z.number()
-          })).optional()
-        })),
-        meta: z.object({
-          timingsMs: z.object({
-            search: z.number(),
-            total: z.number()
-          })
-        })
+        query: z.string().min(1).describe("Search query. Use keywords or natural language, not full sentences."),
+        topK: z.number().int().positive().max(100).optional().describe("Number of results to return (default: 10, max: 100)"),
+        pathPrefix: z.string().optional().describe("Filter results to URLs starting with this prefix (e.g. '/docs')"),
+        tags: z.array(z.string()).optional().describe("Filter results to pages matching all specified tags"),
+        filters: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional().describe('Filter by structured page metadata (e.g. {"version": 2})'),
+        groupBy: z.enum(["page", "chunk"]).optional().describe("'page' (default) groups chunks by page with sub-results; 'chunk' returns individual chunks"),
+        scope: z.string().optional()
       }
     },
     async (input) => {
@@ -21776,85 +21751,18 @@ function createServer(engine) {
         pathPrefix: input.pathPrefix,
         tags: input.tags,
         filters: input.filters,
-        groupBy: input.groupBy,
-        maxSubResults: input.maxSubResults
-      });
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(result, null, 2)
-          }
-        ],
-        structuredContent: result
-      };
-    }
-  );
-  server.registerTool(
-    "get_page",
-    {
-      description: "Fetch indexed markdown for a specific path or URL, including frontmatter and routeFile mapping.",
-      inputSchema: {
-        pathOrUrl: z.string().min(1),
-        scope: z.string().optional()
-      }
-    },
-    async (input) => {
-      const page = await engine.getPage(input.pathOrUrl, input.scope);
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(page, null, 2)
-          }
-        ]
-      };
-    }
-  );
-  server.registerTool(
-    "list_pages",
-    {
-      description: "List indexed pages with optional path prefix filtering and cursor-based pagination. Returns url, title, description, and routeFile for each page. Use nextCursor to fetch subsequent pages.",
-      inputSchema: {
-        pathPrefix: z.string().optional(),
-        cursor: z.string().optional(),
-        limit: z.number().int().positive().max(200).optional(),
-        scope: z.string().optional()
-      }
-    },
-    async (input) => {
-      const result = await engine.listPages({
-        pathPrefix: input.pathPrefix,
-        cursor: input.cursor,
-        limit: input.limit,
-        scope: input.scope
+        groupBy: input.groupBy
       });
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(result, null, 2)
-          }
-        ]
-      };
-    }
-  );
-  server.registerTool(
-    "get_site_structure",
-    {
-      description: "Returns the hierarchical page tree derived from URL paths. Use this to understand site navigation structure, find where pages belong, or scope further operations to a section. Nodes with isIndexed: false are implicit structural parents not directly in the index. Large sites (>2000 pages) return truncated: true.",
-      inputSchema: {
-        pathPrefix: z.string().optional(),
-        scope: z.string().optional(),
-        maxPages: z.number().int().positive().max(2e3).optional()
+      if (result.results.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No results found for "${input.query}". Try broader keywords or remove filters.`
+            }
+          ]
+        };
       }
-    },
-    async (input) => {
-      const result = await engine.getSiteStructure({
-        pathPrefix: input.pathPrefix,
-        scope: input.scope,
-        maxPages: input.maxPages
-      });
       return {
         content: [
           {
@@ -21866,56 +21774,51 @@ function createServer(engine) {
     }
   );
   server.registerTool(
-    "find_source_file",
+    "get_page",
     {
-      description: "Find the SvelteKit source file for a piece of site content. Use this when you need to locate and edit content on the site. Returns the URL, route file path, section title, and a content snippet.",
+      description: "Retrieves the full markdown content and metadata for a specific page by its URL path. Use this after search when snippets lack the detail needed to answer a question. Returns reconstructed page markdown, frontmatter (title, routeFile, tags, link counts, indexedAt), and the source file path. Do NOT use this for discovery \u2014 use search first to find relevant pages.",
       inputSchema: {
-        query: z.string().min(1),
+        path: z.string().min(1).describe("URL path of the page (e.g. '/docs/auth'). Use a URL from search results."),
         scope: z.string().optional()
       }
     },
     async (input) => {
-      const result = await engine.search({
-        q: input.query,
-        topK: 1,
-        scope: input.scope
-      });
-      if (result.results.length === 0) {
+      try {
+        const page = await engine.getPage(input.path, input.scope);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(page, null, 2)
+            }
+          ]
+        };
+      } catch {
+        const suggestions = await engine.search({ q: input.path, topK: 3, scope: input.scope });
+        const similar = suggestions.results.map((r) => r.url);
         return {
           content: [
             {
               type: "text",
-              text: JSON.stringify({
-                error: "No matching content found for the given query."
-              })
+              text: similar.length > 0 ? `Page '${input.path}' not found. Similar pages: ${similar.join(", ")}` : `Page '${input.path}' not found. Use search to find the correct URL.`
             }
           ]
         };
       }
-      const match = result.results[0];
-      const { url, routeFile, sectionTitle, snippet } = match;
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify({ url, routeFile, sectionTitle, snippet })
-          }
-        ]
-      };
     }
   );
   server.registerTool(
     "get_related_pages",
     {
-      description: "Find pages related to a given URL using link graph, semantic similarity, and structural proximity. Returns related pages ranked by a composite relatedness score. Use this to discover content connected to a known page.",
+      description: "Finds pages related to a specific page using link graph analysis, semantic similarity, and URL structure. Returns related pages with relationship type (outgoing_link, incoming_link, sibling, semantic) and relevance score. Do NOT use this for general search \u2014 use search instead. Use this only when you already have a specific page URL and need to discover connected content.",
       inputSchema: {
-        pathOrUrl: z.string().min(1),
-        scope: z.string().optional(),
-        topK: z.number().int().positive().max(25).optional()
+        path: z.string().min(1).describe("URL path of the source page (e.g. '/docs/auth'). Use a URL from search results."),
+        topK: z.number().int().positive().max(25).optional().describe("Number of related pages to return (default: 10, max: 25)"),
+        scope: z.string().optional()
       }
     },
     async (input) => {
-      const result = await engine.getRelatedPages(input.pathOrUrl, {
+      const result = await engine.getRelatedPages(input.path, {
         topK: input.topK,
         scope: input.scope
       });

package/dist/sveltekit.cjs

@@ -18715,45 +18715,20 @@ var SearchEngine = class _SearchEngine {
 function createServer(engine) {
   const server = new mcp_js.McpServer({
     name: "searchsocket-mcp",
-    version: "0.1.0"
+    version: "0.2.0"
   });
   server.registerTool(
     "search",
     {
-      description: `Semantic site search powered by Upstash Search. Returns url, title, snippet, chunkText, score, and routeFile per result. chunkText contains the full raw chunk markdown. When groupBy is 'page' (default), each result includes a chunks array with section-level sub-results containing sectionTitle, headingPath, snippet, and score. Supports optional filters for structured metadata (e.g. {"version": 2, "deprecated": false}).`,
+      description: "Searches indexed site content using semantic similarity. Returns ranked results with url, title, snippet, chunkText (full section markdown), score, and routeFile (source file path for editing). Each result includes the best-matching section; set groupBy to 'page' (default) for additional chunk sub-results per page. Use routeFile to locate the source file when editing content. If snippets lack detail, call get_page with the result URL to retrieve the full page markdown.",
       inputSchema: {
-        query: zod.z.string().min(1),
-        scope: zod.z.string().optional(),
-        topK: zod.z.number().int().positive().max(100).optional(),
-        pathPrefix: zod.z.string().optional(),
-        tags: zod.z.array(zod.z.string()).optional(),
-        filters: zod.z.record(zod.z.string(), zod.z.union([zod.z.string(), zod.z.number(), zod.z.boolean()])).optional(),
-        groupBy: zod.z.enum(["page", "chunk"]).optional(),
-        maxSubResults: zod.z.number().int().positive().max(20).optional()
-      },
-      outputSchema: {
-        q: zod.z.string(),
-        scope: zod.z.string(),
-        results: zod.z.array(zod.z.object({
-          url: zod.z.string(),
-          title: zod.z.string(),
-          sectionTitle: zod.z.string().optional(),
-          snippet: zod.z.string(),
-          score: zod.z.number(),
-          routeFile: zod.z.string(),
-          chunks: zod.z.array(zod.z.object({
-            sectionTitle: zod.z.string().optional(),
-            snippet: zod.z.string(),
-            headingPath: zod.z.array(zod.z.string()),
-            score: zod.z.number()
-          })).optional()
-        })),
-        meta: zod.z.object({
-          timingsMs: zod.z.object({
-            search: zod.z.number(),
-            total: zod.z.number()
-          })
-        })
+        query: zod.z.string().min(1).describe("Search query. Use keywords or natural language, not full sentences."),
+        topK: zod.z.number().int().positive().max(100).optional().describe("Number of results to return (default: 10, max: 100)"),
+        pathPrefix: zod.z.string().optional().describe("Filter results to URLs starting with this prefix (e.g. '/docs')"),
+        tags: zod.z.array(zod.z.string()).optional().describe("Filter results to pages matching all specified tags"),
+        filters: zod.z.record(zod.z.string(), zod.z.union([zod.z.string(), zod.z.number(), zod.z.boolean()])).optional().describe('Filter by structured page metadata (e.g. {"version": 2})'),
+        groupBy: zod.z.enum(["page", "chunk"]).optional().describe("'page' (default) groups chunks by page with sub-results; 'chunk' returns individual chunks"),
+        scope: zod.z.string().optional()
       }
     },
     async (input) => {
@@ -18764,85 +18739,18 @@ function createServer(engine) {
         pathPrefix: input.pathPrefix,
         tags: input.tags,
         filters: input.filters,
-        groupBy: input.groupBy,
-        maxSubResults: input.maxSubResults
-      });
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(result, null, 2)
-          }
-        ],
-        structuredContent: result
-      };
-    }
-  );
-  server.registerTool(
-    "get_page",
-    {
-      description: "Fetch indexed markdown for a specific path or URL, including frontmatter and routeFile mapping.",
-      inputSchema: {
-        pathOrUrl: zod.z.string().min(1),
-        scope: zod.z.string().optional()
-      }
-    },
-    async (input) => {
-      const page = await engine.getPage(input.pathOrUrl, input.scope);
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(page, null, 2)
-          }
-        ]
-      };
-    }
-  );
-  server.registerTool(
-    "list_pages",
-    {
-      description: "List indexed pages with optional path prefix filtering and cursor-based pagination. Returns url, title, description, and routeFile for each page. Use nextCursor to fetch subsequent pages.",
-      inputSchema: {
-        pathPrefix: zod.z.string().optional(),
-        cursor: zod.z.string().optional(),
-        limit: zod.z.number().int().positive().max(200).optional(),
-        scope: zod.z.string().optional()
-      }
-    },
-    async (input) => {
-      const result = await engine.listPages({
-        pathPrefix: input.pathPrefix,
-        cursor: input.cursor,
-        limit: input.limit,
-        scope: input.scope
+        groupBy: input.groupBy
       });
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(result, null, 2)
-          }
-        ]
-      };
-    }
-  );
-  server.registerTool(
-    "get_site_structure",
-    {
-      description: "Returns the hierarchical page tree derived from URL paths. Use this to understand site navigation structure, find where pages belong, or scope further operations to a section. Nodes with isIndexed: false are implicit structural parents not directly in the index. Large sites (>2000 pages) return truncated: true.",
-      inputSchema: {
-        pathPrefix: zod.z.string().optional(),
-        scope: zod.z.string().optional(),
-        maxPages: zod.z.number().int().positive().max(2e3).optional()
+      if (result.results.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No results found for "${input.query}". Try broader keywords or remove filters.`
+            }
+          ]
+        };
       }
-    },
-    async (input) => {
-      const result = await engine.getSiteStructure({
-        pathPrefix: input.pathPrefix,
-        scope: input.scope,
-        maxPages: input.maxPages
-      });
       return {
         content: [
           {
@@ -18854,56 +18762,51 @@ function createServer(engine) {
     }
   );
   server.registerTool(
-    "find_source_file",
+    "get_page",
     {
-      description: "Find the SvelteKit source file for a piece of site content. Use this when you need to locate and edit content on the site. Returns the URL, route file path, section title, and a content snippet.",
+      description: "Retrieves the full markdown content and metadata for a specific page by its URL path. Use this after search when snippets lack the detail needed to answer a question. Returns reconstructed page markdown, frontmatter (title, routeFile, tags, link counts, indexedAt), and the source file path. Do NOT use this for discovery \u2014 use search first to find relevant pages.",
       inputSchema: {
-        query: zod.z.string().min(1),
+        path: zod.z.string().min(1).describe("URL path of the page (e.g. '/docs/auth'). Use a URL from search results."),
         scope: zod.z.string().optional()
       }
     },
     async (input) => {
-      const result = await engine.search({
-        q: input.query,
-        topK: 1,
-        scope: input.scope
-      });
-      if (result.results.length === 0) {
+      try {
+        const page = await engine.getPage(input.path, input.scope);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(page, null, 2)
+            }
+          ]
+        };
+      } catch {
+        const suggestions = await engine.search({ q: input.path, topK: 3, scope: input.scope });
+        const similar = suggestions.results.map((r) => r.url);
         return {
           content: [
             {
               type: "text",
-              text: JSON.stringify({
-                error: "No matching content found for the given query."
-              })
+              text: similar.length > 0 ? `Page '${input.path}' not found. Similar pages: ${similar.join(", ")}` : `Page '${input.path}' not found. Use search to find the correct URL.`
             }
           ]
         };
       }
-      const match = result.results[0];
-      const { url, routeFile, sectionTitle, snippet } = match;
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify({ url, routeFile, sectionTitle, snippet })
-          }
-        ]
-      };
     }
   );
   server.registerTool(
     "get_related_pages",
     {
-      description: "Find pages related to a given URL using link graph, semantic similarity, and structural proximity. Returns related pages ranked by a composite relatedness score. Use this to discover content connected to a known page.",
+      description: "Finds pages related to a specific page using link graph analysis, semantic similarity, and URL structure. Returns related pages with relationship type (outgoing_link, incoming_link, sibling, semantic) and relevance score. Do NOT use this for general search \u2014 use search instead. Use this only when you already have a specific page URL and need to discover connected content.",
       inputSchema: {
-        pathOrUrl: zod.z.string().min(1),
-        scope: zod.z.string().optional(),
-        topK: zod.z.number().int().positive().max(25).optional()
+        path: zod.z.string().min(1).describe("URL path of the source page (e.g. '/docs/auth'). Use a URL from search results."),
+        topK: zod.z.number().int().positive().max(25).optional().describe("Number of related pages to return (default: 10, max: 25)"),
+        scope: zod.z.string().optional()
       }
     },
     async (input) => {
-      const result = await engine.getRelatedPages(input.pathOrUrl, {
+      const result = await engine.getRelatedPages(input.path, {
         topK: input.topK,
         scope: input.scope
       });

package/dist/sveltekit.js

@@ -18703,45 +18703,20 @@ var SearchEngine = class _SearchEngine {
 function createServer(engine) {
   const server = new McpServer({
     name: "searchsocket-mcp",
-    version: "0.1.0"
+    version: "0.2.0"
   });
   server.registerTool(
     "search",
     {
-      description: `Semantic site search powered by Upstash Search. Returns url, title, snippet, chunkText, score, and routeFile per result. chunkText contains the full raw chunk markdown. When groupBy is 'page' (default), each result includes a chunks array with section-level sub-results containing sectionTitle, headingPath, snippet, and score. Supports optional filters for structured metadata (e.g. {"version": 2, "deprecated": false}).`,
+      description: "Searches indexed site content using semantic similarity. Returns ranked results with url, title, snippet, chunkText (full section markdown), score, and routeFile (source file path for editing). Each result includes the best-matching section; set groupBy to 'page' (default) for additional chunk sub-results per page. Use routeFile to locate the source file when editing content. If snippets lack detail, call get_page with the result URL to retrieve the full page markdown.",
       inputSchema: {
-        query: z.string().min(1),
-        scope: z.string().optional(),
-        topK: z.number().int().positive().max(100).optional(),
-        pathPrefix: z.string().optional(),
-        tags: z.array(z.string()).optional(),
-        filters: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
-        groupBy: z.enum(["page", "chunk"]).optional(),
-        maxSubResults: z.number().int().positive().max(20).optional()
-      },
-      outputSchema: {
-        q: z.string(),
-        scope: z.string(),
-        results: z.array(z.object({
-          url: z.string(),
-          title: z.string(),
-          sectionTitle: z.string().optional(),
-          snippet: z.string(),
-          score: z.number(),
-          routeFile: z.string(),
-          chunks: z.array(z.object({
-            sectionTitle: z.string().optional(),
-            snippet: z.string(),
-            headingPath: z.array(z.string()),
-            score: z.number()
-          })).optional()
-        })),
-        meta: z.object({
-          timingsMs: z.object({
-            search: z.number(),
-            total: z.number()
-          })
-        })
+        query: z.string().min(1).describe("Search query. Use keywords or natural language, not full sentences."),
+        topK: z.number().int().positive().max(100).optional().describe("Number of results to return (default: 10, max: 100)"),
+        pathPrefix: z.string().optional().describe("Filter results to URLs starting with this prefix (e.g. '/docs')"),
+        tags: z.array(z.string()).optional().describe("Filter results to pages matching all specified tags"),
+        filters: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional().describe('Filter by structured page metadata (e.g. {"version": 2})'),
+        groupBy: z.enum(["page", "chunk"]).optional().describe("'page' (default) groups chunks by page with sub-results; 'chunk' returns individual chunks"),
+        scope: z.string().optional()
       }
     },
     async (input) => {
@@ -18752,85 +18727,18 @@ function createServer(engine) {
         pathPrefix: input.pathPrefix,
         tags: input.tags,
         filters: input.filters,
-        groupBy: input.groupBy,
-        maxSubResults: input.maxSubResults
-      });
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(result, null, 2)
-          }
-        ],
-        structuredContent: result
-      };
-    }
-  );
-  server.registerTool(
-    "get_page",
-    {
-      description: "Fetch indexed markdown for a specific path or URL, including frontmatter and routeFile mapping.",
-      inputSchema: {
-        pathOrUrl: z.string().min(1),
-        scope: z.string().optional()
-      }
-    },
-    async (input) => {
-      const page = await engine.getPage(input.pathOrUrl, input.scope);
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(page, null, 2)
-          }
-        ]
-      };
-    }
-  );
-  server.registerTool(
-    "list_pages",
-    {
-      description: "List indexed pages with optional path prefix filtering and cursor-based pagination. Returns url, title, description, and routeFile for each page. Use nextCursor to fetch subsequent pages.",
-      inputSchema: {
-        pathPrefix: z.string().optional(),
-        cursor: z.string().optional(),
-        limit: z.number().int().positive().max(200).optional(),
-        scope: z.string().optional()
-      }
-    },
-    async (input) => {
-      const result = await engine.listPages({
-        pathPrefix: input.pathPrefix,
-        cursor: input.cursor,
-        limit: input.limit,
-        scope: input.scope
+        groupBy: input.groupBy
       });
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(result, null, 2)
-          }
-        ]
-      };
-    }
-  );
-  server.registerTool(
-    "get_site_structure",
-    {
-      description: "Returns the hierarchical page tree derived from URL paths. Use this to understand site navigation structure, find where pages belong, or scope further operations to a section. Nodes with isIndexed: false are implicit structural parents not directly in the index. Large sites (>2000 pages) return truncated: true.",
-      inputSchema: {
-        pathPrefix: z.string().optional(),
-        scope: z.string().optional(),
-        maxPages: z.number().int().positive().max(2e3).optional()
+      if (result.results.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No results found for "${input.query}". Try broader keywords or remove filters.`
+            }
+          ]
+        };
       }
-    },
-    async (input) => {
-      const result = await engine.getSiteStructure({
-        pathPrefix: input.pathPrefix,
-        scope: input.scope,
-        maxPages: input.maxPages
-      });
       return {
         content: [
           {
@@ -18842,56 +18750,51 @@ function createServer(engine) {
     }
   );
   server.registerTool(
-    "find_source_file",
+    "get_page",
     {
-      description: "Find the SvelteKit source file for a piece of site content. Use this when you need to locate and edit content on the site. Returns the URL, route file path, section title, and a content snippet.",
+      description: "Retrieves the full markdown content and metadata for a specific page by its URL path. Use this after search when snippets lack the detail needed to answer a question. Returns reconstructed page markdown, frontmatter (title, routeFile, tags, link counts, indexedAt), and the source file path. Do NOT use this for discovery \u2014 use search first to find relevant pages.",
       inputSchema: {
-        query: z.string().min(1),
+        path: z.string().min(1).describe("URL path of the page (e.g. '/docs/auth'). Use a URL from search results."),
         scope: z.string().optional()
       }
     },
     async (input) => {
-      const result = await engine.search({
-        q: input.query,
-        topK: 1,
-        scope: input.scope
-      });
-      if (result.results.length === 0) {
+      try {
+        const page = await engine.getPage(input.path, input.scope);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(page, null, 2)
+            }
+          ]
+        };
+      } catch {
+        const suggestions = await engine.search({ q: input.path, topK: 3, scope: input.scope });
+        const similar = suggestions.results.map((r) => r.url);
         return {
           content: [
             {
               type: "text",
-              text: JSON.stringify({
-                error: "No matching content found for the given query."
-              })
+              text: similar.length > 0 ? `Page '${input.path}' not found. Similar pages: ${similar.join(", ")}` : `Page '${input.path}' not found. Use search to find the correct URL.`
             }
           ]
         };
       }
-      const match = result.results[0];
-      const { url, routeFile, sectionTitle, snippet } = match;
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify({ url, routeFile, sectionTitle, snippet })
-          }
-        ]
-      };
     }
   );
   server.registerTool(
     "get_related_pages",
     {
-      description: "Find pages related to a given URL using link graph, semantic similarity, and structural proximity. Returns related pages ranked by a composite relatedness score. Use this to discover content connected to a known page.",
+      description: "Finds pages related to a specific page using link graph analysis, semantic similarity, and URL structure. Returns related pages with relationship type (outgoing_link, incoming_link, sibling, semantic) and relevance score. Do NOT use this for general search \u2014 use search instead. Use this only when you already have a specific page URL and need to discover connected content.",
       inputSchema: {
-        pathOrUrl: z.string().min(1),
-        scope: z.string().optional(),
-        topK: z.number().int().positive().max(25).optional()
+        path: z.string().min(1).describe("URL path of the source page (e.g. '/docs/auth'). Use a URL from search results."),
+        topK: z.number().int().positive().max(25).optional().describe("Number of related pages to return (default: 10, max: 25)"),
+        scope: z.string().optional()
       }
     },
     async (input) => {
-      const result = await engine.getRelatedPages(input.pathOrUrl, {
+      const result = await engine.getRelatedPages(input.path, {
         topK: input.topK,
         scope: input.scope
       });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "searchsocket",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "description": "Semantic site search and MCP retrieval for SvelteKit static sites",
   "license": "MIT",
   "author": "Greg Priday <greg@siteorigin.com>",