Ara Records MCP Server

Ara记录MCP服务器


一个定制的模型上下文协议（MCP）服务器，用于与Ara Records API集成，通过Claude Code实现Ansible剧本执行监控。

概述

此MCP服务器提供对Ara Records（Ansible Run Analysis）API端点的编程访问，允许Claude Code查询和分析Ansible剧本执行数据。

设置

先决条件

• Node.js>=18.0.0
• Ara API在本地运行（默认值： http://localhost:8000)

安装

通过npx安装（推荐）

最简单的安装方法是使用 claude mcp add 使用npx：

# Local installation (project-specific, default)
claude mcp add ara-api -- npx -y @ultroncore/ara-records-mcp

# User installation (available globally for your user)
claude mcp add --scope user ara-api -- npx -y @ultroncore/ara-records-mcp

使用自定义ARA服务器：

claude mcp add --scope user ara-api -- npx -y @ultroncore/ara-records-mcp --api-server http://ara.example.com:8080

通过身份验证：

claude mcp add --scope user ara-api -- npx -y @ultroncore/ara-records-mcp --api-server https://ara.example.com --username admin --password secret

范围选项：

• local （默认）：项目特定安装
• user：您的用户帐户可在全球范围内使用
• project：项目特定（与当地相同）

您也可以直接运行它而无需安装：

npx @ultroncore/ara-records-mcp --help

通过npm全球安装

用于全局安装（允许运行 ara-records-mcp 从任何地方）：

npm install -g @ultroncore/ara-records-mcp

然后直接运行：

ara-records-mcp --help
ara-records-mcp --api-server http://localhost:8000

从GitHub安装

直接从GitHub仓库安装：

npm install git+https://github.com/syndr/ara-records-mcp.git

这将自动：

• 克隆存储库
• 安装 @modelcontextprotocol/sdk 依赖
• 使MCP服务器准备好使用

从本地克隆安装

如果您已在本地克隆了存储库：

# Quick setup (recommended)
./setup.sh

# Manual setup
npm install

安装脚本将：

• 验证是否安装了Node.js>=18.0.0
• 安装 @modelcontextprotocol/sdk 和依赖关系
• 验证安装是否成功

常见设置场景

• 初始存储库克隆
• 合并特征分支
• 在工作台之间切换
• 运行后 git clean -fdx

特性

资源（只读访问）

服务器通过以下方式公开以下资源 ara:// URI方案：

• ara://playbooks -已录制的Ansible剧本列表
• ara://plays -录制的Ansible戏剧列表
• ara://tasks -已记录的Ansible任务列表
• ara://hosts -已记录的Ansible主机列表
• ara://results -记录的任务结果列表
• ara://latesthosts -每个主机的最新剧本结果
• ara://running -当前正在执行Ansible剧本（用于实时监控）

工具

• ara_query -查询任意Ara API端点，支持GET/POST和自动分页
• watch_playbook -通过详细的进度跟踪、任务完成状态和执行时间表监控特定剧本的执行情况
• get_playbook_status -快速获取剧本执行状态摘要，无需详细的任务信息
• 删除工作簿 -删除单个剧本记录以及所有相关的剧本、任务和结果
• delete_playbooks_bulk -使用可配置的并发限制同时删除多个剧本记录

技术细节

项目结构

ara-records-mcp/
├── ara-server.js    # Main MCP server implementation
├── package.json     # Node.js dependencies
├── package-lock.json # Locked dependency versions
├── setup.sh         # Automated setup script
├── .gitignore       # Git ignore rules
└── README.md        # This documentation

配置

在Claude代码中配置服务器 .mcp.json 文件：

从GitHub安装后

{
  "mcpServers": {
    "ara-api": {
      "command": "node",
      "args": ["node_modules/ara-records-mcp/ara-server.js"],
      "env": {
        "ARA_API_SERVER": "http://localhost:8000"
      }
    }
  }
}

本地克隆/开发后

{
  "mcpServers": {
    "ara-api": {
      "command": "node",
      "args": ["ara-server.js"],
      "env": {
        "ARA_API_SERVER": "http://localhost:8000"
      }
    }
  }
}

环境变量和CLI参数

可以通过环境变量或CLI参数提供配置。CLI参数优先于环境变量。

优先级：CLI参数>环境变量>默认值

身份验证支持

服务器当前支持 HTTP基本认证 用于Ara API在实现身份验证的反向代理（nginx、Apache等）后面的场景。

在未来的版本中，可能会添加额外的身份验证方法（API令牌、OAuth等）。

基本身份验证示例（环境变量）:

{
  "mcpServers": {
    "ara-api": {
      "command": "node",
      "args": ["node_modules/ara-records-mcp/ara-server.js"],
      "env": {
        "ARA_API_SERVER": "https://ara.example.com",
        "ARA_USERNAME": "your-username",
        "ARA_PASSWORD": "your-password"
      }
    }
  }
}

批量操作的自定义并发示例:

{
  "mcpServers": {
    "ara-api": {
      "command": "node",
      "args": ["node_modules/ara-records-mcp/ara-server.js"],
      "env": {
        "ARA_API_SERVER": "http://localhost:8000",
        "ARA_CONCURRENCY": "10"
      }
    }
  }
}

基本身份验证示例（通过npx的CLI参数）:

claude mcp add ara-api -- npx -y @ultroncore/ara-records-mcp --api-server https://ara.example.com --username your-username --password your-password

备注：两者都有 ARA_USERNAME 和 ARA_PASSWORD （或 --username 和 --password)必须设置身份验证才能启用。如果只提供一个，则不会使用身份验证。

API终点

服务器连接到Ara的REST API v1端点：

• 基本URL: http://localhost:8000 （可通过以下方式配置 ARA_API_SERVER 环境变量或 --api-server CLI参数）
• API路径： /api/v1 （硬编码以保持一致性）
• 完整端点： /api/v1/playbooks, /api/v1/plays等等。

自动分页

所有请求都包括自动分页以防止令牌溢出：

• 默认限制：每个请求10个结果（如果未指定）
• 智能订购：自动应用 order=-started 按时间顺序结束（剧本、戏剧、任务、结果）
• 代币效率：防止MCP工具响应超过令牌限制
• 向后兼容：在提供时尊重显式查询参数

需求

• Ara API必须运行并且可以访问（默认值： http://localhost:8000)
• 安装后需要重新启动Claude Code以加载MCP服务器
• 仅支持GET/POST操作

发展

运行测试

该项目包括一个使用Node.js内置测试运行器的全面测试套件（不需要依赖）。

运行所有测试：

npm test

在监视模式下运行测试（节点19+）：

node --test --watch

测试覆盖率

测试包括：

• CLI参数解析：验证 --api-server, --username, --password 标志和默认值
• 身份验证标头：测试基本身份验证标头生成和base64编码
• 分页逻辑：验证自动限额/订单默认值和参数保存
• MCP模式验证：测试资源、工具、URI映射和响应格式

出版发行

该项目使用自动化的GitHub Actions工作流进行发布：

设置npm Token（一次性）

1. 在以下位置创建npm访问令牌https://www.npmjs.com/settings/your-username/tokens
2. 将令牌添加为GitHub存储库密钥：

- 转到存储库设置→ 秘密与变量→ 行动 - 点击“新建存储库密钥” - 姓名： NPM_TOKEN - 值：你的npm令牌

发布新版本

1. 更新版本 package.json （以下 森伯):

   # For bug fixes
   npm version patch

   # For new features (backward compatible)
   npm version minor

   # For breaking changes
   npm version major

1. 提交并推送到主分支：

   git add package.json
   git commit -m "Bump version to X.Y.Z"
   git push origin main

1. 发布工作流会自动执行以下操作：

- 检测版本更改 - 创建git标签（例如。， v1.1.0) - 使用自动生成的注释创建GitHub版本 - 将包发布到npm

您还可以通过GitHub Actions选项卡中的workflow_dispatch手动触发发布。

测试MCP服务器

验证Ara API正在运行

curl -s http://localhost:8000/api/v1/ | jq

测试MCP服务器启动

timeout 2 node ara-server.js 2>&1

预期产量： *whirring* Ara MCP server activated. Testing chamber operational.

验证步骤

1. Ara API检查：确保Ara正在运行并响应 http://localhost:8000/api/v1/
2. MCP服务器测试：直接运行服务器以确认没有启动错误
3. Claude代码集成：重新启动Claude Code并验证MCP资源是否可用
4. 资源访问：测试访问 ara://playbooks 以及其他资源

用法示例

带自动分页的默认查询

mcp__ara-api__ara_query({ endpoint: "/api/v1/playbooks" })
// Automatically applies: limit=10&order=-started

显式分页

mcp__ara-api__ara_query({ endpoint: "/api/v1/playbooks?limit=10&offset=20" })
// Respects user-provided parameters

特定资源查找

mcp__ara-api__ara_query({ endpoint: "/api/v1/playbooks/2273" })
// No pagination applied for specific resource IDs

实时播放监控

在运行过程中监控剧本执行情况：

