<div align="center">

Ditto MCP Server — Secure DQL for Ditto

</div>

📚 Table of Contents

• Ditto MCP Server — Secure DQL for Ditto
  • 📚 Table of Contents
  • Overview
    • Features
  • Requirements
  • Quick Start (Local)
  • Install in Clients
    • Cursor
    • Claude Code CLI
    • VS Code Copilot Chat (Insiders)
    • Windsurf
    • Zed
    • Roo Code / Cline
    • JetBrains AI Assistant
    • LM Studio
    • Warp
    • Amazon Q Developer CLI
    • Gemini CLI
  • Tools & Resources
    • Example: SELECT with named args
  • Configuration
    • MCP Client One‑click Patterns
  • Security Notes
  • Development
    • Test with MCP Inspector
    • Alternative Runtimes
    • Docker
  • Troubleshooting
  • Versioning & Changelog
  • License

Overview

An open‑source Model Context Protocol server that executes Ditto DQL over HTTPS with capability gating and safety checks. Designed for Cursor, Claude Code, VS Code Copilot Chat (MCP), Windsurf, Zed, and more.

Features

• Ping health tool, execute_dql tool, and ditto://config resource
• Statement guardrails: single statement, operation allow‑list, optional query pattern allow‑list
• Config via env, CLI, or client config
• Native ESM, strict TypeScript, zero runtime deps beyond MCP SDK

Requirements

• Node.js >= 18.17
• A Ditto app base URL, e.g. https://MY_APP.cloud.ditto.live
• A Ditto API key with access to that app

Quick Start (Local)

npx -y ditto-mcp-server@latest

Defaults to stdio transport. Provide env vars (recommended):

export DITTO_BASE_URL="https://MY_APP.cloud.ditto.live"
export DITTO_API_KEY="YOUR_API_KEY"
export MCP_DITTO_ALLOWED="READ"   # or ALL / SELECT,INSERT,...

npx -y ditto-mcp-server@latest

Install in Clients

Below are minimal JSON snippets. See each client’s docs for full syntax and options.

Cursor

Add to ~/.cursor/mcp.json or project .cursor/mcp.json:

{
  "mcpServers": {
    "ditto": {
      "command": "npx",
      "args": ["-y", "ditto-mcp-server@latest"],
      "env": {
        "DITTO_BASE_URL": "https://MY_APP.cloud.ditto.live",
        "DITTO_API_KEY": "YOUR_API_KEY",
        "MCP_DITTO_ALLOWED": "READ"
      }
    }
  }
}

Claude Code CLI

claude mcp add ditto -- npx -y ditto-mcp-server --timeout 20000

VS Code Copilot Chat (Insiders)

{
  "mcp": {
    "servers": {
      "ditto": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "ditto-mcp-server"],
        "env": {
          "DITTO_BASE_URL": "https://MY_APP.cloud.ditto.live",
          "DITTO_API_KEY": "YOUR_API_KEY"
        }
      }
    }
  }
}

Windsurf

Add to Windsurf MCP config (see their docs for exact path):

