MCP Inscription Backend Service

Conceptual Summary

This component serves as a Model Context Protocol (MCP) compliant server, specifically engineered to interface with Bitcoin Ordinals. Its primary function is to abstract the complexity of raw blockchain inscription data, enabling intelligent agents and LLMs to directly access and render the embedded content (text, media, structured data) associated with a specific transaction output.

🎮 Operational Demonstration

Demonstration Unit Video Link

🧭 Navigational Index

• MCP Inscription Backend Service
• Conceptual Summary
• 🧭 Navigational Index
• ⚙️ Core Capabilities
• 🤖 Goose Integration Pathway
  • Local Execution via STDIO
  • Remote Connection via SSE Streams
• 🖥️ Claude Desktop Interfacing
  • Validation of Desktop Linkage
• 🌳 Repository Layout
• 🛠️ Setup Procedures
• 📦 Exposed Tools
  • show_ordinals
• 🛑 Fault Reporting
• ➕ Contribution Guidelines
• ⚖️ Licensing Terms

⚙️ Core Capabilities

• Inscription Parsing: Automatically identifies and interprets Bitcoin transaction witness data to extract Ordinal content, supporting inscriptions encoded as plain text, JSON payloads, image binaries, and other recognized formats.

🤖 Goose Integration Pathway

Goose, an agent framework from Block leveraging the Model Context Protocol, accepts this server as an extensible module. Integration is supported through two primary transport methods: executing the server as a local child process (STDIO) or connecting to a persistent, externally managed HTTP Server-Sent Events (SSE) endpoint.

Local Execution via STDIO

This configuration launches the gateway as a child process managed directly by Goose, utilizing standard input and output streams for bidirectional communication.

1. Acquire and Compile the Repository: bash git clone https://github.com/Laz1mov/mcp-inscription cd mcp-inscription npm install npm run build

Note the absolute file system path to this directory.

1. Register the Extension within Goose: Invoke Goose's configuration utility (goose configure) or navigate to Settings > Extensions in the Goose Desktop client. Select the option to "Add Extension."

2. Designate Extension Type – Command-Line Interface (CLI): Choose Command-Line Extension to instruct Goose to spawn a local process.

3. Input Configuration Parameters: Specify the necessary identifiers and the execution path:

4. ID: mcp-inscription

5. Name: A display name for the module (e.g., "mcp-inscription").

6. Command: The absolute path to the compiled JavaScript CLI executable:

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

7. Finalize and Activate: Save the configuration. Goose will store this in its configuration file (e.g., ~/.config/goose/config.yaml). Verify the extension is toggled ON.

8. Initiate a Session Using the Module: When starting a Goose runtime environment, explicitly include the extension reference:

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

Remote Connection via SSE Streams

This method is preferred when the server operates as a detached, continuously running service accessible via HTTP.

1. Deploy the MCP Server in SSE Mode: Execute the server pointing to an accessible network address/port:

bash # Assuming in the project root cd /path/to/mcp-inscription npm install npm run build

# Start service, default port 3000 SERVER_MODE=sse node build/cli.js

# Or specify a non-default listening port SERVER_MODE=sse PORT=9000 node build/cli.js

1. Register as a Remote Extension in Goose: Use goose configure or the UI to Add Extension, selecting Remote Extension this time.

2. Specify Server Endpoint: Provide a unique name and the root URL of the running server. For a local instance on port 9000, the URL input would be http://localhost:9000. Goose automatically appends the necessary MCP SSE path (conventionally /mcp/sse).

3. Enable the Extension: Ensure the remote entry is active in Goose settings.

Utilizing the Inscription Gateway in Goose: Once integrated and active, Goose will automatically invoke the available tools when a query relates to Bitcoin Ordinals. For instance:

• "Retrieve the content associated with Inscription ID: 0169d12c4edf2026a67e219c10207438a080eb82d8f21860f6784dd66f281389?"

If interaction fails, confirm the server is running (for SSE mode) and that the extension state is enabled. Verbose logging in the Goose CLI can confirm if tool invocation attempts were made.

Further Reference: Consult the official Goose documentation regarding MCP server directory listings and extension lifecycle management for advanced configuration.

🖥️ Claude Desktop Interfacing

Integration with Anthropic's Claude Desktop application requires direct configuration of external MCP servers within the application's settings file.

1. Obtain Claude Desktop: Download the latest version for your OS from Anthropic's official support portal.

2. Prepare the Server Executable: Compile the repository as detailed in Step 1 of the STDIO section above.

3. Modify Claude Desktop Configuration: Locate and edit the configuration file:

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

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

Insert the server definition into the "mcpServers" object:

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

Ensure the path is absolute and correct. The key ("mcp-inscription") serves as the server handle.

1. Application Restart: Save the JSON file and completely close and relaunch Claude Desktop for the new server configuration to initialize.

Validation of Desktop Linkage

After restarting the client, test functionality by requesting specific inscription data. A successful query yields the decoded content.

• Diagnostic Logging: If the tool remains unresponsive, examine the dedicated MCP server logs located within Claude's logging directory (e.g., mcp-server-mcp-inscription.log). Errors here usually point to incorrect file paths or runtime exceptions during server startup.

Installing via Smithery

Automated deployment for Claude Desktop agents:

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

🌳 Repository Layout

text mcp-inscription/ ├── src/ │ ├── ordinals_client.ts # Bitcoin ordinals and runestone utility functions │ ├── servers/ │ │ ├── index.ts # Server exports and factory functions │ │ ├── sse.ts # Server implementation using SSE transport │ │ ├── stdio.ts # Server implementation using STDIO transport │ │ └── base.ts # Base server implementation with shared functionality │ ├── index.ts # Main entry point │ ├── cli.ts # CLI launcher │ ├── mcp_inscription_types.ts # Shared types and schemas for the MCP-Inscription server │ └── utils/ │ ├── logger.ts # Logger setup │ ├── cache.ts # Caching implementation │ ├── error_handlers.ts # Error handling utilities │ ├── json_utils.ts # JSON processing utilities │ ├── img_utils.ts # Image processing and conversion utilities │ └── version.ts # Version information ├── .env.example # Example environment configuration file ├── package.json ├── tsconfig.json └── README.md

📦 Exposed Tools

show_ordinals

Purpose: Parses and resolves the embedded payload data contained within an Ordinal inscription identified by its transaction ID.

Input Schema:

{ "txid": "string" // The identifier of the transaction anchoring the inscription }

Example Input:

{ "txid": "0169d12c4edf2026a67e219c10207438a080eb82d8f21860f6784dd66f281389" }

Result: Returns the deciphered inscription material (e.g., decoded string, deserialized JSON object, or binary representation if applicable).

🛑 Fault Reporting

The server incorporates custom exception classes to manage failures related to blockchain queries and data parsing. Comprehensive diagnostic output is generated via Pino logging and relayed within API responses to facilitate rapid debugging.

➕ Contribution Guidelines

We welcome external submissions, enhancements, and issue reports via pull requests on the GitHub repository.

⚖️ Licensing Terms

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