MCP-铭文服务器

概述

模型上下文协议 (MCP) 服务器使 AI 模型能够与序数铭文进行交互，从而允许它们显示来自交易的内容。

🎮 演示

鹅演示视频

💼 目录

MCP-铭文服务器

🔧 功能

序数检测：自动检测并将比特币交易解析为序数，支持基于文本、图像、json 和更多铭文格式。

🦆 Goose 集成

Goose 是由 Block 开发的开源 AI 代理框架，支持通过模型上下文协议 (MCP Protocol) 进行扩展。您可以将 MCP-Inscription 服务器集成为 Goose 扩展，以便 Goose 与 Ordinals Inscriptions 进行交互。Goose 支持两种 MCP 服务器集成模式：将服务器作为本地进程 (STDIO) 运行，或通过服务器发送事件 (SSE) 将其作为远程服务连接。以下是两种方法的说明：

使用 STDIO（本地扩展）

该方法在本地运行 MCP-Inscription 服务器作为 Goose 的子进程，通过标准输入/输出进行通信。

克隆并构建 MCP-Inscription 存储库（如果还没有）：
git clone https://github.com/Laz1mov/mcp-inscription cd mcp-inscription npm install npm run build
请记下存储库的完整绝对路径，因为下一步您将需要它。
在 Goose 中添加新扩展：打开 Goose 的配置界面。您可以通过命令行运行goose configure来执行此操作，或者在 Goose 桌面应用中前往“设置”>“扩展”。从菜单中选择**“添加扩展”。** （使用扩展 | goose ）
选择扩展类型 - 命令行扩展：当提示输入扩展类型时，选择命令行扩展（在 CLI 菜单或 UI 中），以便 Goose 知道它应该启动本地命令（使用扩展 | goose ）（而不是内置或远程扩展）。
**输入扩展详细信息：**为 MCP-Inscription 服务器提供名称和命令：
- ID : mcp-inscription
- **名称：**您可以将其称为“mcp-inscription”，或任何标识符（这将是您引用扩展的方式）。
- **命令：**指定构建的 CLI 脚本的完整路径。例如：
  node /absolute/path/to/mcp-inscription/build/cli.js
  将/absolute/path/to/mcp-inscription替换为您克隆存储库的实际路径。
- 通常，您不需要在脚本路径之外添加任何参数（除非您的服务器需要特殊标志）。
完成并启用：完成扩展添加。Goose 会将此新扩展添加到其配置中（通常为~/.config/goose/config.yaml ）。确保扩展已启用（如果使用 CLI 向导，则添加后应默认启用；在 Goose Desktop 应用中，您可以检查扩展列表，如果尚未启用，请将其切换为启用状态（使用扩展 | goose ）（使用扩展 | goose ））。
**使用新扩展启动 Goose 会话：**您现在可以在 Goose 中使用该扩展。如果您通过 CLI 运行 Goose，请运行以下命令启动包含该扩展的会话：
goose session --with-extension "mcp-inscription"

将“ordinals”替换为您为扩展程序指定的任何名称（使用扩展程序 | goose ）。（这可确保会话加载扩展程序。或者，如果扩展程序已全局启用，则 Goose Desktop 或 CLI 将自动在所有会话中提供该扩展程序。）

使用 SSE（远程扩展）

此方法通过 HTTP SSE 流将 Goose 连接到已运行的 MCP 服务器。如果您想将 MCP-Inscription 服务器作为独立服务运行（可能在另一台机器上，或者独立于 Goose），请使用此方法。

**将 MCP 服务器作为独立服务启动：**以 SSE 模式运行 MCP-Inscription 服务器以监听连接：
# Navigate to your mcp-inscription directory cd /path/to/mcp-inscription # If you havent built it yet npm install npm run build # Run in SSE mode on port 3000 (default) SERVER_MODE=sse node build/cli.js # Alternatively, specify a different port SERVER_MODE=sse PORT=9000 node build/cli.js
这将以 SSE 模式启动服务器，使其在http://localhost:3000 （或您指定的端口）上可用。
在 Goose 中添加新扩展（远程）：像以前一样，运行goose configure或使用 Goose UI添加扩展（使用扩展 | goose ）。这次，当系统询问扩展类型时，选择**“远程扩展”** （使用扩展 | goose ）。这会告诉 Goose 它将通过 SSE 连接到外部服务器。
输入远程扩展的详细信息：为扩展命名（例如“ordinals”）并提供服务器的 URL。对于URL ，请输入 MCP 服务器运行的基址。例如，如果您的服务器在本地计算机上监听的是 9000 端口，您可以输入http://localhost:9000 。Goose 将尝试连接到该地址的 MCP 服务器的 SSE 端点。（Goose 使用标准的 MCP SSE 路径，按照惯例位于服务器上的/mcp/sse路由下，您通常只需提供主机和端口，Goose 会处理其余部分。）
**启用扩展：**添加远程扩展后，请确保在 Goose 的设置中启用该扩展（与 STDIO 的情况类似）。STDIO 或 SSE 扩展（使用相同的工具）只需启用其中一个即可——如果您不小心同时启用了同一服务器的本地版本和远程版本，则可能需要禁用其中一个以避免混淆。

