# cerif-mcp

**Model Context Protocol (MCP) server for CERIF 1.6** — understand, validate,
generate and transform research information in the Common European Research
Information Format (CERIF).

[![npm](https://img.shields.io/npm/v/cerif-mcp)](https://www.npmjs.com/package/cerif-mcp)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D20-green)](package.json)

`cerif-mcp` gives any MCP-capable AI assistant a complete working knowledge of
the **CERIF 1.6** data model and the ability to **produce schema-valid CERIF
XML**. It bundles the official euroCRIS `CERIF_1.6_2.xsd` and validates against
it fully in-process — no external service, no Java, no network at runtime.

It works with Claude Code, Codex, Antigravity, Kilo, opencode, Cline, Cursor,
and any other MCP client.

---

## What is CERIF?

[CERIF](https://eurocris.org/cerif/) (Common European Research Information
Format) is the open standard data model for research information, maintained by
[euroCRIS](https://eurocris.org/). It is the backbone of CRIS (Current Research
Information Systems) and of research-evaluation and open-science data flows
across Europe and beyond.

CERIF 1.6 defines **293 entities**: 19 *core* entities (Person, Organisation
Unit, Project, Funding, Result Publication/Patent/Product, Event, Facility,
Equipment, Service, …), 161 *linking* entities (relationships such as
`cfProj_Pers` or `cfOrgUnit_Class`), 71 *language-dependent* attributes (names,
titles, abstracts, keywords), and 42 *supporting* entities (classification
schemes and terms, languages, countries, currencies, federated identifiers,
addresses, Dublin Core, …).

## Features

**15 tools in 7 families**

| Family | Tool | Purpose |
| --- | --- | --- |
| Knowledge | `list_entities` | Browse the 293-entity catalog, filter by kind, search |
| Knowledge | `get_entity` | Full definition of one entity (children, links, id) |
| Knowledge | `list_schemes` | Canonical classification schemes (vocabularies) |
| Knowledge | `get_scheme` | Full term list of a classification scheme |
| Validation | `validate_xml` | Validate CERIF 1.6 XML against the official XSD |
| Validation | `validate_file` | Validate a CERIF 1.6 XML file on disk |
| Generation | `build_entity` | Generate a `<cfXxx>` entity fragment |
| Generation | `build_link` | Generate a linking entity (e.g. `cfProj_Pers`) |
| Generation | `build_document` | Wrap fragments into a complete CERIF document |
| Analysis | `analyze_document` | Summarize a document: entities, counts, namespace |
| Analysis | `extract_entities` | Extract entity instances with XPaths |
| Analysis | `lookup_in_document` | Find ids across a document |
| Migration | `migrate_15_to_16` | Migrate CERIF 1.5 XML to 1.6 (namespace, schema location, `release` removal) |
| PostgreSQL | `audit_postgresql` | Introspect a live PostgreSQL schema and cross-reference it with CERIF |
| PostgreSQL | `generate_postgresql_ddl` | Generate a CERIF 1.6 PostgreSQL DDL script (tables, views, procedures) |

**4 resources** — `cerif://entities`, `cerif://entities/{entity}`,
`cerif://schemes/{id}` and `cerif://schema` (the full XSD).

**2 prompts** — `cerif_author` (guided authoring workflow) and
`cerif_validator` (fix-until-valid loop).

### Validation is real

Validation runs the bundled official euroCRIS schema
(`CERIF_1.6_2.xsd`, 5,134 lines, namespace `urn:xmlns:org:eurocris:cerif-1.6-2`)
in-process via [`xml-xsd-engine`](https://www.npmjs.com/package/xml-xsd-engine)
(pure TypeScript, zero dependencies, MIT). Errors carry the message, XPath,
line/column, and an error code:

```text
# Validation FAILED

## 1 error(s)
- Unexpected element <cfBogusElement> in <cfOrgUnit[1]> [VALID_UNEXPECTED_ELEMENT] at line 5, column 5
  `/CERIF/cfOrgUnit[1]/cfBogusElement[2]`
```

### PostgreSQL support

The server can scaffold and audit a **PostgreSQL** database for CERIF 1.6.

- `generate_postgresql_ddl` produces a complete DDL script from the CERIF model.
  The **`core`** scope (default) emits the extended core: the 19 research-object
  entities (persons, organisations, projects, funds, services, facilities,
  equipment, publications, patents, products, events, prizes, qualifications,
  expertise/skills, measurements, indicators, CVs, media, geographic boxes),
  their language-dependent attribute tables (`cf_proj_title`, `cf_pers_name`, …),
  supporting tables (`cf_class`, `cf_class_scheme`, `cf_eaddr`, `cf_paddr`),
  and 90+ linking tables — every one with `cfClassId`/`cfClassSchemeId`
  as required by the `cfCoreClassWithFraction` group. The **`full`** scope emits
  all 293 CERIF entities. Every script also includes denormalised views
  (`v_<entity>`) and helper functions (`cerif_insert_<entity>`,
  `cerif_count_<entity>`, `cerif_add_classification`).
- `audit_postgresql` connects to a live database (credentials in arguments or
  `PG*` environment variables — any user's database works, the tool discovers
  the schema itself), introspects tables/columns/primary keys/foreign
  keys/views/routines, and reports a conformity score, the missing required
  CERIF entities, which tables match (and their issues), orphan tables, and the
  routine inventory.

> The generated DDL is tested end-to-end against PostgreSQL 16 in CI and during
> development; both scopes execute with zero errors.

## Installation

### Run directly (any client)

```bash
npx -y cerif-mcp
```

### Install globally

```bash
npm install -g cerif-mcp
```

### Build from source

```bash
git clone https://github.com/adialaleal/cerif-mcp.git
cd cerif-mcp
npm install
npm run build
npm start   # or: npx cerif-mcp
```

## Configure your client

### Claude Code

`.mcp.json` in your project root, or `claude mcp add`:

```bash
claude mcp add cerif-mcp -- npx -y cerif-mcp
```

```json
{
  "mcpServers": {
    "cerif-mcp": {
      "command": "npx",
      "args": ["-y", "cerif-mcp"]
    }
  }
}
```

### Codex

```bash
codex mcp add cerif-mcp -- npx -y cerif-mcp
```

### Cursor

Cursor Settings → MCP → Add server:

- Type: `command`
- Command: `npx -y cerif-mcp`

### Cline

`.clinerules/mcp.json` (or Settings → MCP Servers):

```json
{
  "mcpServers": {
    "cerif-mcp": {
      "command": "npx",
      "args": ["-y", "cerif-mcp"]
    }
  }
}
```

### opencode

`.opencode.json`:

```json
{
  "mcp": {
    "cerif-mcp": {
      "type": "local",
      "command": ["npx", "-y", "cerif-mcp"],
      "enabled": true
    }
  }
}
```

### Kilo

Kilo MCP settings (`mcp.json` or `kilo mcp add`):

```bash
kilo mcp add cerif-mcp -- npx -y cerif-mcp
```

### Antigravity

Antigravity MCP configuration accepts a local command:

```
npx -y cerif-mcp
```

> All clients talk to the same stdio server. If a client requires a server
> URL instead, run `npm install -g cerif-mcp` and point it at the binary with
> `npx cerif-mcp` (an HTTP/Streamable transport can be added later).

## Example prompts

**Author a record**

> Create a CERIF 1.6 record for a researcher, Jane Doe (ORCID
> 0000-0000-0000-0000), employed at the University of Porto and Principal
> Investigator on the project "DEMO", funded with €50 000. Write the XML to
> `output/cerif.xml`.

**Validate**

> Validate `output/cerif.xml` against the CERIF 1.6 schema and fix any errors.

**Extend existing data**

> Here is some CERIF XML: <paste>. Add a second publication by the same author
> and link it with `cfResPubl_Pers`.

**Migrate**

> Migrate this CERIF 1.5 file to 1.6: <paste or point to file>.

**Scaffold a database**

> Generate the PostgreSQL DDL for the CERIF extended core and save it to
> `db/cerif.sql`.

**Audit a database**

> Connect to `postgresql://app:secret@db.internal:5432/research` and tell me how
> conformant the schema is with CERIF 1.6. If something is missing, show me the
> `ALTER TABLE` statements to fix it.

**Learn the model**

> What entities link a person to a project, and which canonical scheme should I
> use for the role?

## Development

```bash
npm install        # dependencies
npm run dev        # run the server with tsx (stdin/stdout)
npm run typecheck  # tsc --noEmit
npm run lint       # eslint
npm test           # vitest (44 tests)
npm run build      # extract model + tsc + copy XSD
npm run check      # lint + typecheck + test + build
```

### Repository layout

```
scripts/extract-model.mjs   # regenerates the entity catalog from the XSD
src/data/xsd/CERIF_1.6_2.xsd # official euroCRIS schema (unchanged, CC BY-ND 3.0)
src/data/model.generated.json # generated structural catalog (293 entities)
src/data/descriptions.ts     # curated descriptions + canonical vocabularies
src/lib/                     # catalog, validate, generate, analyze, migrate, sqlaudit, sqlgen, xml, format
src/tools/                   # the 15 MCP tools (incl. audit_postgresql, generate_postgresql_ddl)
src/resources.ts, prompts.ts # MCP resources and prompts
src/server.ts, index.ts      # assembly and stdio entry point
test/                        # vitest suites + XML fixtures
```

### Regenerating the catalog

The generated catalog is produced from the bundled XSD:

```bash
node scripts/extract-model.mjs
```

## License

- **Code and documentation**: MIT © 2026 Lucas Leal — see [LICENSE](LICENSE).
- **Bundled schema** (`src/data/xsd/CERIF_1.6_2.xsd`): © euroCRIS, distributed
  **unchanged** under Creative Commons Attribution-NoDerivs 3.0 — see
  [`src/data/xsd/README-license.md`](src/data/xsd/README-license.md).

CERIF is a registered standard of euroCRIS. This project is an independent,
community tool for interoperating with CERIF data and is not an official
euroCRIS product.