@nshipster/sosumi 1.0.5 → 1.0.7

package/src/lib/mcp.ts

@@ -9,46 +9,122 @@ import { searchAppleDeveloperDocs } from "./search"
 import { generateAppleDocUrl, normalizeDocumentationPath } from "./url"
 import { fetchVideoTranscriptMarkdown } from "./video"
 
+export const MCP_SERVER_INFO = {
+  name: "sosumi.ai",
+  version: "1.0.0",
+} as const
+
+export interface ToolHttpBinding {
+  path?: string
+  pathFrom?: string
+  pathPrefix?: string
+  query?: Record<string, string>
+}
+
+export interface ToolMeta {
+  name: string
+  title: string
+  description: string
+  inputSchema: z.ZodRawShape
+  outputSchema?: z.ZodRawShape
+  annotations: {
+    readOnlyHint: boolean
+    destructiveHint: boolean
+    idempotentHint: boolean
+    openWorldHint: boolean
+  }
+  http: ToolHttpBinding
+}
+
+const searchResultSchema = z.object({
+  title: z.string().describe("Title of the documentation page"),
+  url: z.string().describe("Full URL to the documentation page"),
+  description: z.string().describe("Brief description of the page content"),
+  breadcrumbs: z.array(z.string()).describe("Navigation breadcrumbs showing the page hierarchy"),
+  tags: z.array(z.string()).describe("Tags associated with the page (languages, platforms, etc.)"),
+  type: z.string().describe("Type of result (documentation, general, etc.)"),
+})
+
+const readOnlyAnnotations = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: true,
+} as const
+
+export const TOOL_DEFINITIONS = {
+  searchAppleDocumentation: {
+    name: "searchAppleDocumentation",
+    title: "Search Apple Documentation",
+    description: "Search Apple Developer documentation and return structured results",
+    inputSchema: {
+      query: z.string().describe("Search query for Apple documentation"),
+    },
+    outputSchema: {
+      query: z.string().describe("The search query that was executed"),
+      results: z.array(searchResultSchema).describe("Array of search results"),
+    },
+    annotations: readOnlyAnnotations,
+    http: { path: "/search", query: { q: "query" } },
+  },
+  fetchAppleDocumentation: {
+    name: "fetchAppleDocumentation",
+    title: "Fetch Apple Documentation",
+    description:
+      "Fetch Apple Developer documentation and Human Interface Guidelines by path and return as markdown",
+    inputSchema: {
+      path: z
+        .string()
+        .describe(
+          "Documentation path (e.g., '/documentation/swift', '/documentation/swiftui/view', '/design/human-interface-guidelines/foundations/color')",
+        ),
+    },
+    annotations: readOnlyAnnotations,
+    http: { pathFrom: "path" },
+  },
+  fetchExternalDocumentation: {
+    name: "fetchExternalDocumentation",
+    title: "Fetch External Documentation",
+    description:
+      "Fetch external Swift-DocC documentation by absolute https URL and return as markdown",
+    inputSchema: {
+      url: z
+        .string()
+        .describe(
+          "External Swift-DocC URL (e.g., 'https://apple.github.io/swift-argument-parser/documentation/argumentparser')",
+        ),
+    },
+    annotations: readOnlyAnnotations,
+    http: { pathFrom: "url", pathPrefix: "/external/" },
+  },
+  fetchAppleVideoTranscript: {
+    name: "fetchAppleVideoTranscript",
+    title: "Fetch Apple Video Transcript",
+    description: "Fetch transcript for an Apple Developer video path and return as markdown",
+    inputSchema: {
+      path: z
+        .string()
+        .describe(
+          "Apple video path (e.g., '/videos/play/wwdc2021/10133' or '/videos/play/meet-with-apple/208')",
+        ),
+    },
+    annotations: readOnlyAnnotations,
+    http: { pathFrom: "path" },
+  },
+} satisfies Record<string, ToolMeta>
+
 export function createMcpServer(externalPolicyEnv: ExternalPolicyEnv = {}) {
-  const server = new McpServer({
-    name: "sosumi.ai",
-    version: "1.0.0",
-  })
+  const server = new McpServer(MCP_SERVER_INFO)
 
-  // Register Apple search tool
+  const search = TOOL_DEFINITIONS.searchAppleDocumentation
   server.registerTool(
-    "searchAppleDocumentation",
+    search.name,
     {
-      title: "Search Apple Documentation",
-      description: "Search Apple Developer documentation and return structured results",
-      inputSchema: {
-        query: z.string().describe("Search query for Apple documentation"),
-      },
-      outputSchema: {
-        query: z.string().describe("The search query that was executed"),
-        results: z
-          .array(
-            z.object({
-              title: z.string().describe("Title of the documentation page"),
-              url: z.string().describe("Full URL to the documentation page"),
-              description: z.string().describe("Brief description of the page content"),
-              breadcrumbs: z
-                .array(z.string())
-                .describe("Navigation breadcrumbs showing the page hierarchy"),
-              tags: z
-                .array(z.string())
-                .describe("Tags associated with the page (languages, platforms, etc.)"),
-              type: z.string().describe("Type of result (documentation, general, etc.)"),
-            }),
-          )
-          .describe("Array of search results"),
-      },
-      annotations: {
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true,
-      },
+      title: search.title,
+      description: search.description,
+      inputSchema: search.inputSchema,
+      outputSchema: search.outputSchema,
+      annotations: search.annotations,
     },
     async ({ query }) => {
       try {
@@ -78,7 +154,6 @@ export function createMcpServer(externalPolicyEnv: ExternalPolicyEnv = {}) {
           }
         }
 
-        // Provide a readable text summary
         const resultText =
           `Found ${searchResponse.results.length} result(s) for "${query}":\n\n` +
           searchResponse.results
@@ -100,50 +175,34 @@ export function createMcpServer(externalPolicyEnv: ExternalPolicyEnv = {}) {
       } catch (error) {
         const errorMessage = error instanceof Error ? error.message : "Unknown error"
 
-        const structuredContent = {
-          query,
-          results: [],
-        }
-
+        // Report the failure as an error rather than as structured content.
+        // An empty `results` array reads as "this documentation does not exist",
+        // which would leave the caller trusting its own memory instead of looking again.
         return {
+          isError: true,
           content: [
             {
               type: "text" as const,
               text: `Error searching Apple Developer documentation: ${errorMessage}`,
             },
           ],
-          structuredContent,
         }
       }
     },
   )
 
-  // Register documentation fetch tool (supports both dev docs and HIG)
+  const fetchDocs = TOOL_DEFINITIONS.fetchAppleDocumentation
   server.registerTool(
-    "fetchAppleDocumentation",
+    fetchDocs.name,
     {
-      title: "Fetch Apple Documentation",
-      description:
-        "Fetch Apple Developer documentation and Human Interface Guidelines by path and return as markdown",
-      inputSchema: {
-        path: z
-          .string()
-          .describe(
-            "Documentation path (e.g., '/documentation/swift', 'swiftui/view', 'design/human-interface-guidelines/foundations/color')",
-          ),
-      },
-      annotations: {
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true,
-      },
+      title: fetchDocs.title,
+      description: fetchDocs.description,
+      inputSchema: fetchDocs.inputSchema,
+      annotations: fetchDocs.annotations,
     },
     async ({ path }) => {
       try {
-        // Check if this is a HIG path
         if (path.includes("design/human-interface-guidelines")) {
-          // Handle HIG content
           const higPath = path.replace(/^\/?(design\/human-interface-guidelines\/)/, "")
           const sourceUrl = `https://developer.apple.com/design/human-interface-guidelines/${higPath}`
 
@@ -162,26 +221,25 @@ export function createMcpServer(externalPolicyEnv: ExternalPolicyEnv = {}) {
               },
             ],
           }
-        } else {
-          // Handle regular developer documentation
-          const normalizedPath = normalizeDocumentationPath(path)
-          const appleUrl = generateAppleDocUrl(normalizedPath)
+        }
 
-          const jsonData = await fetchJSONData(normalizedPath)
-          const markdown = await renderFromJSON(jsonData, appleUrl)
+        const normalizedPath = normalizeDocumentationPath(path)
+        const appleUrl = generateAppleDocUrl(normalizedPath)
 
-          if (!markdown || markdown.trim().length < 100) {
-            throw new Error("Insufficient content in documentation")
-          }
+        const jsonData = await fetchJSONData(normalizedPath)
+        const markdown = await renderFromJSON(jsonData, appleUrl)
 
-          return {
-            content: [
-              {
-                type: "text" as const,
-                text: markdown,
-              },
-            ],
-          }
+        if (!markdown || markdown.trim().length < 100) {
+          throw new Error("Insufficient content in documentation")
+        }
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: markdown,
+            },
+          ],
         }
       } catch (error) {
         const errorMessage = error instanceof Error ? error.message : "Unknown error"
@@ -198,26 +256,14 @@ export function createMcpServer(externalPolicyEnv: ExternalPolicyEnv = {}) {
     },
   )
 
