@jalpp/mcp-adapter 0.3.0 → 0.3.1

package/README.md

@@ -1,6 +1,6 @@
 # @jalpp/mcp-adapter
 
-Lightweight adapter utilities for registering tools on an [MCP](https://modelcontextprotocol.io) server with full TypeScript type safety. Supports manual tool registration and automatic HTTP endpoint-to-tool bridging with built-in auth, path variables, and method-specific adapters.
+Lightweight adapter utilities for registering tools and resources on an [MCP](https://modelcontextprotocol.io) server with full TypeScript type safety. Supports manual tool registration, automatic HTTP endpoint-to-tool bridging with built-in auth, path variables, method-specific adapters, and MCP resource registration.
 
 ## Installation
 
@@ -14,37 +14,48 @@ npm install @jalpp/mcp-adapter
 npm install @modelcontextprotocol/sdk zod axios
 ```
 
+---
+
 ## Adapters
 
-| Adapter | Method | Description |
-|---------|--------|-------------|
-| `toolAdapter` | any | Register a tool with a typed callback |
-| `toolContentAdapter` | — | Normalize a result into a `CallToolResult` |
-| `httpToolAdapter` | any | Register any HTTP endpoint as a tool |
-| `getToolAdapter` | GET | Register a GET endpoint — args → query params |
-| `postToolAdapter` | POST | Register a POST endpoint — args → request body |
-| `putToolAdapter` | PUT | Register a PUT endpoint — args → request body |
-| `patchToolAdapter` | PATCH | Register a PATCH endpoint — args → request body |
-| `deleteToolAdapter` | DELETE | Register a DELETE endpoint — args → query params |
+### Tool adapters
+
+| Adapter | Description |
+|---------|-------------|
+| `toolAdapter` | Registers a tool with a typed callback |
+| `toolContentAdapter` | Normalizes a result into a `CallToolResult` |
+| `httpToolAdapter` | Registers any HTTP endpoint as a tool |
+| `getToolAdapter` | Registers a GET endpoint as a tool — args → query params |
+| `postToolAdapter` | Registers a POST endpoint as a tool — args → request body |
+| `putToolAdapter` | Registers a PUT endpoint as a tool — args → request body |
+| `patchToolAdapter` | Registers a PATCH endpoint as a tool — args → request body |
+| `deleteToolAdapter` | Registers a DELETE endpoint as a tool — args → query params |
+
+### Resource adapters
+
+| Adapter | Description |
+|---------|-------------|
+| `staticResourceAdapter` | Registers a static MCP resource with a fixed URI |
+| `dynamicResourceAdapter` | Registers a dynamic MCP resource with a URI template |
 
 ---
 
 ## Path Variables
 
-All HTTP adapters support `:paramName` path variable syntax. Any input arg whose name matches a path variable is interpolated into the URL and removed from query params / request body.
+All HTTP tool adapters support `:paramName` path variable syntax. Any input arg whose name matches a path variable is interpolated into the URL and removed from query params / request body.
 
 ```ts
 getToolAdapter(server, {
-  name: "get-game-details",
-  description: "Fetch a game by ID",
-  endpoint: "https://api.example.com/games/:gameId",
+  name: "get-user",
+  description: "Fetch a user by ID",
+  endpoint: "https://api.example.com/users/:userId",
   inputSchema: {
-    gameId: z.string().describe("Game ID"),
+    userId: z.string().describe("User ID"),
     expand: z.string().optional().describe("Optional fields to expand"),
   },
   auth: { type: "bearer", token: process.env.API_TOKEN! },
 });
-// GET https://api.example.com/games/abc123?expand=moves
+// Registers get-user tool which calls GET https://api.example.com/users/abc123?expand=profile
 ```
 
 ---
@@ -67,7 +78,7 @@ getToolAdapter(server, {
   },
   auth: { type: "bearer", token: process.env.API_TOKEN! },
 });
-// → GET https://api.example.com/users/abc123?expand=profile
+// Registers get-user tool which calls GET https://api.example.com/users/abc123?expand=profile
 ```
 
 ---
@@ -90,7 +101,7 @@ postToolAdapter(server, {
   },
   auth: { type: "bearer", token: process.env.API_TOKEN! },
 });
-// → POST https://api.example.com/users/abc123/posts  { title, body }
+// Registers create-post tool which calls POST https://api.example.com/users/abc123/posts  { title, body }
 ```
 
 ---
@@ -100,6 +111,8 @@ postToolAdapter(server, {
 Registers a PUT endpoint as an MCP tool. Remaining args are sent as the **JSON request body**.
 
 ```ts
+import { putToolAdapter } from "@jalpp/mcp-adapter";
+
 putToolAdapter(server, {
   name: "update-user",
   description: "Replace a user record",
@@ -111,7 +124,7 @@ putToolAdapter(server, {
   },
   auth: { type: "bearer", token: process.env.API_TOKEN! },
 });
-// → PUT https://api.example.com/users/abc123  { name, email }
+// Registers update-user tool which calls PUT https://api.example.com/users/abc123  { name, email }
 ```
 
 ---
@@ -121,6 +134,8 @@ putToolAdapter(server, {
 Registers a PATCH endpoint as an MCP tool. Remaining args are sent as the **JSON request body**.
 
 ```ts
+import { patchToolAdapter } from "@jalpp/mcp-adapter";
+
 patchToolAdapter(server, {
   name: "update-post-title",
   description: "Partially update a post",
@@ -131,7 +146,7 @@ patchToolAdapter(server, {
   },
   auth: { type: "bearer", token: process.env.API_TOKEN! },
 });
-// → PATCH https://api.example.com/posts/xyz789  { title }
+// Registers update-post-title tool which calls PATCH https://api.example.com/posts/xyz789  { title }
 ```
 
 ---
@@ -141,6 +156,8 @@ patchToolAdapter(server, {
 Registers a DELETE endpoint as an MCP tool. Remaining args (after path variable interpolation) are sent as **query parameters**.
 
 ```ts
+import { deleteToolAdapter } from "@jalpp/mcp-adapter";
+
 deleteToolAdapter(server, {
   name: "delete-post",
   description: "Delete a post by ID",
@@ -148,26 +165,27 @@ deleteToolAdapter(server, {
   inputSchema: { postId: z.string() },
   auth: { type: "bearer", token: process.env.API_TOKEN! },
 });
-// → DELETE https://api.example.com/posts/xyz789
+// Registers delete-post tool which calls DELETE https://api.example.com/posts/xyz789
 ```
 
 ---
 
 ## `httpToolAdapter`
 
-Lower-level adapter that accepts an explicit `method` field. Use this when the method needs to be dynamic or you prefer a single unified call style.
+Lower-level adapter that accepts an explicit `method` field. Use this when you prefer a single unified call style or need to pass the method dynamically.
 
 ```ts
 import { httpToolAdapter } from "@jalpp/mcp-adapter";
 
 httpToolAdapter(server, {
-  name: "get-analysis",
-  description: "Fetch position analysis",
-  endpoint: "https://api.example.com/analyze",
+  name: "search-products",
+  description: "Search the product catalogue",
+  endpoint: "https://api.example.com/products/search",
   method: "POST",
-  inputSchema: { fen: z.string(), depth: z.number() },
-  auth: { type: "bearer", token: process.env.API_TOKEN! },
+  inputSchema: { query: z.string(), limit: z.number().optional() },
+  auth: { type: "apikey", header: "X-API-Key", key: process.env.API_KEY! },
 });
+// Registers search-products tool which calls POST https://api.example.com/products/search  { query, limit }
 ```
 
 ---
@@ -180,19 +198,19 @@ Registers a tool with a fully custom typed callback. Use when you need data tran
 
 ```ts
 import { toolAdapter, toolContentAdapter } from "@jalpp/mcp-adapter";
+import z from "zod";
 
 toolAdapter(server, {
-  name: "get-analysis",
+  name: "summarize-report",
   config: {
-    description: "Analyze a chess position",
+    description: "Fetch and summarize a sales report",
     inputSchema: {
-      fen: z.string().describe("FEN string"),
-      depth: z.number().min(1).max(20),
+      reportId: z.string().describe("Report ID"),
+      format: z.enum(["short", "detailed"]).default("short"),
     },
-    annotations: { openWorldHint: true },
   },
-  cb: async ({ fen, depth }) => {
-    const { data, error } = await myService.analyze(fen, depth);
+  cb: async ({ reportId, format }) => {
+    const { data, error } = await reportService.get(reportId, format);
     return toolContentAdapter(data ?? {}, error);
   },
 });
@@ -202,10 +220,10 @@ toolAdapter(server, {
 
 ```ts
 toolAdapter(server, {
-  name: "get-status",
+  name: "get-server-status",
   config: { description: "Returns current server status" },
   cb: async () => {
-    const { data, error } = await myService.getStatus();
+    const { data, error } = await statusService.get();
     return toolContentAdapter(data ?? {}, error);
   },
 });
@@ -215,7 +233,7 @@ toolAdapter(server, {
 
 ## `toolContentAdapter`
 
-Normalizes a result into a `CallToolResult` text block. If `error` is defined it takes priority; otherwise `data` is serialized as pretty-printed JSON.
+Normalizes a service result into a `CallToolResult` text block. If `error` is defined it takes priority; otherwise `data` is serialized as pretty-printed JSON.
 
 ```ts
 return toolContentAdapter(data ?? {}, error);
@@ -228,9 +246,79 @@ return toolContentAdapter(data ?? {}, error);
 
 ---
 
+## `staticResourceAdapter`
+
+Registers a static MCP resource with a fixed URI. The `load` callback is called on every client request and may return fresh content each time. Use this for resources whose identity is fixed but content may change (e.g. a config file, a status page, a knowledge base).
+
+```ts
+import { staticResourceAdapter } from "@jalpp/mcp-adapter";
+
+// Expose a live system health report
+staticResourceAdapter(server, {
+  name: "system-health",
+  uri: "status://health",
+  title: "System Health",
+  description: "Live health status of all services",
+  mimeType: "application/json",
+  load: async () => JSON.stringify(await healthService.getReport()),
+});
+
+// Expose a markdown documentation page
+staticResourceAdapter(server, {
+  name: "api-docs",
+  uri: "docs://api",
+  title: "API Documentation",
+  description: "REST API reference documentation",
+  mimeType: "text/markdown",
+  load: () => fs.readFileSync("./docs/api.md", "utf-8"),
+});
+```
+
+---
+
+## `dynamicResourceAdapter`
+
+Registers a dynamic MCP resource with a URI template. Use `{paramName}` placeholders — matched values are extracted and passed to the `load` callback. Use this for resources identified by an ID or other variable.
+
+```ts
+import { dynamicResourceAdapter } from "@jalpp/mcp-adapter";
+
+// Expose a user profile by ID
+dynamicResourceAdapter(server, {
+  name: "user-profile",
+  uriTemplate: "users://{userId}/profile",
+  title: "User Profile",
+  description: "Profile data for a specific user",
+  mimeType: "application/json",
+  load: async (uri, { userId }) => JSON.stringify(await userService.getProfile(userId)),
+});
+
+// Expose an order invoice by order ID
+dynamicResourceAdapter(server, {
+  name: "order-invoice",
+  uriTemplate: "orders://{orderId}/invoice",
+  title: "Order Invoice",
+  description: "Invoice details for a specific order",
+  mimeType: "application/json",
+  load: async (uri, { orderId }) => JSON.stringify(await orderService.getInvoice(orderId)),
+});
+
+// Expose a blog post by slug
+dynamicResourceAdapter(server, {
+  name: "blog-post",
+  uriTemplate: "blog://{slug}",
+  title: "Blog Post",
+  description: "Markdown content for a blog post",
+  mimeType: "text/markdown",
+  load: async (uri, { slug }) => await blogService.getPostMarkdown(slug),
+});
+```
+
+---
+
 ## Authentication
 
-All HTTP adapters accept an optional `auth` field. Three strategies are supported:
+All HTTP tool adapters accept an optional `auth` field. Three strategies are supported:
 
 **Bearer token** — `Authorization: Bearer <token>`:
 ```ts
@@ -266,17 +354,26 @@ getToolAdapter(server, {
 
 ## API Reference
 
-### Method-specific adapters
+### Tool adapters
+
+| Function | Registers | Args mapping |
+|----------|-----------|--------------|
+| `getToolAdapter` | GET tool | remaining args → query params |
+| `postToolAdapter` | POST tool | remaining args → request body |
+| `putToolAdapter` | PUT tool | remaining args → request body |
+| `patchToolAdapter` | PATCH tool | remaining args → request body |
+| `deleteToolAdapter` | DELETE tool | remaining args → query params |
+| `httpToolAdapter` | any method tool | depends on method |
+| `toolAdapter` | custom callback tool | fully custom |
+
+All HTTP adapters support optional `inputSchema` and `:paramName` path variables.
 
-| Function | Method | Args mapping |
-|----------|--------|--------------|
-| `getToolAdapter` | GET | remaining args → query params |
-| `postToolAdapter` | POST | remaining args → request body |
-| `putToolAdapter` | PUT | remaining args → request body |
-| `patchToolAdapter` | PATCH | remaining args → request body |
-| `deleteToolAdapter` | DELETE | remaining args → query params |
+### Resource adapters
 
-All support optional `inputSchema` and `:paramName` path variables.
+| Function | Registers | URI style |
+|----------|-----------|-----------|
+| `staticResourceAdapter` | fixed-URI resource | `"scheme://path"` |
+| `dynamicResourceAdapter` | templated resource | `"scheme://{param}/path"` |
 
 ### Auth types
 

package/dist/index.d.ts

@@ -332,4 +332,173 @@ declare function patchToolAdapter<T extends ZodRawShapeCompat>(server: McpServer
  */
 declare function deleteToolAdapter<T extends ZodRawShapeCompat>(server: McpServer, config: DeleteToolAdapterConfig<T>): void;
 
-export { type ApiKeyAuth, type BasicAuth, type BearerAuth, type DeleteToolAdapterConfig, type GetToolAdapterConfig, type GetToolAdapterConfigNoSchema, type HttpAuth, type HttpMethod, type HttpToolAdapterWithSchema, type HttpToolAdapterWithoutSchema, type PatchToolAdapterConfig, type PostToolAdapterConfig, type PostToolAdapterConfigNoSchema, type PutToolAdapterConfig, deleteToolAdapter, getToolAdapter, httpToolAdapter, patchToolAdapter, postToolAdapter, putToolAdapter, toolAdapter, toolContentAdapter };
+/**
+ * Supported MIME types for resource content.
+ * Extend with additional types as needed.
+ */
+type ResourceMimeType = "text/plain" | "text/html" | "text/markdown" | "application/json" | "application/xml" | (string & {});
+/**
+ * Configuration for registering a static MCP resource.
+ *
+ * A static resource has a fixed URI with no variable parameters.
+ * Use this for resources whose content may change but whose identity does not
+ * (e.g. a config file, a status page, a knowledge base).
+ *
+ * @example
+ * staticResourceAdapter(server, {
+ *   name: "server-config",
+ *   uri: "config://server",
+ *   title: "Server Configuration",
+ *   description: "Current server configuration and environment settings",
+ *   mimeType: "application/json",
+ *   load: async () => JSON.stringify(await configService.get()),
+ * });
+ */
+interface StaticResourceConfig {
+    /** Unique resource name used to identify the resource in the MCP registry. */
+    name: string;
+    /**
+     * The fixed URI that clients use to request this resource.
+     * @example "config://server"
+     * @example "docs://readme"
+     */
+    uri: string;
+    /** Human-readable display title shown in client UIs. */
+    title: string;
+    /** Description of what the resource contains, shown to the model. */
+    description: string;
+    /** MIME type of the resource content. Defaults to `"text/plain"`. */
+    mimeType?: ResourceMimeType;
+    /**
+     * Async function that returns the resource content as a string.
+     * Called each time a client requests the resource.
+     *
+     * @returns The resource content string.
+     *
+     * @example
+     * load: async () => JSON.stringify(await configService.get())
+     */
+    load: () => Promise<string> | string;
+}
+/**
+ * Configuration for registering a dynamic MCP resource with URI template parameters.
+ *
+ * A dynamic resource uses a URI template with `{paramName}` placeholders.
+ * The matched parameter values are passed to the `load` callback.
+ * Use this for resources identified by an ID or other variable (e.g. a user profile, an order record).
+ *
+ * @example
+ * dynamicResourceAdapter(server, {
+ *   name: "user-profile",
+ *   uriTemplate: "users://{userId}/profile",
+ *   title: "User Profile",
+ *   description: "Profile data for a given user",
+ *   mimeType: "application/json",
+ *   load: async (uri, { userId }) => JSON.stringify(await userService.getProfile(userId)),
+ * });
+ */
+interface DynamicResourceConfig {
+    /** Unique resource name used to identify the resource in the MCP registry. */
+    name: string;
+    /**
+     * URI template string with `{paramName}` placeholders.
+     * @example "users://{userId}/profile"
+     * @example "orders://{orderId}/invoice"
+     */
+    uriTemplate: string;
+    /** human-readable display title shown in client UIs. */
+    title: string;
+    /** Description of what the resource contains, shown to the model. */
+    description: string;
+    /** MIME type of the resource content. Defaults to `"text/plain"`. */
+    mimeType?: ResourceMimeType;
+    /**
+     * Async function that returns the resource content as a string.
+     * Called each time a client requests the resource with a matching URI.
+     *
+     * @param uri    - The full resolved URI of the request (as a `URL` object).
+     * @param params - Key-value map of extracted URI template parameters.
+     * @returns The resource content string.
+     *
+     * @example
+     * load: async (uri, { orderId }) => JSON.stringify(await orderService.getInvoice(orderId))
+     */
+    load: (uri: URL, params: Record<string, string>) => Promise<string> | string;
+}
+/**
+ * Registers a static MCP resource on an `McpServer`.
+ *
+ * Static resources have a fixed URI. The `load` callback is invoked on every
+ * client request and may return fresh data each time.
+ *
+ * @param server - The `McpServer` instance to register the resource on.
+ * @param config - Static resource configuration.
+ *
+ * @example
+ * // Expose a live system health report
+ * staticResourceAdapter(server, {
+ *   name: "system-health",
+ *   uri: "status://health",
+ *   title: "System Health",
+ *   description: "Live health status of all services",
+ *   mimeType: "application/json",
+ *   load: async () => JSON.stringify(await healthService.getReport()),
+ * });
+ *
+ * @example
+ * // Expose a static markdown documentation page
+ * staticResourceAdapter(server, {
+ *   name: "api-docs",
+ *   uri: "docs://api",
+ *   title: "API Documentation",
+ *   description: "REST API reference documentation",
+ *   mimeType: "text/markdown",
+ *   load: () => fs.readFileSync("./docs/api.md", "utf-8"),
+ * });
+ */
+declare function staticResourceAdapter(server: McpServer, config: StaticResourceConfig): void;
+/**
+ * Registers a dynamic MCP resource with a URI template on an `McpServer`.
+ *
+ * Dynamic resources use `{paramName}` placeholders in the URI template.
+ * Matched parameter values are extracted and passed to the `load` callback.
+ *
+ * @param server - The `McpServer` instance to register the resource on.
+ * @param config - Dynamic resource configuration.
+ *
+ * @example
+ * // Expose a user profile by ID
+ * dynamicResourceAdapter(server, {
+ *   name: "user-profile",
+ *   uriTemplate: "users://{userId}/profile",
+ *   title: "User Profile",
+ *   description: "Profile data for a specific user",
+ *   mimeType: "application/json",
+ *   load: async (uri, { userId }) => JSON.stringify(await userService.getProfile(userId)),
+ * });
+ *
+ * @example
+ * // Expose an order invoice by order ID
+ * dynamicResourceAdapter(server, {
+ *   name: "order-invoice",
+ *   uriTemplate: "orders://{orderId}/invoice",
+ *   title: "Order Invoice",
+ *   description: "Invoice details for a specific order",
+ *   mimeType: "application/json",
+ *   load: async (uri, { orderId }) => JSON.stringify(await orderService.getInvoice(orderId)),
+ * });
+ *
+ * @example
+ * // Expose a blog post by slug
+ * dynamicResourceAdapter(server, {
+ *   name: "blog-post",
+ *   uriTemplate: "blog://{slug}",
+ *   title: "Blog Post",
+ *   description: "Markdown content for a blog post",
+ *   mimeType: "text/markdown",
+ *   load: async (uri, { slug }) => await blogService.getPostMarkdown(slug),
+ * });
+ */
+declare function dynamicResourceAdapter(server: McpServer, config: DynamicResourceConfig): void;
+
+export { type ApiKeyAuth, type BasicAuth, type BearerAuth, type DeleteToolAdapterConfig, type DynamicResourceConfig, type GetToolAdapterConfig, type GetToolAdapterConfigNoSchema, type HttpAuth, type HttpMethod, type HttpToolAdapterWithSchema, type HttpToolAdapterWithoutSchema, type PatchToolAdapterConfig, type PostToolAdapterConfig, type PostToolAdapterConfigNoSchema, type PutToolAdapterConfig, type ResourceMimeType, type StaticResourceConfig, deleteToolAdapter, dynamicResourceAdapter, getToolAdapter, httpToolAdapter, patchToolAdapter, postToolAdapter, putToolAdapter, staticResourceAdapter, toolAdapter, toolContentAdapter };

package/dist/index.js

@@ -121,13 +121,58 @@ function patchToolAdapter(server, config) {
 function deleteToolAdapter(server, config) {
   httpToolAdapter(server, { ...config, method: "DELETE" });
 }
+
+// src/resourceAdapter.ts
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+function staticResourceAdapter(server, config) {
+  server.registerResource(
+    config.name,
+    config.uri,
+    {
+      title: config.title,
+      description: config.description,
+      mimeType: config.mimeType ?? "text/plain"
+    },
+    async (uri) => ({
+      contents: [
+        {
+          uri: uri.href,
+          text: await config.load(),
+          mimeType: config.mimeType ?? "text/plain"
+        }
+      ]
+    })
+  );
+}
+function dynamicResourceAdapter(server, config) {
+  server.registerResource(
+    config.name,
+    new ResourceTemplate(config.uriTemplate, { list: void 0 }),
+    {
+      title: config.title,
+      description: config.description,
+      mimeType: config.mimeType ?? "text/plain"
+    },
+    async (uri, params) => ({
+      contents: [
+        {
+          uri: uri.href,
+          text: await config.load(uri, params),
+          mimeType: config.mimeType ?? "text/plain"
+        }
+      ]
+    })
+  );
+}
 export {
   deleteToolAdapter,
+  dynamicResourceAdapter,
   getToolAdapter,
   httpToolAdapter,
   patchToolAdapter,
   postToolAdapter,
   putToolAdapter,
+  staticResourceAdapter,
   toolAdapter,
   toolContentAdapter
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jalpp/mcp-adapter",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Adapter utilities for registering MCP tools with full TypeScript type safety — supports typed callbacks and automatic HTTP endpoint bridging with auth",
   "author": "jalpp",
   "license": "MIT",
@@ -44,17 +44,17 @@
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": ">=1.0.0",
-    "zod": ">=3.0.0",
-    "axios": ">=1.0.0"
+    "axios": ">=1.0.0",
+    "zod": ">=3.0.0"
   },
   "devDependencies": {
     "@modelcontextprotocol/sdk": ">=1.0.0",
-    "@types/node": "^20.0.0",
+    "@types/node": "^25.4.0",
     "tsup": "^8.0.0",
     "typescript": "^5.0.0",
     "zod": ">=3.0.0"
   },
   "dependencies": {
-    "axios": "^1.13.6"
+    "axios": ">=1.0.0"
   }
 }