{
  "mcpServers": {
    "ditto": {
      "command": "npx",
      "args": ["-y", "ditto-mcp-server"],
      "env": {
        "DITTO_BASE_URL": "https://MY_APP.cloud.ditto.live",
        "DITTO_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Zed

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "Ditto": {
      "command": {
        "path": "npx",
        "args": ["-y", "ditto-mcp-server"]
      }
    }
  }
}

Roo Code / Cline

Add in settings under MCP servers or marketplace manual JSON:

{
  "mcpServers": {
    "ditto": {
      "command": "npx",
      "args": ["-y", "ditto-mcp-server"],
      "env": {
        "DITTO_BASE_URL": "https://MY_APP.cloud.ditto.live",
        "DITTO_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

JetBrains AI Assistant

Settings → Tools → AI Assistant → MCP → Add → As JSON:

{
  "mcpServers": {
    "ditto": {
      "command": "npx",
      "args": ["-y", "ditto-mcp-server"],
      "env": {
        "DITTO_BASE_URL": "https://MY_APP.cloud.ditto.live",
        "DITTO_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

LM Studio

Program → Install → Edit mcp.json:

{
  "mcpServers": {
    "Ditto": {
      "command": "npx",
      "args": ["-y", "ditto-mcp-server"],
      "env": {
        "DITTO_BASE_URL": "https://MY_APP.cloud.ditto.live",
        "DITTO_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Warp

Settings → AI → Manage MCP servers:

{
  "Ditto": {
    "command": "npx",
    "args": ["-y", "ditto-mcp-server"],
    "start_on_launch": true
  }
}

Amazon Q Developer CLI

~/.aws/q/developer/cli/config.json:

{
  "mcpServers": {
    "ditto": {
      "command": "npx",
      "args": ["-y", "ditto-mcp-server"]
    }
  }
}

Gemini CLI

~/.gemini/settings.json:

{
  "mcpServers": {
    "ditto": {
      "command": "npx",
      "args": ["-y", "ditto-mcp-server"]
    }
  }
}

Tools & Resources

• ping – returns pong for connectivity check
• execute_dql – run a parameterized DQL against Ditto
  • statement (string, required) – single statement, no trailing ;
  • args (object, optional) – named parameters
  • transactionId (number, optional) – X‑DITTO‑TXN‑ID
  • apiKey (string, optional) – override key; prefer env
  • baseUrl (string, optional) – override base URL
  • timeoutMs (number, optional, <= 60000)
• Resource: ditto://config – redacted runtime config

Example: SELECT with named args

Tool: execute_dql
Args:
{
  "statement": "SELECT * FROM collection WHERE type = :t LIMIT 5",
  "args": { "t": "note" }
}

Returns a JSON envelope with items, queryType, warnings, and optional error.

Configuration

You can configure via env, CLI, or client configs. Env is preferred for secrets.

Environment variables:

• DITTO_BASE_URL – e.g. https://MY_APP.cloud.ditto.live
• DITTO_API_KEY – Ditto API key
• MCP_DITTO_ALLOWED – READ, ALL, or a comma list like SELECT,INSERT
• MCP_DITTO_QUERY_ALLOW_PATTERNS – comma/semicolon‑separated regex allow‑list
• DITTO_TIMEOUT_MS – default per‑call timeout (ms)
• DITTO_API_KEY_ENV – env var name to read API key from (default DITTO_API_KEY)
• MCP_SERVER_NAME – server display name
• MCP_SERVER_VERSION – overrides the reported server version (default: package.json version; fallback: 0.0.0-dev)
• LOG_LEVEL – controls logging verbosity: debug|info|warn|error|silent (default: info)

Configuration precedence: CLI flags > environment variables. Reported version precedence: MCP_SERVER_VERSION > package.json > 0.0.0-dev.

CLI flags (subset):

ditto-mcp [transport] \
  --name <name> \
  --base-url <url> \
  --api-key-env <VAR> \
  --timeout <ms>

Transport argument defaults to stdio. This package currently exposes stdio only.

MCP Client One‑click Patterns

• Cursor deeplink button above for instant install into ~/.cursor/mcp.json.

Security Notes

• Prefer environment variables for secrets; avoid CLI args containing secrets
• Allowed operation gating and optional regex allow‑list help constrain queries
• Logs redact tokens and obvious secret patterns

Development

yarn
yarn build
node dist/index.js stdio

Linting is TypeScript‑strict by design. The prepack script builds automatically before npm publish.

Test with MCP Inspector

npx -y @modelcontextprotocol/inspector npx ditto-mcp-server

Alternative Runtimes

bunx -y ditto-mcp-server

Windows PowerShell example:

cmd /c npx -y ditto-mcp-server

Docker

Build the image:

docker build -t ditto-mcp .

Run with env vars:

docker run --rm -i \
  -e DITTO_BASE_URL="https://MY_APP.cloud.ditto.live" \
  -e DITTO_API_KEY="YOUR_API_KEY" \
  ditto-mcp

You can also configure Docker as a local MCP command in clients that support running a container for stdio transport. Example:

{
  "mcpServers": {
    "ditto": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "DITTO_BASE_URL",
        "-e",
        "DITTO_API_KEY",
        "ditto-mcp"
      ],
      "env": {
        "DITTO_BASE_URL": "https://MY_APP.cloud.ditto.live",
        "DITTO_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Troubleshooting

• If tools don’t appear, refresh/toggle the server in your client
• Ensure DITTO_BASE_URL and DITTO_API_KEY are set
• In Windows, provide full node and dist/index.js paths if needed

If your client has trouble auto-installing via npx, try bunx -y ditto-mcp-server.

Versioning & Changelog

See CHANGELOG.md.

License

MIT © EVT Engineering and contributors

---

This project is not affiliated with Ditto. “Ditto” is a respective trademark of its owner.