worka42 (Mirithebest)

Workato MCP 服务

这个项目提供了一个与Workato API集成的模型上下文协议（MCP）服务器，使AI助手能够与Workato工作流、配方和数据进行交互。

什么是MCP？

模型上下文协议（MCP）是一项标准，允许人工智能助手连接到外部数据源和工具。此服务在人工智能助手与Workato自动化平台之间架起了一座桥梁。

先决条件

在运行此服务之前，您需要：

• Python 3.10+ 安装在您的系统上
• Git（一种分布式版本控制系统） 用于克隆仓库
• Workato API访问 (API令牌和基础URL)
• 支持MCP的AI助手 （如 Claude Desktop、Cursor 或其他）

安装

1. 克隆仓库

git clone 
cd worka42

2. 安装依赖项

该项目采用 uv 用于依赖管理。如果没有，请先安装它：

# On Windows (PowerShell)
winget install --id=astral-sh.uv

# On macOS
brew install uv

# On Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

然后安装项目依赖项：

uv sync

3. 配置MCP

该项目包含一个智能包装脚本（run_mcp.py) 它能自动检测您的环境并使用正确的 Python 设置。

第一步： 将MCP模板复制到您的Cursor设置中：

# Windows
copy mcp.json.template %USERPROFILE%\.cursor\mcp.json

# macOS/Linux
cp mcp.json.template ~/.cursor/mcp.json

第二步： 编辑复制的文件，填写您的详细信息：

{
  "mcpServers": {
    "workato": {
      "command": "python",
      "args": ["/absolute/path/to/worka42/run_mcp.py"],
      "env": {
        "WORKATO_API_BASE_URL": "https://www.workato.com/api/",
        "WORKATO_API_TOKEN": "your_workato_api_token_here"
      }
    }
  }
}

重要提示：

• 替换 /absolute/path/to/worka42 使用您的实际项目路径
• 替换 your_workato_api_token_here 使用您的Workato API令牌

第三步： 重启光标以加载新的MCP配置。

包装脚本的工作原理

这个（或“该”） run_mcp.py 脚本自动检测您的环境：

• 如果 .venv 存在 （跑步之后 uv sync): 用途 uv run python app/services/mcp_service.py
• 如果没有 .venv回退到直接（模式/方式） python app/services/mcp_service.py

这确保了在不同Python配置下的兼容性，同时保留了（原有）优势 uv的依赖管理。

⚠️ 重要提示： 永远不要把自己的 mcp.json 由于文件包含敏感的API密钥，请将其提交到版本控制中。该文件已添加至 .gitignore.

运行MCP服务

选项1：作为MCP服务器运行（推荐）

该服务旨在作为MCP服务器运行，以便AI助手能够连接到该服务器：

uv run python app/services/mcp_service.py

选项2：作为FastAPI服务器运行

你也可以将其作为独立的 FastAPI 服务器来运行以进行测试：

cd app
uv run uvicorn services.mcp_service:app --reload --host 0.0.0.0 --port 8000

连接AI助手

光标

1. 打开光标
2. 新闻界；媒体 Cmd/Ctrl + Shift + P 打开命令面板
3. 输入“MCP：连接到服务器”
4. 选择您的 mcp.json 文件
5. Workato MCP 服务器将在您的 AI 对话中可用

其他兼容MCP的助手

大多数兼容MCP的助手都会寻找 mcp.json 在您的项目目录中放置文件，或者允许您在设置中指定其位置。

可用的MCP工具

一旦连接成功，您的AI助手将能够访问以下Workato操作：

食谱管理

• 列出食谱，并支持过滤和分页功能
• 获取食谱详情、版本及健康报告
• 查看配方作业及执行历史

连接管理

• 列出并管理Workato连接
• 查看连接器元数据和自定义连接器

数据操作

• 访问查找表和数据表
• 查询和操作Workato数据

项目管理

• 管理Workato项目和部署
• 查看项目属性和构建情况

用户管理

• 列出工作区成员及其权限
• 管理用户角色和权限

环境变量

你可以使用环境变量来配置服务：

export WORKATO_API_BASE_URL="https://www.workato.com/api/"
export WORKATO_API_TOKEN="your_token_here"
export LOG_LEVEL="INFO"

故障排除

