@enconvo/dxt 0.2.6

package/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright 2025 Anthropic, PBC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+# Desktop Extensions (DXT)
+
+Desktop Extensions (`.dxt`) are zip archives containing a local MCP server and a `manifest.json` that describes the server and its capabilities. The format is spiritually similar to Chrome extensions (`.crx`) or VS Code extensions (`.vsix`), enabling end users to install local MCP servers with a single click.
+
+This repository provides three components: The extension specification in [MANIFEST.md](MANIFEST.md), a CLI tool for creating extensions (see [CLI.md](CLI.md)), and the code used by Claude for macOS and Windows to load and verify DXT extensions ([src/index.ts](src/index.ts)).
+
+- For developers of local MCP servers, we aim to make distribution and installation of said servers convenient
+- For developers of apps supporting local MCP servers, we aim to make it easy to add support for DXT extensions
+
+Claude for macOS and Windows uses the code in this repository to enable single-click installation of local MCP servers, including a number of end user-friendly features - such as automatic updates, easy configuration of MCP servers and the variables and parameters they need, and a curated directory. We are committed to the open ecosystem around MCP servers and believe that its ability to be universally adopted by multiple applications and services has benefits developers aiming to connect AI tools to other apps and services. Consequently, we’re open-sourcing the Desktop Extension specification, toolchain, and the schemas and key functions used by Claude for macOS and Windows to implement its own support of Desktop Extensions. It is our hope that the `dxt` format doesn’t just make local MCP servers more portable for Claude, but other AI desktop applications, too.
+
+# For Extension Developers
+
+At the core, DXT are simple zip files containing your entire MCP server and a `manifest.json`. Consequently, turning a local MCP server into an extension is straightforward: You just have to put all your required files in a folder, create a `manifest.json`, and then create an archive.
+
+To make this process easier, this package offers a CLI that helps you with the creation of both the `manifest.json` and the final `.dxt` file. To install it, run:
+
+```sh
+npm install -g @anthropic-ai/dxt
+```
+
+1. In a folder containing your local MCP server, run `dxt init`. This command will guide you through the creation of a `manifest.json`.
+2. Run `dxt pack` to create a `dxt` file.
+3. Now, any app implementing support for DXT can run your local MCP server. As an example, open the file with Claude for macOS and Windows to show an installation dialog.
+
+You can find the full spec for the `manifest.json` and all its mandatory and optional fields in [MANIFEST.md](MANIFEST.md). Examples for extensions can be found in [examples](./examples/).
+
+## Prompt Template for AI Tools
+
+AI tools like Claude Code are particularly good at creating desktop extensions when informed about the spec. When prompting an AI coding tool to build an extension, briefly explain what your extension aims to do - then add the following context to your instructions.
+
+> I want to build this as a Desktop Extension, abbreviated as "DXT". Please follow these steps:
+>
+> 1. **Read the specifications thoroughly:**
+>    - https://github.com/anthropics/dxt/blob/main/README.md - DXT architecture overview, capabilities, and integration
+>      patterns
+>    - https://github.com/anthropics/dxt/blob/main/MANIFEST.md - Complete extension manifest structure and field definitions
+>    - https://github.com/anthropics/dxt/tree/main/examples - Reference implementations including a "Hello World" example
+> 2. **Create a proper extension structure:**
+>    - Generate a valid manifest.json following the MANIFEST.md spec
+>    - Implement an MCP server using @modelcontextprotocol/sdk with proper tool definitions
+>    - Include proper error handling, security measures, and timeout management
+> 3. **Follow best development practices:**
+>    - Implement proper MCP protocol communication via stdio transport
+>    - Structure tools with clear schemas, validation, and consistent JSON responses
+>    - Make use of the fact that this extension will be running locally
+>    - Add appropriate logging and debugging capabilities
+>    - Include proper documentation and setup instructions
+> 4. **Test considerations:**
+>    - Validate that all tool calls return properly structured responses
+>    - Verify manifest loads correctly and host integration works
+>
+> Generate complete, production-ready code that can be immediately tested. Focus on defensive programming, clear error messages, and following the exact DXT specifications to ensure compatibility with the ecosystem.
+
+## Directory Structures
+
+### Minimal Extension
+
+A `manifest.json` is the only required file.
+
+### Example: Node.js Extension
+
+```
+extension.dxt (ZIP file)
+├── manifest.json         # Required: Extension metadata and configuration
+├── server/               # Server files
+│   └── index.js          # Main entry point
+├── node_modules/         # Bundled dependencies
+├── package.json          # Optional: NPM package definition
+├── icon.png              # Optional: Extension icon
+└── assets/               # Optional: Additional assets
+```
+
+### Example: Python Extension
+
+```
+extension.dxt (ZIP file)
+├── manifest.json         # Required: Extension metadata and configuration
+├── server/               # Server files
+│   ├── main.py           # Main entry point
+│   └── utils.py          # Additional modules
+├── lib/                  # Bundled Python packages
+├── requirements.txt      # Optional: Python dependencies list
+└── icon.png              # Optional: Extension icon
+```
+
+### Example: Binary Extension
+
+```
+extension.dxt (ZIP file)
+├── manifest.json         # Required: Extension metadata and configuration
+├── server/               # Server files
+│   ├── my-server         # Unix executable
+│   ├── my-server.exe     # Windows executable
+└── icon.png              # Optional: Extension icon
+```
+
+### Bundling Dependencies
+
+**Python Extensions:**
+
+- Bundle all required packages in `server/lib/` directory
+- OR bundle a complete virtual environment in `server/venv/`
+- Use tools like `pip-tools`, `poetry`, or `pipenv` to create reproducible bundles
+- Set `PYTHONPATH` to include bundled packages via `mcp_config.env`
+
+**Node.js Extensions:**
+
+- Run `npm install --production` to create `node_modules`
+- Bundle the entire `node_modules` directory with your extension
+- Use `npm ci` or `yarn install --frozen-lockfile` for reproducible builds
+- Server entry point specified in manifest.json's `server.entry_point`
+
+**Binary Extensions:**
+
+- Static linking preferred for maximum compatibility
+- Include all required shared libraries if dynamic linking used
+- Test on clean systems without development tools