-  // Register external documentation fetch tool
+  const fetchExternal = TOOL_DEFINITIONS.fetchExternalDocumentation
   server.registerTool(
-    "fetchExternalDocumentation",
+    fetchExternal.name,
     {
-      title: "Fetch External Documentation",
-      description:
-        "Fetch external Swift-DocC documentation by absolute https URL and return as markdown",
-      inputSchema: {
-        url: z
-          .string()
-          .describe(
-            "External Swift-DocC URL (e.g., 'https://apple.github.io/swift-argument-parser/documentation/argumentparser')",
-          ),
-      },
-      annotations: {
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true,
-      },
+      title: fetchExternal.title,
+      description: fetchExternal.description,
+      inputSchema: fetchExternal.inputSchema,
+      annotations: fetchExternal.annotations,
     },
     async ({ url }) => {
       try {
@@ -250,25 +296,14 @@ export function createMcpServer(externalPolicyEnv: ExternalPolicyEnv = {}) {
     },
   )
 
-  // Register Apple video transcript fetch tool
+  const fetchVideo = TOOL_DEFINITIONS.fetchAppleVideoTranscript
   server.registerTool(
-    "fetchAppleVideoTranscript",
+    fetchVideo.name,
     {
-      title: "Fetch Apple Video Transcript",
-      description: "Fetch transcript for an Apple Developer video path and return as markdown",
-      inputSchema: {
-        path: z
-          .string()
-          .describe(
-            "Apple video path (e.g., '/videos/play/wwdc2021/10133' or '/videos/play/meet-with-apple/208')",
-          ),
-      },
-      annotations: {
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true,
-      },
+      title: fetchVideo.title,
+      description: fetchVideo.description,
+      inputSchema: fetchVideo.inputSchema,
+      annotations: fetchVideo.annotations,
     },
     async ({ path }) => {
       try {