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"]
    }
  }
}