dfns-mcp 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Josh Maddington
+
+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,174 @@
+# DFNS MCP Server
+
+A Model Context Protocol (MCP) server that provides AI agents with access to the [DFNS](https://dfns.co) documentation, API reference, and SDK code.
+
+## Features
+
+- **Full-Text Search**: Instantly search across all DFNS guides, API docs, and SDK source code
+- **TypeScript Type Intelligence**: Search and retrieve SDK type definitions with import paths
+- **Auto-Updating Docs**: Documentation is fetched from GitHub on first run and cached locally
+- **Context Initialization**: Dedicated `init` tool to enforce documentation-first behavior
+- **Smart Context**: Retrieve specific documents, code examples, and API endpoint definitions
+- **SDK Intelligence**: Mapped knowledge of supported blockchains and their SDK packages
+
+## Requirements
+
+This MCP server requires [Bun](https://bun.sh) - a fast JavaScript runtime.
+
+**Linux/macOS:**
+```bash
+curl -fsSL https://bun.sh/install | bash
+```
+
+**Windows (PowerShell):**
+```powershell
+powershell -c "irm bun.sh/install.ps1 | iex"
+```
+
+## Quick Start
+
+### Claude Code (Recommended)
+
+```bash
+claude mcp add -s user dfns-docs -- bunx dfns-mcp@latest
+```
+
+The `-s user` flag installs to the user so it's available in all your projects.
+
+### Cursor
+
+Add to your Cursor MCP settings (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "dfns-docs": {
+      "command": "bunx",
+      "args": ["dfns-mcp@latest"]
+    }
+  }
+}
+```
+
+### Codex
+
+```bash
+codex mcp add dfns-docs -- bunx dfns-mcp@latest
+```
+
+### Gemini CLI
+
+Add to your Gemini CLI config (`~/.gemini/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "dfns-docs": {
+      "command": "bunx",
+      "args": ["dfns-mcp@latest"]
+    }
+  }
+}
+```
+
+### Global Installation
+
+If you prefer to install globally instead of using `bunx`:
+
+```bash
+bun install -g dfns-mcp
+
+# Then reference as just "dfns-mcp" in your MCP config
+```
+
+## Agent Instructions (Recommended)
+
+Add this to your global `~/.claude/CLAUDE.md` (or `~/AGENTS.md` for other agents) to ensure your AI always uses up-to-date DFNS documentation:
+
+```markdown
+## DFNS Development
+
+When working with DFNS (wallet infrastructure, key management, blockchain integrations):
+
+1. **Always** call `mcp__dfns-docs__init` at the start of any DFNS-related task
+2. **Never** rely on training data for DFNS APIs - always use `search_docs` and `get_doc` to verify
+3. Use `search_types` and `get_type` to get accurate TypeScript type definitions
+4. DFNS APIs and SDKs change frequently - the MCP server has the latest documentation
+```
+
+This prevents agents from hallucinating outdated API signatures or SDK patterns.
+
+## How It Works
+
+On first run, the server automatically downloads the latest DFNS documentation from GitHub and caches it locally in `~/.cache/dfns-mcp/`. The cache is refreshed every 24 hours automatically, or you can force an update using the `update_docs` tool.
+
+## Available Tools
+
+### Documentation Tools
+
+| Tool | Description |
+|------|-------------|
+| **`init`** | **CALL THIS FIRST.** Initializes the session and mandates strict documentation adherence |
+| `search_docs` | Search all documentation and SDK files |
+| `get_doc` | Retrieve the full content of a specific document |
+| `list_docs` | List available documents by category |
+| `get_code_examples` | Extract code snippets for a specific topic |
+| `browse_api_structure` | View hierarchical API endpoint structure |
+| `get_api_endpoint` | Get details for a specific API endpoint (e.g., `POST /wallets`) |
+| `get_blockchain_info` | Get SDK package info for a specific chain (e.g., `Solana`) |
+| `list_blockchains` | List all supported blockchains with their SDK packages |
+
+### TypeScript Type Tools
+
+| Tool | Description |
+|------|-------------|
+| `search_types` | Search SDK types by name (e.g., "Wallet", "Signer", "Transaction") |
+| `get_type` | Get full type definition, import path, and usage |
+| `list_types` | List all types by category |
+
+### Cache Management
+
+| Tool | Description |
+|------|-------------|
+| `update_docs` | Force update the documentation cache from GitHub |
+| `cache_info` | Get information about the cache (location, last update, etc.) |
+
+## Resources
+
+The server also exposes these quick-reference resources:
+
+| Resource URI | Description |
+|--------------|-------------|
+| `dfns://quickref/authentication` | Authentication patterns and code samples |
+| `dfns://quickref/sdk-setup` | Package installation and setup guide |
+| `dfns://quickref/networks` | All supported blockchain networks |
+
+## Best Practices for Agents
+
+When using this server, agents should follow this workflow:
+
+1. **Initialize**: Call `init` immediately to establish the "Documentation First" protocol
+2. **Search**: Use `search_docs` to find relevant information before answering ANY question
+3. **Read**: Use `get_doc` to read the actual source material
+4. **Answer**: Formulate responses based *only* on the retrieved context
+
+## Development
+
+```bash
+# Clone the repo
+git clone https://github.com/jmaddington/dfns-mcp.git
+cd dfns-mcp
+
+# Install dependencies
+bun install
+
+# Run in development mode with auto-reload
+bun run dev
+
+# Test with MCP Inspector
+bun run inspect
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "dfns-mcp",
+  "version": "1.2.0",
+  "description": "MCP server for DFNS documentation and SDK reference - provides AI agents with access to DFNS API docs, TypeScript types, and code examples",
+  "module": "src/index.ts",
+  "type": "module",
+  "bin": {
+    "dfns-mcp": "./src/index.ts"
+  },
+  "files": [
+    "src/**/*.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "dev": "bun --watch run src/index.ts",
+    "inspect": "bunx @modelcontextprotocol/inspector bun run src/index.ts"
+  },
+  "keywords": [
+    "mcp",
+    "dfns",
+    "wallet",
+    "crypto",
+    "blockchain",
+    "ai",
+    "claude",
+    "documentation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jhubbardsf/dfns-mcp.git"
+  },
+  "author": "Josh Hubbard",
+  "license": "MIT",
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.23.0",
+    "tar": "^7.4.3",
+    "zod": "^4.1.13"
+  }
+}

package/src/docs-fetcher.ts

@@ -0,0 +1,264 @@
+import { mkdir, stat, rm, readFile, writeFile, rename } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { createWriteStream } from "node:fs";
+import { pipeline } from "node:stream/promises";
+import { Readable } from "node:stream";
+import { createGunzip } from "node:zlib";
+import { extract } from "tar";
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+const CACHE_DIR = join(homedir(), ".cache", "dfns-mcp");
+const METADATA_FILE = join(CACHE_DIR, "metadata.json");
+
+const REPOS = {
+  "dfns-api-docs": {
+    owner: "dfns",
+    repo: "dfns-api-docs",
+    branch: "m", // DFNS uses 'm' as their default branch
+  },
+  "dfns-sdk-ts": {
+    owner: "dfns",
+    repo: "dfns-sdk-ts",
+    branch: "m", // DFNS uses 'm' as their default branch
+  },
+};
+
+// How often to check for updates (24 hours)
+const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+interface CacheMetadata {
+  lastUpdated: number;
+  repos: {
+    [key: string]: {
+      sha: string;
+      fetchedAt: number;
+    };
+  };
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readMetadata(): Promise<CacheMetadata | null> {
+  try {
+    const content = await readFile(METADATA_FILE, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+async function writeMetadata(metadata: CacheMetadata): Promise<void> {
+  await writeFile(METADATA_FILE, JSON.stringify(metadata, null, 2));
+}
+
+/**
+ * Fetch the latest commit SHA for a branch
+ */
+async function getLatestSha(owner: string, repo: string, branch: string): Promise<string | null> {
+  try {
+    const response = await fetch(
+      `https://api.github.com/repos/${owner}/${repo}/commits/${branch}`,
+      {
+        headers: {
+          "Accept": "application/vnd.github.v3+json",
+          "User-Agent": "dfns-mcp",
+        },
+      }
+    );
+
+    if (!response.ok) {
+      console.error(`Failed to fetch SHA: ${response.status}`);
+      return null;
+    }
+
+    const data = await response.json() as { sha: string };
+    return data.sha;
+  } catch (err) {
+    console.error(`Error fetching SHA:`, err);
+    return null;
+  }
+}
+
+/**
+ * Download and extract a GitHub repository tarball
+ */
+async function downloadAndExtractRepo(
+  owner: string,
+  repo: string,
+  branch: string,
+  targetDir: string
+): Promise<void> {
+  const url = `https://github.com/${owner}/${repo}/archive/refs/heads/${branch}.tar.gz`;
+  const tempDir = join(CACHE_DIR, `${repo}-temp-${Date.now()}`);
+
+  console.error(`Downloading ${owner}/${repo}...`);
+
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to download ${url}: ${response.status}`);
+  }
+
+  // Create temp directory
+  await mkdir(tempDir, { recursive: true });
+
+  // Extract the tarball
+  const body = response.body;
+  if (!body) {
+    throw new Error("No response body");
+  }
+
+  // Convert web stream to Node stream and extract
+  const nodeStream = Readable.fromWeb(body as any);
+
+  await pipeline(
+    nodeStream,
+    createGunzip(),
+    extract({
+      cwd: tempDir,
+      strip: 1, // Remove the top-level directory (e.g., dfns-api-docs-main/)
+    })
+  );
+
+  // Remove old target if exists
+  if (await exists(targetDir)) {
+    await rm(targetDir, { recursive: true });
+  }
+
+  // Rename temp to target
+  await rename(tempDir, targetDir);
+
+  console.error(`Extracted to ${targetDir}`);
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+export interface DocsPaths {
+  docsDir: string;
+  sdkDir: string;
+  fromCache: boolean;
+}
+
+/**
+ * Ensure docs are available, downloading if necessary.
+ * Returns paths to the docs and SDK directories.
+ */
+export async function ensureDocs(forceUpdate: boolean = false): Promise<DocsPaths> {
+  // Create cache directory
+  await mkdir(CACHE_DIR, { recursive: true });
+
+  const docsDir = join(CACHE_DIR, "dfns-api-docs");
+  const sdkDir = join(CACHE_DIR, "dfns-sdk-ts");
+
+  const metadata = await readMetadata();
+  const now = Date.now();
+
+  // Check if we need to update
+  const docsExist = await exists(docsDir) && await exists(sdkDir);
+  const needsUpdate = forceUpdate ||
+    !docsExist ||
+    !metadata ||
+    (now - metadata.lastUpdated > UPDATE_CHECK_INTERVAL_MS);
+
+  if (!needsUpdate && docsExist) {
+    console.error("Using cached documentation");
+    return { docsDir, sdkDir, fromCache: true };
+  }
+
+  // Download/update repos
+  const newMetadata: CacheMetadata = {
+    lastUpdated: now,
+    repos: {},
+  };
+
+  for (const [name, config] of Object.entries(REPOS)) {
+    const targetDir = name === "dfns-api-docs" ? docsDir : sdkDir;
+    const currentSha = metadata?.repos[name]?.sha;
+
+    // Check if there's a new version
+    const latestSha = await getLatestSha(config.owner, config.repo, config.branch);
+
+    if (!forceUpdate && latestSha && latestSha === currentSha && await exists(targetDir)) {
+      console.error(`${name} is up to date (${latestSha.slice(0, 7)})`);
+      newMetadata.repos[name] = metadata!.repos[name];
+      continue;
+    }
+
+    // Download the repo
+    await downloadAndExtractRepo(
+      config.owner,
+      config.repo,
+      config.branch,
+      targetDir
+    );
+
+    newMetadata.repos[name] = {
+      sha: latestSha || "unknown",
+      fetchedAt: now,
+    };
+  }
+
+  // Save metadata
+  await writeMetadata(newMetadata);
+
+  return { docsDir, sdkDir, fromCache: false };
+}
+
+/**
+ * Force update all docs
+ */
+export async function updateDocs(): Promise<{ success: boolean; message: string }> {
+  try {
+    const result = await ensureDocs(true);
+    return {
+      success: true,
+      message: `Documentation updated successfully. Docs at: ${result.docsDir}`,
+    };
+  } catch (err) {
+    return {
+      success: false,
+      message: `Failed to update documentation: ${err}`,
+    };
+  }
+}
+
+/**
+ * Get the cache directory path
+ */
+export function getCacheDir(): string {
+  return CACHE_DIR;
+}
+
+/**
+ * Get cached metadata
+ */
+export async function getCacheInfo(): Promise<{
+  cacheDir: string;
+  metadata: CacheMetadata | null;
+  docsExist: boolean;
+  sdkExist: boolean;
+}> {
+  const metadata = await readMetadata();
+  return {
+    cacheDir: CACHE_DIR,
+    metadata,
+    docsExist: await exists(join(CACHE_DIR, "dfns-api-docs")),
+    sdkExist: await exists(join(CACHE_DIR, "dfns-sdk-ts")),
+  };
+}