Firelinks MCP

🚀 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

📦 安裝指南

本地開發

1. 安裝依賴：

cd mcp-server
npm install

2. 根據 .env.example 創建 .env 文件：

cp .env.example .env

3. 在 .env 中配置環境變量：

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

4. 啟動服務器：

npm start

或者使用開發模式（自動重載）：

npm run dev

Docker 方式

1. 構建鏡像：

docker build -t firelinks-mcp-server .

2. 運行容器：

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
• 認證方式：在授權頭中使用令牌認證

可用工具

鏈接工具

1. firelinks_create_link - 創建短鏈接
2. firelinks_get_link - 獲取鏈接信息
3. firelinks_list_links - 列出所有鏈接
4. firelinks_update_link_url - 更新鏈接 URL
5. firelinks_add_reserve_url - 添加備用 URL

統計工具

1. firelinks_stat_days - 按天統計
2. firelinks_stat_total - 特定時間段的總統計信息
3. firelinks_stat_links - 所有鏈接的統計信息
4. firelinks_stat_clicks - 詳細的點擊統計信息
5. firelinks_stat_compare - 對比兩個時間段的數據

域名工具

1. firelinks_list_domains - 列出域名
2. firelinks_create_domain - 添加域名

服務器工具

1. 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 的請求超時 解決方案：

1. 檢查 Laravel API 的可用性。
2. 在 src/lib/laravel-api.js 中增加超時時間。
3. 檢查容器之間的網絡連接。

服務器無法啟動

問題：啟動時出錯 解決方案：

1. 查看日誌：docker logs firelinks-mcp-server
2. 確保端口 3000 未被佔用。
3. 檢查環境變量是否正確。

📄 許可證

本項目採用 MIT 許可證。

👨‍💻 支持

如有任何問題或需要支持，請聯繫 support@firelinks.cc。