MCP-Asset-Viewer Server

Introduction

This component functions as a specialized Model Context Protocol (MCP) endpoint, engineered to facilitate seamless data exchange between large language models and the Bitcoin Ordinals ecosystem. Its primary objective is to parse raw transaction metadata (witness data) and render the encapsulated digital asset content for AI consumption.

🎮 Demonstration

Asset Retrieval Example Video Link

🗺️ Navigation Map

• MCP-Asset-Viewer Server
• Introduction
• 🗺️ Navigation Map
• ⚙️ Core Capabilities
• 🤖 Goose Agent Integration
  • STDIO (Local Process Hook)
  • SSE (Remote Service Hook)
• 🖥️ Claude Desktop Connectivity
  • Validation Steps for Desktop Client
• 🗂️ Project Hierarchy
• 🛠️ Deployment Prerequisites
• 📚 Available Utilities
  • reveal_inscription
• ⚠️ Exception Management
• 📢 Community Contributions
• ⚖️ Licensing

⚙️ Core Capabilities

• Inscription Parsing: Intelligent identification and decoding of Bitcoin transaction outputs to accurately interpret inscription artifacts, supporting serialized text, binary image data, JSON payloads, and runestone metadata.

🤖 Goose Agent Integration

Goose, the agent framework from Block, utilizes the Model Context Protocol for extension functionality. This Asset Viewer service can be registered as a Goose extension to grant the agent visibility into Ordinals data. Integration supports two primary transport mechanisms: local execution via STDIO or networked communication over Server-Sent Events (SSE).

Using STDIO (Local Process Hook)

This method establishes a direct, synchronous communication channel between Goose and the Asset Viewer running as a child process.

1. Source Acquisition & Compilation: bash git clone https://github.com/Laz1mov/mcp-inscription cd mcp-inscription npm install npm run build

Retain the absolute directory path for the subsequent configuration step.

1. Extension Registration in Goose: Access Goose's configuration panel (goose configure or via the Desktop app: Settings > Extensions). Select "Add Extension." (Using Extensions | goose)

2. Select Transport Type – Command-Line: Choose Command-Line Extension so Goose manages the process lifecycle via standard I/O streams (Using Extensions | goose).

3. Input Configuration Parameters: Define the identifier and execution path:

4. ID: mcp-inscription

5. Name: Descriptive label (e.g., "Ordinal Data Provider").

6. Command: The absolute path pointing to the compiled executable script:

   bash node /absolute/path/to/mcp-inscription/build/cli.js

   Substitute the placeholder path with the actual location.

7. Activation: Finalize the setup. The extension must be toggled to the enabled state within Goose's global or session settings.

8. Session Launch: Initiate a Goose session explicitly referencing the registered extension ID for activation:

bash goose session --with-extension "mcp-inscription"

This ensures the local server is available for tool invocation during that session (Using Extensions | goose).

SSE (Remote Service Hook)

This is appropriate for instances where the viewer runs as a persistent, detached network service.

1. Initiate Standalone Service: Execute the viewer in SSE mode, typically binding to a specific network port (defaulting to 3000):

bash # Within the project root cd /path/to/mcp-inscription npm run build

# Start service, binding to port 9000 SERVER_MODE=sse PORT=9000 node build/cli.js

1. Register Remote Extension in Goose: In the Goose configuration UI/CLI, select Add Extension, but choose Remote Extension (Using Extensions | goose).

2. Supply Connection Endpoint: Provide the base URL where the service is reachable. If running locally on port 9000, the URL would be http://localhost:9000. Goose automatically targets the correct MCP SSE endpoint relative to this base address.

3. Verification: Confirm the remote extension is active. Only one connection method (STDIO or SSE) for this toolset should be enabled concurrently.

Tool Invocation Example: After successful setup, the agent can be prompted:

• "Query the contents of Inscription ID: 0169d12c4edf2026a67e219c10207438a080eb82d8f21860f6784dd66f281389."

Refer to the official Goose documentation for advanced discovery protocols and supplementary MCP server directories (Using Extensions | goose).

🖥️ Claude Desktop Connectivity

Integration with Anthropic's Claude Desktop application requires modifying its local configuration file to recognize and initiate the MCP server upon startup.

1. Acquire Claude Desktop: Download and install the latest version of the native Claude application for your OS.

2. Source Code Preparation: Compile the service locally as detailed previously (clone, npm install, npm run build).

3. Configuration Modification: Locate and edit the designated configuration file:

4. macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

5. Windows: %APPDATA%\Claude\claude_desktop_config.json

Inject the server definition into the "mcpServers" object:

{ "mcpServers": { "mcp-inscription": { "command": "node", "args": ["/absolute/path/to/mcp-inscription/build/cli.js"] } } }

Ensure /absolute/path/to/mcp-inscription reflects your actual repository location.

1. Application Refresh: Save the configuration file and fully restart the Claude Desktop application for the new server binding to initialize.

Validation Steps for Desktop Client

Verify correct operation by querying information the tool is designed to handle. Claude should return the extracted inscription data.

• Troubleshooting: If responses fail, examine the dedicated log files within the Claude application data directory. Specifically look for mcp.log and the server-specific log file (e.g., mcp-server-mcp-inscription.log) for initialization errors or path resolution issues.

Installing via Smithery

Automated deployment for Claude Desktop integration via the Smithery CLI:

bash npx -y @smithery/cli install @Laz1mov/mcp-inscription --client claude

🗂️ Project Hierarchy

text mcp-inscription/ ├── src/ │ ├── ordinals_client.ts # Bitcoin inscription and runestone protocol interface │ ├── servers/ │ │ ├── index.ts # Server bootstrap module │ │ ├── sse.ts # Server-Sent Events implementation │ │ ├── stdio.ts # Standard I/O transport implementation │ │ └── base.ts # Core server logic foundation │ ├── index.ts # Primary export point │ ├── cli.ts # Command-line interface runner │ ├── mcp_inscription_types.ts # Shared data structures and schema definitions │ └── utils/ │ ├── logger.ts # Structured logging configuration (Pino) │ ├── cache.ts # Data response caching mechanism │ ├── error_handlers.ts # Custom exception handlers │ ├── json_utils.ts # JSON serialization/deserialization helpers │ ├── img_utils.ts # Image data manipulation utilities │ └── version.ts # Versioning metadata ├── .env.example # Environment variable template ├── package.json ├── tsconfig.json └── README.md

📚 Available Utilities

reveal_inscription

Purpose: Extracts and interprets the payload content embedded within an Ordinal inscription referenced by its transaction identifier.

Input Schema:

{ "txid": "string" // The hash of the transaction containing the inscription witness data }

Example Input:

{ "txid": "0169d12c4edf2026a67e219c10207438a080eb82d8f21860f6784dd66f281389" }

Result:
Returns the fully decoded asset representation (e.g., string data, JSON object, or decoded image bytes).

⚠️ Exception Management

The server utilizes dedicated exception classes for handling failures related to blockchain lookups and protocol violations. All errors are logged verbosely using the integrated logger and passed back to the client endpoint for contextual debugging.

📢 Community Contributions

Suggestions for enhancement or bug reports are highly encouraged. Please submit pull requests or create new issues on the primary repository.

⚖️ Licensing

This software is distributed under the terms of the MIT License.