Add a composite tools demo vMCP with arXiv (#31)

Signed-off-by: Dan Barr <[email protected]>
Co-authored-by: Dan Barr <[email protected]>

Author: danbarr

README.md

@@ -8,9 +8,10 @@ The goal is a fully functional ToolHive platform running locally to exercise all
 
 So far, it includes:
 
-- A ToolHive Registry Server with a few servers filtered from the main ToolHive registry and with auto-discovery enabled
+- A ToolHive Registry Server with a few servers filtered from the official and ToolHive registries plus K8s discovery
 - The ToolHive Cloud UI connected to the registry server with a mock OIDC provider for authentication
 - A Virtual MCP Server running a few basic MCP servers: fetch, osv, oci-registry, and context7
+- A vMCP server with a composite tool chaining together multiple arXiv tools
 - The MKP MCP server for managing the cluster, exposed directly
 - An MCP Optimizer server for intelligent tool calling across multiple MCP servers
 - Traefik as the gateway for routing traffic into the cluster
@@ -101,6 +102,7 @@ Bootstrap complete! Access your demo services at the following URLs:
    (run 'thv config set-registry http://registry-172-19-0-3.traefik.me/registry --allow-private-ip' to configure ToolHive to use it)
  - MKP MCP server at http://mcp-172-19-0-3.traefik.me/mkp/mcp
  - vMCP demo server at http://mcp-172-19-0-3.traefik.me/vmcp-demo/mcp
+ - vMCP composite tool demo server at http://mcp-172-19-0-3.traefik.me/vmcp-research/mcp
  - MCP Optimizer at http://mcp-172-19-0-3.traefik.me/mcp-optimizer/mcp
  - Grafana at http://grafana-172-19-0-3.traefik.me
 ```

bootstrap.sh

@@ -175,6 +175,7 @@ run_quiet kubectl apply -f demo-manifests/vmcp-mcpservers.yaml || die "Failed to
 # Wait for vMCP backend MCPServer resources to reach Running phase
 run_quiet kubectl wait --for=jsonpath='{.status.phase}'=Running --timeout=300s mcpserver -l demo.toolhive.stacklok.dev/vmcp-backend=true -n toolhive-system || die "vMCP backend MCPServer resources failed to become ready"
 run_quiet sh -c "envsubst < demo-manifests/vmcp-demo-simple.yaml | kubectl apply -f -" || die "Failed to apply vMCP demo"
+run_quiet sh -c "envsubst < demo-manifests/vmcp-demo-composite.yaml | kubectl apply -f -" || die "Failed to apply vMCP composite tools demo"
 # run_quiet sh -c "envsubst < demo-manifests/vmcp-demo-auth.yaml | kubectl apply -f -" || die "Failed to apply vMCP demo with auth"
 echo " ✓"
 
@@ -225,6 +226,13 @@ cat > demo-endpoints.json <<EOF
       "test_with_thv": true,
       "healthcheck_path": "/vmcp-demo/health"
     },
+    {
+      "name": "vMCP Composite Tool Demo Server",
+      "url": "http://$MCP_HOSTNAME/vmcp-research/mcp",
+      "type": "mcp",
+      "test_with_thv": true,
+      "healthcheck_path": "/vmcp-research/health"
+    },
     {
       "name": "MCP Optimizer",
       "url": "http://$MCP_HOSTNAME/mcp-optimizer/mcp",
@@ -249,5 +257,6 @@ echo " - ToolHive Registry Server at http://$REGISTRY_HOSTNAME/registry"
 echo "   (run 'thv config set-registry http://$REGISTRY_HOSTNAME/registry --allow-private-ip' to configure ToolHive to use it)"
 echo " - MKP MCP server at http://$MCP_HOSTNAME/mkp/mcp"
 echo " - vMCP demo server at http://$MCP_HOSTNAME/vmcp-demo/mcp"
+echo " - vMCP composite tool demo server at http://$MCP_HOSTNAME/vmcp-research/mcp"
 echo " - MCP Optimizer at http://$MCP_HOSTNAME/mcp-optimizer/mcp"
 echo " - Grafana at http://$GRAFANA_HOSTNAME"

demo-manifests/vmcp-demo-composite.yaml

@@ -0,0 +1,89 @@
+apiVersion: toolhive.stacklok.dev/v1alpha1
+kind: VirtualMCPServer
+metadata:
+  name: vmcp-research
+  namespace: toolhive-system
+  annotations:
+    toolhive.stacklok.dev/registry-export: "true"
+    toolhive.stacklok.dev/registry-url: "http://$MCP_HOSTNAME/vmcp-research/mcp"
+    toolhive.stacklok.dev/registry-description: |
+      A vMCP server demonstrating a research workflow with a composite tool.
+spec:
+  config:
+    groupRef: research-tools
+    telemetry:
+      endpoint: mcp-collector.observability:4318
+      insecure: true
+      serviceName: vmcp-research-server
+      serviceVersion: "1.0.0"
+      metricsEnabled: true
+      tracingEnabled: true
+      samplingRate: "1.0"
+    aggregation:
+      conflictResolution: prefix
+      conflictResolutionConfig:
+        prefixFormat: "{workload}_"
+      tools:
+        - workload: arxiv
+          filter:
+            - "list_papers"
+    compositeTools:
+      - name: research_topic
+        description: Search arXiv for papers and read the top result
+        parameters:
+          type: object
+          properties:
+            query:
+              type: string
+              description: Research topic to search for
+          required:
+            - query
+        steps:
+          # Step 1: Search arXiv for papers matching the query
+          - id: search
+            tool: arxiv_search_papers
+            arguments:
+              query: "{{.params.query}}"
+              max_results: 1
+          # Step 2: Download the paper (required before reading)
+          # Note: fromJson is needed when the MCP server returns JSON as text
+          # rather than structured content. This is common for servers that
+          # don't fully support MCP's structuredContent field.
+          - id: download
+            tool: arxiv_download_paper
+            arguments:
+              paper_id: "{{(index (fromJson .steps.search.output.text).papers 0).id}}"
+            dependsOn: [search]
+          # Step 3: Read the downloaded paper content
+          - id: read
+            tool: arxiv_read_paper
+            arguments:
+              paper_id: "{{(index (fromJson .steps.search.output.text).papers 0).id}}"
+            dependsOn: [download]
+  incomingAuth:
+    type: anonymous
+  serviceType: ClusterIP
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+  name: vmcp-research-route
+  namespace: toolhive-system
+spec:
+  parentRefs:
+    - name: traefik-gateway
+      namespace: traefik
+  rules:
+    - matches:
+        - path:
+            type: PathPrefix
+            value: /vmcp-research
+      filters:
+        - type: URLRewrite
+          urlRewrite:
+            path:
+              type: ReplacePrefixMatch
+              replacePrefixMatch: /
+      backendRefs:
+        - name: vmcp-vmcp-research
+          port: 4483

demo-manifests/vmcp-mcpservers.yaml

@@ -61,3 +61,38 @@ spec:
   transport: stdio
   proxyPort: 8080
   proxyMode: streamable-http
+---
+apiVersion: toolhive.stacklok.dev/v1alpha1
+kind: MCPGroup
+metadata:
+  name: research-tools
+  namespace: toolhive-system
+spec:
+  description: Group for vMCP research workflow tools
+---
+apiVersion: toolhive.stacklok.dev/v1alpha1
+kind: MCPServer
+metadata:
+  name: arxiv
+  namespace: toolhive-system
+  labels:
+    demo.toolhive.stacklok.dev/vmcp-backend: "true"
+spec:
+  image: ghcr.io/stacklok/dockyard/uvx/arxiv-mcp-server:0.3.2
+  groupRef: research-tools
+  transport: stdio
+  proxyPort: 8080
+  proxyMode: streamable-http
+  args:
+    - --storage-path
+    - /arxiv-papers
+  podTemplateSpec:
+    spec:
+      volumes:
+        - name: arxiv-papers
+          emptyDir: {}
+      containers:
+        - name: mcp
+          volumeMounts:
+            - name: arxiv-papers
+              mountPath: /arxiv-papers