Maritime context pack

Shared maritime knowledge for developers and AI agents, plus tooling to use it:

• Knowledge cards for ship certificates (knowledge/certificates/), a glossary and a guide to the roles involved (owner, manager, class society, flag state, PSC).

• JSON Schemas for vessels and certificates (schema/).

• A synthetic fleet of 20 made-up vessels with certificates in a mix of valid, expiring and expired (data/synthetic-fleet/).

• A validator that checks certificate records against the schema (src/validate.ts).

• An MCP server with three tools: list_certificate_types, get_certificate_card and query_fleet.

The cards are summaries in our own words with links to official sources. They are not legal advice and do not replace the convention text or the flag state's instructions. A card's verified_by field stays empty until a qualified reviewer has checked it.

Built from AhumLabs-Pvt-Ltd/repo-template.

10-minute quickstart

You need Git and Node.js 22 or newer.

1. Clone and install (3 min):

   git clone https://github.com/AhumLabs-Pvt-Ltd/maritime-context-pack.git
   cd maritime-context-pack
   corepack enable
   pnpm install
   pnpm run init      # creates .env, installs the secret scan hook, runs the doctor

   No API key is needed for anything in this repository.

2. Test (1 min):

   pnpm lint
   pnpm test

3. Read a card (1 min): open knowledge/certificates/international-load-line-certificate.md.

4. Validate data (1 min):

   pnpm validate                      # the synthetic fleet
   pnpm validate path/to/record.json  # your own certificate or vessel JSON

5. Run the MCP server (4 min). Add it to Claude Code:

   claude mcp add maritime-context-pack -- pnpm --dir "$PWD" mcp

   Then ask, for example, "Which certificates in the synthetic fleet expire in the next 30 days?" Any MCP client that can start a stdio server works the same way: the command is pnpm --dir /path/to/maritime-context-pack mcp.

Related MCP server: Maritime Vessel Data MCP Server

MCP tools

as_of defaults to today. The fleet's dates were generated around 2026-11-01. As time passes, more certificates will show as expired. Regenerate around a new date with pnpm generate:fleet --as-of YYYY-MM-DD.

Synthetic data

Everything in data/ is invented:

• Vessel names start with SYN. Owners, managers and class societies are named "Synthetic ...".

• IMO numbers start with IMO0 and deliberately fail the IMO check digit. No real IMO number starts with 0, and every real one passes the check, so these can never match a real ship. The validator rejects records that break this rule.

• Every record has "synthetic": true.

Never add real ship, client or crew data, even to tests.

Layout

Adding a certificate card

1. Copy knowledge/certificates/_TEMPLATE.md to <id>.md. Keep every section heading.

2. Write in your own words. Link the official source. Do not copy convention text.

3. Leave verified_by empty and set last_checked to today.

4. Add the id to the type enum in schema/certificate.schema.json.

5. Run pnpm test. The card tests check the structure.

Licenses

This repository uses two licenses:

• Code (everything outside knowledge/, including src/, scripts/, schema/, test/ and data/) is licensed under Apache-2.0. You can use, change and redistribute it, including commercially, as long as you keep the license and notices.

• Content in knowledge/ (the certificate cards, glossary and roles) is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). You can share and adapt it for any purpose, including commercially, as long as you credit "Ahum community, maritime-context-pack" with a link to this repository and say if you changed it.

Contributions to each part are accepted under that part's license.

Contributing and security

See CONTRIBUTING.md and SECURITY.md. Found a factual mistake in a card? Open a Maritime knowledge correction issue.