feat: MCP resources support (#47)

Signed-off-by: John McBride <[email protected]>

Author: jpmcb

examples/servers/prompts/package-lock.json

@@ -0,0 +1,70 @@
+# Resources Example Server
+
+This example demonstrates how to use the Zuplo MCP SDK
+to create a server that exposes resources.
+
+## Running the Example
+
+```bash
+npm install
+npm run build
+npm start
+```
+
+## Testing
+
+### List available resources
+
+```bash
+curl -X POST http://localhost:3000/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "resources/list",
+    "params": {}
+  }'
+```
+
+### Read a specific resource
+
+```bash
+curl -X POST http://localhost:3000/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 2,
+    "method": "resources/read",
+    "params": {
+      "uri": "file:///example/document.txt"
+    }
+  }'
+```
+
+### List resource templates
+
+```bash
+curl -X POST http://localhost:3000/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 3,
+    "method": "resources/templates/list",
+    "params": {}
+  }'
+```
+
+### Read a resource using a template
+
+```bash
+curl -X POST http://localhost:3000/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 4,
+    "method": "resources/read",
+    "params": {
+      "uri": "file:///example/test.txt"
+    }
+  }'
+```

examples/servers/resources/README.md

@@ -0,0 +1,15 @@
+{
+  "name": "@zuplo/mcp example resources server",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "clean": "rm -rf ./dist/ && rm -rf ./node_modules/"
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.14.1",
+    "@zuplo/mcp": "file:../../../",
+    "hono": "^4.7.9"
+  }
+}

examples/servers/resources/package-lock.json

@@ -0,0 +1,152 @@
+import { serve } from "@hono/node-server";
+import { Hono } from "hono";
+import { MCPServer } from "@zuplo/mcp/server";
+import { HTTPStreamableTransport } from "@zuplo/mcp/transport/httpstreamable";
+import { ConsoleLogger } from "@zuplo/mcp/logger";
+import { ResourceMetadata, ResourceReader, URITemplate } from "@zuplo/mcp/resources";
+
+const app = new Hono();
+
+const logger = new ConsoleLogger();
+
+const server = new MCPServer({
+  name: "Resources Example Server",
+  version: "1.0.0",
+  logger,
+  capabilities: {
+    resources: {},
+  },
+});
+
+server.addResource(
+  "document",
+  "file:///example/document.txt",
+  {
+    title: "Example Document",
+    description: "A sample text document",
+    mimeType: "text/plain",
+    annotations: {
+      audience: ["user" as const, "assistant" as const],
+      priority: 0.8,
+    },
+  },
+  async (uri) => ({
+    contents: [
+      {
+        uri,
+        mimeType: "text/plain",
+        text: "This is a sample document.\n\nIt contains multiple lines of text that demonstrate how resources work in the MCP protocol.",
+      },
+    ],
+  })
+);
+
+server.addResource(
+  "data",
+  "file:///example/data.json",
+  {
+    title: "Sample Data",
+    description: "JSON data file with sample information",
+    mimeType: "application/json",
+    annotations: {
+      audience: ["assistant" as const],
+      priority: 0.5,
+    },
+  },
+  async (uri) => ({
+    contents: [
+      {
+        uri,
+        mimeType: "application/json",
+        text: JSON.stringify(
+          {
+            name: "Example Data",
+            items: [
+              { id: 1, value: "First item" },
+              { id: 2, value: "Second item" },
+              { id: 3, value: "Third item" },
+            ],
+            metadata: {
+              created: "2025-01-01",
+              version: "1.0",
+            },
+          },
+          null,
+          2
+        ),
+      },
+    ],
+  })
+);
+
+server.addResource(
+  "image",
+  "file:///example/image.png",
+  {
+    title: "Example Image",
+    description: "A sample PNG image",
+    mimeType: "image/png",
+  },
+  async (uri) => ({
+    contents: [
+      {
+        uri,
+        mimeType: "image/png",
+        blob: "aW1hZ2Vwbmc=",
+      },
+    ],
+  })
+);
+
+const uriTemp: URITemplate = { template: "file:///example/{filename}" };
+const resMetadata: ResourceMetadata = {
+  title: "📁 Example Files",
+  description: "Access any file in the example directory by name",
+  annotations: {
+    audience: ["user" as const],
+    priority: 0.6,
+  }
+};
+
+const resHandler: ResourceReader = async (uri) => {
+  const filename = uri.split("/").pop();
+  return {
+    contents: [
+      {
+        uri,
+        mimeType: "text/plain",
+        text: `This is a dynamically generated file: ${filename}`,
+      },
+    ],
+  };
+};
+
+server.addResource(
+  "files",
+  uriTemp,
+  resMetadata,
+  resHandler
+);
+
+const transport = new HTTPStreamableTransport({ logger });
+await transport.connect();
+server.withTransport(transport);
+
+app.post("/mcp", async (c) => {
+  try {
+    const request = c.req.raw;
+    return transport.handleRequest(request);
+  } catch (error) {
+    logger.error("Error handling MCP request:", error);
+    return new Response(JSON.stringify({ error: "Internal server error" }), {
+      status: 500,
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+});
+
+logger.info("Resources MCP server starting on port 3000");
+serve({
+  fetch: app.fetch,
+  port: 3000
+});

examples/servers/resources/package.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": [
+    "./src/**/*"
+  ],
+  "references": [
+    { "path": "../../../" }
+  ]
+}

examples/servers/resources/src/index.ts

@@ -8,8 +8,8 @@
     "test": "NODE_OPTIONS=\"$NODE_OPTIONS --experimental-vm-modules\" npx jest",
     "lint": "npx @biomejs/[email protected] check src/",
     "lint:fix": "npx @biomejs/[email protected] check src/ --fix && prettier format . --write",
-    "lint:fix-unsafe": "npx @biomejs/[email protected] check src/ --fix --unsafe",
-    "format": "npx @biomejs/[email protected] format src/ --write"
+    "lint:fix-unsafe": "npx @biomejs/[email protected] check src/ --fix --unsafe && prettier format . --write",
+    "format": "npx @biomejs/[email protected] format src/ --write && prettier format . --write"
   },
   "files": [
     "dist/**/**",
@@ -74,6 +74,10 @@
       "types": "./dist/prompts/index.d.ts",
       "import": "./dist/prompts/index.js"
     },
+    "./resources": {
+      "types": "./dist/resources/index.d.ts",
+      "import": "./dist/resources/index.js"
+    },
     "./openapi/types": {
       "types": "./dist/openapi/types.d.ts",
       "import": "./dist/openapi/types.js"

examples/servers/resources/tsconfig.json

@@ -21,6 +21,7 @@ export enum ErrorCode {
   // SDK error codes
   ConnectionClosed = -32000,
   RequestTimeout = -32001,
+  ResourceNotFound = -32002,
 
   // Standard JSON-RPC error codes
   ParseError = -32700,

package.json

@@ -0,0 +1,5 @@
+export type {
+  ResourceReader,
+  ResourceMetadata,
+  URITemplate,
+} from "./types.js";