OrdiscanMCP v1
具有 Ordiscan API 集成的 MCP 框架 HTTP 服务器实现。
特征
- 端口 1337 上的 HTTP 流传输
- 流响应模式，实现实时通信
- 全面的 Ordiscan API 集成（29 种工具）
- 使用 Zod 模式验证的 TypeScript 实现
- 详细的错误处理和响应格式
- 直接 API 连接（无需代理）
- 持有者令牌身份验证
- Ordiscan API 处理的速率限制
API 连接和身份验证
直接连接
所有工具均直接连接到 Ordiscan API ( api.ordiscan.com )，无需任何代理。这确保了：
- 响应时间更快
- 减少延迟
- 无需额外配置
- 直接错误处理
- Ordiscan API 自动限制速率
验证
每个工具都需要使用 Bearer 令牌进行身份验证：
- 必须提供 API 密钥：
- 作为每次工具调用中的参数（
apiKey参数） - 通过
ORDISCAN_API_KEY环境变量
- 身份验证使用 Bearer 令牌格式
- 所有请求都包含
Authorization: Bearer <your-api-key>标头 - 无效或缺失的 API 密钥将导致身份验证错误
设置
- 安装依赖项：
- 构建项目：
- 配置您的 MCP 客户端：
{
"mcpServers": {
"ordiscanmcpv1": {
"command": "npx",
"args": [
"mcp-remote",
"https://your-deployed-server.com/mcp"
]
}
}
}
网址：（ http://localhost:1337/mcp ）
- 启动服务器：
对于使用热重载进行开发：
只需通过请求传入密钥一次，就可以了。
项目结构
ordiscanmcpv1/
├── src/
│ ├── tools/
│ │ ├── ordiscan-utils.ts
│ │ ├── ordiscan.ts # Main Ordiscan Tool
│ │ │
│ │ ├── # Address Tools
│ │ ├── ordiscan-utxo.ts
│ │ ├── ordiscan-inscriptions.ts
│ │ ├── ordiscan-inscriptions-detail.ts
│ │ ├── ordiscan-runes-balance.ts
│ │ ├── ordiscan-brc20-balance.ts
│ │ ├── ordiscan-rare-sats.ts
│ │ │
│ │ ├── # Activity Tools
│ │ ├── ordiscan-inscriptions-activity.ts
│ │ ├── ordiscan-runes-activity.ts
│ │ ├── ordiscan-brc20-activity.ts
│ │ │
│ │ ├── # Transaction Tools
│ │ ├── ordiscan-tx-info.ts
│ │ ├── ordiscan-tx-inscriptions.ts
│ │ ├── ordiscan-tx-inscription-transfers.ts
│ │ ├── ordiscan-tx-runes.ts
│ │ │
│ │ ├── # Inscription Tools
│ │ ├── ordiscan-inscription-info.ts
│ │ ├── ordiscan-inscription-traits.ts
│ │ ├── ordiscan-inscriptions-list.ts
│ │ ├── ordiscan-inscriptions-detail.ts
│ │ │
│ │ ├── # Collection Tools
│ │ ├── ordiscan-collections-list.ts
│ │ ├── ordiscan-collection-info.ts
│ │ ├── ordiscan-collection-inscriptions.ts
│ │ │
│ │ ├── # Rune Tools
│ │ ├── ordiscan-runes-list.ts
│ │ ├── ordiscan-rune-market.ts
│ │ ├── ordiscan-rune-name-unlock.ts
│ │ │
│ │ ├── # BRC-20 Tools
│ │ ├── ordiscan-brc20-list.ts
│ │ ├── ordiscan-brc20-info.ts
│ │ │
│ │ ├── # Sat Tools
│ │ ├── ordiscan-sat-info.ts
│ │ ├── ordiscan-utxo-rare-sats.ts
│ │ └── ordiscan-utxo-sat-ranges.ts
│ │
│ └── index.ts
├── package.json
├── tsconfig.json
└── README.md
参数处理
所有工具都使用ordiscan-utils.ts中的强大参数处理实用程序：
灵活的号码处理
flexibleNumber() ：接受数字参数的字符串和数字输入- 自动将字符串数字转换为整数
- 验证适用的数字范围
- 用于分页、序数和块高度
灵活的枚举处理
flexibleEnum() ：根据预定义值验证字符串输入- 用于排序顺序（“最新”/“最旧”）
- 用于类型过滤器和其他枚举值
- 为无效输入提供清晰的错误消息
这些实用程序确保所有工具的参数处理一致，同时保持类型安全和验证。
可用工具（共 29 个）
1. 主要工具
- ordiscan_main ：用于符文信息和状态的通用工具
2. 地址工具 (6)
- UTXO 工具：获取比特币地址拥有的所有 UTXO
- 基本和详细的铭文工具：获取地址的铭文信息
- 符文余额工具：获取地址的符文余额
- BRC-20 余额工具：获取地址的 BRC-20 代币余额
- Rare Sats Tool ：获取某个地址拥有的稀有 Sats
3. 活动工具 (3)
- 铭文活动工具：追踪地址的铭文转移
- 符文活动工具：追踪地址的符文转移
- BRC-20 活动工具：跟踪地址的 BRC-20 代币转移
4.交易工具 (4)
- 交易信息工具：获取详细的交易信息
- 交易铭文工具：在交易中获取铭文
- 交易铭文转移工具：跟踪交易中的铭文转移
- 交易符文工具：跟踪交易中的符文转移
5. 铭文工具（4）
- 铭文信息工具：获取有关铭文的详细信息
- 铭文特质工具：获取铭文特质
- 铭文列表工具：获取所有铭文的分页列表
- 铭文转移工具：追踪铭文的转移
6. 收集工具 (3)
- 收藏列表工具：获取收藏的分页列表
- 收藏信息工具：获取有关收藏的详细信息
- 收藏铭文工具：获取收藏中的铭文
7. 符文工具 (3)
- 符文列表工具：获取所有符文的列表
- 符文市场信息工具：获取符文的市场信息
- 符文名称解锁工具：检查符文名称的可用性
8.BRC-20工具（2）
- BRC-20 列表工具：获取所有 BRC-20 代币的列表
- BRC-20 代币信息工具：获取有关 BRC-20 代币的详细信息
9. 卫星工具 (3)
- 卫星信息工具：获取有关特定卫星的信息
- UTXO Rare Sats Tool : 在 UTXO 中获取稀有 Sats
- UTXO Sat Ranges 工具：获取 UTXO 中的 Sat Ranges
工具示例
铭文信息工具
获取有关特定铭文的详细信息。
工具名称： ordiscan_inscription_info
参数：
id （字符串）：铭文ID（例如b61b0172d95e266c18aea0c624db987e971a5d6d4ebc2aaed85da4642d635735i0）apiKey （字符串，可选）：您的 Ordiscan API 密钥
响应示例：
{
"success": true,
"formatted": {
"id": "b61b0172d95e266c18aea0c624db987e971a5d6d4ebc2aaed85da4642d635735i0",
"number": 123456,
"type": "image/png",
"timestamp": "2024-01-01 12:00:00",
"sat": "1,234,567",
"content_url": "https://ordinals.com/content/...",
"collection": "example-collection",
"owner": {
"address": "bc1...",
"output": "txid:vout"
},
"genesis": {
"address": "bc1...",
"output": "txid:vout"
}
}
}
符文市场工具
获取特定符文的市场信息。
工具名称： ordiscan_rune_market
参数：
name （字符串）：符文的唯一名称（不带空格）apiKey （字符串，可选）：您的 Ordiscan API 密钥
响应示例：
{
"success": true,
"formatted": {
"price": {
"sats": "1,234.56",
"usd": "$0.50"
},
"market_cap": {
"btc": "12.3456",
"usd": "$500,000"
}
}
}
BRC-20 信息工具
获取有关 BRC-20 代币的详细信息。
工具名称： ordiscan_brc20_info
参数：
tick （字符串）：代币的唯一标记apiKey （字符串，可选）：您的 Ordiscan API 密钥
响应示例：
{
"success": true,
"formatted": {
"tick": "ORDI",
"supply": {
"max": "21,000,000",
"minted": "15,000,000",
"remaining": "6,000,000",
"percent_minted": "71.43%"
},
"market": {
"price_usd": "$1.23",
"market_cap_usd": "$18,450,000",
"fully_diluted_market_cap_usd": "$25,830,000"
}
}
}
错误处理
所有工具都包括全面的错误处理：
- API 密钥验证
- 网络请求错误
- 输入验证无效
- Ordiscan API 的速率限制响应
- 详细错误消息
响应格式
每个工具都提供原始和格式化的响应：
data字段中的原始数据formatted字段中的人性化格式化数据- 所有工具的错误格式一致
- 正确的数字格式和日期本地化
安全建议
API 密钥管理
- 切勿在代码中对 API 密钥进行硬编码
- 使用环境变量存储 API 密钥
- 定期轮换 API 密钥
- 为开发和生产使用不同的 API 密钥
错误处理
服务器实现安全错误处理：
- 错误消息中不包含敏感信息
- 正确的 HTTP 状态代码
- 结构化错误响应
- 记录错误而不暴露内部信息
输入验证
所有工具都使用严格的输入验证：
- 所有参数的 Zod 模式验证
- 使用 TypeScript 进行类型检查
- 灵活的数字输入处理
- 枚举值的字符串验证
速率限制
速率限制由 Ordiscan API 处理：
- 无需额外的速率限制
- 基于 API 密钥的速率限制
- 超出速率限制的正确错误响应
- 自动速率限制处理