Simplified MCP Server

🚀 簡化版MCP服務器

這是一個模型上下文協議（MCP）服務器，可實現Claude、Cursor、Kiro（以及其他支持MCP的平臺）與簡化版API的無縫集成。該服務器使大語言模型（LLMs）能夠通過標準化的MCP工具與簡化版服務進行交互，從而實現跨多個平臺的社交媒體賬戶管理和帖子創建。

🚀 快速開始

本服務器可助力大語言模型藉助標準化的MCP工具與簡化版服務交互，實現多平臺的社交媒體賬戶管理與帖子創建。你可以按照以下步驟進行安裝和配置。

✨ 主要特性

• 全面支持MCP協議：基於官方的@modelcontextprotocol/sdk構建。
• 社交媒體管理：提供全面的社交媒體賬戶和帖子管理功能。
• 多平臺支持：支持Facebook、Instagram、Twitter、LinkedIn、TikTok、YouTube、Pinterest、Threads、Google Business Profile和Bluesky等平臺。
• 類型安全實現：使用TypeScript編寫，具備完整的類型安全保障。
• 強大的錯誤處理：提供全面的錯誤處理機制，附帶詳細的錯誤信息。
• 可配置的日誌記錄：可調整日誌級別，方便調試和監控。
• 特定平臺特性：為Google Business Profile、TikTok、YouTube、Instagram等平臺提供高級特定設置。
• 日程安排支持：可創建帶有特定平臺設置的定時帖子。
• 認證管理：安全處理API令牌，具備自動重試邏輯。

📦 安裝指南

前提條件

• Node.js 18.0.0 或更高版本
• npm 8.0.0 或更高版本
• 一個簡化版API令牌

從NPM安裝

npm install -g simplified-mcp-server

從源代碼安裝

git clone https://github.com/celeryhq/simplified-mcp-server.git
cd simplified-mcp-server
npm install
npm run build

打包DXT文件

npm install -g @anthropic-ai/dxt
npx @anthropic-ai/dxt pack        

配置

服務器通過環境變量進行配置。你可以在項目根目錄創建一個.env文件，或者在環境中設置這些變量：

必需配置

變量	描述	示例
SIMPLIFIED_API_TOKEN	你的簡化版API令牌	sk_live_abc123...

可選配置

變量	描述	默認值	選項
SIMPLIFIED_API_BASE_URL	簡化版API基礎URL	https://api.simplified.com	任何有效的URL
LOG_LEVEL	日誌詳細程度	info	debug, info, warn, error
REQUEST_TIMEOUT	API請求超時時間（毫秒）	30000	任何正數
RETRY_ATTEMPTS	重試次數	3	任何非負數
RETRY_DELAY	重試間隔時間（毫秒）	1000	任何正數

配置示例

# 必需
SIMPLIFIED_API_TOKEN=sk_live_your_token_here
SIMPLIFIED_API_BASE_URL=https://api.simplified.com
LOG_LEVEL=info

# 可選
REQUEST_TIMEOUT=30000
RETRY_ATTEMPTS=3
RETRY_DELAY=1000

💻 使用示例

編程式使用

import { SimplifiedMCPServer } from 'simplified-mcp-server';
import { ConfigurationManager } from 'simplified-mcp-server/config';

async function startServer() {
  const config = ConfigurationManager.loadConfig();
  const server = new SimplifiedMCPServer(config);
  await server.start();
}

startServer().catch(console.error);

與Claude集成

將服務器添加到你的Claude MCP配置中：

{
   "mcpServers": {
      "simplified": {
        "command": "node",
        "args": [
          "{PATH_TO_CLONED_REPOSITORY}/dist/cli.js",
          "start"
        ],
        "env": {
          "SIMPLIFIED_API_TOKEN": "your_token_here",
          "SIMPLIFIED_API_BASE_URL": "https://api.simplified.com",
          "LOG_LEVEL": "info"
        }
      }
    }
}

安裝DXT擴展： Extensions -> Advanced settings -> Install Extension... 選擇simplified-mcp.dxt文件，添加你的令牌。