常见问题

1. “MCP 包不可用”错误

- 确保你已安装所有依赖项： uv sync - 验证FastMCP是否已安装： uv run python -c "import mcp.server.fastmcp"

1. 运行时提示“权限被拒绝”

- 确保你对Python文件有执行权限 - 试着和……一起跑步 uv run python -m app.services.mcp_service

1. AI助手无法连接或无法识别工具

- 检查MCP配置位置确保 mcp.json 位于您的 Cursor 设置目录中（~/.cursor/ 或者 %USERPROFILE%\.cursor\) - 验证项目路径确保其中的绝对路径是 mcp.json 指向你的实际项目目录 - 测试包装脚本跑 python run_mcp.py 从项目目录中查看是否能无错误地启动 - 检查环境变量验证 WORKATO_API_TOKEN 已正确设置在 mcp.json - 验证JSON确保 mcp.json 是有效的JSON（没有尾随逗号，引号使用正确） - 重启光标（或：重置光标）在更改MCP配置后，务必重启Cursor

1. “没有可用工具”或工具列表为空

- 测试包装脚本跑 python run_mcp.py 验证MCP服务器是否正确启动 - 检查依赖项确保所有依赖项都已安装 uv sync - 验证API令牌测试您的Workato API令牌： uv run python -c "from app.services.workato_service import WorkatoService; WorkatoService().get_user_info()" - 检查包装脚本确保 run_mcp.py 位于您的项目根目录中

1. Workato API 错误

- 请验证您的API令牌是否有效且具有必要的权限 - 检查API基础URL是否正确 - 确保您的Workato帐户已启用API访问权限

调试步骤

1. 测试包装脚本：

   cd /path/to/worka42
   python run_mcp.py

1. 检查工具是否已注册：

   uv run python -c "from app.services.mcp_service import app; import asyncio; tools = asyncio.run(app.list_tools()); print('Tools count:', len(tools))"

1. 验证环境和依赖项：

   # Check if dependencies are installed
   uv run python -c "import mcp.server.fastmcp; print('FastMCP available')"

   # Check environment variables
   uv run python -c "import os; print('API Token set:', bool(os.getenv('WORKATO_API_TOKEN')))"

1. 测试Workato API连接：

   uv run python -c "from app.services.workato_service import WorkatoService; print('API test:', WorkatoService().get_user_info())"

调试模式

通过设置环境变量来启用调试日志记录：

export LOG_LEVEL="DEBUG"

发展

项目结构

worka42/
├── app/
│   ├── __init__.py             # Package initialization
│   ├── services/
│   │   ├── __init__.py         # Services package initialization
│   │   ├── mcp_service.py      # Main MCP server
│   │   └── workato_service.py  # Workato API client
│   ├── utils/
│   │   ├── __init__.py         # Utils package initialization
│   │   ├── logging.py          # Logging configuration
│   │   ├── params.py           # Parameter parsing utilities
│   │   └── response_helpers.py # Response formatting utilities
│   ├── pyproject.toml          # Python project configuration
│   └── uv.lock                 # uv dependency lock file
├── mcp.json.template           # MCP configuration template
├── .gitignore                  # Git ignore rules
├── run_mcp.py                  # MCP server wrapper script
└── README.md                   # This file

实用模块

该项目包含几个实用模块 app/utils/:

• logging.py使用loguru进行集中日志配置
• params.pyMCP工具的参数解析和验证实用程序
• response_helpers.py标准化响应格式化功能

添加新的MCP工具

要添加新的MCP工具，请修改 app/services/mcp_service.py 并添加新功能 @app.tool 装饰器：

@app.tool("new_tool_name", "Description of what this tool does")
def new_tool_function(param1: str, param2: int) -> dict:
    # Your tool implementation here
    return {"result": "success"}

安全注意事项

• 永远不要提交API令牌 进行版本控制
• 使用环境变量 对于敏感配置
• 验证所有输入 在处理之前
• 实施适当的认证措施 如果公开提供服务

支持

对于以下相关问题：

• MCP协议检查一下 MCP文档
• Workato API（Workato应用程序编程接口）参考 Workato API 文档
• 本服务在项目仓库中打开一个问题（或议题）

许可证

\[在此添加您的许可证信息\]