n8n-nodes-cat-mip

n8n-nodes-cat-mip is an n8n community node for CAT-MIP.

It helps workflows normalize text, look up canonical terms, and list CAT-MIP terminology from published standards.

Installation Local-development Operations Usage AI-Agent-tool-usage Caching-and-sources Workflow-e2e-tests Security-notes Resources

Installation

Follow the n8n community nodes installation guide: https://docs.n8n.io/integrations/community-nodes/installation/

If you run n8n from a local installation:

npm install n8n-nodes-cat-mip

Restart n8n and search for "CAT-MIP Terminology".

Local development

This repo includes a Docker-based local n8n setup that installs this node from a local package tarball.

1. Install dependencies:

npm install

2. Build the node and create a tarball:

npm run build
npm pack

3. Start local n8n:

docker compose up --build

4. Open http://localhost:5678 and complete n8n owner setup on first run.

Development loop after code changes:

npm run build
npm pack
docker compose up --build -d --force-recreate

Useful cleanup commands:

docker compose down

rm -rf local-data/*

Notes:

• Local runtime data is stored in ./local-data (mounted to /home/node/.n8n in the container).
• The local image expects tarball n8n-nodes-cat-mip-0.1.0.tgz by default (docker-compose.yml, Dockerfile.local, and scripts/entrypoint-local.sh).

Operations

Resource: Terms

• Normalize Text: replace or annotate input text using CAT-MIP canonical terms.
• Lookup Term: resolve a canonical term, definition, and synonyms for a user term.
• List Terms: return term objects with optional substring filter.

Usage

Normalize text with defaults (uses $json.text if present):

{
  "text": "Our CSP partners follow vendor onboarding rules."
}

Output (example):

{
  "normalizedText": "Our Cloud Service Provider partners follow Vendor Onboarding rules.",
  "replacements": [
    {
      "from": "CSP",
      "to": "Cloud Service Provider",
      "source": "synonym",
      "standard": "cloud",
      "termId": "CSP-1",
      "confidence": 1
    }
  ],
  "matchedCanonicalTerms": ["Cloud Service Provider"],
  "unmatchedTokens": ["Our", "partners", "follow", "vendor", "onboarding", "rules"],
  "metadata": {
    "version": "latest",
    "fetchedFrom": [
      "https://raw.githubusercontent.com/cat-mip/cat-mip/main/standards/accepted/cloud.yaml",
      "https://raw.githubusercontent.com/cat-mip/cat-mip/main/standards/accepted/vendor.yaml"
    ],
    "fetchedAt": "2025-01-01T00:00:00.000Z",
    "cacheHit": false
  }
}

Demo workflow JSON is available at examples/cat-mip-terminology-normalize.json.

AI Agent tool usage

This node can also be used as an AI Agent tool.

1. Add an AI Agent node to your workflow.
2. Add CAT-MIP Terminology.
3. Connect CAT-MIP Terminology to the Agent using the AI Tool connection (the tool node will expose an AI Tool output when used as a tool).

Recommended parameter patterns for tool calls:

• Normalize text: set Operation = normalizeText, and set Text Source to the literal text you want to normalize.
• Lookup term: set Operation = lookupTerm, and set Term to the term you want to resolve.
• List terms: set Operation = listTerms, optionally set Filter and Limit.

When called as an AI tool, the node also accepts a plain string input (it will treat it as text to normalize). For advanced usage, pass an object like { "operation": "lookupTerm", "term": "CSP" }.

Requirements:

• Outbound HTTPS access to cat-mip.org and/or raw.githubusercontent.com (and api.github.com when Standards includes all).

Caching and sources

The node caches fetched standards using this.getWorkflowStaticData('node'). The cache key includes:

• Standard Version
• Standard Source
• Custom URL (if used)
• Selected standards (cloud, vendor, or all)

Cache TTL defaults to 1440 minutes. Set TTL to 0 to bypass caching.

During manual/test executions, n8n may not persist workflow static data between runs. To make local iteration fast, the node also keeps a small in-process memory cache. The output metadata includes:

• cacheHit: true when terms were reused
• cacheLayer: memory, workflowStaticData, or none

Standard Source options:

• catmip_org: https://cat-mip.org/standard/{version}/{standard}.yaml
• github_raw: https://raw.githubusercontent.com/cat-mip/cat-mip/main/standards/accepted/{standard}.yaml
• custom_url: HTTPS URL pointing to a YAML file.

When standards is set to all, the node fetches the list of accepted YAML files from the CAT-MIP GitHub repository and loads every file in standards/accepted.

Use standardVersion = v1-0 to pin to CAT-MIP v1.0. latest is the default.

Workflow e2e tests

The repo includes a real n8n workflow e2e suite in test/e2e/cache.workflow.e2e.test.ts.

You can run it in one command:

npm run test:e2e:workflow

Run all tests (unit + workflow e2e) in one command:

npm run test:all

Run workflow e2e directly against an already-running n8n instance in one command:

npm run test:e2e:workflow:local

This command:

• builds and starts n8n with plain container commands (docker)
• uses session auth by default (auto owner setup + login)
• runs workflow cache e2e assertions
• shuts the stack down automatically

Optional environment overrides:

• N8N_E2E_PORT (default 5678)
• N8N_E2E_ENGINE (docker; default docker)
• N8N_E2E_AUTH_MODE (session or basic, default session)
• N8N_E2E_EMAIL (default [email protected], used in session mode)
• N8N_E2E_PASSWORD (default E2ePassword1!, used in session mode)
• N8N_E2E_BASIC_AUTH_USER (default e2e)
• N8N_E2E_BASIC_AUTH_PASSWORD (default e2e-pass)
• N8N_E2E_TEST_FILE (default test/e2e/cache.workflow.e2e.test.ts)
• N8N_E2E_IMAGE_TAG (default n8n-cat-mip:e2e)
• N8N_E2E_CONTAINER_NAME (default n8n-cat-mip-e2e-<timestamp>)
• N8N_E2E_CONTAINER_VOLUME (default n8n-cat-mip-e2e-data-<timestamp>)
• N8N_E2E_NODE_TARBALL (default n8n-nodes-cat-mip-0.1.0.tgz)
• N8N_REST_PATH (default rest; set if your n8n REST endpoints use a custom base path, for example api)

Security notes

• custom_url must use HTTPS.
• Responses are limited to 2 MB to prevent oversized payloads.
• HTTP timeout is 20 seconds by default.

Resources

• n8n community nodes: https://docs.n8n.io/integrations/community-nodes/
• CAT-MIP standards: https://github.com/cat-mip/cat-mip