@jalpp/mcp-adapter

Lightweight adapter utilities for registering tools and resources on an MCP 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

npm install @jalpp/mcp-adapter

Peer dependencies — install these in your project if not already present:

npm install @modelcontextprotocol/sdk zod axios

Adapters

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 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.

getToolAdapter(server, {
  name: "get-user",
  description: "Fetch a user by ID",
  endpoint: "https://api.example.com/users/:userId",
  inputSchema: {
    userId: z.string().describe("User ID"),
    expand: z.string().optional().describe("Optional fields to expand"),
  },
  auth: { type: "bearer", token: process.env.API_TOKEN! },
});
// Registers get-user tool which calls GET https://api.example.com/users/abc123?expand=profile

getToolAdapter

Registers a GET endpoint as an MCP tool. Remaining args (after path variable interpolation) are sent as query parameters.

import { getToolAdapter } from "@jalpp/mcp-adapter";
import z from "zod";

getToolAdapter(server, {
  name: "get-user",
  description: "Fetch a user by ID",
  endpoint: "https://api.example.com/users/:userId",
  inputSchema: {
    userId: z.string().describe("User ID"),
    expand: z.string().optional().describe("Comma-separated fields to expand"),
  },
  auth: { type: "bearer", token: process.env.API_TOKEN! },
});
// Registers get-user tool which calls GET https://api.example.com/users/abc123?expand=profile

postToolAdapter

Registers a POST endpoint as an MCP tool. Remaining args (after path variable interpolation) are sent as the JSON request body.

import { postToolAdapter } from "@jalpp/mcp-adapter";

postToolAdapter(server, {
  name: "create-post",
  description: "Create a new post for a user",
  endpoint: "https://api.example.com/users/:userId/posts",
  inputSchema: {
    userId: z.string().describe("User ID"),
    title: z.string().describe("Post title"),
    body: z.string().describe("Post body"),
  },
  auth: { type: "bearer", token: process.env.API_TOKEN! },
});
// Registers create-post tool which calls POST https://api.example.com/users/abc123/posts  { title, body }

putToolAdapter

Registers a PUT endpoint as an MCP tool. Remaining args are sent as the JSON request body.

import { putToolAdapter } from "@jalpp/mcp-adapter";

putToolAdapter(server, {
  name: "update-user",
  description: "Replace a user record",
  endpoint: "https://api.example.com/users/:userId",
  inputSchema: {
    userId: z.string(),
    name: z.string(),
    email: z.string(),
  },
  auth: { type: "bearer", token: process.env.API_TOKEN! },
});
// Registers update-user tool which calls PUT https://api.example.com/users/abc123  { name, email }

patchToolAdapter

Registers a PATCH endpoint as an MCP tool. Remaining args are sent as the JSON request body.

import { patchToolAdapter } from "@jalpp/mcp-adapter";

patchToolAdapter(server, {
  name: "update-post-title",
  description: "Partially update a post",
  endpoint: "https://api.example.com/posts/:postId",
  inputSchema: {
    postId: z.string(),
    title: z.string(),
  },
  auth: { type: "bearer", token: process.env.API_TOKEN! },
});
// Registers update-post-title tool which calls PATCH https://api.example.com/posts/xyz789  { title }

deleteToolAdapter

Registers a DELETE endpoint as an MCP tool. Remaining args (after path variable interpolation) are sent as query parameters.

import { deleteToolAdapter } from "@jalpp/mcp-adapter";

deleteToolAdapter(server, {
  name: "delete-post",
  description: "Delete a post by ID",
  endpoint: "https://api.example.com/posts/:postId",
  inputSchema: { postId: z.string() },
  auth: { type: "bearer", token: process.env.API_TOKEN! },
});
// 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 you prefer a single unified call style or need to pass the method dynamically.

import { httpToolAdapter } from "@jalpp/mcp-adapter";

httpToolAdapter(server, {
  name: "search-products",
  description: "Search the product catalogue",
  endpoint: "https://api.example.com/products/search",
  method: "POST",
  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 }

toolAdapter

Registers a tool with a fully custom typed callback. Use when you need data transformation, custom error handling, or logic that goes beyond a single HTTP call.

With input schema:

import { toolAdapter, toolContentAdapter } from "@jalpp/mcp-adapter";
import z from "zod";

toolAdapter(server, {
  name: "summarize-report",
  config: {
    description: "Fetch and summarize a sales report",
    inputSchema: {
      reportId: z.string().describe("Report ID"),
      format: z.enum(["short", "detailed"]).default("short"),
    },
  },
  cb: async ({ reportId, format }) => {
    const { data, error } = await reportService.get(reportId, format);
    return toolContentAdapter(data ?? {}, error);
  },
});

Without input schema:

toolAdapter(server, {
  name: "get-server-status",
  config: { description: "Returns current server status" },
  cb: async () => {
    const { data, error } = await statusService.get();
    return toolContentAdapter(data ?? {}, error);
  },
});

toolContentAdapter

Normalizes a service result into a CallToolResult text block. If error is defined it takes priority; otherwise data is serialized as pretty-printed JSON.

return toolContentAdapter(data ?? {}, error);

| Argument | Type | Description | |----------|------|-------------| | data | object | Successful result payload | | error | string \| undefined | Error message — takes priority over data |

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).

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.

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 tool adapters accept an optional auth field. Three strategies are supported:

Bearer token — Authorization: Bearer <token>:

auth: { type: "bearer", token: process.env.API_TOKEN! }

API key — custom header:

auth: { type: "apikey", header: "X-API-Key", key: process.env.API_KEY! }

Basic auth — Authorization: Basic <base64>:

auth: { type: "basic", username: "user", password: process.env.PASSWORD! }

Extra axios config

Pass any axios request config via axiosConfig:

getToolAdapter(server, {
  name: "get-data",
  description: "Fetch with custom timeout",
  endpoint: "https://api.example.com/data",
  axiosConfig: { timeout: 5000 },
});

API Reference

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.

Resource adapters

| Function | Registers | URI style | |----------|-----------|-----------| | staticResourceAdapter | fixed-URI resource | "scheme://path" | | dynamicResourceAdapter | templated resource | "scheme://{param}/path" |

Auth types

| Type | Interface | Fields | |------|-----------|--------| | Bearer | BearerAuth | token | | API Key | ApiKeyAuth | header, key | | Basic | BasicAuth | username, password |

Repository

github.com/jalpp/mcp-adapter

License

MIT