icf-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

ICF MCP Server (icf-mcp-server v0.1.0) is a Model Context Protocol (MCP) server that provides tools for accessing the WHO International Classification of Functioning, Disability and Health (ICF) classification system via the WHO ICD-API. It enables AI assistants (e.g., Claude) to look up, search, and browse ICF codes through a standardized tool interface.

Repository: stayce/icf-mcp-server (MIT License)

Architecture

Package Layout

src/icf_mcp/
├── __init__.py      # Package exports: main, mcp, WHOICFClient, ICFEntity, ICFSearchResult
├── instruments.py   # Clinical assessment instruments with ICF mappings (971 lines)
├── server.py        # FastMCP server with 17 MCP tools + qualifier parsing (1400 lines)
└── who_client.py    # Async WHO ICD-API client with OAuth2 auth (509 lines)

Uses src/ layout with Hatchling build system. Entry point: icf-mcp = "icf_mcp:main".

Three-Module Design

• server.py — FastMCP server defining 17 tools via @mcp.tool() decorators:
  • icf_lookup(code) — Look up a specific ICF code (e.g., "b280", "d450")
  • icf_search(query, max_results=10) — Search by keywords
  • icf_browse_category(category) — Browse categories and sub-chapters ("b", "d4", "e3", etc.)
  • icf_get_children(code) — Get subcategories of a code
  • icf_explain_qualifier(component, qualifier) — Component-specific qualifier reference (b/s/d/e)
  • icf_overview() — Return full ICF classification overview
  • icf_get_parent(code) — Navigate up the hierarchy to a code's parent category
  • icf_get_siblings(code) — Get codes at the same level (same parent)
  • icf_validate_code(code) — Validate code format, qualifiers, and verify existence
  • icf_parse_qualified_code(code) — Parse fully qualified codes (d450.23, s730.312, e120+3)
  • icf_build_profile(codes) — Build a structured functional profile from multiple codes
  • icf_get_code_chain(code) — Show the full hierarchy path from root to a code
  • icf_list_instruments(domain) — List available clinical assessment instruments
  • icf_instrument_details(name) — Full instrument spec: items, scoring, ICF mappings
  • icf_score_instrument(name, responses) — Score responses and get clinical interpretation
  • icf_suggest_instruments(condition, icf_code, domain) — Suggest instruments for a condition or ICF code
  • icf_instrument_icf_mapping(name) — Show how an instrument maps to ICF codes
• instruments.py — Clinical assessment instrument definitions with ICF mappings. 11 instruments: GAD-7, PHQ-9, RADAI-5, SLEDAI-2K, WHODAS 2.0, HAQ-DI, PROMIS-10, CAT, ODI, NRS Pain, Short FES-I. Includes scoring logic, score interpretation ranges, and alias resolution.
• who_client.py — WHOICFClient class handling OAuth2 client credentials auth and all HTTP communication with the WHO ICD-API