mcp-server

Access comprehensive ExoQuery documentation organized by topic and category.

ExoQuery is a Language Integrated Query library for Kotlin Multiplatform that translates Kotlin DSL expressions into SQL at compile time. This resource provides access to the complete documentation covering all aspects of the library.

AVAILABLE DOCUMENTATION CATEGORIES:

1. Getting Started

   • Introduction: What ExoQuery is and why it exists

   • Installation: Project setup and dependencies

   • Quick Start: First query in minutes

2. Core Concepts

   • SQL Blocks: The sql { } construct and query building

   • Parameters: Safe runtime data handling

   • Composing Queries: Functional query composition

3. Query Operations

   • Basic Operations: Map, filter, and transformations

   • Joins: Inner, left, and implicit joins

   • Grouping: GROUP BY and HAVING clauses

   • Sorting: ORDER BY operations

   • Subqueries: Correlated and nested queries

   • Window Functions: Advanced analytics

4. Actions

   • Insert: INSERT with returning and conflict handling

   • Update: UPDATE operations with setParams

   • Delete: DELETE with returning

   • Batch Operations: Bulk inserts and updates

5. Advanced Features

   • SQL Fragment Functions: Reusable SQL components with @SqlFragment

   • Dynamic Queries: Runtime query generation with @SqlDynamic

   • Free Blocks: Custom SQL and user-defined functions

   • Transactions: Transaction support patterns

   • Polymorphic Queries: Interfaces, sealed classes, higher-order functions

   • Local Variables: Variables within SQL blocks

6. Data Handling

   • Serialization: kotlinx.serialization integration

   • Custom Type Encoding: Custom encoders and decoders

   • JSON Columns: JSON and JSONB support (PostgreSQL)

   • Column Naming: @SerialName and @ExoEntity annotations

   • Nested Datatypes: Complex data structures

   • Kotlinx Integration: JSON and other serialization formats

7. Schema-First Development

   • Entity Generation: Compile-time code generation from database schema

   • AI-Enhanced Entities: Using LLMs to generate cleaner entity code

8. Reference

   • SQL Functions: Available string, math, and date functions

   • API Reference: Core types and function signatures

HOW TO USE THIS RESOURCE:

The resource URI follows the pattern: exoquery://docs/{file-path}

Where {file-path} is the relative path from the docs root, e.g.:

• exoquery://docs/01-getting-started/01-introduction.md

• exoquery://docs/03-query-operations/02-joins.md

• exoquery://docs/05-advanced-features/01-sql-fragments.md

To discover available documents, use the MCP resources/list endpoint which will return all available documentation files with their titles, descriptions, and categories.

Each document includes:

• Title and description

• Category classification

• Complete markdown content with code examples

• Cross-references to related topics

WHEN TO USE:

• User asks about ExoQuery syntax, features, or capabilities

• User needs examples of specific query patterns

• User encounters errors and needs to verify correct usage

• User wants to understand advanced features or best practices

Access multiple ExoQuery documentation sections simultaneously.

This tool is similar to the single-document retrieval tool but allows fetching multiple documentation files in a single request. This is particularly useful when you need to gather information from several related topics at once.

ExoQuery is a Language Integrated Query library for Kotlin Multiplatform that translates Kotlin DSL expressions into SQL at compile time. This resource provides access to the complete documentation covering all aspects of the library.

HOW TO USE THIS RESOURCE:

Provide a list of file paths, where each path is the relative path from the docs root, e.g.:

• 01-getting-started/01-introduction.md

• 03-query-operations/02-joins.md

• 05-advanced-features/01-sql-fragments.md

To discover available documents, use the MCP resources/list endpoint which will return all available documentation files with their titles, descriptions, and categories.

Each returned document includes:

• Title and description

• Category classification

• Complete markdown content with code examples

• Cross-references to related topics

WHEN TO USE:

• User asks about multiple ExoQuery topics that require information from different sections

• User needs to compare or understand relationships between different features

• User wants to get comprehensive information across multiple categories

• More efficient than making multiple single-document requests

Lists all available ExoQuery documentation resources with their metadata

Compile ExoQuery Kotlin code and EXECUTE it against an Sqlite database with provided schema. ExoQuery is a compile-time SQL query builder that translates Kotlin DSL expressions into SQL.

WHEN TO USE: When you need to verify ExoQuery produces correct results against actual data.

INPUT REQUIREMENTS:

• Complete Kotlin code (same requirements as validateExoquery)

• SQL schema with CREATE TABLE and INSERT statements for test data

• Data classes MUST exactly match the schema table structure

• Column names in data classes must match schema (use @SerialName for snake_case columns)

