Merge pull request #16 from evalstate/feat/semantic-search

Semantic Search: find HF Spaces using semantic search

Author: evalstate

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@llmindset/mcp-hfspace",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "MCP Server to connect to Hugging Face spaces. Simple configuration, Claude Desktop friendly.",
   "type": "module",
   "publishConfig": {
@@ -40,23 +40,23 @@
     "coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@gradio/client": "^1.8.0",
-    "@modelcontextprotocol/sdk": "0.6.0",
-    "mime": "^4.0.6",
+    "@gradio/client": "^1.14.2",
+    "@modelcontextprotocol/sdk": "1.9.0",
+    "mime": "^4.0.7",
     "minimist": "^1.2.8"
   },
   "devDependencies": {
-    "@eslint/js": "9.19.0",
+    "@eslint/js": "9.24.0",
     "@types/minimist": "^1.2.5",
-    "@types/node": "^20.11.24",
+    "@types/node": "^22.14.1",
     "@typescript-eslint/eslint-plugin": "latest",
     "@typescript-eslint/parser": "latest",
-    "eslint": "9.19.0",
-    "globals": "15.14.0",
+    "eslint": "9.24.0",
+    "globals": "16.0.0",
     "prettier": "latest",
-    "rimraf": "^5.0.1",
-    "typescript": "^5.3.3",
-    "typescript-eslint": "8.21.0",
-    "vitest": "^2.1.8"
+    "rimraf": "^6.0.1",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "8.30.1",
+    "vitest": "^3.1.1"
   }
 }

package.json

