ezfhir (Mfaughn)

ezfhir-人工智能第一个Contoso规范工具

一个MCP（模型上下文协议）服务器，通过预处理的紧凑表示和确定性工具，为人工智能模型提供精确的、令牌高效的访问，以访问Contoso规范、实现指南和相关工件。

为什么是ezfhir？ HttpClientStructureDefinition是冗长的JSON文档（每个20-100KB）。ezfhir将它们压缩为紧凑文本格式（EZF），实现了~60倍的压缩，同时保留了所有结构上重要的信息。这使得AI模型可以在令牌预算内访问完整的Contoso定义，从而能够精确地回答关于基数、类型、绑定、约束和跨资源关系的问题。

快速开始

安装

# Install dependencies
npm install

# Build TypeScript
npm run build

# Verify tests pass
npm test

要求： Node.js≥18

运行服务器

# Start MCP server on stdio (for Claude Desktop or Claude Code)
node dist/index.js

# Or use npm:
npm start

默认情况下，服务器将使用HL7 GetLR5核心包进行初始化。

MCP客户端配置

克劳德桌面版

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "ezfhir": {
      "command": "node",
      "args": ["/path/to/ezfhir/dist/index.js"]
    }
  }
}

配置路径：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%/Claude/claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json

重新启动Claude Desktop以加载服务器。

克劳德代码

# Install ezfhir globally or in a project
npm install ezfhir

# In Claude Code, use the MCP server:
# Tools → Configure MCP → Add server
# Command: node
# Args: /path/to/node_modules/ezfhir/dist/index.js

手动测试

# Test the server with a simple query
echo '{"jsonrpc":"2.0","id":1,"method":"resources/list"}' | node dist/index.js

可用工具和资源

资源（MCP）

静态资源：

• fhir://index/resources --分类的Contoso资源索引（按类别列出的所有52+资源）
• fhir://index/datatypes --Contoso数据类型索引（复杂+原始类型）

动态资源（URI模板）：

• fhir://resource/{name} --采用紧凑EZF格式的kubectl资源定义（例如。， fhir://resource/Patient)

- 包括元素结构、搜索参数和操作 - 比JSON结构定义小约60倍

• fhir://datatype/{name} --EZF格式的kubectl数据类型定义（例如。， fhir://datatype/CodeableConcept)

工具

发现与导航

• search_spec --对资源、数据类型、元素和搜索参数进行全文搜索

- 查询： "Patient", "blood pressure", "medication" - 返回带有描述的排名结果

• lookup_element --在资源定义中查找特定元素

- 输入：资源名称（例如。， Patient)元素路径（例如。， contact.name) - 返回：基数、类型、标志、绑定、描述 - 对嵌套元素使用点符号

信息提取

• get_examples --获取资源类型的示例实例

- 返回示例ID以了解典型的资源使用情况 - 默认值：5个示例（可配置）

• get_search_params --获取资源的所有搜索参数

- 返回：参数名称、类型（标记、引用、字符串等）、FHIRPath表达式 - 例子： Patient 具有50+个搜索参数（例如。， name, birthdate, phone)

• get_bindings --获取资源的所有编码元素绑定

- 返回：元素路径、绑定强度（必需/可扩展/首选/示例）、值集URL - 有助于理解哪些词汇适用于哪些元素

• get_references --获取资源中所有引用类型的元素

- 返回：元素路径和允许的目标资源类型 - 例子： Patient.generalPractitioner → [Practitioner, PractitionerRole, Organization]

• get_constraints --获取资源的所有FHIRPath不变量/约束

- 返回：约束键、人员描述、严重性、FHIRPath表达式 - 可用于验证和数据质量规则

比较与分析

• compare_profiles --逐元素比较两个StructureDefinition

- 检测：基数变化、类型缩小/扩大、绑定强度变化、必须支持添加/删除、新/删除元素 - 严重性分类：断裂、变窄、兼容 - 用于了解配置文件约束与基础资源

