MapForge
MapForge is the knowledge-graph generation engine. It takes a source data file, profiles it, maps its columns onto a discipline schema, resolves entities against the existing graph, and — after a human approval gate — writes new nodes and relationships into the knowledge graph.
MapForge is exposed as MCP tools (and a CLI). Every tool name is prefixed mapforge_.
The workflow
MapForge works over a bundle — a working session that accumulates artifacts (a mapping, a resolution, a routing plan, generated Cypher, an approval manifest) as it progresses through stages:
create_bundle → inspect → [templates] → map_heuristic → resolve → plan → emit → approve → submit| Step | Tool | What happens |
|---|---|---|
| 1 | mapforge_create_bundle |
Create an empty bundle; returns a bundle_dir handle. |
| 2 | mapforge_inspect |
Profile the source file: column names, inferred types, row-count estimate, sample values. |
| 3 | mapforge_templates_list / mapforge_templates_show |
(Optional) list or inspect the built-in discipline templates. |
| 4 | mapforge_map_heuristic |
Draft a mapping.yaml from the column profile (optionally against a schema template). The source file's checksum is sealed at map time. |
| 5 | mapforge_resolve |
Resolve source entities against the existing graph; returns resolved / unresolved / ambiguous counts. |
| 6 | mapforge_plan |
Plan how resolved entities route into the graph; writes a routing.yaml. |
| 7 | mapforge_emit |
Generate the Cypher that would create the new nodes and relationships. Nothing is written to the graph yet. |
| 8 | mapforge_approve |
Human approval gate — a reviewer approves the bundle, recording their identity and a timestamp. |
| 9 | mapforge_submit |
Execute the approved Cypher against the graph. Returns nodes/relationships written and a contribution_id. |
The approval gate
MapForge will not write to the graph without an explicit human approval. mapforge_approve records the reviewer and an approval timestamp on the bundle; mapforge_submit refuses to run on an unapproved bundle and requires the submitting reviewer to match the approver. This is a deliberate design property: every contribution to the knowledge graph is human-reviewed and attributable.
Supported input formats
MapForge ingests tabular and document-style data:
- Delimited:
.csv,.tsv - JSON:
.json,.jsonl,.ndjson - Columnar:
.parquet - SQL dumps:
.sql - Spreadsheets:
.xlsx,.xlsm(choose a sheet) - PDF tables:
.pdf(extract a table) - Archives:
.tar.gz,.tgz,.tar.bz2,.tar.xz,.tar,.zip(expanded, then members inspected)
Any other extension is rejected with a clear error.
Scope note. MapForge ingests tabular omics — it does not yet parse native assay formats such as VCF, BIOM, AnnData, mzTab, FASTQ, or BAM. To go from raw reads to a tabular table, run the appropriate Workbench pipeline first, then feed its output to MapForge.
Discipline templates
MapForge ships schema templates for five disciplines, each version 1.0.0:
| Template | Ontology |
|---|---|
microbiome |
Taxon / Disease / Metabolite / … |
genomics |
Gene / Variant / Disease / Phenotype / Pathway / … |
transcriptomics |
Gene / Sample / Condition / Tissue / CellType / … |
proteomics |
Protein / Modification / Gene / Disease / Pathway / Tissue / … |
metabolomics |
Compound / Measurement / Study / Sample / … |
You can also supply your own schema_config to map a source against a custom ontology.