@@ -43,7 +43,7 @@ export function parsePath(path: string): EndpointPath {
 
   if (parts.length != 3) {
     throw new Error(
-      `Invalid Endpoint path format [${path}]. Use or vendor/space/endpoint`,
+      `Invalid Endpoint path format [${path}]. Use or vendor/space/endpoint`
     );
   }
 
@@ -74,19 +74,19 @@ export class EndpointWrapper {
     private endpointPath: EndpointPath,
     private endpoint: ApiEndpoint,
     private client: Client,
-    private workingDir: WorkingDirectory,
+    private workingDir: WorkingDirectory
   ) {
     this.converter = new GradioConverter(workingDir);
   }
 
   static async createEndpoint(
     configuredPath: string,
-    workingDir: WorkingDirectory,
+    workingDir: WorkingDirectory
   ): Promise<EndpointWrapper> {
     const pathParts = configuredPath.split("/");
     if (pathParts.length < 2 || pathParts.length > 3) {
       throw new Error(
-        `Invalid space path format [${configuredPath}]. Use: vendor/space or vendor/space/endpoint`,
+        `Invalid space path format [${configuredPath}]. Use: vendor/space or vendor/space/endpoint`
       );
     }
 
@@ -114,7 +114,7 @@ export class EndpointWrapper {
     if (config.debug) {
       await fs.writeFile(
         `${pathParts[0]}_${pathParts[1]}_debug_api.json`,
-        JSON.stringify(api, null, 2),
+        JSON.stringify(api, null, 2)
       );
     }
     // Try chosen API if specified
@@ -123,20 +123,20 @@ export class EndpointWrapper {
         parsePath(configuredPath),
         api.named_endpoints[endpointTarget],
         gradio,
-        workingDir,
+        workingDir
       );
     }
 
     // Try preferred APIs
     const preferredApi = preferredApis.find(
-      (name) => api.named_endpoints[name],
+      (name) => api.named_endpoints[name]
     );
     if (preferredApi) {
       return new EndpointWrapper(
         parsePath(`${configuredPath}${preferredApi}`),
         api.named_endpoints[preferredApi],
         gradio,
-        workingDir,
+        workingDir
       );
     }
 
@@ -147,22 +147,22 @@ export class EndpointWrapper {
         parsePath(`${configuredPath}${firstNamed[0]}`),
         firstNamed[1],
         gradio,
-        workingDir,
+        workingDir
       );
     }
 
     // Try unnamed endpoints
     const validUnnamed = Object.entries(api.unnamed_endpoints).find(
       ([, endpoint]) =>
-        endpoint.parameters.length > 0 && endpoint.returns.length > 0,
+        endpoint.parameters.length > 0 && endpoint.returns.length > 0
     );
 
     if (validUnnamed) {
       return new EndpointWrapper(
         parsePath(`${configuredPath}/${validUnnamed[0]}`),
         validUnnamed[1],
         gradio,
-        workingDir,
+        workingDir
       );
     }
 
@@ -192,7 +192,7 @@ export class EndpointWrapper {
 
   async call(
     request: CallToolRequest,
-    server: Server,
+    server: Server
   ): Promise<CallToolResult> {
     const progressToken = request.params._meta?.progressToken as
       | string
@@ -207,7 +207,7 @@ export class EndpointWrapper {
     // Process each parameter, applying handle_file for file inputs
     for (const [key, value] of Object.entries(parameters)) {
       const param = endpointParams.find(
-        (p) => p.parameter_name === key || p.label === key,
+        (p) => p.parameter_name === key || p.label === key
       );
       if (param && isFileParameter(param) && typeof value === "string") {
         const file = await this.validatePath(value);
@@ -226,22 +226,22 @@ export class EndpointWrapper {
   async handleToolCall(
     parameters: Record<string, unknown>,
     progressToken: string | undefined,
-    server: Server,
+    server: Server
   ): Promise<CallToolResult> {
     const events = [];
     try {
       let result = null;
       const submission: AsyncIterable<GradioEvent> = this.client.submit(
         this.endpointPath.endpoint,
-        parameters,
+        parameters
       ) as AsyncIterable<GradioEvent>;
       const progressNotifier = createProgressNotifier(server);
       for await (const msg of submission) {
         if (config.debug) events.push(msg);
         if (msg.type === "data") {
           if (Array.isArray(msg.data)) {
             const hasContent = msg.data.some(
-              (item: unknown) => typeof item !== "object",
+              (item: unknown) => typeof item !== "object"
             );
 
             if (hasContent) result = msg.data;
@@ -262,7 +262,7 @@ export class EndpointWrapper {
       return await this.convertPredictResults(
         this.endpoint.returns,
         result,
-        this.endpointPath,
+        this.endpointPath
       );
     } catch (error) {
       const errorMessage =
@@ -274,7 +274,7 @@ export class EndpointWrapper {
           `${this.mcpToolName}_status_${crypto
             .randomUUID()
             .substring(0, 5)}.json`,
-          JSON.stringify(events, null, 2),
+          JSON.stringify(events, null, 2)
         );
       }
     }
@@ -283,7 +283,7 @@ export class EndpointWrapper {
   private async convertPredictResults(
     returns: ApiReturn[],
     predictResults: unknown[],
-    endpointPath: EndpointPath,
+    endpointPath: EndpointPath
   ): Promise<CallToolResult> {
     const content: (TextContent | ImageContent | EmbeddedResource)[] = [];
 
@@ -292,7 +292,7 @@ export class EndpointWrapper {
       const converted = await this.converter.convert(
         output,
         value as GradioResourceValue,
-        endpointPath,
+        endpointPath
       );
       content.push(converted);
     }
@@ -317,13 +317,13 @@ export class EndpointWrapper {
           name,
           description: prop?.description || name,
           required: schema.required?.includes(name) || false,
-        }),
+        })
       ),
     };
   }
 
   async getPromptTemplate(
-    args?: Record<string, string>,
+    args?: Record<string, string>
   ): Promise<GetPromptResult> {
     const schema = convertApiToSchema(this.endpoint);
     let promptText = `Using the ${this.mcpDescriptionName()}:\n\n`;

src/endpoint_wrapper.ts

@@ -2,7 +2,7 @@
 
 const AVAILABLE_RESOURCES = "Available Resources";
 const AVAILABLE_FILES = "available-files";
-
+const SEARCH_FOR_SPACE = "search-spaces";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { VERSION } from "./version.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -19,6 +19,7 @@ import {
 import { EndpointWrapper } from "./endpoint_wrapper.js";
 import { parseConfig } from "./config.js";
 import { WorkingDirectory } from "./working_directory.js";
+import { SemanticSearch } from "./semantic_search.js";
 
 // Create MCP server
 const server = new Server(
@@ -34,17 +35,18 @@ const server = new Server(
         list: true,
       },
     },
-  },
+  }
 );
 // Parse configuration
 const config = parseConfig();
+const semanticSearch = new SemanticSearch();
 
 // Change to configured working directory
 process.chdir(config.workDir);
 
 const workingDir = new WorkingDirectory(
   config.workDir,
-  config.claudeDesktopMode,
+  config.claudeDesktopMode
 );
 
 // Create a map to store endpoints by their tool names
@@ -55,7 +57,7 @@ for (const spacePath of config.spacePaths) {
   try {
     const endpoint = await EndpointWrapper.createEndpoint(
       spacePath,
-      workingDir,
+      workingDir
     );
     endpoints.set(endpoint.toolDefinition().name, endpoint);
   } catch (e) {
@@ -87,8 +89,26 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           properties: {},
         },
       },
+      {
+        name: SEARCH_FOR_SPACE,
+        description:
+          "Use semantic search to find an endpoint on the `Hugging Face Spaces` service. The search term will usually " +
+          "be 3-7 words describing a task or activity the Person is trying to accomplish. The results are returned in a markdown table. " +
+          "Present all results to the Person. Await specific guidance from the Person before making further Tool calls.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            query: {
+              type: "string",
+              // TODO description assumes  user is using claude desktop which has knowledge of HF Spaces.
+              // consider updating for not CLAUDE_DESKTOP mode. 3.7 sys prompt refers to Human as Person
+              description: "The semantic search term to use.",
+            },
+          },
+        },
+      },
       ...Array.from(endpoints.values()).map((endpoint) =>
-        endpoint.toolDefinition(),
+        endpoint.toolDefinition()
       ),
     ],
   };
@@ -110,6 +130,40 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     };
   }
 
+  if (SEARCH_FOR_SPACE === request.params.name) {
+    try {
+      const query = request.params.arguments?.query as string;
+      if (!query || typeof query !== "string") {
+        throw new Error("Search query must be a non-empty string");
+      }
+
+      const results = await semanticSearch.search(query);
+      const markdownTable = semanticSearch.formatSearchResults(results);
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: markdownTable,
+          },
+        ],
+      };
+    } catch (error) {
+      if (error instanceof Error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Search error: ${error.message}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+      throw error;
+    }
+  }
+
   const endpoint = endpoints.get(request.params.name);
 
   if (!endpoint) {
@@ -142,7 +196,7 @@ server.setRequestHandler(ListPromptsRequestSchema, async () => {
         arguments: [],
       },
       ...Array.from(endpoints.values()).map((endpoint) =>
-        endpoint.promptDefinition(),
+        endpoint.promptDefinition()
       ),
     ],
   };