MCP 服务器

mcp-inscription

使AI助手能够直接与比特币Ordinals铭文交互。与Goose和Claude Desktop无缝集成，以从交易中检索和显示铭文内容。

README

MCP-铭文服务器

<div align="center"> <h3> <a href="https://github.com/Laz1mov/mcp-inscription/"> 文档 </a> <span> | </span> <a href="https://github.com/Laz1mov/mcp-inscription/#-available-tools"> 可用工具 </a> <span> | </span> <a href="https://modelcontextprotocol.com/"> MCP 文档 </a> <span> | </span> <a href="https://docs.ordinals.com/"> Ordinals 文档 </a> </h3> </div>

概述

一个模型上下文协议 (MCP) 服务器，使 AI 模型能够与 Ordinals 铭文交互，允许它们显示来自交易的内容。

🎮 演示

Goose 演示视频
<div style="display: flex; align-items: center; justify-content: center;"><a href="https://github.com/user-attachments/assets/55f606d7-03f6-438b-93bc-9ec09a9f7fd6"><img src="https://github.com/user-attachments/assets/7b8b5fe1-6c3c-4741-ad16-c70887d954b6" style="width: 60%; height: auto;" alt="Goose screenshot" /></a></div>

💼 目录

MCP-铭文服务器

🔧 功能

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

🦆 Goose 集成

Goose 是 Block 的一个开源 AI 代理框架，它支持通过模型上下文协议进行扩展。您可以将 MCP-Inscription 服务器集成为 Goose 扩展，以允许 Goose 与 Ordinals 铭文交互。 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 Desktop 应用程序中，转到 Settings > Extensions。从菜单中，选择 "Add Extension." (Using Extensions | goose)
选择扩展类型 – 命令行扩展： 当提示选择扩展类型时，选择 Command-Line Extension（在 CLI 菜单或 UI 中），以便 Goose 知道它应该启动本地命令 (Using Extensions | 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 应用程序中，您可以检查扩展列表并在未启用时将其打开 (Using Extensions | goose) (Using Extensions | goose)).
使用新扩展启动 Goose 会话： 您现在可以在 Goose 中使用该扩展。如果您通过 CLI 运行 Goose，请启动一个包含该扩展的会话，方法是运行：
```
goose session --with-extension "mcp-inscription"
```

将 "ordinals" 替换为您为扩展指定的任何名称 (Using Extensions | goose)。（这确保会话加载扩展。或者，如果扩展已全局启用，则 Goose Desktop 或 CLI 将自动在所有会话中提供它。）

使用 SSE (远程扩展)

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

将 MCP 服务器作为独立服务启动： 在 SSE 模式下运行 MCP-Inscription 服务器以侦听连接：

# 导航到您的 mcp-inscription 目录
cd /path/to/mcp-inscription

# 如果您尚未构建它
npm install
npm run build

# 在端口 3000（默认）上以 SSE 模式运行
SERVER_MODE=sse node build/cli.js

# 或者，指定不同的端口
SERVER_MODE=sse PORT=9000 node build/cli.js

这将在 SSE 模式下启动服务器，使其在 http://localhost:3000（或您指定的端口）上可用。

在 Goose 中添加新扩展（远程）： 与之前一样，运行 goose configure 或使用 Goose UI Add Extension (Using Extensions | goose)。这次，当被问及扩展类型时，选择 Remote Extension (Using Extensions | 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 交互并通过它查询 ord 数据。在新的 Goose 聊天或会话中，只需像往常一样提问即可。 Goose 将识别何时使用 MCP-Inscription 工具来满足您的请求。例如：

"Show me Ordinals: 0169d12c4edf2026a67e219c10207438a080eb82d8f21860f6784dd66f281389?"

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

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

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

🔑 Claude Desktop 集成

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

下载并安装 Claude Desktop： 访问官方 Claude Desktop 下载页面并获取适用于您的操作系统（macOS 或 Windows）的应用程序 (Installing Claude for Desktop | Anthropic Help Center)。安装该应用程序并确保您使用的是最新版本（您可以在应用程序菜单中检查更新）。

克隆并构建 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 Desktop 集成

重新启动 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 和 runestone 实用程序函数
│   ├── servers/
│   │   ├── index.ts            # 服务器导出和工厂函数
│   │   ├── sse.ts              # 使用 SSE 传输的服务器实现
│   │   ├── stdio.ts            # 使用 STDIO 传输的服务器实现
│   │   └── base.ts             # 具有共享功能的基本服务器实现
│   ├── index.ts                # 主要入口点
│   ├── cli.ts                  # CLI 启动器
│   ├── mcp_inscription_types.ts # MCP-Inscription 服务器的共享类型和模式
│   └── utils/
│       ├── logger.ts           # Logger 设置
│       ├── cache.ts            # 缓存实现
│       ├── error_handlers.ts   # 错误处理实用程序
│       ├── json_utils.ts       # JSON 处理实用程序
│       ├── img_utils.ts        # 图像处理和转换实用程序
│       └── version.ts          # 版本信息
├── .env.example                # 示例环境配置文件
├── package.json
├── tsconfig.json
└── README.md

📦 可用工具

show_ordinals

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

输入模式：

{
  "txid": "string"
}

示例输入：

{
  "txid": "0169d12c4edf2026a67e219c10207438a080eb82d8f21860f6784dd66f281389"
}

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

🚨 错误处理

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

🤝 贡献

欢迎贡献和功能请求！请随时提交拉取请求或在 GitHub 上打开问题。

📝 许可证

该项目已获得 MIT 许可证的许可。