MCP 服务器

Ditto MCP Server

Enables secure execution of Ditto DQL (Data Query Language) queries over HTTPS with safety checks and capability gating. Supports parameterized queries, health checks, and configuration management for Ditto database operations.

README

Ditto MCP Server — Secure DQL for Ditto

</div>

📚 Table of Contents

Ditto MCP Server — Secure DQL for Ditto

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

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