Sample Laboratory Data Transformation MCP

Allotrope MCP服务器

一种模型上下文协议（MCP）服务器，提供用于处理Allotrope简单模型（ASM）数据格式的工具。该服务器使AI助手能够根据ASM模式验证仪器数据文件，并发现可用的ASM。

什么是Allotrope？

同素异形体 是实验室和分析仪器数据的数据标准框架。Allotrope Simple Model（ASM）提供了一种标准化的JSON格式来表示仪器数据，使不同系统和组织之间更容易集成、分析和共享科学数据。

特性

此MCP服务器提供以下工具：

• describe_asm：按名称检索特定ASM模型的完整元数据，包括其描述、清单URL、JSON模式URL和数据实例示例URL
• fetch_asm_document：从下载原始ASM JSON文档 purl.allotrope.org 到镜像URI结构的路径上的本地文件系统
• list_asms：从捆绑的参考文件中列出所有可用的Allotrope简单模型（ASM）及其描述
• validate_asm_schema：根据相应的JSON模式验证ASM JSON文档，以验证数据合规性
• validate_field_map：验证由自定义转换器脚本生成的字段映射文件，将源值与ASM值进行比较以确认数据完整性

安装

先决条件

• Python 3.10或更高版本
• 紫外线 包管理器

安装MCP服务器

将以下配置添加到MCP客户端以下载和安装服务器。

{
  "mcpServers": {
    "allotrope-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/aws-samples/sample-laboratory-data-transformation-mcp.git",
        "allotrope-mcp-server"
      ],
      "disabled": false,
      "autoApprove": [],
      "disabledTools": []
    }
  }
}

地方发展设置

# Clone the repository
git clone 
cd allotrope-mcp-server

# Install dependencies
uv sync

# Run the server
uv run allotrope-mcp-server

工作流程图

sequenceDiagram
    participant Client as MCP Client
(AI Assistant / IDE)
    participant Server as allotrope-mcp-server
(FastMCP / stdio)
    participant FS as Local Filesystem
    participant Ref as model_reference.json
(bundled)
    participant PURL as purl.allotrope.org
(HTTPS)

    Note over Client,Server: Trust Boundary: stdio (no auth)

    Client->>Server: list_asms()
    Server->>Ref: read model_reference.json
    Ref-->>Server: ASM name → description map
    Server-->>Client: JSON result

    Client->>Server: describe_asm(model_name)
    Server->>Ref: lookup model_name
    Ref-->>Server: metadata (URIs, description)
    Server-->>Client: JSON result

    Client->>Server: validate_asm_schema(asm_document_path, asm_schema_path)
    Note over Server,FS: Path traversal risk (T1) — sanitised by M1
    Server->>FS: read asm_document_path
    FS-->>Server: ASM JSON document
    Server->>FS: read asm_schema_path
    FS-->>Server: JSON Schema
    Server->>Server: validate document against schema
    Server-->>Client: validation result

    Client->>Server: fetch_asm_document(asm_document_uri, output_dir)
    Note over Server: URI prefix check (PURL_ORIGIN allowlist — A002)
    Note over Server,PURL: TLS encrypted (CN001) — MitM risk (T5)
    Server->>PURL: GET asm_document_uri (HTTPS)
    PURL-->>Server: ASM JSON document
    Note over Server,FS: Arbitrary write risk (T2) — sanitised by M1
    Server->>FS: write to output_dir/

    Server-->>Client: saved file path

与AI编码工具集成

基罗

此回购包括 基洛电力 在 power-instrument-data-to-allotrope/ 文件夹。该电源捆绑了MCP服务器配置和将实验室仪器数据转换为有效ASM JSON的指导工作流程。

安装电源

1. 打开Kiro并转到电源面板（单击 权力 侧边栏中的图标，或运行 View: Show Powers 从命令面板）。
2. 点击 添加自定义电源 然后 从文件夹导入电源。选择 power-instrument-data-to-allotrope/ 此仓库中的目录。
3. Kiro将注册 allotrope-mcp-server MCP服务器自动使用捆绑 mcp.json.

使用权力

安装后，打开新聊天并键入 / 浏览可用电源。选择 同素异形体的仪器数据 并提供：

