deluge-mcp

A strict, beginner-friendly MCP server for Deluge syntax support.

Features

• Strict source curation (www.zoho.com/deluge/help/** only)

• Corrupt/noisy snippet rejection

• Tooling for:

  • deluge_health

  • deluge_explain

  • deluge_validate

  • deluge_fix

  • deluge_examples

  • zoho_crm_js_examples

• MCP resources:

  • deluge://rules/v1

  • deluge://cheatsheet/beginner

  • deluge://topics/v1

  • deluge://snippets/v1

  • deluge://canonical-index/v1

  • deluge://coverage/v1

  • zoho://crm-js-sdk/snippets/v1

  • zoho://crm-js-sdk/topics/v1

  • zoho://crm-js-sdk/canonical-index/v1

  • zoho://crm-js-sdk/coverage/v1

What's New In This PR

• Curated knowledge-pack pipelines for both Deluge and Zoho CRM JavaScript SDK.

• Canonical snippet model with:

  • canonicalKey, apiFamily, operation, version, stability

  • requiresScopes, requiresModule

  • sampleVsReference, confidence, tier

  • merged variants and canonical index groups

• New retrieval controls in tools:

  • canonical_key

  • tier (A|B|C)

  • include_variants

• New MCP resources for governance and observability:

  • deluge://canonical-index/v1

  • deluge://coverage/v1

  • zoho://crm-js-sdk/canonical-index/v1

  • zoho://crm-js-sdk/coverage/v1

• deluge_health now reports curation metadata (schema version, coverage completion, missing keys, tier counts, variant stats).

• Drift-control automation:

  • weekly refresh workflows for Deluge and Zoho

  • diff reports in data/reports/

  • manual review gate for Tier A canonical changes

• Added curation/retrieval test coverage and scenario-based smoke checks for both knowledge packs.

Setup

npm install

Install git hooks (usually auto-run via prepare on install):

npm run prepare

Project Governance

Repository policy and contribution docs:

• CONTRIBUTING.md

• CONTRIBUTORS.md

• SECURITY.md

GitHub metadata files:

• .github/CODEOWNERS

• .github/pull_request_template.md

• .github/ISSUE_TEMPLATE/*

• .github/dependabot.yml

• .github/labels.json

Code Quality Automation

This repo uses Biome + lint-staged + Husky:

• Pre-commit hook runs on staged *.ts|*.tsx|*.js|*.mjs|*.cjs

• Each staged file is linted and auto-formatted via biome check --write

Manual commands:

npm run lint
npm run lint:fix
npm run format

Single command for the stable full suite:

npm run verify

Full suite including stdio checks:

npm run verify:full

Sync GitHub labels from repo config:

npm run labels:sync

Release

This repo includes a release helper with flags:

npm run release -- --help

Common release commands:

npm run release:patch
npm run release:minor
npm run release:major
npm run release:alpha
npm run release:beta
npm run release:rc

Flag-based examples:

npm run release -- --type prerelease --preid beta
npm run release -- --type minor --no-push
npm run release -- --type patch --skip-verify
npm run release -- --type patch --dry-run

Supported flags:

• --type <patch|minor|major|prerelease>

• --preid <alpha|beta|rc|...> (used with --type prerelease)

• --skip-verify (skip npm run verify)

• --no-push (create version commit/tag locally only)

• --allow-dirty (allow release on dirty working tree)

• --remote <name> (default origin)

• --dry-run (print planned commands only)

Notes:

• Release flow runs npm version ... (creates commit + tag), then pushes branch and tags.

• This package is marked "private": true, so this flow manages git versions/tags, not npm publish.

Ingest Context Data

Place your Context7 export in data/raw/context7.md and run:

npm run ingest -- data/raw/context7.md

Output is written to data/processed/snippets.json.

Build/refresh curated Deluge KB metadata (canonical index, tiers, coverage):

npm run kb:deluge

One-click helper:

npm run ingest:oneclick -- data/raw/context7.md data/processed/snippets.json

After ingest, re-apply Deluge curation:

npm run kb:deluge

Deluge Knowledge Curation

Schema: deluge-kb/v1

Curated Deluge snippets include:

• canonicalKey (api_family.operation)

• apiFamily, operation

• version, stability

• requiresScopes, requiresModule

• sampleVsReference

• confidence and tier (A|B|C)

• variants (merged alternates)

Tier policy:

• A: high-confidence production-safe references

• B: standard examples and usage patterns

• C: risky/error-path or lower-confidence references

Commands:

npm run kb:deluge
npm run kb:deluge:refresh
npm run kb:deluge:refresh:allow-tier-a
npm run kb:deluge:diff

Zoho CRM JS SDK Knowledge Pack (Context7)

The repo includes a curated knowledge pack for Context7 library:

• Library ID: /zoho/zohocrm-javascript-sdk-8.0

• Raw seed file: data/raw/zoho-crm-js-sdk-context7.md

• Processed output: data/processed/zoho-crm-js-sdk-snippets.json

• Diff reports:

  • data/reports/zoho-crm-js-sdk-diff-report.json

  • data/reports/zoho-crm-js-sdk-diff-report.md

Curation Model

Schema: zoho-crm-js-sdk-kb/v1

Each canonical snippet includes:

• canonicalKey (api_family.operation)

• apiFamily, operation

• version, stability

• requiresScopes, requiresModule

• sampleVsReference

• confidence and tier (A|B|C)

• variants (merged alternates)

Tier policy:

• A: production-safe reference patterns

• B: sample/demo usage

• C: structural reference fragments (APIDOC-heavy)

Build the pack:

npm run kb:zoho-crm-js-sdk

Refresh + diff + manual-review gate:

npm run kb:zoho-crm-js-sdk:refresh

Allow Tier A promotions after human review:

npm run kb:zoho-crm-js-sdk:refresh:allow-tier-a

Run diff only:

npm run kb:zoho-crm-js-sdk:diff

Run Server

npm run dev

or

npm run build && npm start

Smoke Tests

Primary smoke (in-memory MCP client/server):

npm run smoke

Optional stdio smoke (environment-dependent):

npm run smoke:stdio

Matrix smoke (extensible scenario-based checks):

npm run smoke:matrix

Retrieval quality scenario:

npm run smoke:retrieval

Zoho retrieval quality scenario:

npm run smoke:zoho-retrieval

Matrix smoke over stdio:

npm run smoke:matrix:stdio

Deep stdio diagnosis (pinpoints failing step):

npm run diagnose:stdio

Diagnose against a specific cwd/timeout:

npm run diagnose:stdio -- --cwd /absolute/path/to/project --timeout 180000

Diagnose an MCP config that starts with npm:

npm run diagnose:stdio -- --command npm --args-json '["run","dev"]' --cwd /absolute/path/to/project

Run a custom scenario file:

npm run build
node scripts/smoke-matrix.mjs --scenario scripts/scenarios/default-smoke.json

Local test shortcut (runs stdio smoke):

npm run test:local

Run both core smoke and matrix smoke:

npm run test:mcp

Example MCP client config (stdio)

{
  "mcpServers": {
    "deluge": {
      "command": "node",
      "args": ["/absolute/path/to/deluge-mcp/dist/src/index.js"]
    }
  }
}

Troubleshooting

If you see ENOENT or Could not read package.json, your MCP client is running the command in the wrong working directory.

• If using npm run dev, set the MCP server cwd to this repo root.

• For a portable setup, prefer direct node command:

{
  "mcpServers": {
    "deluge": {
      "command": "node",
      "args": ["/absolute/path/to/deluge-mcp/dist/src/index.js"]
    }
  }
}