@jalpp/mcp-adapter 0.1.2 → 0.2.0

package/README.md

@@ -1,25 +1,37 @@
-# mcp-adapter
+# @jalpp/mcp-adapter
 
-Lightweight adapter utilities for registering tools on an [MCP](https://modelcontextprotocol.io) server with full TypeScript type safety.
+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.
 
 ## Installation
 
 ```bash
-npm install mcp-adapter
+npm install @jalpp/mcp-adapter
 ```
 
-> **Peer dependency:** `@modelcontextprotocol/sdk >= 1.0.0` must be installed in your project.
+**Peer dependencies** — install these in your project if not already present:
 
-## Usage
+```bash
+npm install @modelcontextprotocol/sdk zod axios
+```
+
+## Adapters
+
+| Adapter | Description |
+|---------|-------------|
+| `toolAdapter` | Register a tool with a typed callback |
+| `toolContentAdapter` | Normalize a result into a `CallToolResult` |
+| `httpToolAdapter` | Register an HTTP endpoint directly as a tool |
 
-### `toolAdapter`
+---
+
+## `toolAdapter`
 
 Registers a typed tool on an `McpServer`. Input schema types flow through to the callback automatically — no manual type annotations needed.
 
 **With input schema:**
 
 ```ts
-import { toolAdapter, toolContentAdapter } from "mcp-adapter";
+import { toolAdapter, toolContentAdapter } from "@jalpp/mcp-adapter";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import z from "zod";
 
@@ -57,12 +69,14 @@ toolAdapter(server, {
 });
 ```
 
-### `toolContentAdapter`
+---
+
+## `toolContentAdapter`
 
-Normalizes a service result into a `CallToolResult`. If `error` is defined it takes priority; otherwise `data` is pretty-printed as 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
-import { toolContentAdapter } from "mcp-adapter";
+import { toolContentAdapter } from "@jalpp/mcp-adapter";
 
 return toolContentAdapter(data ?? {}, error);
 ```
@@ -70,21 +84,136 @@ return toolContentAdapter(data ?? {}, error);
 | Argument | Type | Description |
 |----------|------|-------------|
 | `data` | `object` | Successful result payload |
-| `error` | `string \| undefined` | Error message — takes priority over `data` |
+| `error` | `string \| undefined` | Error message — takes priority over `data` when present |
+
+---
+
+## `httpToolAdapter`
+
+Registers an HTTP endpoint directly as an MCP tool. Handles the full request lifecycle — auth headers, query params vs request body, and error mapping — so you only need to declare the tool metadata and schema.
+
+- **GET** requests map input args to **query parameters**
+- **POST / PUT / PATCH / DELETE** map input args to the **JSON request body**
+
+**With input schema:**
+
+```ts
+import { httpToolAdapter } from "@jalpp/mcp-adapter";
+import z from "zod";
+
+httpToolAdapter(server, {
+  name: "get-analysis",
+  description: "Fetch position analysis from external API",
+  endpoint: "https://api.example.com/analyze",
+  method: "POST",
+  inputSchema: {
+    fen: z.string().describe("FEN string"),
+    depth: z.number().min(1).max(20),
+  },
+  auth: {
+    type: "bearer",
+    token: process.env.API_TOKEN!,
+  },
+});
+```
+
+**Without input schema:**
+
+```ts
+httpToolAdapter(server, {
+  name: "get-server-status",
+  description: "Fetch API health status",
+  endpoint: "https://api.example.com/status",
+  method: "GET",
+});
+```
+
+### Authentication
+
+Three auth strategies are supported, all passed via the `auth` field:
 
-## API
+**Bearer token** — sends `Authorization: Bearer <token>`:
+
+```ts
+auth: {
+  type: "bearer",
+  token: process.env.API_TOKEN!,
+}
+```
+
+**API key** — sends the key in a custom header:
+
+```ts
+auth: {
+  type: "apikey",
+  header: "X-API-Key",
+  key: process.env.API_KEY!,
+}
+```
+
+**Basic auth** — sends `Authorization: Basic <base64(username:password)>`:
+
+```ts
+auth: {
+  type: "basic",
+  username: "myuser",
+  password: process.env.PASSWORD!,
+}
+```
+
+### Extra axios config
+
+Pass any additional [axios request config](https://axios-http.com/docs/req_config) via `axiosConfig`:
+
+```ts
+httpToolAdapter(server, {
+  name: "get-data",
+  description: "Fetch with custom timeout",
+  endpoint: "https://api.example.com/data",
+  method: "GET",
+  axiosConfig: {
+    timeout: 5000,
+    headers: { "Accept-Language": "en" },
+  },
+});
+```
+
+---
+
+## API Reference
 
 ### `toolAdapter(server, adapter)`
 
-| Overload | Description |
+| Overload | When to use |
 |----------|-------------|
-| `toolAdapter<T>(server, ToolInputAdapterWithSchema<T>)` | Tool with typed input schema |
-| `toolAdapter(server, ToolInputAdapterWithoutSchema)` | Tool with no input arguments |
+| `toolAdapter<T>(server, ToolInputAdapterWithSchema<T>)` | Tool that receives typed input args |
+| `toolAdapter(server, ToolInputAdapterWithoutSchema)` | Tool that takes no input |
 
 ### `toolContentAdapter(data, error)`
 
 Returns a `CallToolResult` with a single `text` content block.
 
+### `httpToolAdapter(server, adapter)`
+
+| Overload | When to use |
+|----------|-------------|
+| `httpToolAdapter<T>(server, HttpToolAdapterWithSchema<T>)` | Endpoint that receives typed input args |
+| `httpToolAdapter(server, HttpToolAdapterWithoutSchema)` | Endpoint that takes no input |
+
+### Auth types
+
+| Type | Interface | Fields |
+|------|-----------|--------|
+| Bearer | `BearerAuth` | `token` |
+| API Key | `ApiKeyAuth` | `header`, `key` |
+| Basic | `BasicAuth` | `username`, `password` |
+
+---
+
+## Repository
+
+[github.com/jalpp/mcp-adapter](https://github.com/jalpp/mcp-adapter)
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { McpServer, ToolCallback } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { ZodRawShapeCompat } from '@modelcontextprotocol/sdk/server/zod-compat.js';
 import { ToolAnnotations, CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { AxiosRequestConfig } from 'axios';
 
 /**
  * Adapter input for registering a tool that declares an input schema.
@@ -92,4 +93,116 @@ declare function toolAdapter<T extends ZodRawShapeCompat>(server: McpServer, too
  */
 declare function toolAdapter(server: McpServer, toolInputAdapter: ToolInputAdapterWithoutSchema): void;
 
-export { toolAdapter, toolContentAdapter };
+/**
+ * Supported HTTP methods for the HTTP tool adapter.
+ */
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/**
+ * API key authentication — sent as a request header.
+ * @example { type: "apikey", header: "X-API-Key", key: process.env.API_KEY! }
+ */
+interface ApiKeyAuth {
+    type: "apikey";
+    /** Header name to send the key in (e.g. `"X-API-Key"`) */
+    header: string;
+    key: string;
+}
+/**
+ * Bearer token authentication — sends `Authorization: Bearer <token>`.
+ * @example { type: "bearer", token: process.env.API_TOKEN! }
+ */
+interface BearerAuth {
+    type: "bearer";
+    token: string;
+}
+/**
+ * HTTP Basic authentication — sends `Authorization: Basic <base64>`.
+ * @example { type: "basic", username: "user", password: process.env.PASSWORD! }
+ */
+interface BasicAuth {
+    type: "basic";
+    username: string;
+    password: string;
+}
+/**
+ * Union of all supported authentication strategies.
+ */
+type HttpAuth = ApiKeyAuth | BearerAuth | BasicAuth;
+/**
+ * Configuration for registering an HTTP endpoint as an MCP tool with an input schema.
+ *
+ * @template T - Zod raw shape inferred from `inputSchema`, typed through to the request.
+ */
+interface HttpToolAdapterWithSchema<T extends ZodRawShapeCompat> {
+    /** Unique tool name in the MCP registry. */
+    name: string;
+    /** Description of the tool shown to the model. */
+    description: string;
+    /** Full URL of the API endpoint. */
+    endpoint: string;
+    /** HTTP method to use. GET maps args to query params; others map to request body. */
+    method: HttpMethod;
+    /** Zod shape defining the tool's input arguments. */
+    inputSchema: T;
+    /** Optional authentication strategy. */
+    auth?: HttpAuth;
+    /** Optional extra axios config (e.g. headers, timeout). */
+    axiosConfig?: AxiosRequestConfig;
+}
+/**
+ * Configuration for registering an HTTP endpoint as an MCP tool with no input arguments.
+ */
+interface HttpToolAdapterWithoutSchema {
+    /** Unique tool name in the MCP registry. */
+    name: string;
+    /** Description of the tool shown to the model. */
+    description: string;
+    /** Full URL of the API endpoint. */
+    endpoint: string;
+    /** HTTP method to use. */
+    method: HttpMethod;
+    inputSchema?: undefined;
+    /** Optional authentication strategy. */
+    auth?: HttpAuth;
+    /** Optional extra axios config (e.g. headers, timeout). */
+    axiosConfig?: AxiosRequestConfig;
+}
+/**
+ * Registers an HTTP endpoint as an MCP tool with a typed input schema.
+ *
+ * GET requests map input args to query parameters.
+ * All other methods map input args to the JSON request body.
+ *
+ * @template T - Zod raw shape inferred from `inputSchema`.
+ * @param server  - The `McpServer` instance to register the tool on.
+ * @param adapter - HTTP tool configuration including endpoint, method, schema, and auth.
+ *
+ * @example
+ * httpToolAdapter(server, {
+ *   name: "get-analysis",
+ *   description: "Fetch position analysis",
+ *   endpoint: "https://api.example.com/analyze",
+ *   method: "POST",
+ *   inputSchema: { fen: z.string(), depth: z.number() },
+ *   auth: { type: "bearer", token: process.env.API_TOKEN! },
+ * });
+ */
+declare function httpToolAdapter<T extends ZodRawShapeCompat>(server: McpServer, adapter: HttpToolAdapterWithSchema<T>): void;
+/**
+ * Registers an HTTP endpoint as an MCP tool with no input arguments.
+ *
+ * @param server  - The `McpServer` instance to register the tool on.
+ * @param adapter - HTTP tool configuration including endpoint, method, and auth.
+ *
+ * @example
+ * httpToolAdapter(server, {
+ *   name: "get-status",
+ *   description: "Fetch API status",
+ *   endpoint: "https://api.example.com/status",
+ *   method: "GET",
+ *   auth: { type: "apikey", header: "X-API-Key", key: process.env.API_KEY! },
+ * });
+ */
+declare function httpToolAdapter(server: McpServer, adapter: HttpToolAdapterWithoutSchema): void;
+
+export { type ApiKeyAuth, type BasicAuth, type BearerAuth, type HttpAuth, type HttpMethod, type HttpToolAdapterWithSchema, type HttpToolAdapterWithoutSchema, httpToolAdapter, toolAdapter, toolContentAdapter };

package/dist/index.js

@@ -24,7 +24,81 @@ function toolAdapter(server, toolInputAdapter) {
     );
   }
 }
+
+// src/axiosAdapter.ts
+import axios from "axios";
+function buildAuthHeaders(auth) {
+  switch (auth.type) {
+    case "apikey":
+      return { [auth.header]: auth.key };
+    case "bearer":
+      return { Authorization: `Bearer ${auth.token}` };
+    case "basic": {
+      const encoded = Buffer.from(`${auth.username}:${auth.password}`).toString("base64");
+      return { Authorization: `Basic ${encoded}` };
+    }
+  }
+}
+async function executeRequest(endpoint, method, args, auth, extraConfig) {
+  try {
+    const authHeaders = auth ? buildAuthHeaders(auth) : {};
+    const config = {
+      url: endpoint,
+      method,
+      headers: {
+        "Content-Type": "application/json",
+        ...authHeaders,
+        ...extraConfig?.headers
+      },
+      ...method === "GET" ? { params: args } : { data: args },
+      ...extraConfig
+    };
+    const response = await axios(config);
+    return { data: response.data };
+  } catch (err) {
+    if (axios.isAxiosError(err)) {
+      const status = err.response?.status ?? "unknown";
+      const message = err.response?.data?.message ?? err.message;
+      return { error: `HTTP ${status}: ${message}` };
+    }
+    return { error: `Unexpected error: ${String(err)}` };
+  }
+}
+function httpToolAdapter(server, adapter) {
+  if (adapter.inputSchema) {
+    const { endpoint, method, auth, axiosConfig, inputSchema } = adapter;
+    toolAdapter(server, {
+      name: adapter.name,
+      config: {
+        description: adapter.description,
+        inputSchema
+      },
+      cb: (async (args) => {
+        const { data, error } = await executeRequest(endpoint, method, args, auth, axiosConfig);
+        return toolContentAdapter(data ?? {}, error);
+      })
+    });
+  } else {
+    toolAdapter(server, {
+      name: adapter.name,
+      config: {
+        description: adapter.description
+      },
+      cb: async () => {
+        const { data, error } = await executeRequest(
+          adapter.endpoint,
+          adapter.method,
+          {},
+          adapter.auth,
+          adapter.axiosConfig
+        );
+        return toolContentAdapter(data ?? {}, error);
+      }
+    });
+  }
+}
 export {
+  httpToolAdapter,
   toolAdapter,
   toolContentAdapter
 };

package/package.json

@@ -1,12 +1,27 @@
 {
   "name": "@jalpp/mcp-adapter",
-  "version": "0.1.2",
-  "description": "Adapter utilities for registering MCP tools",
+  "version": "0.2.0",
+  "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",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "adapter",
+    "llm",
+    "typescript",
+    "axios",
+    "http",
+    "tool"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/jalpp/mcp-adapter.git"
   },
+  "homepage": "https://github.com/jalpp/mcp-adapter#readme",
+  "bugs": {
+    "url": "https://github.com/jalpp/mcp-adapter/issues"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -18,7 +33,9 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
     "build": "tsup",
@@ -27,13 +44,17 @@
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": ">=1.0.0",
-    "zod": ">=3.0.0"
+    "zod": ">=3.0.0",
+    "axios": ">=1.0.0"
   },
   "devDependencies": {
     "@modelcontextprotocol/sdk": ">=1.0.0",
-    "zod": ">=3.0.0",
-    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0",
     "tsup": "^8.0.0",
-    "@types/node": "^20.0.0"
+    "typescript": "^5.0.0",
+    "zod": ">=3.0.0"
+  },
+  "dependencies": {
+    "axios": "^1.13.6"
   }
 }