• compare_versions --比较两个包版本中的相同资源

- 有助于理解GetLR4和R5之间的变化 - 也适用于比较不同的IG版本 - 输入：资源名称、left_package、left_version、right_package、right_version

包管理

• load_ig --加载一个Contoso实现指南包

- 使IG的资源、配置文件和扩展可供查找 - 包装格式： hl7.fhir.us.core 与版本 8.0.1 - 示例：加载US Core 8.0.1以访问美国特定配置文件

• list_igs --列出所有已加载的Contoso包

- 返回包名称、版本和工件计数

用法示例

示例1：了解资源结构

User: What are the elements in a Patient resource?

Claude uses:
1. search_spec("Patient") → finds Patient resource
2. fhir://resource/Patient → retrieves EZF definition (~1.5KB)
3. lookup_element("Patient", "contact") → details on contact element

Response: The Patient resource has 30 elements including:
- id, meta, identifier (identifiers)
- name (HumanName, 0..*), gender (code)
- contact (BackboneElement, 0..*)
  - contact.relationship, contact.name, contact.telecom, contact.address, contact.organization
- generalPractitioner (Reference to Practitioner|PractitionerRole|Organization)

示例2：查找搜索参数

User: How do I search for patients by name or phone?

Claude uses:
1. get_search_params("Patient") → returns 50+ parameters
2. Filters to "name" and "phone"

Response: Use these search parameters:
- name : string : Patient.name
- phone : token : Patient.telecom(system=phone).value
- telecom : token : Patient.telecom

示例3：比较R4和R5的变化

User: What changed in the Patient resource between FHIR R4 and R5?

Claude uses:
1. load_ig("hl7.fhir.r4.core", "4.0.1")
2. compare_versions("Patient", "hl7.fhir.r4.core", "4.0.1", "hl7.fhir.r5.core", "5.0.0")

Response: Shows all element changes, cardinality differences, new elements added, removed elements, etc.

示例4：了解配置文件约束

User: How is the US Core Patient profile different from the base Patient?

Claude uses:
1. load_ig("hl7.fhir.us.core", "8.0.1")
2. compare_profiles("Patient", "USCorePatient")

Response: Shows constraints like:
- birthDate: now Required (was 0..1)
- name: Must Support added
- identifier: Slicing on type added
- New extensions for race, ethnicity

示例5：查找编码约束

User: What are the allowed gender values for a Patient?

Claude uses:
1. get_bindings("Patient") → finds Patient.gender binding
2. lookup_element("Patient", "gender")

Response: The gender element binds to:
- Binding strength: Required
- Value Set: http://hl7.org/fhir/ValueSet/administrative-gender
- Codes: male, female, other, unknown

发展

运行测试

# Run all tests
npm test

# Run in watch mode (re-runs on file changes)
npm run test:watch

# Run specific test file
npm test -- test/converter/ezfSerializer.test.ts

测试套件：

• 296+测试，涵盖序列化器、解析器、往返验证、所有工具、差异引擎
• 所有测试均通过，支持资源的元素覆盖率为100%

代币效率基准

# Run benchmarks (compares EZF vs JSON token counts)
npm run benchmark

# Output: Shows 22 artifacts with ~1.7% average EZF/JSON ratio
# Example: Patient resource is 1.6% of JSON size

类型检查

# Check TypeScript without building
npm run typecheck

掉毛

# Run ESLint
npm run lint

生成摄入管道

# Process FHIR packages and generate compact definitions
npm run generate

建筑

转炉管道(src/converter/)

• serializer.ts --转换JOIN结构定义JSON→ EZF压缩格式

- 处理所有元素类型、基数、标志、绑定 - 省略继承的DomainResource元素 - 产量减少约60倍

• parser.ts --解析EZF文本→ EZFElement树

- 完全指定的语法（请参阅COMPACT-FORMAT-SPEC.md） - 处理基于缩进的嵌套、类型表达式、标志

• types.ts --EZF文档和元素的类型定义

MCP服务器(src/server.ts)