// Get detailed progress with task information
mcp__ara-api__watch_playbook({
  playbook_id: 2510,
  include_tasks: true,
  include_results: false
})

// Returns:
// - Execution status (running, completed, failed)
// - Progress percentage (tasks completed / total tasks)
// - Task list with status, timing, and action details
// - Host and play counts

快速状态检查

在没有详细任务信息的情况下检查剧本状态：

mcp__ara-api__get_playbook_status({ playbook_id: 2510 })

// Returns:
// - Current status
// - Progress percentage
// - Start/end times and duration
// - Playbook path

删除单个剧本

永久删除剧本和所有相关数据：

mcp__ara-api__delete_playbook({ playbook_id: 2510 })

// Returns:
// { "success": true, "message": "Playbook 2510 deleted successfully" }

批量删除播放簿

同时删除多个剧本：

mcp__ara-api__delete_playbooks_bulk({ playbook_ids: [2510, 2511, 2512, 2513] })

// Returns:
// {
//   "total": 4,
//   "deleted": [2510, 2511, 2512, 2513],
//   "failed": [],
//   "summary": "Deleted 4/4 playbooks"
// }

批量删除操作使用可配置的并发限制（默认值：5）并发处理请求。通过配置 --concurrency CLI参数或 ARA_CONCURRENCY 环境变量，以平衡性能与API服务器负载。

监控正在运行的播放簿

列出当前正在执行的所有剧本：

// Using resource
ReadMcpResourceTool({ server: "ara-api", uri: "ara://running" })

// Or using ara_query
mcp__ara-api__ara_query({ endpoint: "/api/v1/playbooks?status=running" })

实施说明

建筑

• 使用基于模式的请求处理程序(ListResourcesRequestSchema, ReadResourceRequestSchema, CallToolRequestSchema)
• 实施MCP SDK v1.0.0+标准
• 为全面的API访问提供资源公开和工具功能
• 自动分页和排序，以防止大型结果集中的令牌溢出

实时监控

虽然Ara本身不支持WebSockets，但MCP服务器提供了基于轮询的监控，Claude可以使用它来监视剧本的执行：

• 投票模式：工具返回可重复调用的当前状态
• 进度跟踪：根据已完成的任务与总任务计算完成百分比
• 资源过滤：The ara://running 仅针对正在进行的剧本的资源筛选器
• 结构化数据：返回带有状态、时间和进度信息的规范化JSON

如何用于监控：

1. 从以下位置获取正在运行的剧本列表 ara://running 资源
2. 使用 get_playbook_status() 定期检查进度的工具
3. 使用 watch_playbook() 用于详细任务级别监控的工具
4. 重复调用工具（每隔几秒钟）以跟踪执行进度

错误处理

服务器实现了以下基本错误处理：

• 资源URI无效
• 来自Ara API的HTTP错误
• 网络连接问题
• 缺少或无效的剧本ID

未来的增强功能

• \[x\] 基本身份验证：通过环境变量支持HTTP基本身份验证（已完成）
• \[ \] 其他身份验证方法：支持API令牌、OAuth、JWT或其他身份验证机制
• \[x\] 分页：对大型结果集实施适当的分页处理（已完成）
• \[ \] 高级过滤：为资源端点添加更复杂的查询参数支持
• \[ \] 增强的错误处理：改进错误消息和恢复策略
• \[x\] 实时监控：基于轮询的行动手册执行监控和进度跟踪（已完成-注意：Ara API不支持WebSocket，而是实现了基于轮询的解决方案）
• \[ \] 自动化部署：用于更新和部署MCP服务器的可靠剧本

版本历史

v1.0.0（2025-10-20）-初始版本

• 基本身份验证支持：反向代理场景的HTTP基本身份验证

- 环境变量 ARA_USERNAME 和 ARA_PASSWORD 获取凭据 - 使用base64编码自动生成授权标头 - 未来为其他身份验证方法做好准备

• 实时监控：基于轮询的剧本执行监控

- 新 ara://running 用于列出活动剧本的资源 - watch_playbook 使用任务信息进行详细进度跟踪的工具 - get_playbook_status 快速状态检查工具 - 进度计算（百分比、任务计数、时间信息）

• 分页支持：具有可配置限制和智能排序的自动分页
• MCP SDK集成：使用MCP SDK v1.0.0的基于模式的请求处理程序+
• 令牌优化：防止响应中令牌溢出的保护措施
• GitHub安装：用于直接安装git的正确package.json元数据

许可证

麻省理工学院

支持

有关问题或疑问，请参阅主要项目文档或向存储库提交问题。