**在 Goose 中使用 MCP-Inscription 扩展：**设置扩展程序（通过上述任一方法）并启用后，您就可以与 Goose 交互并通过它查询订单数据。在新的 Goose 聊天或会话中，您可以像平常一样提问。Goose 会识别何时使用 MCP-Inscription 工具来满足您的请求。例如：

“显示序数：0169d12c4edf2026a67e219c10207438a080eb82d8f21860f6784dd66f281389？”

当你提出这些问题时，Goose 会调用 MCP-Inscription 服务器的工具并返回答案（例如，最新的比特币区块信息）。你应该会看到 Goose 通过 MCP-Inscription 服务器从比特币区块链中提取最新信息。

如果 Goose 似乎未使用该扩展程序（例如，它响应说找不到信息），请确保该扩展程序已启用且服务器正在运行（远程服务器处于 SSE 模式）。您还可以运行 Goose 的 CLI 并记录详细日志，以查看它是否尝试调用该扩展程序。通常，如果配置正确，Goose 会自动发现 MCP-Inscription 服务器的功能并在需要时使用它们。

**更多资源：**有关 Goose 扩展和 MCP 的更多详细信息，请参阅 Goose 官方文档（使用扩展 | goose ）。该文档包含内置扩展和社区扩展的列表，并解释了 MCP 服务器如何集成到 Goose 中。您还可以在 Goose 文档和模型上下文协议文档中找到可用 MCP 服务器的目录和其他配置技巧。如果您想探索更多扩展或开发自己的扩展，这些文档会对您有所帮助。

🔑 Claude 桌面集成

要将 MCP-Inscription 服务器与 Claude Desktop（Anthropic 为 Claude 开发的桌面应用程序）一起使用，请按照以下步骤操作：

**下载并安装 Claude Desktop：**访问 Claude Desktop 官方下载页面，获取适用于您操作系统（macOS 或 Windows）的应用程序（安装 Claude Desktop | Anthropic 帮助中心）。安装应用程序并确保您使用的是最新版本（您可以在应用程序菜单中检查更新）。
克隆并构建 MCP-Inscription 存储库：
git clone https://github.com/Laz1mov/mcp-inscription cd mcp-inscription npm install npm run build
**配置 Claude Desktop 以使用 MCP-Inscription 服务器：**打开 Claude Desktop 配置文件（它是在您第一次在 Claude Desktop 中编辑设置时创建的）：
- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows： %APPDATA%\Claude\claude_desktop_config.json
  在此 JSON 配置的"mcpServers"部分下添加 MCP-Inscription 服务器的条目。例如：
{ "mcpServers": { "mcp-inscription": { "command": "node", "args": ["/absolute/path/to/mcp-inscription/build/cli.js"] } } }
在上面的代码片段中， "mcp-inscription"是服务器的标识符（您可以随意命名）。请将/absolute/path/to/mcp-inscription替换为您克隆仓库的实际完整路径。
重启 Claude Desktop：保存claude_desktop_config.json文件，然后关闭并重新打开 Claude Desktop 。下次启动时，Claude 将自动按照配置启动 MCP-Inscription 服务器。如果 Claude Desktop 正在运行，则需要重启它以使更改生效。

测试 Claude 桌面集成

一旦 Claude Desktop 重新启动，您就可以测试 MCP-Inscription 服务器是否正常工作：

验证响应： Claude 应该返回一个详细的答案（例如铭文本身或符文信息），并且没有错误。如果您收到错误消息或没有有用的响应，则 MCP 服务器可能未正确连接。
检查 Claude 的日志（如有需要）： Claude Desktop 提供了日志文件，可帮助调试 MCP 集成。如果该工具没有响应，请检查以下日志文件：
- macOS： ~/Library/Logs/Claude/
- Windows： %APPDATA%\Claude\logs\
  查找mcp.log以获取常规 MCP 连接消息，以及名为mcp-server-mcp-inscription.log （或您使用的任何名称）的文件以获取 MCP 服务器的输出/错误。这些日志将显示服务器是否启动或是否存在任何错误（例如路径错误或服务器异常）。如果发现错误，请根据需要修复配置或环境，然后重新启动 Claude Desktop 并再次测试。

📂 项目结构

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

📦可用工具

显示序数

描述：
从交易的见证数据中解码序数铭文数据。

输入模式：

{
  "txid": "string"
}

示例输入：

{
  "txid": "0169d12c4edf2026a67e219c10207438a080eb82d8f21860f6784dd66f281389"
}

输出：
返回解码后的铭文内容，可以是文本、JSON、HTML 或其他格式。

🚨错误处理

服务器使用自定义错误类型来处理比特币操作和区块链查询。详细的错误消息使用 Pino 记录，并包含在客户端响应中，以便于调试。

🤝 贡献

欢迎贡献代码和功能请求！欢迎在 GitHub 上提交 Pull 请求或提出问题。

📝 许可证

该项目已获得MIT 许可。