與Kiro集成

將服務器添加到你的Kiro MCP配置中：

{
  "mcpServers": {
    "simplified": {
      "command": "simplified-mcp-server",
      "env": {
        "SIMPLIFIED_API_TOKEN": "your_token_here"
      }
    }
  }
}

📚 詳細文檔

可用工具

服務器提供了全面的社交媒體管理工具，具備特定平臺特性：

社交媒體工具

用於管理社交媒體賬戶和帖子的工具。

get_social_media_accounts

檢索所有已連接的社交媒體賬戶。 參數：

• network（可選）：按平臺過濾（facebook、instagram、linkedin、tiktok、youtube、pinterest、threads、google、bluesky、tiktokBusiness）

示例：

{
  "name": "get_social_media_accounts",
  "arguments": {
    "network": "instagram"
  }
}

create_social_media_post

使用特定平臺設置為Google、TikTok、Threads、YouTube、Facebook、LinkedIn、Instagram和Pinterest創建新的社交媒體帖子。 參數：

• message（必需）：帖子消息/內容（1 - 5000個字符）
• accountId（必需）：社交媒體賬戶ID
• action（必需）：要執行的操作（schedule、add_to_queue、draft）
• date（可選）：帖子的預定日期（格式：YYYY-MM-DD HH:MM）
• media（可選）：要附加的媒體文件URL數組（最多10項）
• additional（可選）：特定平臺的帖子設置和元數據

基本示例：

{
  "name": "create_social_media_post",
  "arguments": {
    "message": "Excited to announce our new product launch! 🚀",
    "accountId": "acc_fb123",
    "action": "schedule",
    "date": "2024-01-22 12:00",
    "media": [
      "https://example.com/product-image.jpg",
      "https://example.com/launch-video.mp4"
    ],
    "additional": {}
  }
}

媒體文件

media參數接受一個指向媒體文件的URL字符串數組：

{
  "media": [
    "https://example.com/image1.jpg",
    "https://example.com/video.mp4",
    "https://example.com/image2.png"
  ]
}

媒體要求：

• 每個帖子最多10個媒體文件
• URL必須是公開可訪問的
• 支持的格式因平臺而異（圖像：JPG、PNG、GIF；視頻：MP4、MOV等）

特定平臺特性

additional參數支持特定平臺的配置：

Google Business Profile

{
  "additional": {
    "google": {
      "post": {
        "title": "New Product Launch",
        "topicType": "OFFER",
        "couponCode": "LAUNCH20",
        "callToActionUrl": "https://example.com/product",
        "callToActionType": "SHOP",
        "termsConditions": "Valid until end of month"
      }
    }
  }
}

TikTok / TikTok Business

{
  "additional": {
    "tiktok": {
      "post": {
        "brandContent": true,
        "privacyStatus": "PUBLIC_TO_EVERYONE",
        "duetDisabled": false,
        "commentDisabled": false
      },
      "channel": { "value": "direct" },
      "postType": { "value": "video" }
    }
  }
}

YouTube

{
  "additional": {
    "youtube": {
      "post": {
        "title": "Product Launch Video",
        "license": "standard",
        "privacyStatus": "public",
        "selfDeclaredMadeForKids": "no"
      },
      "postType": { "value": "short" }
    }
  }
}

Instagram

{
  "additional": {
    "instagram": {
      "postReel": {
        "audioName": "Trending Audio Track",
        "shareToFeed": true
      },
      "postType": { "value": "reel" }
    }
  }
}

Pinterest

{
  "additional": {
    "pinterest": {
      "post": {
        "link": "https://example.com/product",
        "title": "Amazing Product",
        "imageAlt": "Product showcase image"
      }
    }
  }
}

LinkedIn

{
  "additional": {
    "linkedin": {
      "audience": { "value": "PUBLIC" }
    }
  }
}

Facebook

{
  "additional": {
    "facebook": {
      "postType": { "value": "feed" }
    }
  }
}

Threads

