JinDaGe - firelinks-mcp MCP Details

article

README

🚀 Firelinks MCP 服务器

Firelinks 平台的 MCP（模型上下文协议）服务器，允许外部大语言模型（LLMs）与 Firelinks API 进行交互 - https://firelinks.cc/p/api

🚀 快速开始

此服务器实现了由 Anthropic 开发的 MCP 协议，并提供了一套用于 Firelinks 平台的工具。它能够让外部大语言模型与 Firelinks API 交互，可用于创建、管理短链接，获取统计信息等。

✨ 主要特性

链接管理：创建、检索和编辑短链接。
统计功能：获取详细的点击统计信息，并对比不同时间段的数据。
域名管理：管理自定义域名。
服务器管理：获取可用服务器列表。

🔧 技术细节

架构

LLM 客户端 → HTTPS (mcp.firelinks.cc) → Node.js MCP 服务器 → Firelinks API 后端

项目结构

mcp-server/
├── src/
│   ├── index.js              # 主 Express 服务器文件
│   ├── lib/
│   │   ├── laravel-api.js    # Laravel API 的 HTTP 客户端
│   │   └── mcp-handler.js    # MCP 协议处理程序
│   └── tools/
│       ├── links.js          # 链接相关工具
│       ├── statistics.js     # 统计相关工具
│       ├── domains.js        # 域名相关工具
│       └── servers.js        # 服务器相关工具
├── package.json
├── Dockerfile
├── docker-compose.yml
├── .env.example
└── README.md

📦 安装指南

本地开发

安装依赖：

cd mcp-server
npm install

根据 .env.example 创建 .env 文件：

cp .env.example .env

在 .env 中配置环境变量：

PORT=3000
LARAVEL_API_URL=https://firelinks.cc/api
NODE_ENV=development

启动服务器：

npm start

或者使用开发模式（自动重载）：

npm run dev

Docker 方式

构建镜像：

docker build -t firelinks-mcp-server .

运行容器：

docker run -d \
  -p 3000:3000 \
  -e LARAVEL_API_URL=https://firelinks.cc/api \
  --name firelinks-mcp-server \
  firelinks-mcp-server

Docker Compose 方式

docker-compose up -d

💻 使用示例

端点

GET /health - 服务器健康检查
POST /mcp - 主要 MCP 端点（JSON-RPC 2.0）
GET /sse - 用于流式传输的服务器发送事件

认证

所有对 /mcp 的请求都需要在请求头中包含认证令牌：

Authorization: Bearer YOUR_API_TOKEN

你可以在你的 Firelinks 账户中获取 API 令牌。

与 LLM 客户端集成

Claude Desktop

添加到 Claude Desktop 配置文件 (claude_desktop_config.json)：

{
  "mcpServers": {
    "firelinks": {
      "url": "https://mcp.firelinks.cc/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Cursor

添加到 Cursor 配置文件 (mcp.json)：

{
  "mcpServers": {
    "firelinks": {
      "url": "https://mcp.firelinks.cc/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

其他 MCP 客户端

若要连接其他兼容 MCP 的客户端，请使用以下信息：

URL：https://mcp.firelinks.cc/mcp
传输协议：HTTP
认证方式：在授权头中使用令牌认证

可用工具

链接工具

firelinks_create_link - 创建短链接
firelinks_get_link - 获取链接信息
firelinks_list_links - 列出所有链接
firelinks_update_link_url - 更新链接 URL
firelinks_add_reserve_url - 添加备用 URL

统计工具

firelinks_stat_days - 按天统计
firelinks_stat_total - 特定时间段的总统计信息
firelinks_stat_links - 所有链接的统计信息
firelinks_stat_clicks - 详细的点击统计信息
firelinks_stat_compare - 对比两个时间段的数据

域名工具

firelinks_list_domains - 列出域名
firelinks_create_domain - 添加域名

服务器工具

firelinks_list_servers - 列出可用服务器

请求示例

初始化

curl -X POST https://mcp.firelinks.cc/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {},
    "id": 1
  }'

列出工具

curl -X POST https://mcp.firelinks.cc/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "params": {},
    "id": 1
  }'

创建链接

curl -X POST https://mcp.firelinks.cc/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "firelinks_create_link",
      "arguments": {
        "url": "https://example.com",
        "type": "url",
        "redirect_type": 0,
        "code": "my-link"
      }
    },
    "id": 1
  }'

必需参数：

url - 有效的 http 或 https 链接
type - 链接类型（网页链接使用 "url"）
redirect_type - 重定向类型：0 (301)、1 (302)、2 (303)、4 (META 刷新)

可选参数：

link_name - 链接名称
code - 自定义链接代码（必须唯一）
domain_id - 域名 ID
sub_domain - 子域名
keywords - 搜索关键词
keywords_mode - 关键词搜索逻辑（1、2 或 3）
group_id - 链接组 ID
options - 附加设置字符串

获取统计信息

curl -X POST https://mcp.firelinks.cc/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "firelinks_stat_days",
      "arguments": {
        "date_from": "2024-01-01",
        "date_to": "2024-01-31"
      }
    },
    "id": 1
  }'

📚 详细文档

故障排除

认证错误

问题：Missing or invalid Authorization header 解决方案：确保请求头中包含有效的令牌：

Authorization: Bearer YOUR_API_TOKEN

请求超时

问题：对 Laravel API 的请求超时 解决方案：

检查 Laravel API 的可用性。
在 src/lib/laravel-api.js 中增加超时时间。
检查容器之间的网络连接。

服务器无法启动

问题：启动时出错 解决方案：

查看日志：docker logs firelinks-mcp-server
确保端口 3000 未被占用。
检查环境变量是否正确。

📄 许可证

本项目采用 MIT 许可证。

👨‍💻 支持

如有任何问题或需要支持，请联系 support@firelinks.cc。

firelinks-mcp