tool-mcp

{
  "$schema": "https://recipaie.com/schemas/recipaie.schema.json",
  "name": "tool-mcp",
  "version": "1.0.0",
  "description": "Install MCP bridge tools for AI assistant integration - standalone binaries, no containers required",
  "prerequisites": [
    "Linux, macOS, or Windows with WSL",
    "curl or wget for downloading",
    "Claude Code, Claude Desktop, or Codex installed (for MCP client registration)"
  ],
  "steps": [
    {
      "order": 1,
      "what": "Create local bin directory",
      "why": "MCP tools install as standalone binaries in user's local bin",
      "when": "First installation of any tool-mcp client",
      "skip_if": "~/.local/bin directory already exists",
      "how": "mkdir -p ~/.local/bin",
      "verify": "ls -la ~/.local/bin exists"
    },
    {
      "order": 2,
      "what": "Add local bin to PATH",
      "why": "Ensures binaries are accessible from command line",
      "when": "If ~/.local/bin is not in PATH",
      "skip_if": "echo $PATH | grep -q '.local/bin'",
      "how": "Add 'export PATH=\"$HOME/.local/bin:$PATH\"' to ~/.bashrc or ~/.zshrc",
      "verify": "which pubdoc returns ~/.local/bin/pubdoc after shell restart",
      "comments": [
        "On macOS with zsh: add to ~/.zshrc",
        "On Linux with bash: add to ~/.bashrc",
        "On Windows WSL: add to ~/.bashrc"
      ]
    },
    {
      "order": 3,
      "what": "Download the MCP client binary",
      "why": "Each tool (pubdoc, publog, pubtask, etc.) is a separate binary",
      "when": "Installing a new MCP client or updating",
      "skip_if": "Current version matches latest (check with: pubdoc --version)",
      "how": "Download from https://binary.dixt.io - use 'make install pubdoc' from tool-mcp repo, or download binary directly for your platform (linux-amd64, darwin-arm64, etc.)",
      "verify": "pubdoc --version shows version number",
      "comments": [
        "Available clients: pubdoc, publog, pubtask, pubchk, pubmem, pubvol, pubbin",
        "Binaries are ~6-8MB each with embedded configuration",
        "Auto-updates every 24 hours from binary.dixt.io"
      ]
    },
    {
      "order": 4,
      "what": "Register with MCP clients",
      "why": "Adds the tool to Claude Code/Desktop/Codex configuration",
      "when": "After binary is installed",
      "skip_if": "Tool already registered (check ~/.claude.json or claude mcp list)",
      "how": "pubdoc register",
      "verify": "claude mcp list shows pubdoc",
      "comments": [
        "Registration modifies ~/.claude.json for Claude Code",
        "Also registers with Codex if installed",
        "Use 'pubdoc unregister' to remove"
      ]
    },
    {
      "order": 5,
      "what": "Verify MCP connection",
      "why": "Confirms the tool can communicate with remote MCP server",
      "when": "After registration",
      "how": "pubdoc --tool tool_status",
      "verify": "Response shows version, username, and connection status"
    }
  ],
  "step_count": 5
}

