@contextvm/sdk 0.1.1 → 0.1.2

package/README.md

@@ -1,3 +1,179 @@
-# ctxvm-sdk
+# @ctxvm/sdk: CTXVM Protocol SDK
 
-`@ctxvm/sdk` is a TypeScript SDK designed to implement the `ctxvm` protocol, providing modular access to core functionalities, relay interactions, and signing operations.
+A JavaScript/TypeScript SDK that implements the Context Vending Machine (CTXVM) Protocol, bridging Nostr and Model Context Protocol (MCP) to enable decentralized access and exposure of computational services.
+
+## Overview
+
+The CTXVM Protocol defines how Nostr and Model Context Machines can be used to expose MCP server capabilities, enabling standardized usage of these resources through a decentralized, cryptographically secure messaging system.
+
+This SDK provides the necessary components to interact with the CTXVM Protocol:
+
+- **Core Module**: Contains fundamental definitions, constants, interfaces, and utilities (e.g., encryption, serialization).
+- **Transports**: Critical for communication, providing `NostrClientTransport` and `NostrServerTransport` implementations for enabling MCP over Nostr.
+- **Proxy**: A client-side MCP server that connects to other servers through Nostr, exposing server capabilities locally. Particularly useful for clients that don't natively support Nostr transport.
+- **Gateway**: Implements Nostr server transport, binding to another MCP server and exposing its capabilities through the Nostr network.
+- **Relay**: Functionality for managing Nostr relays, abstracting relay interactions.
+- **Signer**: Provides cryptographic signing capabilities required for Nostr events.
+
+Both the Proxy and Gateway leverage Nostr transports, allowing existing MCP servers to maintain their conventional transports while gaining Nostr interoperability.
+
+## Installation
+
+This project requires [Bun](https://bun.sh/) (version 1.2.0 or higher).
+
+1.  **Clone the repository:**
+
+    ```bash
+    git clone https://github.com/ContextVM/ts-sdk.git
+    cd ts-sdk
+    ```
+
+2.  **Install dependencies:**
+
+    ```bash
+    bun install
+    ```
+
+3.  **Build the project:**
+    ```bash
+    bun run build
+    ```
+
+## Usage
+
+The SDK provides methods for bridging MCP and Nostr. At its core, the SDK relies on Nostr transports and utilities to facilitate communication.
+
+### Core Building Blocks: Signers and Relay Pools
+
+The SDK provides default implementations: `PrivateKeySigner` implements the `NostrSigner` interface, and `SimpleRelayPool` implements the `RelayHandler` interface. You can extend the SDK's capabilities by creating custom implementations that satisfy these interfaces, allowing you to integrate with different signing mechanisms or relay management logic.ª
+
+### Nostr Transports
+
+The SDK provides specialized transports to send and receive MCP messages over the Nostr network.
+
+#### `NostrClientTransport`
+
+Used by MCP clients to connect to remote MCP servers exposed via Nostr.
+
+```typescript
+import { Client } from '@modelcontextprotocol/sdk/client';
+import { NostrClientTransport } from '@ctxvm/sdk/transport';
+import { EncryptionMode } from '@ctxvm/sdk/core';
+
+// Public key of the target MCP server on Nostr
+const REMOTE_SERVER_PUBKEY = 'remote_server_public_key_here';
+
+const clientNostrTransport = new NostrClientTransport({
+  signer: signer, // Your NostrSigner instance
+  relayHandler: relayPool, // Your RelayHandler instance
+  serverPubkey: REMOTE_SERVER_PUBKEY, // Public key of the target MCP server
+  encryptionMode: EncryptionMode.OPTIONAL, // Optional: REQUIRED, OPTIONAL (default), or DISABLED
+});
+
+const mcpClient = new Client();
+
+// To connect the MCP client:
+await mcpClient.connect(clientNostrTransport);
+// Subsequent MCP calls (e.g., listTools, callTool) would use this transport.
+await mcpClient.listTools();
+// await mcpClient.close();
+```
+
+#### `NostrServerTransport`
+
+Used by MCP servers to expose their capabilities to Nostr clients.
+
+```typescript
+import { McpServer } from '@modelcontextprotocol/sdk/server';
+import { NostrServerTransport } from '@ctxvm/sdk/transport';
+import { EncryptionMode } from '@ctxvm/sdk/core';
+// Assume signer and relayPool are configured as shown above.
+
+const server = new McpServer({
+  name: 'demo-server',
+  version: '1.0.0',
+});
+
+// Before connecting, register your MCP server's capabilities.
+
+const serverNostrTransport = new NostrServerTransport({
+  signer: signer, // Server's NostrSigner instance
+  relayHandler: relayPool, // Server's RelayHandler instance
+  isPublicServer: true, // Optional: set to true to announce server capabilities via Nostr events
+  encryptionMode: EncryptionMode.OPTIONAL, // Optional: REQUIRED, OPTIONAL (default), or DISABLED
+  serverInfo: {
+    // Optional: Information for public announcements
+    name: 'Nostr MCP Example Server',
+    website: 'https://example.com/mcp-server',
+  },
+});
+
+// To connect the MCP server and make it available via Nostr:
+await mcpServer.connect(serverNostrTransport);
+// This will keep the server running and listening for Nostr events.
+// To gracefully shut down: await mcpServer.close();
+```
+
+### Bridging Components: Proxy and Gateway
+
+The SDK also provides higher-level components that leverage these transports to bridge conventional MCP setups with Nostr.
+
+#### `NostrMCPProxy` (Client-Side Bridge)
+
+Allows an MCP client (e.g., a local application communicating via a mcp transport) to communicate with a remote MCP server over Nostr. The proxy acts as a translation layer, using `NostrClientTransport` internally.
+
+```typescript
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/stdio';
+import { NostrMCPProxy } from '@ctxvm/sdk/proxy';
+
+// This transport represents the connection between your local MCP client and the proxy.
+const hostTransport = new StdioServerTransport();
+
+const proxy = new NostrMCPProxy({
+  mcpHostTransport: hostTransport, // Your local client's transport
+  nostrTransportOptions: {
+    signer: signer,
+    relayHandler: relayPool,
+    serverPubkey: REMOTE_SERVER_PUBKEY, // Target the remote MCP server public key via Nostr
+  },
+});
+
+// To start the proxy:
+await proxy.start();
+```
+
+#### `NostrMCPGateway` (Server-Side Bridge)
+
+Allows an existing MCP server (e.g., communicating via a mcp transport) to expose its capabilities through Nostr. The gateway uses `NostrServerTransport` internally.
+
+```typescript
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/stdio';
+import { NostrMCPGateway } from '@ctxvm/sdk/gateway';
+
+// This transport defines how the Gateway connects to your traditional MCP server.
+const serverTransport = new StdioClientTransport({
+  command: 'bun',
+  args: ['path/to/your/mcp-server.ts'],
+});
+
+const gateway = new NostrMCPGateway({
+  mcpServerTransport: serverTransport, // Your existing MCP server's transport
+  nostrTransportOptions: {
+    signer: signer,
+    relayHandler: relayPool,
+    isPublicServer: true, // Set to true to announce server capabilities to Nostr clients for discovery
+  },
+});
+
+// To start the gateway and expose your MCP server to Nostr clients:
+await gateway.start();
+// The gateway will run indefinitely, relaying messages between Nostr and your MCP server.
+```
+
+## Running Tests
+
+To run the test suite, use Bun:
+
+```bash
+bun tests
+```

package/dist/esm/core/constants.d.ts

@@ -0,0 +1,65 @@
+import { AnnouncementMethods } from './interfaces.js';
+/**
+ * CTXVM-specific event kinds.
+ *
+ * All CTXVM messages are ephemeral events.
+ * @see https://github.com/nostr-protocol/nips/blob/master/01.md#kinds
+ */
+export declare const CTXVM_MESSAGES_KIND = 25910;
+/**
+ * Encrypted CTXVM messages using NIP-59 Gift Wrap.
+ * @see https://github.com/nostr-protocol/nips/blob/master/59.md
+ */
+export declare const GIFT_WRAP_KIND = 1059;
+/**
+ * Addressable event for server announcements.
+ */
+export declare const SERVER_ANNOUNCEMENT_KIND = 11316;
+/**
+ * Addressable event for listing available tools.
+ */
+export declare const TOOLS_LIST_KIND = 11317;
+/**
+ * Addressable event for listing available resources.
+ */
+export declare const RESOURCES_LIST_KIND = 11318;
+/**
+ * Addressable event for listing available resources.
+ */
+export declare const RESOURCETEMPLATES_LIST_KIND = 11319;
+/**
+ * Addressable event for listing available prompts.
+ */
+export declare const PROMPTS_LIST_KIND = 11320;
+/**
+ * CTXVM-specific Nostr event tags.
+ */
+export declare const NOSTR_TAGS: {
+    readonly PUBKEY: "p";
+    /**
+     * Event ID for correlating requests and responses.
+     */
+    readonly EVENT_ID: "e";
+    /**
+     * Capability tag for tools, resources, and prompts to provide pricing metadata.
+     */
+    readonly CAPABILITY: "cap";
+    /**
+     * Name tag for server announcements.
+     */
+    readonly NAME: "name";
+    /**
+     * Website tag for server announcements.
+     */
+    readonly WEBSITE: "website";
+    /**
+     * Picture tag for server announcements.
+     */
+    readonly PICTURE: "picture";
+    /**
+     * Support encryption tag for server announcements.
+     */
+    readonly SUPPORT_ENCRYPTION: "support_encryption";
+};
+export declare const announcementMethods: AnnouncementMethods;
+//# sourceMappingURL=constants.d.ts.map

package/dist/esm/core/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/core/constants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEtD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AAEzC;;;GAGG;AACH,eAAO,MAAM,cAAc,OAAO,CAAC;AAEnC;;GAEG;AACH,eAAO,MAAM,wBAAwB,QAAQ,CAAC;AAE9C;;GAEG;AACH,eAAO,MAAM,eAAe,QAAQ,CAAC;AAErC;;GAEG;AACH,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AAEzC;;GAEG;AACH,eAAO,MAAM,2BAA2B,QAAQ,CAAC;AAEjD;;GAEG;AACH,eAAO,MAAM,iBAAiB,QAAQ,CAAC;AAEvC;;GAEG;AACH,eAAO,MAAM,UAAU;;IAErB;;OAEG;;IAEH;;OAEG;;IAEH;;OAEG;;IAEH;;OAEG;;IAEH;;OAEG;;IAEH;;OAEG;;CAEK,CAAC;AAEX,eAAO,MAAM,mBAAmB,EAAE,mBAMxB,CAAC"}

package/dist/esm/core/constants.js

@@ -0,0 +1,70 @@
+/**
+ * CTXVM-specific event kinds.
+ *
+ * All CTXVM messages are ephemeral events.
+ * @see https://github.com/nostr-protocol/nips/blob/master/01.md#kinds
+ */
+export const CTXVM_MESSAGES_KIND = 25910;
+/**
+ * Encrypted CTXVM messages using NIP-59 Gift Wrap.
+ * @see https://github.com/nostr-protocol/nips/blob/master/59.md
+ */
+export const GIFT_WRAP_KIND = 1059;
+/**
+ * Addressable event for server announcements.
+ */
+export const SERVER_ANNOUNCEMENT_KIND = 11316;
+/**
+ * Addressable event for listing available tools.
+ */
+export const TOOLS_LIST_KIND = 11317;
+/**
+ * Addressable event for listing available resources.
+ */
+export const RESOURCES_LIST_KIND = 11318;
+/**
+ * Addressable event for listing available resources.
+ */
+export const RESOURCETEMPLATES_LIST_KIND = 11319;
+/**
+ * Addressable event for listing available prompts.
+ */
+export const PROMPTS_LIST_KIND = 11320;
+/**
+ * CTXVM-specific Nostr event tags.
+ */
+export const NOSTR_TAGS = {
+    PUBKEY: 'p',
+    /**
+     * Event ID for correlating requests and responses.
+     */
+    EVENT_ID: 'e',
+    /**
+     * Capability tag for tools, resources, and prompts to provide pricing metadata.
+     */
+    CAPABILITY: 'cap',
+    /**
+     * Name tag for server announcements.
+     */
+    NAME: 'name',
+    /**
+     * Website tag for server announcements.
+     */
+    WEBSITE: 'website',
+    /**
+     * Picture tag for server announcements.
+     */
+    PICTURE: 'picture',
+    /**
+     * Support encryption tag for server announcements.
+     */
+    SUPPORT_ENCRYPTION: 'support_encryption',
+};
+export const announcementMethods = {
+    server: 'initialize',
+    tools: 'tools/list',
+    resources: 'resources/list',
+    resourceTemplates: 'resources/templates/list',
+    prompts: 'prompts/list',
+};
+//# sourceMappingURL=constants.js.map

package/dist/esm/core/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/core/constants.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC;AAEzC;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAC;AAEnC;;GAEG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,KAAK,CAAC;AAE9C;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,CAAC;AAErC;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC;AAEzC;;GAEG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,KAAK,CAAC;AAEjD;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,CAAC;AAEvC;;GAEG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,MAAM,EAAE,GAAG;IACX;;OAEG;IACH,QAAQ,EAAE,GAAG;IACb;;OAEG;IACH,UAAU,EAAE,KAAK;IACjB;;OAEG;IACH,IAAI,EAAE,MAAM;IACZ;;OAEG;IACH,OAAO,EAAE,SAAS;IAClB;;OAEG;IACH,OAAO,EAAE,SAAS;IAClB;;OAEG;IACH,kBAAkB,EAAE,oBAAoB;CAChC,CAAC;AAEX,MAAM,CAAC,MAAM,mBAAmB,GAAwB;IACtD,MAAM,EAAE,YAAY;IACpB,KAAK,EAAE,YAAY;IACnB,SAAS,EAAE,gBAAgB;IAC3B,iBAAiB,EAAE,0BAA0B;IAC7C,OAAO,EAAE,cAAc;CACf,CAAC"}

package/dist/esm/core/encryption.d.ts

@@ -0,0 +1,18 @@
+import { type Event as NostrEvent } from 'nostr-tools';
+/**
+ * Encrypts a JSON-RPC message using a simplified NIP-17/NIP-59 gift wrap scheme.
+ * The message is encrypted with NIP-44 and wrapped in a kind 1059 event.
+ * @param message The JSON-RPC message to encrypt.
+ * @param recipientPublicKey The public key of the recipient.
+ * @returns The encrypted gift wrap event.
+ */
+export declare function encryptMessage(message: string, recipientPublicKey: string): NostrEvent;
+/**
+ * Decrypts a gift-wrapped Nostr event.
+ * @param event The gift wrap event (kind 1059).
+ * @param recipientPrivateKey The private key of the recipient.
+ * @returns The decrypted message content.
+ * @throws If the event is not a valid gift wrap or decryption fails.
+ */
+export declare function decryptMessage(event: NostrEvent, recipientPrivateKey: Uint8Array): string;
+//# sourceMappingURL=encryption.d.ts.map

package/dist/esm/core/encryption.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption.d.ts","sourceRoot":"","sources":["../../../src/core/encryption.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,KAAK,IAAI,UAAU,EAAE,MAAM,aAAa,CAAC;AAQ9D;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,kBAAkB,EAAE,MAAM,GACzB,UAAU,CAiBZ;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,UAAU,EACjB,mBAAmB,EAAE,UAAU,GAC9B,MAAM,CAWR"}

package/dist/esm/core/encryption.js

@@ -0,0 +1,40 @@
+import { nip44 } from 'nostr-tools';
+import { finalizeEvent, generateSecretKey, getPublicKey, } from 'nostr-tools/pure';
+import { GIFT_WRAP_KIND, NOSTR_TAGS } from './constants.js';
+/**
+ * Encrypts a JSON-RPC message using a simplified NIP-17/NIP-59 gift wrap scheme.
+ * The message is encrypted with NIP-44 and wrapped in a kind 1059 event.
+ * @param message The JSON-RPC message to encrypt.
+ * @param recipientPublicKey The public key of the recipient.
+ * @returns The encrypted gift wrap event.
+ */
+export function encryptMessage(message, recipientPublicKey) {
+    const giftWrapPrivateKey = generateSecretKey();
+    const giftWrapPublicKey = getPublicKey(giftWrapPrivateKey);
+    const conversationKey = nip44.v2.utils.getConversationKey(giftWrapPrivateKey, recipientPublicKey);
+    const encryptedContent = nip44.v2.encrypt(message, conversationKey);
+    const giftWrap = {
+        kind: GIFT_WRAP_KIND,
+        content: encryptedContent,
+        tags: [[NOSTR_TAGS.PUBKEY, recipientPublicKey]],
+        created_at: Math.floor(Date.now() / 1000),
+        pubkey: giftWrapPublicKey,
+    };
+    return finalizeEvent(giftWrap, giftWrapPrivateKey);
+}
+/**
+ * Decrypts a gift-wrapped Nostr event.
+ * @param event The gift wrap event (kind 1059).
+ * @param recipientPrivateKey The private key of the recipient.
+ * @returns The decrypted message content.
+ * @throws If the event is not a valid gift wrap or decryption fails.
+ */
+export function decryptMessage(event, recipientPrivateKey) {
+    if (event.kind !== GIFT_WRAP_KIND) {
+        throw new Error('Event is not a gift wrap.');
+    }
+    const conversationKey = nip44.v2.utils.getConversationKey(recipientPrivateKey, event.pubkey);
+    const decryptedMsg = nip44.v2.decrypt(event.content, conversationKey);
+    return decryptedMsg;
+}
+//# sourceMappingURL=encryption.js.map

package/dist/esm/core/encryption.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption.js","sourceRoot":"","sources":["../../../src/core/encryption.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAA4B,MAAM,aAAa,CAAC;AAC9D,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,YAAY,GACb,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAe,EACf,kBAA0B;IAE1B,MAAM,kBAAkB,GAAG,iBAAiB,EAAE,CAAC;IAC/C,MAAM,iBAAiB,GAAG,YAAY,CAAC,kBAAkB,CAAC,CAAC;IAC3D,MAAM,eAAe,GAAG,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,kBAAkB,CACvD,kBAAkB,EAClB,kBAAkB,CACnB,CAAC;IACF,MAAM,gBAAgB,GAAG,KAAK,CAAC,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;IACpE,MAAM,QAAQ,GAAG;QACf,IAAI,EAAE,cAAc;QACpB,OAAO,EAAE,gBAAgB;QACzB,IAAI,EAAE,CAAC,CAAC,UAAU,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;QAC/C,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;QACzC,MAAM,EAAE,iBAAiB;KAC1B,CAAC;IAEF,OAAO,aAAa,CAAC,QAAQ,EAAE,kBAAkB,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAiB,EACjB,mBAA+B;IAE/B,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;IAC/C,CAAC;IAED,MAAM,eAAe,GAAG,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,kBAAkB,CACvD,mBAAmB,EACnB,KAAK,CAAC,MAAM,CACb,CAAC;IACF,MAAM,YAAY,GAAG,KAAK,CAAC,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;IACtE,OAAO,YAAY,CAAC;AACtB,CAAC"}

package/dist/esm/core/index.d.ts

@@ -0,0 +1,5 @@
+export * from './constants.js';
+export * from './interfaces.js';
+export * from './utils/serializers.js';
+export * from './encryption.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,iBAAiB,CAAC"}

package/dist/esm/core/index.js

@@ -0,0 +1,5 @@
+export * from './constants.js';
+export * from './interfaces.js';
+export * from './utils/serializers.js';
+export * from './encryption.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,iBAAiB,CAAC"}

package/dist/esm/core/interfaces.d.ts

@@ -0,0 +1,39 @@
+import { InitializeRequest, ListPromptsRequest, ListResourcesRequest, ListResourceTemplatesRequest, ListToolsRequest } from '@modelcontextprotocol/sdk/types.js';
+import type { Filter, NostrEvent } from 'nostr-tools';
+/**
+ * Defines the encryption mode for the transport.
+ * - `optional`: Encrypts messages if the incoming message was encrypted.
+ * - `required`: Enforces encryption for all messages.
+ * - `disabled`: Disables encryption entirely.
+ */
+export declare enum EncryptionMode {
+    OPTIONAL = "optional",
+    REQUIRED = "required",
+    DISABLED = "disabled"
+}
+/**
+ * A generic interface for Nostr signers.
+ */
+export interface NostrSigner {
+    getPublicKey(): Promise<string>;
+    signEvent(event: Omit<NostrEvent, 'sig' | 'id'>): Promise<NostrEvent>;
+    getSecretKey(): Promise<Uint8Array>;
+}
+/**
+ * A generic interface for Nostr relays.
+ */
+export interface RelayHandler {
+    connect(): Promise<void>;
+    disconnect(relayUrls?: string[]): Promise<void>;
+    publish(event: NostrEvent): Promise<void>;
+    subscribe(filters: Filter[], onEvent: (event: NostrEvent) => void, onEose?: () => void): Promise<void>;
+    unsubscribe(): void;
+}
+export interface AnnouncementMethods {
+    server: InitializeRequest['method'];
+    tools: ListToolsRequest['method'];
+    resources: ListResourcesRequest['method'];
+    resourceTemplates: ListResourceTemplatesRequest['method'];
+    prompts: ListPromptsRequest['method'];
+}
+//# sourceMappingURL=interfaces.d.ts.map

package/dist/esm/core/interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../../src/core/interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,4BAA4B,EAC5B,gBAAgB,EACjB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEtD;;;;;GAKG;AACH,oBAAY,cAAc;IACxB,QAAQ,aAAa;IACrB,QAAQ,aAAa;IACrB,QAAQ,aAAa;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAChC,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,KAAK,GAAG,IAAI,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACtE,YAAY,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,UAAU,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,SAAS,CACP,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,EACpC,MAAM,CAAC,EAAE,MAAM,IAAI,GAClB,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,WAAW,IAAI,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IACpC,KAAK,EAAE,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAClC,SAAS,EAAE,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IAC1C,iBAAiB,EAAE,4BAA4B,CAAC,QAAQ,CAAC,CAAC;IAC1D,OAAO,EAAE,kBAAkB,CAAC,QAAQ,CAAC,CAAC;CACvC"}

package/dist/esm/core/interfaces.js

@@ -0,0 +1,13 @@
+/**
+ * Defines the encryption mode for the transport.
+ * - `optional`: Encrypts messages if the incoming message was encrypted.
+ * - `required`: Enforces encryption for all messages.
+ * - `disabled`: Disables encryption entirely.
+ */
+export var EncryptionMode;
+(function (EncryptionMode) {
+    EncryptionMode["OPTIONAL"] = "optional";
+    EncryptionMode["REQUIRED"] = "required";
+    EncryptionMode["DISABLED"] = "disabled";
+})(EncryptionMode || (EncryptionMode = {}));
+//# sourceMappingURL=interfaces.js.map

package/dist/esm/core/interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../../../src/core/interfaces.ts"],"names":[],"mappings":"AASA;;;;;GAKG;AACH,MAAM,CAAN,IAAY,cAIX;AAJD,WAAY,cAAc;IACxB,uCAAqB,CAAA;IACrB,uCAAqB,CAAA;IACrB,uCAAqB,CAAA;AACvB,CAAC,EAJW,cAAc,KAAd,cAAc,QAIzB"}

package/dist/esm/core/utils/serializers.d.ts

@@ -0,0 +1,29 @@
+import type { Event as NostrEvent, UnsignedEvent } from 'nostr-tools';
+import type { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * Serializes an MCP message into a Nostr event object.
+ *
+ * @param mcpMessage The MCP message (request or response) to serialize.
+ * @param pubkey The public key of the sender.
+ * @param kind The kind of Nostr event to create.
+ * @param tags An array of tags to include in the event.
+ * @returns A Nostr event object (without `id` and `sig`).
+ */
+export declare function mcpToNostrEvent(mcpMessage: JSONRPCMessage, pubkey: string, kind: number, tags?: string[][]): UnsignedEvent;
+/**
+ * Deserializes a Nostr event into an MCP message.
+ *
+ * @param event The Nostr event to deserialize.
+ * @returns An MCP request or response object.
+ * @throws Error if the event content is not valid JSON
+ */
+export declare function nostrEventToMcpMessage(event: NostrEvent): JSONRPCMessage;
+/**
+ * Extracts a specific tag from a Nostr event.
+ *
+ * @param event The Nostr event.
+ * @param tagName The name of the tag to extract (e.g., 'e', 'p', 'd').
+ * @returns The value of the tag, or undefined if not found.
+ */
+export declare function getNostrEventTag(tags: NostrEvent['tags'], tagName: string): string | undefined;
+//# sourceMappingURL=serializers.d.ts.map

package/dist/esm/core/utils/serializers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serializers.d.ts","sourceRoot":"","sources":["../../../../src/core/utils/serializers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,IAAI,UAAU,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,cAAc,EAC1B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,MAAM,EAAE,EAAO,GACpB,aAAa,CAQf;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,UAAU,GAAG,cAAc,CASxE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,EACxB,OAAO,EAAE,MAAM,GACd,MAAM,GAAG,SAAS,CAGpB"}

package/dist/esm/core/utils/serializers.js

@@ -0,0 +1,46 @@
+/**
+ * Serializes an MCP message into a Nostr event object.
+ *
+ * @param mcpMessage The MCP message (request or response) to serialize.
+ * @param pubkey The public key of the sender.
+ * @param kind The kind of Nostr event to create.
+ * @param tags An array of tags to include in the event.
+ * @returns A Nostr event object (without `id` and `sig`).
+ */
+export function mcpToNostrEvent(mcpMessage, pubkey, kind, tags = []) {
+    return {
+        pubkey,
+        kind,
+        tags,
+        content: JSON.stringify(mcpMessage),
+        created_at: Math.floor(Date.now() / 1000),
+    };
+}
+/**
+ * Deserializes a Nostr event into an MCP message.
+ *
+ * @param event The Nostr event to deserialize.
+ * @returns An MCP request or response object.
+ * @throws Error if the event content is not valid JSON
+ */
+export function nostrEventToMcpMessage(event) {
+    try {
+        const content = JSON.parse(event.content);
+        return content;
+    }
+    catch (error) {
+        throw new Error(`Invalid JSON in Nostr event content: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}
+/**
+ * Extracts a specific tag from a Nostr event.
+ *
+ * @param event The Nostr event.
+ * @param tagName The name of the tag to extract (e.g., 'e', 'p', 'd').
+ * @returns The value of the tag, or undefined if not found.
+ */
+export function getNostrEventTag(tags, tagName) {
+    const tag = tags.find((t) => t[0] === tagName);
+    return tag ? tag[1] : undefined;
+}
+//# sourceMappingURL=serializers.js.map

package/dist/esm/core/utils/serializers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serializers.js","sourceRoot":"","sources":["../../../../src/core/utils/serializers.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAC7B,UAA0B,EAC1B,MAAc,EACd,IAAY,EACZ,OAAmB,EAAE;IAErB,OAAO;QACL,MAAM;QACN,IAAI;QACJ,IAAI;QACJ,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC;QACnC,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;KAC1C,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAiB;IACtD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC1C,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,wCAAwC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,EAAE,CACnG,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAwB,EACxB,OAAe;IAEf,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC;IAC/C,OAAO,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAClC,CAAC"}

package/dist/esm/gateway/index.d.ts

@@ -0,0 +1,60 @@
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { NostrServerTransportOptions } from '../transport/nostr-server-transport.js';
+/**
+ * Options for configuring the NostrMCPGateway.
+ */
+export interface NostrMCPGatewayOptions {
+    /** The MCP server transport (e.g., StdioServerTransport) to connect to the original MCP server */
+    mcpServerTransport: Transport;
+    /** Options for configuring the Nostr server transport */
+    nostrTransportOptions: NostrServerTransportOptions;
+}
+/**
+ * The main gateway class that orchestrates communication between Nostr clients
+ * and a local MCP server. It acts as a bridge, receiving MCP requests via Nostr
+ * events and forwarding them to the local MCP server, then publishing the
+ * responses back to Nostr. All request/response correlation is handled by the
+ * NostrServerTransport, making this a simple message forwarder.
+ */
+export declare class NostrMCPGateway {
+    private readonly mcpServerTransport;
+    private readonly nostrServerTransport;
+    private isRunning;
+    constructor(options: NostrMCPGatewayOptions);
+    /**
+     * Sets up event handlers for both transports.
+     */
+    private setupEventHandlers;
+    /**
+     * Starts the gateway, initializing both transports.
+     */
+    start(): Promise<void>;
+    /**
+     * Stops the gateway, closing both transports.
+     */
+    stop(): Promise<void>;
+    /**
+     * Handles errors from the Nostr transport.
+     * @param error The error that occurred.
+     */
+    private handleNostrError;
+    /**
+     * Handles the Nostr transport closing.
+     */
+    private handleNostrClose;
+    /**
+     * Handles errors from the MCP server transport.
+     * @param error The error that occurred.
+     */
+    private handleServerError;
+    /**
+     * Handles the MCP server transport closing.
+     */
+    private handleServerClose;
+    /**
+     * Gets the current status of the gateway.
+     * @returns True if the gateway is running, false otherwise.
+     */
+    isActive(): boolean;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/gateway/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/gateway/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAC/E,OAAO,EAEL,2BAA2B,EAC5B,MAAM,wCAAwC,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,kGAAkG;IAClG,kBAAkB,EAAE,SAAS,CAAC;IAC9B,yDAAyD;IACzD,qBAAqB,EAAE,2BAA2B,CAAC;CACpD;AAED;;;;;;GAMG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAY;IAC/C,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAuB;IAC5D,OAAO,CAAC,SAAS,CAAS;gBAEd,OAAO,EAAE,sBAAsB;IAS3C;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAoB1B;;OAEG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmBnC;;OAEG;IACU,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkBlC;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAIxB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAIxB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAIzB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAIzB;;;OAGG;IACI,QAAQ,IAAI,OAAO;CAG3B"}