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讨论