starlight-mcp 0.1.0 → 0.2.0

package/README.md

@@ -149,7 +149,7 @@ All options are optional.
 | `include` | all | Only index docs whose id starts with one of these prefixes |
 | `exclude` | none | Drop docs whose id starts with one of these prefixes |
 | `docsRedirect` | — | 302 humans who open the endpoint in a browser to this page (otherwise: a polite 405 JSON explainer) |
-| `toolDescriptions` | generated | Replace the description of any tool, e.g. `{ search_docs: "Search the Acme docs (billing, webhooks, SDKs)…" }` — worth hand-tuning so agents know when to reach for it |
+| `toolDescriptions` | generated | Replace the description of any tool, e.g. `{ search_docs: "Search the Acme docs (billing, webhooks, SDKs)…" }` — worth hand-tuning so agents know when to reach for it. Object form also overrides argument descriptions: `{ search_docs: { description: "…", args: { query: "e.g. 'webhook retries'" } } }` |
 
 MDX noise (import statements, standalone `<Component>` tag lines) is stripped from indexed bodies automatically.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "starlight-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Give your Astro or Starlight docs site an MCP server — search_docs, get_doc and list_docs over stateless streamable HTTP. Astro integration, pure fetch handler, and Cloudflare static-assets glue included.",
   "type": "module",
   "license": "MIT",

package/src/tools.ts

@@ -8,19 +8,42 @@ export interface McpTool {
   inputSchema: Record<string, unknown>;
 }
 
+/**
+ * Override a tool's description with a plain string, or use the object
+ * form to also replace argument descriptions inside its inputSchema:
+ * `{ search_docs: { description: "…", args: { query: "…" } } }`.
+ */
+export type ToolOverride =
+  | string
+  | { description?: string; args?: Record<string, string> };
+
 export type ToolDescriptions = Partial<
-  Record<"search_docs" | "get_doc" | "list_docs", string>
+  Record<"search_docs" | "get_doc" | "list_docs", ToolOverride>
 >;
 
+const overrideDescription = (override: ToolOverride | undefined) =>
+  typeof override === "string" ? override : override?.description;
+
+function applyArgOverrides(tool: McpTool, override: ToolOverride | undefined): McpTool {
+  if (typeof override !== "object" || !override.args) return tool;
+  const properties = {
+    ...(tool.inputSchema.properties as Record<string, Record<string, unknown>>),
+  };
+  for (const [arg, description] of Object.entries(override.args)) {
+    if (properties[arg]) properties[arg] = { ...properties[arg], description };
+  }
+  return { ...tool, inputSchema: { ...tool.inputSchema, properties } };
+}
+
 export function makeTools(
   siteLabel: string,
   overrides: ToolDescriptions = {},
 ): McpTool[] {
-  return [
+  const tools: McpTool[] = [
     {
       name: "search_docs",
       description:
-        overrides.search_docs ??
+        overrideDescription(overrides.search_docs) ??
         `Search the ${siteLabel} documentation. Returns the best-matching pages with snippets and URLs.`,
       inputSchema: {
         type: "object",
@@ -36,7 +59,7 @@ export function makeTools(
     {
       name: "get_doc",
       description:
-        overrides.get_doc ??
+        overrideDescription(overrides.get_doc) ??
         "Fetch one documentation page as full markdown by its path (as returned by search_docs or list_docs).",
       inputSchema: {
         type: "object",
@@ -49,9 +72,12 @@ export function makeTools(
     {
       name: "list_docs",
       description:
-        overrides.list_docs ??
+        overrideDescription(overrides.list_docs) ??
         "List every documentation page with its title, description and URL.",
       inputSchema: { type: "object", properties: {} },
     },
   ];
+  return tools.map((tool) =>
+    applyArgOverrides(tool, overrides[tool.name as keyof ToolDescriptions]),
+  );
 }