{
  "$schema": "https://recipaie.com/schemas/prodaie.schema.json",
  "name": "tool-mcp",
  "description": "Deployment record showing MCP tool installation across different platforms and common issues encountered",
  "prerequisites": [
    "Linux, macOS, or Windows with WSL",
    "curl or wget for downloading",
    "Claude Code, Claude Desktop, or compatible MCP client"
  ],
  "locations": [
    {
      "path": "macOS (Apple Silicon)",
      "description": "MacBook with M1/M2/M3 chip",
      "status": "complete",
      "step_count": 5,
      "steps": [
        {
          "order": 1,
          "what": "Create local bin directory",
          "why": "MCP tools install as standalone binaries in user's local bin",
          "when": "First installation of any MCP tool",
          "skip_if": "~/.local/bin directory already exists",
          "how": "mkdir -p ~/.local/bin",
          "verify": "ls -la ~/.local/bin exists",
          "success": true,
          "details": "created ~/.local/bin"
        },
        {
          "order": 2,
          "what": "Add local bin to PATH",
          "why": "Ensures binaries are accessible from command line",
          "when": "If ~/.local/bin is not in PATH",
          "skip_if": "echo $PATH | grep -q '.local/bin'",
          "how": "echo 'export PATH=\"$HOME/.local/bin:$PATH\"' >> ~/.zshrc && source ~/.zshrc",
          "verify": "echo $PATH | grep '.local/bin'",
          "success": true,
          "details": "added to ~/.zshrc, reloaded shell"
        },
        {
          "order": 3,
          "what": "Download the MCP client binary",
          "why": "Each MCP tool is a separate binary optimized for your platform",
          "when": "Installing a new MCP client or updating",
          "skip_if": "Current version matches latest",
          "how": "curl -LO https://example.com/mcp-tool/darwin-arm64 && chmod +x mcp-tool && mv mcp-tool ~/.local/bin/",
          "verify": "mcp-tool --version shows version number",
          "success": true,
          "details": "downloaded darwin-arm64 binary, v0.15.2"
        },
        {
          "order": 4,
          "what": "Register with MCP client",
          "why": "Adds the tool to Claude Code/Desktop configuration",
          "when": "After binary is installed",
          "skip_if": "Tool already registered in ~/.claude.json",
          "how": "mcp-tool register",
          "verify": "claude mcp list shows the tool",
          "success": true,
          "details": "registered, appears in claude mcp list"
        },
        {
          "order": 5,
          "what": "Verify MCP connection",
          "why": "Confirms the tool can communicate with remote server",
          "when": "After registration",
          "how": "mcp-tool --tool tool_status",
          "verify": "Response shows version and connection status",
          "success": true,
          "details": "connection verified, auto-update enabled"
        }
      ]
    },
    {
      "path": "Ubuntu 22.04 (WSL2)",
      "description": "Windows Subsystem for Linux - common enterprise setup",
      "status": "complete",
      "step_count": 5,
      "steps": [
        {
          "order": 1,
          "what": "Create local bin directory",
          "why": "MCP tools install as standalone binaries",
          "when": "First installation",
          "skip_if": "~/.local/bin exists",
          "how": "mkdir -p ~/.local/bin",
          "verify": "Directory exists",
          "success": true,
          "details": "created ~/.local/bin"
        },
        {
          "order": 2,
          "what": "Add local bin to PATH",
          "why": "Ensures binaries are accessible",
          "when": "If not in PATH",
          "skip_if": "Already in PATH",
          "how": "echo 'export PATH=\"$HOME/.local/bin:$PATH\"' >> ~/.bashrc",
          "verify": "Path includes .local/bin",
          "success": true,
          "details": "added to ~/.bashrc, opened new terminal to verify"
        },
        {
          "order": 3,
          "what": "Download the MCP client binary",
          "why": "Each tool is a separate binary",
          "when": "Installing or updating",
          "skip_if": "Version matches latest",
          "how": "curl -LO https://example.com/mcp-tool/linux-amd64",
          "verify": "mcp-tool --version works",
          "success": true,
          "details": "downloaded linux-amd64, had to run chmod +x first"
        },
        {
          "order": 4,
          "what": "Register with MCP client",
          "why": "Adds tool to configuration",
          "when": "After install",
          "skip_if": "Already registered",
          "how": "mcp-tool register",
          "verify": "Tool listed",
          "success": true,
          "details": "registration updated ~/.claude.json in Windows home via symlink"
        },
        {
          "order": 5,
          "what": "Verify MCP connection",
          "why": "Confirms communication works",
          "when": "After registration",
          "how": "mcp-tool --tool tool_status",
          "verify": "Shows connection status",
          "success": true,
          "details": "working, note: WSL network sometimes needs wsl --shutdown to reset"
        }
      ]
    },
    {
      "path": "Debian (ARM64 server)",
      "description": "Headless ARM server - Raspberry Pi or cloud ARM instance",
      "status": "partial",
      "step_count": 5,
      "steps": [
        {
          "order": 1,
          "what": "Create local bin directory",
          "why": "MCP tools install as standalone binaries",
          "when": "First installation",
          "skip_if": "Directory exists",
          "how": "mkdir -p ~/.local/bin",
          "verify": "Directory exists",
          "success": true,
          "details": "created ~/.local/bin"
        },
        {
          "order": 2,
          "what": "Add local bin to PATH",
          "why": "Ensures binaries are accessible",
          "when": "If not in PATH",
          "skip_if": "Already in PATH",
          "how": "Add to ~/.bashrc",
          "verify": "Path verified",
          "success": true,
          "details": "added export, sourced bashrc"
        },
        {
          "order": 3,
          "what": "Download the MCP client binary",
          "why": "Each tool is a separate binary",
          "when": "Installing or updating",
          "skip_if": "Version matches",
          "how": "Download linux-arm64 binary",
          "verify": "Binary runs",
          "success": true,
          "details": "downloaded linux-arm64, chmod +x applied"
        },
        {
          "order": 4,
          "what": "Register with MCP client",
          "why": "Adds tool to configuration",
          "when": "After install",
          "skip_if": "Headless server - no GUI client",
          "how": "Skip registration for headless use",
          "verify": "Direct invocation works",
          "success": true,
          "details": "headless server, using direct API invocation instead of registration"
        },
        {
          "order": 5,
          "what": "Verify MCP connection",
          "why": "Confirms communication works",
          "when": "After setup",
          "how": "mcp-tool --tool tool_status",
          "verify": "Shows connection status",
          "success": false,
          "details": "connection timeout, firewall blocking outbound HTTPS on port 443",
          "comments": [
            "Firewall issue resolved by adding outbound HTTPS rule",
            "ARM64 binaries work on Raspberry Pi 4/5 and AWS Graviton instances"
          ]
        }
      ]
    }
  ]
}