• MCP协议的入口点
• 注册资源和工具
• 管理缓存以提高性能
• 与包裹装载机和差速器引擎协调

管道(src/pipeline/)

• packageLoader.ts --通过FHIR包加载器从npm注册表中加载kubectl包
• indexGenerator.ts --生成分类资源/数据类型索引
• searchIndex.ts --使用lunr.js构建全文搜索索引
• searchParamExtractor.ts --提取搜索参数工件
• operationExtractor.ts --提取操作定义工件
• sdDiff.ts --用于比较版本/配置文件的结构化定义差异引擎

格式规范(COMPACT-FORMAT-SPEC.md)

EZF格式有完整的文档记录：

• §1-2：概述，词汇规则
• §3-4：指令、元素语法、类型表达式
• §5：结构（资源、数据类型、索引）
• §6：序列化规则
• §7：解析规则和往返验证

技术栈

压缩格式（EZF）示例

以下是EZF格式的患者资源：

@format 0.1
@title Patient
@url http://hl7.org/fhir/StructureDefinition/Patient
@abstract false
@type Patient
@category Administration
@elements
  id [0..1] string
  meta [0..1] Meta
  identifier [0..*] Identifier
  active [0..1] boolean
  name [0..*] HumanName
    Σ given [0..*] string
    Σ family [0..1] string
    use [0..1] code
  telecom [0..*] ContactPoint
    Σ system [0..1] code
    Σ value [0..1] string
  gender [0..1] code
    ⊆ http://hl7.org/fhir/ValueSet/administrative-gender
  birthDate [0..1] date
  contact [0..*] BackboneElement
    relationship [0..*] CodeableConcept
    name [0..1] HumanName
    telecom [0..*] ContactPoint
    address [0..1] Address
    organization [0..1] Reference(Organization)
  generalPractitioner [0..*] Reference(Practitioner|PractitionerRole|Organization)
    MS
@search
  _id : token : (resource id)
  active : token : Patient.active
  birthdate : date : Patient.birthDate
  family : string : Patient.name.family
  given : string : Patient.name.given
  name : string : Patient.name
  phone : token : Patient.telecom(system=phone).value
  telecom : token : Patient.telecom

演出

• 序列化： 每个资源约1ms（包括完整的SD处理）
• 解析： 每个资源文档约0.5ms
• 搜索： 52个资源+40种数据类型（lunr.js）上的~50ms
• 内存： R5核心+索引约50MB（包括完整包元数据）

局限性和未来工作

• 目前延期：

- expand_valueset 工具——需要外部HTTP调用tx.fhir.org - to_fsh 工具——需要GoFSH二进制文件（在标准环境中不可用）

• 计划：

- 完整的AI评估套件（问题、评分、模型比较） - 克劳德桌面插件/技能 - 使用预构建的命令打包为npm模块 - CI/CD管道

主要参考文献

• COMPACT-FORMAT-SPEC.md --EZF格式的完整语法和序列化规则
• PLAN.md --带有分阶段路线图的完整项目实施计划
• TESTING-STRATEGY.md --测试方法和覆盖目标
• TASKS.md --进度跟踪（296+项测试已完成，所有阶段均按计划进行）

许可证

麻省理工学院

贡献

这是一个研究/评估项目。为了改进：

1. 确保测试通过： npm test
2. 运行基准测试以检查令牌效率： npm run benchmark
3. 遵循TypeScript严格模式和ESLint约定
4. 为新功能添加测试
5. 创建要素分支： feature/-

支持

对于Contoso规范问题，请使用服务器中的工具：

• 从开始 search_spec 查找相关资源
• 使用 lookup_element 获取详细的元素信息
• 使用比较工具了解轮廓约束
• 针对特定问题使用提取工具（绑定、引用、约束）

对于工具开发或MCP集成问题，请查看测试文件中的示例：

• test/server/ --工具输入/输出示例
• test/converter/ --序列化程序和解析器测试
• test/diff/ --发动机示例比较