Markup.ai MCP Server

一个与Markup.ai API集成的模型上下文协议（MCP）服务器，为像Claude和Cursor这样的AI助手提供高级文本分析和改进功能。

特性

• 文本重写：自动改善文本的清晰度、语气和风格指南合规性
• 内容分析：获取多个维度的详细质量评分
• 写作建议：接收具体的文本改进推荐
• 风格指南支持：AP、芝加哥手册、Microsoft和Proofpoint
• 多种方言：美式英语、英式英语、澳式英语和加式英语
• 语气灵活性：学术、商务、休闲、对话、正式、Z世代、非正式和技术

安装

先决条件

• Node.js 18.0.0 或更高版本
• 一个Markup AI API密钥

设置

1. 克隆仓库：

git clone https://github.com/markupai/mcp.git
cd mcp

2. 安装依赖项：

npm install

3. 配置环境变量：

cp .env.example .env
# 编辑.env文件并添加你的MARKUPAI_API_KEY

4. 构建项目：

npm run build

配置

变量	必需	描述	默认值
MARKUPAI_API_KEY	是	你的Markup.ai API密钥	-
MARKUPAI_BASE_URL	否	API基础URL	https://api.markup.ai
DEBUG	否	启用调试日志	false
MAX_TEXT_LENGTH	否	最大文本长度（字符）	100000
WORKFLOW_TIMEOUT	否	工作流超时（毫秒）	60000
POLL_INTERVAL	否	状态检查间隔（毫秒）	2000
MAX_RETRIES	否	API重试次数	3

与AI IDE的使用

此MCP服务器兼容任何支持模型上下文协议的IDE，包括Claude Desktop和Cursor。

配置

所有MCP兼容IDE的配置相同。只有配置文件位置不同：

IDE	配置文件位置
Claude Desktop (macOS)	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows)	%APPDATA%\Claude\claude_desktop_config.json
Cursor (macOS/Linux)	~/.cursor/mcp.json
Cursor (Windows)	%USERPROFILE%\.cursor\mcp.json

方案1：直接从GitHub运行（推荐）

在IDE的MCP配置文件中添加以下配置：

{
  "mcpServers": {
    "markupai": {
      "command": "npx",
      "args": [
        "-y",
        "github:markupai/mcp"
      ],
      "env": {
        "MARKUPAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

方案2：从本地安装运行

对于本地开发或希望从本地安装运行：

{
  "mcpServers": {
    "markupai": {
      "command": "node",
      "args": ["/path/to/mcp/dist/index.js"],
      "env": {
        "MARKUPAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

注意：更新配置后，请重启IDE以使更改生效。

使用Cursor

当使用此MCP服务器与Cursor一起工作时，当AI想要使用Markup.ai工具时，你会看到一个“调用未定义”的消息和一个“运行工具”按钮。这是正常行为——只需点击“运行工具”以批准分析。这是Cursor执行MCP工具的安全特性，需要手动批准。

可用工具

markupai_rewrite

自动重写和改进文本内容。

参数：

• text（必需）：要重写的文本
• dialect：语言方言（默认："american_english"）
• tone：期望的语气（默认："formal"）
• style_guide：遵循的风格指南（默认："microsoft"）

markupai_check

分析文本的质量问题而不进行修改。

参数：

• text（必需）：要分析的文本
• dialect：语言方言（默认："american_english"）
• tone：要检查的目标语气（默认："formal"）
• style_guide：要检查的风格指南（默认："microsoft"）

markupai_suggestions

获得详细的编辑建议以改进文本。

参数：

• text（必需）：要获取建议的文本
• dialect：语言方言（默认："american_english"）
• tone：建议的目标语气（默认："formal"）
• style_guide：建议的风格指南（默认："microsoft"）

markupai_workflow_status

检查异步工作流的状态。

参数：

• workflow_id（必需）：要检查的工作流ID
• workflow_type（必需）：工作流类型（"rewrites"、"checks"或"suggestions"）

开发

在开发模式下运行

npm run dev

运行测试

# 测试建议端点
node test-suggestions.js

# 测试完整的流程
node test-suggestions-complete.js

构建

npm run build

故障排除

常见问题

1. Cursor中的“调用未定义”消息：这是正常的Cursor行为，不是错误。当你看到带有“运行工具”按钮的消息时，点击该按钮以执行Markup.ai分析。这是Cursor执行MCP工具的安全特性，需要手动批准。

2. Cursor中的“客户端已关闭”错误：尝试清除npx缓存：npx clear-npx-cache 并重新启动Cursor

3. API密钥问题：验证你的MARKUPAI_API_KEY是否正确设置在环境变量中

4. 权限错误：在Unix系统上，确保编译的JavaScript文件是可执行的（chmod +x dist/index.js）

调试模式

通过在环境中设置DEBUG=true启用调试日志：

DEBUG=true npm run start

架构

服务器使用stdio传输实现模型上下文协议，并提供了四个主要工具与Markup.ai API交互。关键特性包括：

• 跨IDE兼容性：适用于Claude Desktop、Cursor以及任何MCP兼容的IDE
• 重试逻辑：指数退避以提高可靠性
• 超时处理：长运行操作的可配置超时
• 全面的日志记录：调试模式用于故障排除
• 类型安全：完整的TypeScript实现，具有适当的类型保护
• 优雅的关闭：终止时进行适当的清理

许可证

MIT

贡献

1. 分叉仓库
2. 创建一个功能分支
3. 进行更改
4. 运行npm run build以确保一切都能编译
5. 提交拉取请求

支持

对于问题和疑问：

• 在GitHub上创建一个问题
• 查看Markup AI文档
• 联系Markup.ai支持