@ctxprotocol/sdk 0.1.1

package/README.md

@@ -0,0 +1,103 @@
+# Context SDK
+> Server-side helpers for publishing HTTP tools to the Context marketplace.
+
+The Context SDK is a tiny server-side helper for contributors who want to
+expose HTTP-based tools to the Context marketplace in a safe, typed, and
+consistent way.
+
+---
+
+## Install
+
+Using **pnpm**:
+
+```bash
+pnpm add @ctxprotocol/sdk zod
+```
+
+Using **npm**:
+
+```bash
+npm install @ctxprotocol/sdk zod
+```
+
+---
+
+## Quick start
+
+Define a tool with input/output schemas and a handler, then expose it via a
+single HTTP endpoint:
+
+```ts
+import { z } from "zod";
+import { defineHttpTool, executeHttpTool } from "@ctxprotocol/sdk";
+
+const tool = defineHttpTool({
+  name: "blocknative_gas_base",
+  inputSchema: z.object({ chainId: z.number().default(8453) }),
+  outputSchema: z.object({
+    endpoint: z.string(),
+    data: z.unknown(),
+  }),
+  async handler(input) {
+    const response = await fetch("https://your-endpoint", {
+      method: "POST",
+      body: JSON.stringify(input),
+    });
+
+    return {
+      endpoint: "gas_price",
+      data: await response.json(),
+    };
+  },
+});
+
+export async function handler(req: Request) {
+  const body = await req.json();
+  const result = await executeHttpTool(tool, body.input, {
+    headers: Object.fromEntries(req.headers.entries()),
+  });
+
+  return Response.json(result);
+}
+```
+
+See `examples/blocknative-contributor/` for a full Express server that wraps
+the Blocknative Gas Platform.
+
+---
+
+## Scripts
+
+From the repo root:
+
+- **Build** – bundle to `dist/`:
+
+  ```bash
+  pnpm run build
+  ```
+
+- **Lint** – Biome checks:
+
+  ```bash
+  pnpm run lint
+  ```
+
+- **Test** – Vitest (add tests as needed):
+
+  ```bash
+  pnpm run test
+  ```
+
+---
+
+## Publishing (for maintainers)
+
+Install dependencies, build once to ensure everything compiles, then publish:
+
+```bash
+pnpm install
+pnpm run build
+pnpm publish --access public
+```
+

package/dist/index.d.mts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+
+type ToolContext = {
+    /**
+     * Raw headers from the incoming request. Useful if contributors need to
+     * inspect authentication or tracing metadata.
+     */
+    headers?: Record<string, string | string[] | undefined>;
+};
+type DefineHttpToolOptions<I extends z.ZodTypeAny, O extends z.ZodTypeAny> = {
+    name: string;
+    version?: string;
+    description?: string;
+    inputSchema: I;
+    outputSchema: O;
+    handler: (input: z.infer<I>, context: ToolContext) => Promise<z.infer<O>>;
+};
+type HttpToolDefinition<I extends z.ZodTypeAny, O extends z.ZodTypeAny> = {
+    name: string;
+    version?: string;
+    description?: string;
+    inputSchema: I;
+    outputSchema: O;
+    handler: (input: z.infer<I>, context: ToolContext) => Promise<z.infer<O>>;
+};
+type ExecuteHttpToolOptions = {
+    headers?: Record<string, string | string[] | undefined>;
+};
+type ContextResponse<T> = {
+    data: T;
+    meta: {
+        tool: string;
+        version?: string;
+        generatedAt: string;
+    };
+};
+declare function defineHttpTool<I extends z.ZodTypeAny, O extends z.ZodTypeAny>(options: DefineHttpToolOptions<I, O>): HttpToolDefinition<I, O>;
+declare function executeHttpTool<I extends z.ZodTypeAny, O extends z.ZodTypeAny>(tool: HttpToolDefinition<I, O>, input: unknown, options?: ExecuteHttpToolOptions): Promise<ContextResponse<z.infer<O>>>;
+
+export { type ContextResponse, type DefineHttpToolOptions, type ExecuteHttpToolOptions, type HttpToolDefinition, type ToolContext, defineHttpTool, executeHttpTool };

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+
+type ToolContext = {
+    /**
+     * Raw headers from the incoming request. Useful if contributors need to
+     * inspect authentication or tracing metadata.
+     */
+    headers?: Record<string, string | string[] | undefined>;
+};
+type DefineHttpToolOptions<I extends z.ZodTypeAny, O extends z.ZodTypeAny> = {
+    name: string;
+    version?: string;
+    description?: string;
+    inputSchema: I;
+    outputSchema: O;
+    handler: (input: z.infer<I>, context: ToolContext) => Promise<z.infer<O>>;
+};
+type HttpToolDefinition<I extends z.ZodTypeAny, O extends z.ZodTypeAny> = {
+    name: string;
+    version?: string;
+    description?: string;
+    inputSchema: I;
+    outputSchema: O;
+    handler: (input: z.infer<I>, context: ToolContext) => Promise<z.infer<O>>;
+};
+type ExecuteHttpToolOptions = {
+    headers?: Record<string, string | string[] | undefined>;
+};
+type ContextResponse<T> = {
+    data: T;
+    meta: {
+        tool: string;
+        version?: string;
+        generatedAt: string;
+    };
+};
+declare function defineHttpTool<I extends z.ZodTypeAny, O extends z.ZodTypeAny>(options: DefineHttpToolOptions<I, O>): HttpToolDefinition<I, O>;
+declare function executeHttpTool<I extends z.ZodTypeAny, O extends z.ZodTypeAny>(tool: HttpToolDefinition<I, O>, input: unknown, options?: ExecuteHttpToolOptions): Promise<ContextResponse<z.infer<O>>>;
+
+export { type ContextResponse, type DefineHttpToolOptions, type ExecuteHttpToolOptions, type HttpToolDefinition, type ToolContext, defineHttpTool, executeHttpTool };

package/dist/index.js

@@ -0,0 +1,49 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  defineHttpTool: () => defineHttpTool,
+  executeHttpTool: () => executeHttpTool
+});
+module.exports = __toCommonJS(index_exports);
+function defineHttpTool(options) {
+  return options;
+}
+async function executeHttpTool(tool, input, options = {}) {
+  const parsedInput = tool.inputSchema.parse(input);
+  const data = await tool.handler(parsedInput, {
+    headers: options.headers
+  });
+  const parsedOutput = tool.outputSchema.parse(data);
+  return {
+    data: parsedOutput,
+    meta: {
+      tool: tool.name,
+      version: tool.version,
+      generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  defineHttpTool,
+  executeHttpTool
+});

package/dist/index.mjs

@@ -0,0 +1,23 @@
+// src/index.ts
+function defineHttpTool(options) {
+  return options;
+}
+async function executeHttpTool(tool, input, options = {}) {
+  const parsedInput = tool.inputSchema.parse(input);
+  const data = await tool.handler(parsedInput, {
+    headers: options.headers
+  });
+  const parsedOutput = tool.outputSchema.parse(data);
+  return {
+    data: parsedOutput,
+    meta: {
+      tool: tool.name,
+      version: tool.version,
+      generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+}
+export {
+  defineHttpTool,
+  executeHttpTool
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@ctxprotocol/sdk",
+  "version": "0.1.1",
+  "description": "Server-side helpers for publishing Context HTTP tools.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ctxprotocol/sdk.git"
+  },
+  "author": "Context Protocol",
+  "license": "MIT",
+  "dependencies": {
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4",
+    "@biomejs/biome": "^2.2.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "lint": "biome check src",
+    "test": "vitest"
+  }
+}