{
  "additional": {
    "threads": {
      "channel": { "value": "direct" }
    }
  }
}

特定平臺選項參考

平臺	可用選項	描述
Google Business Profile	title, topicType, couponCode, callToActionUrl, callToActionType, termsConditions	帶有CTA和優惠的商業帖子增強功能
TikTok/TikTok Business	brandContent, privacyStatus, duetDisabled, stitchDisabled, commentDisabled	內容設置和互動控制
YouTube	title, license, privacyStatus, selfDeclaredMadeForKids	視頻元數據和合規設置
Instagram	audioName, shareToFeed, postType	卷軸特定設置和動態分享
Pinterest	link, title, imageAlt	圖釘目標和可訪問性
LinkedIn	audience	專業受眾定位
Facebook	postType	內容類型指定
Threads	channel	發佈方法

錯誤處理

服務器提供全面的錯誤處理，帶有詳細的錯誤信息：

錯誤類型

• 配置錯誤：缺少或無效的配置
• 認證錯誤：無效或過期的API令牌
• API錯誤：來自簡化版API的錯誤
• 工具執行錯誤：工具執行期間的錯誤
• 驗證錯誤：無效的工具參數

錯誤響應格式

{
  "success": false,
  "error": "Error message",
  "details": {
    "type": "AUTHENTICATION_ERROR",
    "code": 401,
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

開發

從源代碼構建

git clone https://github.com/celeryhq/simplified-mcp-server.git
cd simplified-mcp-server
npm install
npm run build

運行測試

# 運行所有測試
npm test

# 運行帶覆蓋率的測試
npm run test:coverage

# 以監聽模式運行測試
npm run test:watch

開發模式

# 以自動重新加載的開發模式啟動
npm run dev

# 以監聽模式的開發模式啟動
npm run dev:watch

項目結構

simplified-mcp-server/
├── src/
│   ├── index.ts              # 主入口點
│   ├── server.ts             # MCP服務器實現
│   ├── cli.ts                # 命令行界面
│   ├── config/
│   │   └── configuration.ts  # 配置管理
│   ├── tools/
│   │   ├── registry.ts       # 工具註冊表
│   │   ├── definitions.ts    # 工具定義實用程序
│   │   └── implementations/  # 工具實現
│   │       ├── social-media-tools.ts  # 社交媒體管理工具
│   │       └── index.ts               # 工具導出
│   ├── api/
│   │   └── client.ts         # 簡化版API客戶端
│   ├── utils/
│   │   ├── errors.ts         # 錯誤處理實用程序
│   │   └── logger.ts         # 日誌記錄實用程序
│   └── types/
│       └── index.ts          # TypeScript類型定義
├── tests/                    # 測試文件
├── dist/                     # 編譯後的JavaScript
└── docs/                     # 文檔

故障排除

常見問題

服務器無法啟動

問題：服務器因配置錯誤無法啟動。 解決方案：

1. 驗證你的.env文件包含SIMPLIFIED_API_TOKEN
2. 檢查你的API令牌是否有效
3. 確保Node.js版本為18.0.0或更高

# 檢查Node.js版本
node --version

# 驗證環境變量
echo $SIMPLIFIED_API_TOKEN

認證錯誤

問題：API調用因認證錯誤失敗。 解決方案：

1. 驗證你的API令牌是否正確且未過期
2. 檢查令牌是否具有必要的權限
3. 確保API基礎URL正確

工具執行失敗

問題：工具返回錯誤或意外結果。 解決方案：

1. 檢查工具參數是否符合預期模式
2. 驗證API端點是否存在且可訪問
3. 檢查服務器日誌以獲取詳細的錯誤信息

# 啟用調試日誌
LOG_LEVEL=debug simplified-mcp-server

連接問題

問題：無法連接到簡化版API。 解決方案：

1. 檢查你的互聯網連接
2. 驗證API基礎URL是否可訪問
3. 檢查是否存在防火牆限制
4. 使用健康檢查工具診斷連接問題

調試模式

啟用調試日誌以進行詳細的故障排除：

LOG_LEVEL=debug simplified-mcp-server

健康檢查

使用內置的健康檢查工具驗證服務器狀態：

{
  "name": "simplified-health-check",
  "arguments": {
    "includeDetails": true
  }
}

獲取幫助

1. 檢查日誌：啟用調試日誌以查看詳細的錯誤信息
2. 驗證配置：確保所有必需的環境變量都已設置
3. 測試連接：使用健康檢查和API狀態工具
4. 檢查API文檔：驗證端點路徑和參數
5. 報告問題：在GitHub倉庫上創建一個問題，並提供日誌和配置詳細信息

API參考

服務器配置

服務器接受以下配置選項：

interface ServerConfig {
  apiToken: string;           // 必需：簡化版API令牌
  apiBaseUrl: string;         // 可選：API基礎URL
  logLevel: 'debug' | 'info' | 'warn' | 'error'; // 可選：日誌級別
  timeout: number;            // 可選：請求超時時間（毫秒）
  retryAttempts: number;      // 可選：重試次數
  retryDelay: number;         // 可選：重試間隔時間（毫秒）
}

工具響應格式

所有工具返回的響應格式如下：

interface ToolResponse {
  content: Array<{
    type: 'text';
    text: string; // 包含實際響應數據的JSON字符串
  }>;
}

成功響應

{
  "success": true,
  "data": { /* 響應數據 */ },
  "message": "Operation completed successfully"
}

錯誤響應

{
  "success": false,
  "error": "Error description",
  "details": { /* 額外的錯誤信息 */ }
}

🔧 技術細節

項目結構

simplified-mcp-server/
├── src/
│   ├── index.ts              # 主入口點
│   ├── server.ts             # MCP服務器實現
│   ├── cli.ts                # 命令行界面
│   ├── config/
│   │   └── configuration.ts  # 配置管理
│   ├── tools/
│   │   ├── registry.ts       # 工具註冊表
│   │   ├── definitions.ts    # 工具定義實用程序
│   │   └── implementations/  # 工具實現
│   │       ├── social-media-tools.ts  # 社交媒體管理工具
│   │       └── index.ts               # 工具導出
│   ├── api/
│   │   └── client.ts         # 簡化版API客戶端
│   ├── utils/
│   │   ├── errors.ts         # 錯誤處理實用程序
│   │   └── logger.ts         # 日誌記錄實用程序
│   └── types/
│       └── index.ts          # TypeScript類型定義
├── tests/                    # 測試文件
├── dist/                     # 編譯後的JavaScript
└── docs/                     # 文檔

服務器配置

interface ServerConfig {
  apiToken: string;           // 必需：簡化版API令牌
  apiBaseUrl: string;         // 可選：API基礎URL
  logLevel: 'debug' | 'info' | 'warn' | 'error'; // 可選：日誌級別
  timeout: number;            // 可選：請求超時時間（毫秒）
  retryAttempts: number;      // 可選：重試次數
  retryDelay: number;         // 可選：重試間隔時間（毫秒）
}

工具響應格式

interface ToolResponse {
  content: Array<{
    type: 'text';
    text: string; // 包含實際響應數據的JSON字符串
  }>;
}

📄 許可證

本項目採用MIT許可證，請參閱LICENSE文件以獲取詳細信息。

貢獻

我們歡迎貢獻！請參閱我們的貢獻指南以獲取詳細信息。

開發設置

1. 分叉倉庫
2. 克隆你的分叉：git clone https://github.com/your-username/simplified-mcp-server.git
3. 安裝依賴項：npm install
4. 創建一個功能分支：git checkout -b feature/your-feature
5. 進行更改並添加測試
6. 運行測試：npm test
7. 構建項目：npm run build
8. 提交更改：git commit -m "Add your feature"
9. 推送到你的分叉：git push origin feature/your-feature
10. 創建一個拉取請求

支持

• API文檔：API文檔
• 文檔：GitHub Wiki
• 問題：GitHub問題
• 討論：GitHub討論