• Must include or or more .runSample() calls in main() to trigger SQL generation and execution (note that .runSample() is NOT or real production use, use .runOn(database) instead)

OUTPUT FORMAT:

Returns one or more JSON objects, each on its own line. Each object can be:

1. SQL with output (query executed successfully): {"sql": "SELECT u.name FROM "User" u", "output": "[(name=Alice), (name=Bob)]"}

2. Output only (e.g., print statements, intermediate results): {"output": "Before: [(id=1, title=Ion Blend Beans)]"}

3. Error output (runtime errors, exceptions): {"outputErr": "java.sql.SQLException: Table "USERS" not found"}

Multiple results appear when code has multiple queries or print statements:

{"sql": "SELECT * FROM "InventoryItem"", "output": "[(id=1, title=Ion Blend Beans, unit_price=32.00, in_stock=25)]"} {"output": "Before:"} {"sql": "INSERT INTO "InventoryItem" (title, unit_price, in_stock) VALUES (?, ?, ?)", "output": "Rows affected: 1"} {"output": "After:"} {"sql": "SELECT * FROM "InventoryItem"", "output": "[(id=1, title=Ion Blend Beans, unit_price=32.00, in_stock=25), (id=2, title=Luna Fuel Flask, unit_price=89.50, in_stock=6)]"}

Compilation errors return the same format as validateExoquery: { "errors": { "File.kt": [ { "interval": {"start": {"line": 12, "ch": 10}, "end": {"line": 12, "ch": 15}}, "message": "Type mismatch: inferred type is String but Int was expected", "severity": "ERROR", "className": "ERROR" } ] } }

Runtime Errors can have the following format: { "errors" : { "File.kt" : [ ] }, "exception" : { "message" : "[SQLITE_ERROR] SQL error or missing database (no such table: User)", "fullName" : "org.sqlite.SQLiteException", "stackTrace" : [ { "className" : "org.sqlite.core.DB", "methodName" : "newSQLException", "fileName" : "DB.java", "lineNumber" : 1179 }, ...] }, "text" : "\n{"sql": "SELECT x.id, x.name, x.age FROM User x"}\n\n" } If there was a SQL query generated before the error, it will appear in the "text" field output stream.

EXAMPLE INPUT CODE:

EXAMPLE INPUT SCHEMA:

EXAMPLE SUCCESS OUTPUT: {"sql": "SELECT u.name AS first, o.total AS second, u.age AS third FROM "User" u INNER JOIN "Order" o ON o.user_id = u.id", "output": "[(first=Alice, second=100, third=30), (first=Alice, second=200, third=30), (first=Bob, second=150, third=25)]"}

EXAMPLE WITH MULTIPLE OPERATIONS (insert with before/after check): {"output": "Before:"} {"sql": "SELECT * FROM "InventoryItem"", "output": "[(id=1, title=Ion Blend Beans)]"} {"sql": "INSERT INTO "InventoryItem" (title, unit_price, in_stock) VALUES (?, ?, ?)", "output": ""} {"output": "After:"} {"sql": "SELECT * FROM "InventoryItem"", "output": "[(id=1, title=Ion Blend Beans), (id=2, title=Luna Fuel Flask)]"}

EXAMPLE RUNTIME ERROR (if a user divided by zero): {"outputErr": "Exception in thread "main" java.lang.ArithmeticException: / by zero"}

KEY PATTERNS:

(See validateExoquery for complete pattern reference)

Summary of most common patterns:

• Filter: sql { Table().filter { x -> x.field == value } }

• Select: sql.select { val x = from(Table()); where { ... }; x }

• Join: sql.select { val a = from(Table()); val b = join(Table()) { b -> b.aId == a.id }; Pair(a, b) }

• Left join: joinLeft(Table()) { ... } returns nullable

• Insert: sql { insert { setParams(obj).excluding(id) } }

• Update: sql { update().set { it.field to value }.where { it.id == x } }

• Delete: sql { delete().where { it.id == x } }

SCHEMA RULES:

• Table names should match data class names (case-sensitive, use quotes for exact match)

• Column names must match @SerialName values or property names

• Include realistic test data to verify query logic

• Sqlite database syntax (mostly compatible with standard SQL)

COMMON PATTERNS:

• JSON columns: Use VARCHAR for storage, @SqlJsonValue on the nested data class

• Auto-increment IDs: Use INTEGER PRIMARY KEY

• Nullable columns: Use Type? in Kotlin, allow NULL in schema

Compile ExoQuery Kotlin code and EXECUTE it against an Sqlite database with provided schema. ExoQuery is a compile-time SQL query builder that translates Kotlin DSL expressions into SQL.

WHEN TO USE: When you need to verify ExoQuery produces correct results against actual data.

INPUT REQUIREMENTS:

• Complete Kotlin code (same requirements as validateExoquery)

• SQL schema with CREATE TABLE and INSERT statements for test data

• Data classes MUST exactly match the schema table structure

• Column names in data classes must match schema (use @SerialName for snake_case columns)

• Must include or or more .runSample() calls in main() to trigger SQL generation and execution (note that .runSample() is NOT or real production use, use .runOn(database) instead)

OUTPUT FORMAT:

Returns one or more JSON objects, each on its own line. Each object can be:

1. SQL with output (query executed successfully): {"sql": "SELECT u.name FROM "User" u", "output": "[(name=Alice), (name=Bob)]"}

2. Output only (e.g., print statements, intermediate results): {"output": "Before: [(id=1, title=Ion Blend Beans)]"}

3. Error output (runtime errors, exceptions): {"outputErr": "java.sql.SQLException: Table "USERS" not found"}

Multiple results appear when code has multiple queries or print statements:

{"sql": "SELECT * FROM "InventoryItem"", "output": "[(id=1, title=Ion Blend Beans, unit_price=32.00, in_stock=25)]"} {"output": "Before:"} {"sql": "INSERT INTO "InventoryItem" (title, unit_price, in_stock) VALUES (?, ?, ?)", "output": "Rows affected: 1"} {"output": "After:"} {"sql": "SELECT * FROM "InventoryItem"", "output": "[(id=1, title=Ion Blend Beans, unit_price=32.00, in_stock=25), (id=2, title=Luna Fuel Flask, unit_price=89.50, in_stock=6)]"}

Compilation errors return the same format as validateExoquery: { "errors": { "File.kt": [ { "interval": {"start": {"line": 12, "ch": 10}, "end": {"line": 12, "ch": 15}}, "message": "Type mismatch: inferred type is String but Int was expected", "severity": "ERROR", "className": "ERROR" } ] } }

Runtime Errors can have the following format: { "errors" : { "File.kt" : [ ] }, "exception" : { "message" : "[SQLITE_ERROR] SQL error or missing database (no such table: User)", "fullName" : "org.sqlite.SQLiteException", "stackTrace" : [ { "className" : "org.sqlite.core.DB", "methodName" : "newSQLException", "fileName" : "DB.java", "lineNumber" : 1179 }, ...] }, "text" : "\n{"sql": "SELECT x.id, x.name, x.age FROM User x"}\n\n" } If there was a SQL query generated before the error, it will appear in the "text" field output stream.

EXAMPLE INPUT CODE:

EXAMPLE INPUT SCHEMA:

EXAMPLE SUCCESS OUTPUT: {"sql": "SELECT u.name AS first, o.total AS second, u.age AS third FROM "User" u INNER JOIN "Order" o ON o.user_id = u.id", "output": "[(first=Alice, second=100, third=30), (first=Alice, second=200, third=30), (first=Bob, second=150, third=25)]"}

EXAMPLE WITH MULTIPLE OPERATIONS (insert with before/after check): {"output": "Before:"} {"sql": "SELECT * FROM "InventoryItem"", "output": "[(id=1, title=Ion Blend Beans)]"} {"sql": "INSERT INTO "InventoryItem" (title, unit_price, in_stock) VALUES (?, ?, ?)", "output": ""} {"output": "After:"} {"sql": "SELECT * FROM "InventoryItem"", "output": "[(id=1, title=Ion Blend Beans), (id=2, title=Luna Fuel Flask)]"}

EXAMPLE RUNTIME ERROR (if a user divided by zero): {"outputErr": "Exception in thread "main" java.lang.ArithmeticException: / by zero"}

KEY PATTERNS:

(See validateExoquery for complete pattern reference)

Summary of most common patterns:

• Filter: sql { Table().filter { x -> x.field == value } }

• Select: sql.select { val x = from(Table()); where { ... }; x }

• Join: sql.select { val a = from(Table()); val b = join(Table()) { b -> b.aId == a.id }; Pair(a, b) }

• Left join: joinLeft(Table()) { ... } returns nullable

• Insert: sql { insert { setParams(obj).excluding(id) } }

• Update: sql { update().set { it.field to value }.where { it.id == x } }

• Delete: sql { delete().where { it.id == x } }

SCHEMA RULES:

• Table names should match data class names (case-sensitive, use quotes for exact match)

• Column names must match @SerialName values or property names

• Include realistic test data to verify query logic

• Sqlite database syntax (mostly compatible with standard SQL)

COMMON PATTERNS:

• JSON columns: Use VARCHAR for storage, @SqlJsonValue on the nested data class

• Auto-increment IDs: Use INTEGER PRIMARY KEY

• Nullable columns: Use Type? in Kotlin, allow NULL in schema