Veracity MCP

Veracity LRS MCP服务器

一 MCP（模型上下文协议） 将人工智能助手（Claude、Copilot和其他人）连接到 Veracity学习记录商店.直接从您的AI工作流中查询学习者、课程、课程、发布和分析，而无需登录LRS仪表板。

由...建造 浮动 为了 SparkLearn 平台。

______________________________________________________________________

先决条件

• Node.js 18+ —
• 跑步 Veracity LRS 实例（云或本地）
• A. 管理API密钥 对于您的LRS（请参阅 获取API密钥)
• 克劳德桌面 或 克劳德代码 （CLI）

______________________________________________________________________

快速开始

git clone 
cd veracity-lrs-mcp-server
npm run setup

安装向导将：

1. 询问您的LRS URL和API密钥
2. 实时测试连接
3. 在本地保存凭据（从不提交到git）
4. 构建服务器
5. 打印要添加到Claude的确切配置片段

就这样 按照打印的说明将代码段添加到Claude配置中，然后重新启动Claude Desktop。

______________________________________________________________________

获取API密钥

1. 登录您的Veracity LRS仪表板
2. 导航到您的LRS→ 所有管理工具 → API密钥
3. 单击绿色按钮创建新密钥
4. 选择名称和权限级别：

- lrs.api.**.read --只读（查询的安全默认值） - lrs.api.* --完全访问权限（创建/更新工具所需）

1. 复制UUID-这是您的API密钥

注： 这就是 *管理API密钥* （UUID在 x-veracity-api-key header）而不是xAPI访问密钥（其对语句端点使用Basic Auth用户名/密码）。

______________________________________________________________________

手动设置（无向导）

对于CI环境或脚本安装，跳过向导并通过环境变量进行配置：

npm install
npm run build

export VERACITY_LRS_URL="https://yourhost.lrs.io/api/your-lrs-name"
export VERACITY_LRS_API_KEY="your-uuid-api-key"
node build/index.js

或者创建一个 .env 项目根目录中的文件（已在 .gitignore):

VERACITY_LRS_URL=https://yourhost.lrs.io/api/your-lrs-name
VERACITY_LRS_API_KEY=your-uuid-api-key

服务器读取 .env 启动时自动。

______________________________________________________________________

多租户：管理多个LRS实例

对于与多个客户或环境合作的团队，使用命名配置文件而不是环境变量。

每个LRS运行一次安装程序：

npm run setup   # profile: "client-a"
npm run setup   # profile: "client-b"

配置文件存储在 ~/.veracity-lrs/profiles.json （权限已锁定到 600):

{
  "profiles": {
    "client-a": {
      "url": "https://client-a.lrs.io/api/main",
      "apiKey": "uuid-for-client-a",
      "name": "Client A Production"
    },
    "client-b": {
      "url": "https://client-b.lrs.io/api/main",
      "apiKey": "uuid-for-client-b",
      "name": "Client B Staging"
    }
  },
  "default": "client-a"
}

在Claude配置中切换配置文件：

{
  "mcpServers": {
    "veracity-lrs": {
      "command": "node",
      "args": ["/path/to/veracity-lrs-mcp-server/build/index.js", "--profile", "client-b"]
    }
  }
}

______________________________________________________________________

添加到克劳德

克劳德桌面

编辑您的Claude Desktop配置文件：

合并 mcpServers 安装向导打印的块。然后 完全退出并重新打开 克劳德桌面。

克劳德代码（CLI）

添加到您的设置文件中：

# Global (all projects)
~/.claude/settings.json

# Project-level (this project only)
.claude/settings.json

例子：

{
  "mcpServers": {
    "veracity-lrs": {
      "command": "node",
      "args": ["/absolute/path/to/veracity-lrs-mcp-server/build/index.js"],
      "env": {
        "VERACITY_LRS_URL": "https://yourhost.lrs.io/api/your-lrs-name",
        "VERACITY_LRS_API_KEY": "your-uuid-api-key"
      }
    }
  }
}

______________________________________________________________________

可用工具（共20个）

学习者

课程与内容

类

发射

xAPI密钥

分析和日志

连接

______________________________________________________________________

搜索查询

全部 list_* 工具接受可选 search 使用MongoDB查询语法的参数（JSON字符串）：

# Find learners by email
{"email": "jane@example.com"}

# Find courses matching "safety" (case-insensitive)
{"title": {"$regex": "safety", "$options": "i"}}

# Find launches for a specific learner
{"learnerId": "uuid-here"}

______________________________________________________________________

安全

• API密钥从未被记录 或包含在工具响应/错误中
• xAPI密钥密码已编辑 到 ***REDACTED*** 在 list_xapi_keys 输出
• .env 和 profiles.json 在 .gitignore --凭据不受版本控制
• 文件权限警告 如果 profiles.json 其他用户可读
• HTTPS警告 如果配置HTTP端点
• chmod 600 自动应用于 ~/.veracity-lrs/profiles.json 通过安装脚本

______________________________________________________________________

建筑

服务器使用 运输无关设计 因此，相同的工具代码在多种部署模式下运行：

src/
├── index.ts        ← stdio transport (Claude Code/Desktop)
├── server.ts       ← MCP server + tool registration (no transport logic)
├── config.ts       ← env var / profile loading and validation
├── client.ts       ← Veracity LRS HTTP client
├── types.ts        ← TypeScript interfaces for all LRS models
└── tools/
    ├── learners.ts
    ├── courses.ts
    ├── classes.ts
    ├── launches.ts
    ├── keys.ts
    └── analytics.ts

添加流式HTTP传输 （对于远程/云部署）意味着添加一个新的入口点文件——不对工具逻辑或客户端进行更改。

______________________________________________________________________

贡献

有用的命令

npm run setup      # Interactive credential setup
npm run build      # Compile TypeScript → build/
npm run dev        # Watch mode (recompiles on save)
npm start          # Run the compiled server

添加新工具

1. 将工具功能添加到中的相应文件中 src/tools/
2. 通过注册 server.tool(...) 调用（Zod模式+处理程序）
3. 跑 npm run build 和测试

______________________________________________________________________

合格LRS API参考

• LRS管理API文档
• 管理员API（企业版）
• API密钥设置指南
• xAPI规范（ADL）