package/dist/browser.d.ts

@@ -0,0 +1,3 @@
+export * from "./schemas.js";
+export * from "./shared/config.js";
+export * from "./types.js";

package/dist/browser.js

@@ -0,0 +1,4 @@
+// Browser-compatible exports
+export * from "./schemas.js";
+export * from "./shared/config.js";
+export * from "./types.js";

package/dist/cli/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/cli.js

@@ -0,0 +1,275 @@
+#!/usr/bin/env node
+import { execSync } from "child_process";
+import { Command } from "commander";
+import { existsSync, readFileSync, statSync } from "fs";
+import { basename, dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+import { signDxtFile, unsignDxtFile, verifyDxtFile } from "../node/sign.js";
+import { cleanDxt, validateManifest } from "../node/validate.js";
+import { initExtension } from "./init.js";
+import { packExtension } from "./pack.js";
+import { unpackExtension } from "./unpack.js";
+// ES modules equivalent of __dirname
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Get version from package.json
+const packageJsonPath = join(__dirname, "..", "..", "package.json");
+const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+const version = packageJson.version;
+/**
+ * Create a self-signed certificate for signing DXT extensions
+ */
+function createSelfSignedCertificate(certPath, keyPath) {
+    const subject = "/CN=DXT Self-Signed Certificate/O=DXT Extensions/C=US";
+    try {
+        // Generate a self-signed certificate valid for 10 years, no password
+        execSync(`openssl req -x509 -newkey rsa:4096 -keyout "${keyPath}" -out "${certPath}" -days 3650 -nodes -subj "${subject}"`, { stdio: "pipe" });
+    }
+    catch (error) {
+        throw new Error(`Failed to create self-signed certificate: ${error}`);
+    }
+}
+// Create the CLI program
+const program = new Command();
+program
+    .name("dxt")
+    .description("Tools for building Desktop Extensions")
+    .version(version);
+// Init command
+program
+    .command("init [directory]")
+    .description("Create a new DXT extension manifest")
+    .option("-y, --yes", "Accept all defaults (non-interactive mode)")
+    .action((directory, options) => {
+    void (async () => {
+        try {
+            const success = await initExtension(directory, options?.yes);
+            process.exit(success ? 0 : 1);
+        }
+        catch (error) {
+            console.error(`ERROR: ${error instanceof Error ? error.message : "Unknown error"}`);
+            process.exit(1);
+        }
+    })();
+});
+// Validate command
+program
+    .command("validate <manifest>")
+    .description("Validate a DXT manifest file")
+    .action((manifestPath) => {
+    const success = validateManifest(manifestPath);
+    process.exit(success ? 0 : 1);
+});
+// Clean command
+program
+    .command("clean <dxt>")
+    .description("Cleans a DXT file, validates the manifest, and minimizes bundle size")
+    .action(async (dxtFile) => {
+    await cleanDxt(dxtFile);
+});
+// Pack command
+program
+    .command("pack [directory] [output]")
+    .description("Pack a directory into a DXT extension")
+    .action((directory = process.cwd(), output) => {
+    void (async () => {
+        try {
+            const success = await packExtension({
+                extensionPath: directory,
+                outputPath: output,
+            });
+            process.exit(success ? 0 : 1);
+        }
+        catch (error) {
+            console.error(`ERROR: ${error instanceof Error ? error.message : "Unknown error"}`);
+            process.exit(1);
+        }
+    })();
+});
+// Unpack command
+program
+    .command("unpack <dxt-file> [output]")
+    .description("Unpack a DXT extension file")
+    .action((dxtFile, output) => {
+    void (async () => {
+        try {
+            const success = await unpackExtension({
+                dxtPath: dxtFile,
+                outputDir: output,
+            });
+            process.exit(success ? 0 : 1);
+        }
+        catch (error) {
+            console.error(`ERROR: ${error instanceof Error ? error.message : "Unknown error"}`);
+            process.exit(1);
+        }
+    })();
+});
+// Sign command
+program
+    .command("sign <dxt-file>")
+    .description("Sign a DXT extension file")
+    .option("-c, --cert <path>", "Path to certificate file (PEM format)", "cert.pem")
+    .option("-k, --key <path>", "Path to private key file (PEM format)", "key.pem")
+    .option("-i, --intermediate <paths...>", "Paths to intermediate certificate files")
+    .option("--self-signed", "Create a self-signed certificate if none exists")
+    .action((dxtFile, options) => {
+    void (async () => {
+        try {
+            const dxtPath = resolve(dxtFile);
+            if (!existsSync(dxtPath)) {
+                console.error(`ERROR: DXT file not found: ${dxtFile}`);
+                process.exit(1);
+            }
+            let certPath = options.cert;
+            let keyPath = options.key;
+            // Create self-signed certificate if requested
+            if (options.selfSigned) {
+                const dxtDir = resolve(__dirname, "..");
+                certPath = join(dxtDir, "self-signed-cert.pem");
+                keyPath = join(dxtDir, "self-signed-key.pem");
+                if (!existsSync(certPath) || !existsSync(keyPath)) {
+                    console.log("Creating self-signed certificate...");
+                    createSelfSignedCertificate(certPath, keyPath);
+                    console.log("Self-signed certificate created");
+                }
+                else {
+                    console.log("Using existing self-signed certificate");
+                }
+            }
+            else {
+                // Check for manual certificate paths
+                if (!existsSync(certPath)) {
+                    console.error(`ERROR: Certificate file not found: ${certPath}`);
+                    console.log("Tip: Use --self-signed to create a self-signed certificate");
+                    process.exit(1);
+                }
+                if (!existsSync(keyPath)) {
+                    console.error(`ERROR: Private key file not found: ${keyPath}`);
+                    process.exit(1);
+                }
+            }
+            console.log(`Signing ${basename(dxtPath)}...`);
+            signDxtFile(dxtPath, certPath, keyPath, options.intermediate);
+            console.log(`Successfully signed ${basename(dxtPath)}`);
+            // Display certificate info
+            const signatureInfo = await verifyDxtFile(dxtPath);
+            if (signatureInfo.status === "signed" ||
+                signatureInfo.status === "self-signed") {
+                console.log(`Signed by: ${signatureInfo.publisher}`);
+                console.log(`Issuer: ${signatureInfo.issuer}`);
+                if (signatureInfo.status === "self-signed") {
+                    console.log(`Warning: Certificate is self-signed`);
+                }
+            }
+        }
+        catch (error) {
+            console.log(`ERROR: Signing failed: ${error instanceof Error ? error.message : "Unknown error"}`);
+            process.exit(1);
+        }
+    })();
+});
+// Verify command
+program
+    .command("verify <dxt-file>")
+    .description("Verify the signature of a DXT extension file")
+    .action((dxtFile) => {
+    void (async () => {
+        try {
+            const dxtPath = resolve(dxtFile);
+            if (!existsSync(dxtPath)) {
+                console.error(`ERROR: DXT file not found: ${dxtFile}`);
+                process.exit(1);
+            }
+            console.log(`Verifying ${basename(dxtPath)}...`);
+            const result = await verifyDxtFile(dxtPath);
+            if (result.status === "signed") {
+                console.log(`Signature is valid`);
+                console.log(`Signed by: ${result.publisher}`);
+                console.log(`Issuer: ${result.issuer}`);
+                console.log(`Valid from: ${new Date(result.valid_from).toLocaleDateString()} to ${new Date(result.valid_to).toLocaleDateString()}`);
+                console.log(`Fingerprint: ${result.fingerprint}`);
+            }
+            else if (result.status === "self-signed") {
+                console.log(`Signature is valid (self-signed)`);
+                console.log(`WARNING: This extension is self-signed`);
+                console.log(`Signed by: ${result.publisher}`);
+                console.log(`Valid from: ${new Date(result.valid_from).toLocaleDateString()} to ${new Date(result.valid_to).toLocaleDateString()}`);
+                console.log(`Fingerprint: ${result.fingerprint}`);
+            }
+            else {
+                console.error(`ERROR: Extension is not signed`);
+                process.exit(1);
+            }
+        }
+        catch (error) {
+            console.log(`ERROR: Verification failed: ${error instanceof Error ? error.message : "Unknown error"}`);
+            process.exit(1);
+        }
+    })();
+});
+// Info command
+program
+    .command("info <dxt-file>")
+    .description("Display information about a DXT extension file")
+    .action((dxtFile) => {
+    void (async () => {
+        try {
+            const dxtPath = resolve(dxtFile);
+            if (!existsSync(dxtPath)) {
+                console.error(`ERROR: DXT file not found: ${dxtFile}`);
+                process.exit(1);
+            }
+            const stat = statSync(dxtPath);
+            console.log(`File: ${basename(dxtPath)}`);
+            console.log(`Size: ${(stat.size / 1024).toFixed(2)} KB`);
+            // Check if signed
+            const signatureInfo = await verifyDxtFile(dxtPath);
+            if (signatureInfo.status === "signed") {
+                console.log(`\nSignature Information:`);
+                console.log(`  Subject: ${signatureInfo.publisher}`);
+                console.log(`  Issuer: ${signatureInfo.issuer}`);
+                console.log(`  Valid from: ${new Date(signatureInfo.valid_from).toLocaleDateString()} to ${new Date(signatureInfo.valid_to).toLocaleDateString()}`);
+                console.log(`  Fingerprint: ${signatureInfo.fingerprint}`);
+                console.log(`  Status: Valid`);
+            }
+            else if (signatureInfo.status === "self-signed") {
+                console.log(`\nSignature Information:`);
+                console.log(`  Subject: ${signatureInfo.publisher}`);
+                console.log(`  Issuer: ${signatureInfo.issuer} (self-signed)`);
+                console.log(`  Valid from: ${new Date(signatureInfo.valid_from).toLocaleDateString()} to ${new Date(signatureInfo.valid_to).toLocaleDateString()}`);
+                console.log(`  Fingerprint: ${signatureInfo.fingerprint}`);
+                console.log(`  Status: Valid (self-signed)`);
+            }
+            else {
+                console.log(`\nWARNING: Not signed`);
+            }
+        }
+        catch (error) {
+            console.log(`ERROR: Failed to read DXT info: ${error instanceof Error ? error.message : "Unknown error"}`);
+            process.exit(1);
+        }
+    })();
+});
+// Unsign command (for development/testing)
+program
+    .command("unsign <dxt-file>")
+    .description("Remove signature from a DXT extension file")
+    .action((dxtFile) => {
+    try {
+        const dxtPath = resolve(dxtFile);
+        if (!existsSync(dxtPath)) {
+            console.error(`ERROR: DXT file not found: ${dxtFile}`);
+            process.exit(1);
+        }
+        console.log(`Removing signature from ${basename(dxtPath)}...`);
+        unsignDxtFile(dxtPath);
+        console.log(`Signature removed`);
+    }
+    catch (error) {
+        console.log(`ERROR: Failed to remove signature: ${error instanceof Error ? error.message : "Unknown error"}`);
+        process.exit(1);
+    }
+});
+// Parse command line arguments
+program.parse();

package/dist/cli/init.d.ts

@@ -0,0 +1,185 @@
+import type { DxtManifest } from "../types.js";
+interface PackageJson {
+    name?: string;
+    version?: string;
+    description?: string;
+    main?: string;
+    author?: string | {
+        name?: string;
+        email?: string;
+        url?: string;
+    };
+    repository?: string | {
+        type?: string;
+        url?: string;
+    };
+    license?: string;
+}
+export declare function readPackageJson(dirPath: string): PackageJson;
+export declare function getDefaultAuthorName(packageData: PackageJson): string;
+export declare function getDefaultAuthorEmail(packageData: PackageJson): string;
+export declare function getDefaultAuthorUrl(packageData: PackageJson): string;
+export declare function getDefaultRepositoryUrl(packageData: PackageJson): string;
+export declare function getDefaultBasicInfo(packageData: PackageJson, resolvedPath: string): {
+    name: string;
+    authorName: string;
+    displayName: string;
+    version: string;
+    description: string;
+};
+export declare function getDefaultAuthorInfo(packageData: PackageJson): {
+    authorEmail: string;
+    authorUrl: string;
+};
+export declare function getDefaultServerConfig(packageData?: PackageJson): {
+    serverType: "node";
+    entryPoint: string;
+    mcp_config: {
+        command: string;
+        args: string[];
+        env?: Record<string, string>;
+    };
+};
+export declare function getDefaultOptionalFields(packageData: PackageJson): {
+    keywords: string;
+    license: string;
+    repository: undefined;
+};
+export declare function createMcpConfig(serverType: "node" | "python" | "binary", entryPoint: string): {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+};
+export declare function getDefaultEntryPoint(serverType: "node" | "python" | "binary", packageData?: PackageJson): string;
+export declare function promptBasicInfo(packageData: PackageJson, resolvedPath: string): Promise<{
+    name: string;
+    authorName: string;
+    displayName: string;
+    version: string;
+    description: string;
+}>;
+export declare function promptAuthorInfo(packageData: PackageJson): Promise<{
+    authorEmail: string;
+    authorUrl: string;
+}>;
+export declare function promptServerConfig(packageData?: PackageJson): Promise<{
+    serverType: "python" | "node" | "binary";
+    entryPoint: string;
+    mcp_config: {
+        command: string;
+        args: string[];
+        env?: Record<string, string>;
+    };
+}>;
+export declare function promptTools(): Promise<{
+    tools: {
+        name: string;
+        description?: string;
+    }[];
+    toolsGenerated: boolean;
+}>;
+export declare function promptPrompts(): Promise<{
+    prompts: {
+        name: string;
+        description?: string;
+        arguments?: string[];
+        text: string;
+    }[];
+    promptsGenerated: boolean;
+}>;
+export declare function promptOptionalFields(packageData: PackageJson): Promise<{
+    keywords: string;
+    license: string;
+    repository: {
+        type: string;
+        url: string;
+    } | undefined;
+}>;
+export declare function promptLongDescription(description: string): Promise<string | undefined>;
+export declare function promptUrls(): Promise<{
+    homepage: string;
+    documentation: string;
+    support: string;
+}>;
+export declare function promptVisualAssets(): Promise<{
+    icon: string;
+    screenshots: string[];
+}>;
+export declare function promptCompatibility(serverType: "node" | "python" | "binary"): Promise<{
+    runtimes?: {
+        python?: string;
+        node?: string;
+    } | undefined;
+    platforms?: ("darwin" | "win32" | "linux")[] | undefined;
+} | undefined>;
+export declare function promptUserConfig(): Promise<Record<string, {
+    type: "string" | "number" | "boolean" | "directory" | "file";
+    title: string;
+    description: string;
+    required?: boolean;
+    default?: string | number | boolean | string[];
+    multiple?: boolean;
+    sensitive?: boolean;
+    min?: number;
+    max?: number;
+}>>;
+export declare function buildManifest(basicInfo: {
+    name: string;
+    displayName: string;
+    version: string;
+    description: string;
+    authorName: string;
+}, longDescription: string | undefined, authorInfo: {
+    authorEmail: string;
+    authorUrl: string;
+}, urls: {
+    homepage: string;
+    documentation: string;
+    support: string;
+}, visualAssets: {
+    icon: string;
+    screenshots: string[];
+}, serverConfig: {
+    serverType: "node" | "python" | "binary";
+    entryPoint: string;
+    mcp_config: {
+        command: string;
+        args: string[];
+        env?: Record<string, string>;
+    };
+}, tools: Array<{
+    name: string;
+    description?: string;
+}>, toolsGenerated: boolean, prompts: Array<{
+    name: string;
+    description?: string;
+    arguments?: string[];
+    text: string;
+}>, promptsGenerated: boolean, compatibility: {
+    claude_desktop?: string;
+    platforms?: ("darwin" | "win32" | "linux")[];
+    runtimes?: {
+        python?: string;
+        node?: string;
+    };
+} | undefined, userConfig: Record<string, {
+    type: "string" | "number" | "boolean" | "directory" | "file";
+    title: string;
+    description: string;
+    required?: boolean;
+    default?: string | number | boolean | string[];
+    multiple?: boolean;
+    sensitive?: boolean;
+    min?: number;
+    max?: number;
+}>, optionalFields: {
+    keywords: string;
+    license: string;
+    repository?: {
+        type: string;
+        url: string;
+    };
+}): DxtManifest;
+export declare function printNextSteps(): void;
+export declare function initExtension(targetPath?: string, nonInteractive?: boolean): Promise<boolean>;
+export {};