• input_path --仪器数据文件的路径
• asm_model --目标ASM模型名称（例如。 plate-reader)
• output_path _（可选）_ --生成的ASM JSON的目标（默认为 .asm.json)

Kiro将指导您完成模式发现、数据解析、代码生成和ASM模式验证。

代理技能

回购还包括 代理技能 在 .agents/skills/instrument-data-to-allotrope/SKILL.md技能遵循开放标准，可以独立于Power导入Kiro（或任何兼容的AI工具）。

注： 技能需要 allotrope-mcp-server 要连接MCP服务器。使用电源（如上）自动配置，或通过MCP设置手动添加服务器。

用法示例

在Kiro中配置后，您可以使用自然语言与工具进行交互：

• “列出所有可用的ASM”
• “描述读板器ASM型号”
• “根据读板器模式验证此ASM文档”
• “检查我的仪器数据文件是否为有效的ASM格式”
• “将读板器嵌入模式文档提取到我的项目中”

示例：验证ASM文档

You: Validate tests/testdata/plate_reader_weyland_yutani_valid.json 
     against tests/testdata/plate_reader.embed.schema.json

Kiro将使用 validate_asm_schema 用于检查文档并报告任何验证错误的工具。

示例：获取原始ASM文档

You: Download the plate reader schema document to my project

Kiro将使用 fetch_asm_document 从下载原始JSON文档的工具 purl.allotrope.org 并将其保存在本地镜像URI结构的路径上。

工具参考

describe_asm

按名称返回特定ASM模型的完整元数据。在捆绑包中查找模型 model_reference.json 并将其描述、清单URL、JSON模式URL和数据实例示例URL作为JSON字符串返回。

参数：

退货： 成功时带有模型元数据的JSON对象，或带有 error 钥匙和a valid_model_names 如果无法识别型号名称，请列出。

示例响应（成功）：

{
  "description": "...",
  "asm_manifest": "http://purl.allotrope.org/manifests/...",
  "asm_json_schema": "http://purl.allotrope.org/json-schemas/...",
  "asm_data_instance_examples": ["http://purl.allotrope.org/test/..."]
}

fetch_asm_document

从Allotrope PURL存储库下载原始ASM JSON文档(purl.allotrope.org)并将其保存到本地文件系统中与URI结构镜像的路径。 $ref 参考文献有 不 resolved--文档将完全按接收时的原样保存。

参数：

行为：

• 拒绝不以开头的URI http://purl.allotrope.org （区分大小写）--拒绝时不会进行网络呼叫
• 如果导出的本地路径上已存在该文件，则立即返回路径，而无需重新下载
• 下载文档并在写入之前验证其是否为格式良好的JSON
• 根据需要创建父目录，并将文档保存为UTF-8 JSON格式，带有2个空格的缩进
• 返回一个JSON对象 path 成功的关键，或 error 故障钥匙

示例响应（成功）：

{"path": "/absolute/path/to/json-schemas/adm/plate-reader/REC/2025/12/plate-reader.embed.schema"}

list_asms

列出所有可用的Allotrope简单模型（ASM）及其描述。从捆绑中读取 model_reference.json 文件，并返回ASM ID到描述的映射。

参数： 无

退货： 将ASM标识符映射到其描述的JSON对象，或 error 关键在于失败。

validate_asm_schema

根据相应的JSON模式验证ASM JSON文档。

参数：

validate_field_map

验证由自定义转换器脚本生成的字段映射文件。读取JSON文件并比较每个条目的 source_value 反对其 asm_value 使用字符串相等（主要）和数字浮点相等（回退）。返回包含匹配计数、不匹配和摘要消息的结构化结果。

参数：

退货： 一个JSON对象 matched, total, mismatches，以及 message 成功的关键，或 error 关键在于失败。

示例响应（全部匹配）：

{
  "matched": 19,
  "total": 19,
  "mismatches": [],
  "message": "The conversion script accurately reproduced all 19 field(s) from the raw data file."
}

示例响应（不匹配）：

