Maps Governed Data Records to documented formats while reporting the transformation status of every value.
Also known as SemanticDataCharter/sdc-mapper
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- 1,488
- Latest version
- 4.3.2
- Last commit
- Nov 10, 2026
- License
- Apache-2.0
What is sdc-mapper MCP?
sdc-mapper maps Governed Data Records to documented formats while reporting the transformation status of every value.
Summary generated from the project's README
About sdc-mapper MCP server
The sdc-mapper serves as a core engine for mapping Governed Data Records to specific documented formats. It is designed for developers and agents working with semantic data who need to validate records against a model and transform them into standardized outputs. The server operates as an MCP stdio server, allowing AI agents to interact with it directly to perform mapping tasks, check mapping files, or verify the fidelity of records across multiple target formats simultaneously.
Users can map data to several released target packages, including OASIS UBL 2.3, UN/EDIFACT D.24A, OMOP CDM 5.4, HL7 FHIR R4, and HL7 v2.5.1. The system distinguishes itself by providing a detailed report for every single value, explaining how it reached the target or why it could not be held. It handles Exceptional Values based on ISO 21090 to ensure that missing or unusable data is accounted for. All mapping calls are recorded in a hash-chained log for auditability.
What you can do with it
- 1Transform records to standard formatsAn agent can map an XML record to a specific target package like UBL or FHIR using a YAML mapping file.
- 2Audit data transformation fidelityA developer can compare how a single record performs across every installed target format to check for Exceptional Values.
- 3Validate mapping configurationsYou can verify that a YAML mapping file is correctly structured and bound to the right model and target versions.
- 4Verify transformation logsAn automated process can summarize and verify the hash-chained logs to ensure mapping history integrity.
Written from the project's README. Every use case is checked against a quote from it.
How to install sdc-mapper MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall sdc-mapper MCP in Claude Code
$ claude mcp add sdc-mapper -- uvx sdc-mapperInstall sdc-mapper MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"sdc-mapper": {
"command": "uvx",
"args": [
"sdc-mapper"
]
}
}
}Install sdc-mapper MCP in VS Code
.vscode/mcp.json
{
"servers": {
"sdc-mapper": {
"type": "stdio",
"command": "uvx",
"args": [
"sdc-mapper"
]
}
}
}Install sdc-mapper MCP in VS Code CLI
$ code --add-mcp '{"name":"sdc-mapper","type":"stdio","command":"uvx","args":["sdc-mapper"]}'Install sdc-mapper MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"sdc-mapper": {
"command": "uvx",
"args": [
"sdc-mapper"
]
}
}
}Install sdc-mapper MCP in Codex
$ codex mcp add sdc-mapper -- uvx sdc-mapperInstall sdc-mapper MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.sdc-mapper] command = "uvx" args = ["sdc-mapper"]
Install sdc-mapper MCP in Gemini CLI
$ gemini mcp add -s user sdc-mapper uvx -- sdc-mapperInstall sdc-mapper MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"sdc-mapper": {
"command": "uvx",
"args": [
"sdc-mapper"
]
}
}
}Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablesemanticdatacharter/sdc-mapper is public and reachablegithub.com/semanticdatacharter/sdc-mapper ↗Pass
- Package names this repository as its sourcesdc-mapper names semanticdatacharter/sdc-mapper as sourcepypi.org/project/sdc-mapper/ ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for sdc-mapperpypi.org/project/sdc-mapper/ ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-10github.com/semanticdatacharter/sdc-mapper ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from sdc-mapperPass
- No critical advisory in the package or its dependencies17 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubsdc-mapper
The shared core of the Semantic Data Charter's Governed Data Record mappers. It validates a record, reads the model the record names, resolves every value against what the model says about it, hands the result to a target mapper, and reports every value: how it reached the target, or that the target cannot hold it. Where the record says why a value is missing or unusable (an Exceptional Value, from the ISO 21090 null flavors), the report also says whether the target could say it too. Every call is appended to a hash-chained log that holds no values.
Each target format is its own package (sdc-gdr2ubl, sdc-gdr2edifact, sdc-gdr2omop, ...) registered under the
entry-point group sdc_mapper.targets. Outbound only. Apache 2.0.
Status: 4.3.2. Five target mappers are released: sdc-gdr2ubl (OASIS UBL 2.3), sdc-gdr2edifact (UN/EDIFACT
D.24A), sdc-gdr2omop (OMOP CDM 5.4), sdc-gdr2fhir (HL7 FHIR R4) and sdc-gdr2hl7v2 (HL7 v2.5.1).
Use
sdc-map targets
sdc-map map TARGET record.xml --package DIR [--mapping m.yaml] [-o out/]
sdc-map fidelity record.xml --package DIR # every installed target, side by side, per Exceptional Value
sdc-map check-mapping m.yaml --package DIR
sdc-map log summary --days 7 | sdc-map log verify
sdc-mapper [--log-dir DIR] [--host URL] # MCP stdio server (also sdc-mapper-mcp): the primary way agents use the mappers
A model is a package directory (dm-<ct>.jsonld, dm-<ct>.xsd) or a published model's --ct-id, fetched from the
SDCStudio host; with neither, the record's own root names it. Exit status: 0 mapped, 1 refused, 2 error.
Also listed on mcprush.
The three outcomes
- valid: mapped.
- valid with Exceptional Values: a value that failed its constraint is covered by an Exceptional Value (Invalid, with the constraint kept), and the rest of the record is mapped. Exceptional Values written at the source (a refusal, a masked field) are kept as written.
- refused: a broken structure, the wrong model, or an error no Exceptional Value covers. Nothing is written; the reasons are returned and logged.
Mapping files
YAML, validated against schemas/mapping.schema.json, bound to one model schema version and one target version.
mapping: {id: credit-note-to-ubl, version: 1}
model: {ct_id: jkuyr38hydqaiwlq5vhp2rjr, schema_sha256: "…"}
target: {name: OASIS UBL, version: "2.3 CreditNote"}
rules:
- cluster: <Accounting Supplier Party> # a cluster to a target element
to: cac:AccountingSupplierParty
- cluster: <Party> # relative to the enclosing mapped cluster
to: cac:Party
- component: <Party Identification Value>
to: cac:PartyIdentification/cbc:ID
transform: copy
- component: <Party Identification Scheme>
to: cac:PartyIdentification/cbc:ID/@schemeName # an attribute of the same element
transform: copy
- component: <Line Extension Amount>
to: cbc:LineExtensionAmount
transform: copy
units: {to: "@currencyID", transform: copy}
- cluster: <Party Contact>
to: "-"
transform: omit
reason: the target profile carries no contact
Transforms: copy, code (a table), format, constant, binding (the code the model defines an enumerated value
by), link (the code of the concept the component links to), omit; clusters group or omit. binding and link
take a system (http://loinc.org, http://snomed.info/sct, a code list's IRI); their text is the model's, so a mapper
reports it as a lookup (LOOKUP_TRANSFORMS). Steps: .. up, . none, +name an element of the value's own, =name
the element of that name the parent already has. within: restricts a rule to a context. A value no rule reaches is
reported, never dropped. place(record, mapping) turns a record and its mapping into placements a mapper writes from.
Codes the model names
sdc_mapper.codes reads the IRIs the component libraries use for a concept as a code system and a code: LOINC codes
and answers, SNOMED CT, NCI Thesaurus, and any code list whose IRI ends in #code (UBL's, HL7's). A code system is
named by the IRI FHIR uses for it; a mapper turns that into its own name for the system (OMOP's vocabulary_id, HL7
v2's coding system). bound_code(value) is the code an enumerated value is defined by, linked_code(value) the code
of the concept its component links to (skos:exactMatch, then dcterms:subject), and model_codes(value) every code
the model names for it: a target code that is one of these came from the model.
Writing to a target
place() gives each value its target steps. Steps written =name join an element made by another value, so a writer
holds those writes back until every other value is written, then writes them shallowest first: sort them by
join_depth(steps). A row-oriented target (a set of tables, as OMOP's) can treat each step as a table or a column,
+TABLE as one new row per value, and keep the record's own row (its person, its document) under a name of its own;
sdc-gdr2omop does so with a RECORD table.
Writing a mapper
A mapper has name, target, target_version, package, version, an Exceptional Value table (ev_table: an
EVRule per ISO 21090 code: preserved, degraded, carried or lost) and map(record, mapping) -> MapResult. It returns
one ValueOutcome for every value it was given, never writes a rejected value as a value, and registers itself:
[project.entry-points."sdc_mapper.targets"]
ubl = "sdc_gdr2ubl:UBLMapper"
Tests
python -m pytest tests -q (offline). The fixture is a HalvorsenDemo Credit Note record and its model's package;
the reference mapper in tests/refmapper.py is a flat CSV used only to exercise the contract.
License
Apache 2.0. See NOTICE for the shipped SDC4 reference model schema and the fixture.
sdc-mapper MCP questions
How do I add sdc-mapper MCP to Claude Code?
Run claude mcp add sdc-mapper -- uvx sdc-mapper in your terminal. Add --scope user to make it available in every project.
How do I add sdc-mapper MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What formats can sdc-mapper map to?
It supports several target formats including OASIS UBL 2.3, UN/EDIFACT D.24A, OMOP CDM 5.4, HL7 FHIR R4, and HL7 v2.5.1.
How does the server handle missing or unusable values?
It uses ISO 21090 null flavors (Exceptional Values) to report why a value is missing or unusable and whether the target format can support that status.
What are the possible outcomes of a mapping operation?
The outcomes are valid (successfully mapped), valid with Exceptional Values (mapped with specific constraints or refusals preserved), or refused (broken structure or errors).