MCP-DSL: A Token-Efficient Language for Model Context Protocol

75-85% token reduction. Same MCP power. Real cost savings.

MCP-DSL is a domain-specific language designed to replace verbose JSON-RPC in the Model Context Protocol, cutting token usage by up to 85% while maintaining full compatibility and expressiveness.

Quick Example

Traditional JSON-RPC:

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "weather"
    }
  }
}

MCP-DSL:

> tools/call#42 {name: "search", args: {query: "weather"}}

Result: 176 tokens → 42 tokens (76% reduction)

Installation

bun install mcp-dsl

Or with npm:

npm install mcp-dsl

Usage

As a Library

import { compileDsl, decompile } from 'mcp-dsl';

// Compile DSL to JSON-RPC
const result = compileDsl('> initialize#1 {v: "2025-06-18"}');
console.log(result.messages[0]);
// {
//   jsonrpc: "2.0",
//   id: 1,
//   method: "initialize",
//   params: { protocolVersion: "2025-06-18" }
// }

// Decompile JSON-RPC back to DSL
const dsl = decompile(result.messages);
console.log(dsl);
// > initialize#1 {v: "2025-06-18"}

CLI Tool

# Compile DSL to JSON
echo '> initialize#1 {v: "2025-06-18"}' | mcp-dsl compile --pretty

# Decompile JSON to DSL
cat message.json | mcp-dsl decompile

# Validate DSL
mcp-dsl lint input.mcp

# Format DSL
mcp-dsl format input.mcp -o output.mcp

CLI Commands

• compile - Convert DSL to JSON-RPC

  • --pretty - Pretty-print JSON output
  • --messages - Output only messages
  • --tools - Output only tool definitions
  • --resources - Output only resource definitions
  • --no-validate - Skip semantic validation

• decompile - Convert JSON-RPC to DSL

  • --messages/--tools/--resources - Decompile specific types

• lint - Validate DSL syntax and semantics

• format - Parse and pretty-print DSL

All commands support -i/--input (file or - for stdin) and -o/--output (file or - for stdout).

Language Features

Message Types

• > Request (with method#id)
• < Response (with #id)
• ! Notification (no response expected)
• x Error (with code:message)

Definition Types

• T Tool (executable function with schema)
• R Resource (data source with URI)
• P Prompt (template with arguments)
• RT Resource Template (parameterized URI pattern)

Type System

Compact type notation with inference:

T analyze_code {
  desc: "Analyzes code for issues"
  in: {
    code: str!           # Required string
    language: str!
    rules?: {            # Optional nested object
      complexity?: int = 10
      lineLength?: int = 100
    }
  }
  out: {
    issues: [{          # Array of objects
      line: int
      severity: enum[error, warning, info]
      message: str
    }]
  }
}

Field Name Abbreviations

| DSL | JSON-RPC | |-----|----------| | v | protocolVersion | | caps | capabilities | | info | clientInfo / serverInfo | | args | arguments | | desc | description | | mime | mimeType | | in | inputSchema | | out | outputSchema |

See GRAMMAR.md for complete language specification.

Why MCP-DSL?

Token Efficiency

For a system processing 1 million MCP messages per day:

• Tokens saved: 341M tokens/day
• API cost savings (at $3/M input tokens): $1,023/day = $373,395/year
• With output tokens (at $15/M): Total savings $1.2M+/year

Even at moderate scale (100K messages/day), annual savings exceed $120K.

When to Use MCP-DSL

MCP-DSL provides maximum value when:

• High message volume: Servers handling thousands of requests daily
• Context-constrained models: Smaller models with limited windows
• Cost-sensitive applications: Production systems at scale
• Real-time systems: Lower token counts mean faster processing
• Multi-turn conversations: Savings compound across multiple exchanges

Development

Setup

This project uses mise for tool version management:

# Install mise (if not already installed)
curl https://mise.run | sh

# Install project dependencies
mise install
bun install

Running Tests

mise run test              # Run all tests
mise run test-watch        # Watch mode
bun test                   # Direct via bun

Development Tasks

mise run check            # Run all checks (tests + CLI verification)
mise run build            # Verify CLI tool works
mise run lint             # Lint example files (when available)
mise run format           # Format example files (when available)

Project Structure

src/
├── ast/              # Abstract Syntax Tree definitions
├── lexer/            # Tokenization
├── parser/           # Recursive descent parser
├── compiler/         # DSL → JSON-RPC transformation
├── decompiler/       # JSON-RPC → DSL transformation
├── semantic/         # Semantic validation
├── types/            # Common type definitions
├── utils/            # Utilities (mappings, string handling)
├── cli.ts            # CLI tool
└── index.ts          # Public API

Grammar

See GRAMMAR.md for the complete EBNF grammar specification.

Contributing

Contributions welcome! Please check the issue tracker for current tasks and planned features.

License

MIT License - see LICENSE for details.

Why This Matters

Model Context Protocol is becoming the standard for LLM-tool interactions. As MCP adoption grows, protocol efficiency directly impacts:

• Cost at scale: Production systems handling millions of messages
• Model capability: More tokens available for actual content
• Developer experience: Readable, maintainable protocol definitions
• Ecosystem growth: Lower barriers to building MCP servers/clients

MCP-DSL makes the protocol more accessible and cost-effective without compromising power or compatibility.