{
  "matched": 17,
  "total": 19,
  "mismatches": [
    {
      "source_field": "Recorded",
      "source_value": "2023-10-26:11:15:40",
      "asm_field": "measurement time",
      "asm_value": "2023-10-26T11:15:40+00:00",
      "unit": ""
    }
  ],
  "message": "The conversion script needs to be updated to address 2 mismatched field(s)."
}

注： 条目在哪里 asm_value 是ISO 8601标准化形式 source_value （例如时间戳转换）将显示为不匹配。这是有意的——该工具会显示所有价值差异，以便开发人员或人工智能代理可以审查它们是否可接受。

安全考虑

服务器提供什么

• 路径遍历保护 — validate_asm_schema 和 fetch_asm_document 解析并清理所有调用者提供的文件路径。在任何文件I/O发生之前，逃逸预期工作目录的路径都会被拒绝。
• 仅HTTPS外部请求 — fetch_asm_document 强制执行硬编码 http://purl.allotrope.org URI前缀检查。任何与此来源不匹配的URI都会被拒绝，而不会进行网络调用。
• 文件大小限制 — validate_asm_schema 在将文档或模式读入内存之前，强制执行最大文件大小，防止因输入过大而导致资源耗尽。
• 递归架构深度限制 --JSON模式验证限制了递归深度，以防止循环模式的堆栈溢出或CPU耗尽 $ref 循环。
• 清除错误消息 --从返回给MCP客户端的错误响应中剥离内部文件系统路径和堆栈跟踪。

你负责什么

• 保护您的本地环境 --服务器作为本地进程运行，具有与调用用户相同的文件系统权限。确保您的机器、用户帐户和运行服务器的任何Docker容器都得到了适当的强化。
• 验证AI助手行为 --服务器信任MCP客户端传递的所有工具参数，而无需对调用者进行身份验证。受损或行为异常的AI助手可能会提供恶意文件路径或URI。请检查IDE中的工具调用，并将意外调用视为可疑调用。
• 及时注射意识 --从以下位置获取的内容 purl.allotrope.org 或者将从本地文件读取的数据返回给AI助手。这些文件中的恶意内容可能会试图影响后续的辅助操作（间接提示注入）。只将服务器指向您信任的文件和URI。看 快速注射 详见下文。
• 供应链卫生 --使用以下命令从官方PyPI版本和pin依赖版本安装包 uv.lock。在运行服务器之前，请验证您的Python环境没有被篡改。
• 无身份验证层 --MCP stdio接口没有内置身份验证。如果您将服务器暴露在本地进程之外（例如通过网络套接字），您有责任添加适当的访问控制。

快速注射

MCP服务器将AI助手提供的工具参数直接传递给文件系统和网络操作。因为服务器无法区分合法的辅助请求和被恶意内容操纵的请求， 所有MCP工具参数都必须被视为不受信任的输入.

间接快速注射可能发生在以下情况：

• 由读取的文档或模式文件 validate_asm_schema 包含AI助手解释为命令的嵌入式指令。
• 从以下位置获取的JSON文档 purl.allotrope.org 通过 fetch_asm_document 包含使助手使用攻击者控制的参数调用进一步工具调用的文本。
• AI代理循环将一个工具调用的输出作为下一个工具的输入路径或URI传递，而无需人工审查。

MCP客户端操作员的建议缓解措施：

• 在批准工具调用之前，请先检查它们，特别是提供您没有明确请求的文件路径或URI的调用。
• 避免在不检查中间内容的情况下将工具输出直接链接到后续工具输入中。
• 限制服务器可用的工作目录，这样即使成功的路径遍历尝试也无法访问项目外的敏感文件。
• 将任何意外或未经请求的工具调用视为潜在的注入尝试，并中止会话。

发展

运行测试

uv run pytest --cov --cov-branch --cov-report=term-missing

装订和格式化

uv run ruff check .
uv run ruff format .

类型检查

uv run pyright

资源

• 同素异形体基金会
• 模型上下文协议文档

许可证

该项目根据MIT-0许可证获得许可。看 许可证 文件以获取详细信息。

Allotrope Foundation®Simple Models（“ASM”）和其他数据根据预期用途和会员状态，在三个许可证下共同获得许可。请访问https://gitlab.com/allotrope-public/asm/-/blob/main/LICENSE.md了解更多信息。