diff --git a/docs/images/scalardb-mcp-server-architecture.png b/docs/images/scalardb-mcp-server-architecture.png new file mode 100644 index 00000000..0c7cd0ca Binary files /dev/null and b/docs/images/scalardb-mcp-server-architecture.png differ diff --git a/docs/scalardb-mcp-server/getting-started-with-scalardb-mcp-server.mdx b/docs/scalardb-mcp-server/getting-started-with-scalardb-mcp-server.mdx new file mode 100644 index 00000000..985f42fe --- /dev/null +++ b/docs/scalardb-mcp-server/getting-started-with-scalardb-mcp-server.mdx @@ -0,0 +1,627 @@ +--- +tags: + - Community + - Enterprise Standard + - Enterprise Premium +displayed_sidebar: docsEnglish +--- + +# Getting Started with ScalarDB MCP Server + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +ScalarDB MCP Server is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) implementation that enables LLMs to access and manage your data through ScalarDB. By leveraging LLMs, you can use natural language to search and update across multiple, potentially siloed, databases. + +ScalarDB MCP Server works with both single and multiple storage configurations. Unlike traditional approaches that require separate MCP servers for each database, ScalarDB MCP Server takes advantage of the [multi-storage capabilities of ScalarDB](../multi-storage-transactions.mdx) to provide unified access to heterogeneous databases (PostgreSQL, MySQL, Cosmos DB, DynamoDB, etc.) through a single MCP server. By simply submitting queries in natural language, the server automatically executes the appropriate operations across your databases, improving and accelerating decision-making processes. + +## Architecture and key features + +The following diagram shows how ScalarDB MCP Server differs from traditional approaches. Instead of requiring separate MCP servers for each database, you connect once to ScalarDB MCP Server to access all your databases through ScalarDB. + +![ScalarDB MCP server architecture](../images/scalardb-mcp-server-architecture.png) + +At its core, ScalarDB MCP Server provides the following capabilities. + +### ScalarDB connectivity + +The MCP server connects to your ScalarDB deployment (either ScalarDB Cluster or ScalarDB direct-to-database mode) and handles all technical complexity while providing AI assistants with simple, standardized tools. + +### Transactional operations + +ScalarDB MCP Server supports ACID-compliant transactions, allowing an LLM to execute multiple operations safely. When the LLM determines that operations should be grouped together, the MCP server ensures the operations either all succeed or all fail together, maintaining data integrity across your databases. + +### Operational mode + +ScalarDB MCP Server supports two operational modes that match your ScalarDB deployment type: SQL mode and CRUD mode. + +#### SQL mode + +SQL mode with ScalarDB Cluster provides a SQL interface for database operations. When you make natural language requests, the LLM automatically generates and executes SQL commands through the supported SQL operations in ScalarDB and handles transactions by using standard SQL syntax (`BEGIN`, `COMMIT`, `ROLLBACK`). This mode could be more efficient because the LLM only needs to use one tool to perform all operations. + +#### CRUD mode + +CRUD mode with ScalarDB Core is for when you prefer programmatic control over your operations. Since ScalarDB Core doesn't include the SQL interface, this mode uses the native SDK operations in ScalarDB instead. The LLM converts your natural language requests into appropriate SDK calls by using individual tools for schema management, CRUD operations, and explicit transaction control. This mode could be less efficient because the LLM has to work with multiple tools to complete operations. + +### Deployment limitations + +:::note + +The ScalarDB MCP Server currently runs in STDIO mode for local deployment only. Remote server deployment via Server-Sent Events (SSE) is not yet supported but is planned for future releases. + +**What this means:** + +- ✅ The MCP server runs locally alongside your AI client (Claude Desktop, Visual Studio Code, etc.). +- ✅ Perfect for development, testing, and single-user scenarios. +- ❌ Cannot deploy the MCP server on remote servers for multi-user access. +- ❌ No web-based or cloud deployment options yet. + +::: + +## Example workflow + +Here's how you interact with ScalarDB MCP Server through natural language: + +**Querying data (SQL mode):** + +```markdown +You: "Show me all users from the customer table" +🤖 LLM automatically uses: scalardb_execute_sql tool +SQL generated: SELECT * FROM customer +Result: Customer data displayed with columns and values +``` + +**Querying data (CRUD mode):** + +```markdown +You: "Show me all users from the customer table" +🤖 LLM automatically uses: scalardb_scan tool +Result: Customer data displayed with columns and values +``` + +**Creating database structures (CRUD mode):** + +```markdown +You: "Create a new table called products with columns id, name, and price" +🤖 LLM automatically uses: scalardb_create_table tool +Result: ✅ Table 'products' created successfully +``` + +**Cross-database operations (multi-storage):** + +```markdown +You: "Get user profile and order history for user ID 123" +🤖 LLM automatically uses: scalardb_get tool (queries across multiple databases) +Result: Combined user profile (from PostgreSQL) and order history (from DynamoDB) +``` + +The LLM automatically selects the appropriate tools based on your request—you don't need to know which specific tools exist or how to use them. + +## Tutorial + +The following configuration samples use the same Cassandra and MySQL multi-storage configuration as our [Multi-Storage Transaction Sample](../scalardb-samples/multi-storage-transaction-sample/). You can follow that hands-on tutorial to set up your databases, then use the same setup to test the MCP server with this tutorial. + +Configurations may vary depending on your specific MCP client and database environment. Refer to your MCP client's documentation for detailed setup instructions on how to add a connection to an MCP server. + +### Setup + +Follow these steps to set up ScalarDB MCP Server. + +#### Prerequisites + +Ensure you have the following: + +- (For JAR distribution) Java Runtime Environment: + - Oracle JDK: 17 or 21 + - OpenJDK (Eclipse Temurin, Amazon Corretto, or Microsoft Build of OpenJDK): 17 or 21 +- (For Docker distribution) Docker 20.10 or later +- (For this tutorial's examples) Cassandra and MySQL databases must be running +- (For SQL mode) ScalarDB Cluster must also be running +- MCP-compatible client (Claude Desktop, Visual Studio Code with Cline, etc.) + +#### Step 1: Choose your MCP client type + +Select the configuration method that matches your MCP client. If you're using the Claude Code CLI or similar tools that support command-line MCP server management, choose **CLI tools**. If you're using Claude Desktop or other clients that require manual JSON configuration files, choose **Manual configuration files**. + + + + For MCP clients with command-line server management (for example, the Claude Code CLI). + + #### Step 2: Choose your distribution method + + + + Pull the Docker image: + + ```bash + docker pull ghcr.io/scalar-labs/scalardb-mcp-server:0.9.0 + ``` + + #### Step 3: Choose your ScalarDB deployment type + + + + Run the following command to add the MCP server: + + ```bash + claude mcp add scalardb -- docker run --rm -i \ + --name scalardb-mcp-server \ + ghcr.io/scalar-labs/scalardb-mcp-server:0.9.0 \ + --scalar.mcp.db.server.tool.mode=SQL \ + --scalar.db.transaction_manager=cluster \ + --scalar.db.contact_points=indirect:host.docker.internal \ + --scalar.db.contact_port=60053 + ``` + + This configuration uses SQL mode, which is recommended for ScalarDB Cluster as it provides a more efficient single-tool approach. + +:::note + +**ScalarDB Cluster configuration** + +The configuration above shows how the MCP server connects to ScalarDB Cluster as a client. The ScalarDB Cluster itself must be separately configured. + +For example, your ScalarDB Cluster configuration with multi-storage support would include: + +```properties +scalar.db.transaction_manager=consensus-commit +scalar.db.storage=multi-storage +scalar.db.multi_storage.storages=cassandra,mysql +scalar.db.multi_storage.storages.cassandra.storage=cassandra +scalar.db.multi_storage.storages.cassandra.contact_points=localhost +scalar.db.multi_storage.storages.cassandra.username=cassandra +scalar.db.multi_storage.storages.cassandra.password=cassandra +scalar.db.multi_storage.storages.mysql.storage=jdbc +scalar.db.multi_storage.storages.mysql.contact_points=jdbc:mysql://localhost:3306/ +scalar.db.multi_storage.storages.mysql.username=root +scalar.db.multi_storage.storages.mysql.password=mysql +scalar.db.multi_storage.namespace_mapping=customer:mysql,order:cassandra,coordinator:cassandra +scalar.db.multi_storage.default_storage=cassandra + +scalar.db.sql.enabled=true + +# License key configurations +scalar.db.cluster.node.licensing.license_key= +scalar.db.cluster.node.licensing.license_check_cert_pem= +``` + +For complete ScalarDB Cluster deployment and configuration instructions, see [ScalarDB Cluster Configurations](../scalardb-cluster/scalardb-cluster-configurations/). For a hands-on setup guide with multi-storage, see the [Multi-Storage Transaction Sample](../scalardb-samples/multi-storage-transaction-sample/). + +::: + +:::important + +Docker flags: + +- `--rm`: Required to automatically remove the container after the MCP client disconnects +- `--name`: Required to prevent dangling container instances from accumulating + +::: + + + Run the following command to add the MCP server: + + ```bash + claude mcp add scalardb -- docker run --rm -i \ + --name scalardb-mcp-server \ + ghcr.io/scalar-labs/scalardb-mcp-server:0.9.0 \ + --scalar.mcp.db.server.tool.mode=CRUD \ + --scalar.db.transaction_manager=consensus-commit \ + --scalar.db.storage=multi-storage \ + --scalar.db.multi_storage.storages=cassandra,mysql \ + --scalar.db.multi_storage.storages.cassandra.storage=cassandra \ + --scalar.db.multi_storage.storages.cassandra.contact_points=host.docker.internal \ + --scalar.db.multi_storage.storages.cassandra.username=cassandra \ + --scalar.db.multi_storage.storages.cassandra.password=cassandra \ + --scalar.db.multi_storage.storages.mysql.storage=jdbc \ + --scalar.db.multi_storage.storages.mysql.contact_points=jdbc:mysql://host.docker.internal:3306/ \ + --scalar.db.multi_storage.storages.mysql.username=root \ + --scalar.db.multi_storage.storages.mysql.password=mysql \ + --scalar.db.multi_storage.namespace_mapping=customer:mysql,order:cassandra,coordinator:cassandra \ + --scalar.db.multi_storage.default_storage=cassandra + ``` + + This configuration uses CRUD mode, which is required for ScalarDB Core as it doesn't include the SQL interface. + +:::note + +The example above demonstrates a multi-storage configuration. For other ScalarDB Core configuration options, see [ScalarDB Configurations](../configurations/). + +::: + +:::important + +Docker flags: + +- `--rm`: Required to automatically remove the container after the MCP client disconnects +- `--name`: Required to prevent ghost container instances from accumulating + +::: + + + + + Download the latest JAR file from the [ScalarDB MCP Server releases page](https://github.com/scalar-labs/scalardb-mcp-server/releases/latest). + + #### Step 3: Choose your ScalarDB deployment type + + + + Run the following command to add the MCP server: + + ```bash + claude mcp add scalardb \ + -- java -jar /path/to/scalardb-mcp-server-0.9.0.jar \ + --scalar.mcp.db.server.tool.mode=SQL \ + --scalar.db.transaction_manager=indirect:localhost \ + --scalar.db.contact_points=indirect:localhost \ + --scalar.db.contact_port=60053 + ``` + + This configuration uses SQL mode, which is recommended for ScalarDB Cluster as it provides a more efficient single-tool approach. + +:::note + +**ScalarDB Cluster configuration** + +The configuration above shows how the MCP server connects to ScalarDB Cluster as a client. The ScalarDB Cluster itself must be separately configured. + +For example, your ScalarDB Cluster configuration with multi-storage support would include: + +```properties +scalar.db.transaction_manager=consensus-commit +scalar.db.storage=multi-storage +scalar.db.multi_storage.storages=cassandra,mysql +scalar.db.multi_storage.storages.cassandra.storage=cassandra +scalar.db.multi_storage.storages.cassandra.contact_points=localhost +scalar.db.multi_storage.storages.cassandra.username=cassandra +scalar.db.multi_storage.storages.cassandra.password=cassandra +scalar.db.multi_storage.storages.mysql.storage=jdbc +scalar.db.multi_storage.storages.mysql.contact_points=jdbc:mysql://localhost:3306/ +scalar.db.multi_storage.storages.mysql.username=root +scalar.db.multi_storage.storages.mysql.password=mysql +scalar.db.multi_storage.namespace_mapping=customer:mysql,order:cassandra,coordinator:cassandra +scalar.db.multi_storage.default_storage=cassandra + +scalar.db.sql.enabled=true + +# License key configurations +scalar.db.cluster.node.licensing.license_key= +scalar.db.cluster.node.licensing.license_check_cert_pem= +``` + +For complete ScalarDB Cluster deployment and configuration instructions, see [ScalarDB Cluster Configurations](../scalardb-cluster/scalardb-cluster-configurations/). For a hands-on setup guide with multi-storage, see the [Multi-Storage Transaction Sample](../scalardb-samples/multi-storage-transaction-sample/). + +::: + + + Run the following command to add the MCP server: + + ```bash + claude mcp add scalardb \ + -- java -jar /path/to/scalardb-mcp-server-0.9.0.jar \ + --scalar.mcp.db.server.tool.mode=CRUD \ + --scalar.db.transaction_manager=consensus-commit \ + --scalar.db.storage=multi-storage \ + --scalar.db.multi_storage.storages=cassandra,mysql \ + --scalar.db.multi_storage.storages.cassandra.storage=cassandra \ + --scalar.db.multi_storage.storages.cassandra.contact_points=localhost \ + --scalar.db.multi_storage.storages.cassandra.username=cassandra \ + --scalar.db.multi_storage.storages.cassandra.password=cassandra \ + --scalar.db.multi_storage.storages.mysql.storage=jdbc \ + --scalar.db.multi_storage.storages.mysql.contact_points=jdbc:mysql://localhost:3306/ \ + --scalar.db.multi_storage.storages.mysql.username=root \ + --scalar.db.multi_storage.storages.mysql.password=mysql \ + --scalar.db.multi_storage.namespace_mapping=customer:mysql,order:cassandra,coordinator:cassandra \ + --scalar.db.multi_storage.default_storage=cassandra + ``` + + This configuration uses CRUD mode, which is required for ScalarDB Core as it doesn't include the SQL interface. + +:::note + +The example above demonstrates a multi-storage configuration. For other ScalarDB Core configuration options, see [ScalarDB Configurations](../configurations/). + +::: + + + + + + + The examples below use the configuration format for Claude Desktop, but most MCP clients use the same JSON structure. Refer to your specific client's documentation for the exact configuration file location. + + #### Step 2: Choose your distribution method + + + + Pull the Docker image: + + ```bash + docker pull ghcr.io/scalar-labs/scalardb-mcp-server:0.9.0 + ``` + + #### Step 3: Choose your ScalarDB deployment type + + + + Add the following to your MCP client configuration file: + + ```json + { + "mcpServers": { + "scalardb": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "--name", "scalardb-mcp-server", + "ghcr.io/scalar-labs/scalardb-mcp-server:0.9.0", + "--scalar.db.transaction_manager=cluster", + "--scalar.db.contact_points=indirect:host.docker.internal", + "--scalar.db.contact_port=60053", + "--scalar.mcp.db.server.tool.mode=SQL" + ] + } + } + } + ``` + + This configuration uses SQL mode, which is recommended for ScalarDB Cluster as it provides a more efficient single-tool approach. + +:::note + +**ScalarDB Cluster configuration** + +The configuration above shows how the MCP server connects to ScalarDB Cluster as a client. The ScalarDB Cluster itself must be separately configured. + +For example, your ScalarDB Cluster configuration with multi-storage support would include: + +```properties +scalar.db.transaction_manager=consensus-commit +scalar.db.storage=multi-storage +scalar.db.multi_storage.storages=cassandra,mysql +scalar.db.multi_storage.storages.cassandra.storage=cassandra +scalar.db.multi_storage.storages.cassandra.contact_points=localhost +scalar.db.multi_storage.storages.cassandra.username=cassandra +scalar.db.multi_storage.storages.cassandra.password=cassandra +scalar.db.multi_storage.storages.mysql.storage=jdbc +scalar.db.multi_storage.storages.mysql.contact_points=jdbc:mysql://localhost:3306/ +scalar.db.multi_storage.storages.mysql.username=root +scalar.db.multi_storage.storages.mysql.password=mysql +scalar.db.multi_storage.namespace_mapping=customer:mysql,order:cassandra,coordinator:cassandra +scalar.db.multi_storage.default_storage=cassandra + +scalar.db.sql.enabled=true + +# License key configurations +scalar.db.cluster.node.licensing.license_key= +scalar.db.cluster.node.licensing.license_check_cert_pem= +``` + +For complete ScalarDB Cluster deployment and configuration instructions, see [ScalarDB Cluster Configurations](../scalardb-cluster/scalardb-cluster-configurations/). For a hands-on setup guide with multi-storage, see the [Multi-Storage Transaction Sample](../scalardb-samples/multi-storage-transaction-sample/). + +::: + +:::important + +**Docker flags** + +- `--rm`: Required to automatically remove the container after the MCP client disconnects +- `--name`: Required to prevent ghost container instances from accumulating + +::: + + + Add the following to your MCP client configuration file: + + ```json + { + "mcpServers": { + "scalardb": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "--name", "scalardb-mcp-server", + "ghcr.io/scalar-labs/scalardb-mcp-server:0.9.0", + "--scalar.mcp.db.server.tool.mode=CRUD", + "--scalar.db.transaction_manager=consensus-commit", + "--scalar.db.storage=multi-storage", + "--scalar.db.multi_storage.storages=cassandra,mysql", + "--scalar.db.multi_storage.storages.cassandra.storage=cassandra", + "--scalar.db.multi_storage.storages.cassandra.contact_points=host.docker.internal", + "--scalar.db.multi_storage.storages.cassandra.username=cassandra", + "--scalar.db.multi_storage.storages.cassandra.password=cassandra", + "--scalar.db.multi_storage.storages.mysql.storage=jdbc", + "--scalar.db.multi_storage.storages.mysql.contact_points=jdbc:mysql://host.docker.internal:3306/", + "--scalar.db.multi_storage.storages.mysql.username=root", + "--scalar.db.multi_storage.storages.mysql.password=mysql", + "--scalar.db.multi_storage.namespace_mapping=customer:mysql,order:cassandra,coordinator:cassandra", + "--scalar.db.multi_storage.default_storage=cassandra" + ] + } + } + } + ``` + + This configuration uses CRUD mode, which is required for ScalarDB Core as it doesn't include the SQL interface. + +:::note + +The example above demonstrates a multi-storage configuration. For other ScalarDB Core configuration options, see [ScalarDB Configurations](../configurations/). + +::: + +:::important + +**Docker flags** + +- `--rm`: Required to automatically remove the container after the MCP client disconnects +- `--name`: Required to prevent ghost container instances from accumulating + +::: + + + + + Download the latest JAR file from the [ScalarDB MCP Server releases page](https://github.com/scalar-labs/scalardb-mcp-server/releases/latest). + + #### Step 3: Choose your ScalarDB deployment type + + + + Add the following to your MCP client configuration file: + + ```json + { + "mcpServers": { + "scalardb": { + "command": "java", + "args": [ + "-jar", + "/path/to/scalardb-mcp-server-0.9.0.jar", + "--scalar.mcp.db.server.tool.mode=SQL" + "--scalar.db.transaction_manager=cluster", + "--scalar.db.contact_points=indirect:localhost", + "--scalar.db.contact_port=60053", + ], + } + } + } + ``` + + This configuration uses SQL mode, which is recommended for ScalarDB Cluster as it provides a more efficient single-tool approach. + +:::note + +**ScalarDB Cluster configuration** + +The configuration above shows how the MCP server connects to ScalarDB Cluster as a client. The ScalarDB Cluster itself must be separately configured. + +For example, your ScalarDB Cluster configuration with multi-storage support would include: + +```properties +scalar.db.transaction_manager=consensus-commit +scalar.db.storage=multi-storage +scalar.db.multi_storage.storages=cassandra,mysql +scalar.db.multi_storage.storages.cassandra.storage=cassandra +scalar.db.multi_storage.storages.cassandra.contact_points=localhost +scalar.db.multi_storage.storages.cassandra.username=cassandra +scalar.db.multi_storage.storages.cassandra.password=cassandra +scalar.db.multi_storage.storages.mysql.storage=jdbc +scalar.db.multi_storage.storages.mysql.contact_points=jdbc:mysql://localhost:3306/ +scalar.db.multi_storage.storages.mysql.username=root +scalar.db.multi_storage.storages.mysql.password=mysql +scalar.db.multi_storage.namespace_mapping=customer:mysql,order:cassandra,coordinator:cassandra +scalar.db.multi_storage.default_storage=cassandra + +scalar.db.sql.enabled=true + +# License key configurations +scalar.db.cluster.node.licensing.license_key= +scalar.db.cluster.node.licensing.license_check_cert_pem= +``` + +For complete ScalarDB Cluster deployment and configuration instructions, see [ScalarDB Cluster Configurations](../scalardb-cluster/scalardb-cluster-configurations/). For a hands-on setup guide with multi-storage, see the [Multi-Storage Transaction Sample](../scalardb-samples/multi-storage-transaction-sample/). + +::: + + + Add the following to your MCP client configuration file: + + ```json + { + "mcpServers": { + "scalardb": { + "command": "java", + "args": [ + "-jar", + "/path/to/scalardb-mcp-server-0.9.0.jar", + "--scalar.mcp.db.server.tool.mode=CRUD", + "--scalar.db.transaction_manager=consensus-commit", + "--scalar.db.storage=multi-storage", + "--scalar.db.multi_storage.storages=cassandra,mysql", + "--scalar.db.multi_storage.storages.cassandra.storage=cassandra", + "--scalar.db.multi_storage.storages.cassandra.contact_points=localhost", + "--scalar.db.multi_storage.storages.cassandra.username=cassandra", + "--scalar.db.multi_storage.storages.cassandra.password=cassandra", + "--scalar.db.multi_storage.storages.mysql.storage=jdbc", + "--scalar.db.multi_storage.storages.mysql.contact_points=jdbc:mysql://localhost:3306/", + "--scalar.db.multi_storage.storages.mysql.username=root", + "--scalar.db.multi_storage.storages.mysql.password=mysql", + "--scalar.db.multi_storage.namespace_mapping=customer:mysql,order:cassandra,coordinator:cassandra", + "--scalar.db.multi_storage.default_storage=cassandra" + ] + } + } + } + ``` + + This configuration uses CRUD mode, which is required for ScalarDB Core as it doesn't include the SQL interface. + +:::note + +The example above demonstrates a multi-storage configuration. For other ScalarDB Core configuration options, see [ScalarDB Configurations](../configurations/). + +::: + + + + + + + +### ScalarDB MCP Server configuration + +Configure the MCP server by providing command-line arguments with lowercase dot notations when starting the server. + +#### ScalarDB MCP Server–specific configuration + +These properties control how the ScalarDB MCP server operates: + +##### `scalar.mcp.db.server.tool.mode` + +- **Property:** `scalar.mcp.db.server.tool.mode` +- **Description:** Tool availability mode. +- **Default value:** `CRUD` +- **Options:** `SQL`, `CRUD` + +##### `scalar.mcp.db.server.connection.health_check_interval_seconds` + +- **Property:** `scalar.mcp.db.server.connection.health_check_interval_seconds` +- **Description:** Health check interval in seconds. +- **Default value:** `30` +- **Options:** Any positive integer value + +##### `scalar.mcp.db.server.logging.file.name` + +- **Property:** `scalar.mcp.db.server.logging.file.name` +- **Description:** Enable file logging by specifying a log file path. +- **Default value:** No file logging +- **Example:** `scalardb-mcp-server.log` + +##### `scalar.mcp.db.server.logging.level` + +- **Property:** `scalar.mcp.db.server.logging.level` +- **Description:** Set the logger level for the MCP server. +- **Default value:** `INFO` +- **Options:** `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR` + +#### ScalarDB connection configuration + +The MCP server uses ScalarDB client configuration properties to connect to your ScalarDB deployment (either ScalarDB Cluster or ScalarDB Core). These properties are passed as command-line arguments with lowercase dot notations. See the setup examples above for complete configuration examples for both connection types. + +## Available tools + +The ScalarDB MCP Server provides comprehensive database operations through specialized MCP tools. The LLM automatically selects and uses the appropriate tools based on your natural language requests. + +For complete tool documentation including all available operations, parameters, and examples, see the [ScalarDB MCP Server Tools Reference](./tools-reference.mdx). + +## ScalarDB version compatibility + +| ScalarDB MCP Server | ScalarDB Core | ScalarDB Cluster | Java Version | Notes | +|-------------------|-------------------|------------------|--------------|--------| +| 0.9.x | 3.16+ | 3.16+ | 17+ | Initial release | diff --git a/docs/scalardb-mcp-server/tools-reference.mdx b/docs/scalardb-mcp-server/tools-reference.mdx new file mode 100644 index 00000000..7ebbc860 --- /dev/null +++ b/docs/scalardb-mcp-server/tools-reference.mdx @@ -0,0 +1,98 @@ +--- +tags: + - Community + - Enterprise Standard + - Enterprise Premium +displayed_sidebar: docsEnglish +--- + +# ScalarDB MCP Server Tools Reference + +The ScalarDB MCP Server provides comprehensive database operations through more than 20 specialized MCP tools. You can interact with the LLM by using natural language, and the LLM automatically selects and uses the appropriate tools to fulfill requests. Understanding these tools helps you know what database operations the LLM can perform on your behalf. + +## Connection tools + +Monitor and verify your ScalarDB connection status and configuration. The following tool is available in both CRUD and SQL mode. + +| Tool | Description | +|------|-------------| +| `scalardb_connection_info` | Get the current connection status, configuration details, and health check results. | + +## Schema management tools + +Create, modify, and inspect database structures including namespaces, tables, and indexes. The following tools are available in CRUD mode. + +| Tool | Description | +|------|-------------| +| `scalardb_create_namespace` | Create a new namespace/keyspace for organizing tables. | +| `scalardb_drop_namespace` | Drop an existing namespace and all its tables. | +| `scalardb_list_namespaces` | List all available namespaces in the database. | +| `scalardb_create_table` | Create a new table with complete schema definition including partition keys, clustering keys, and columns. | +| `scalardb_drop_table` | Drop an existing table and all its data. | +| `scalardb_truncate_table` | Remove all data from a table while keeping the schema. | +| `scalardb_describe_table` | Get detailed table schema including columns, keys, and metadata. | +| `scalardb_list_tables` | List all tables within a specific namespace. | +| `scalardb_add_new_column` | Add a new column to an existing table schema. | +| `scalardb_create_index` | Create secondary indexes on table columns for faster queries. | +| `scalardb_drop_index` | Drop an existing secondary index. | + +## CRUD operation tools + +Perform data manipulation operations by using the ScalarDB Java client SDK for granular control and type safety. The following tools are available in CRUD mode. + +| Tool | Description | +|------|-------------| +| `scalardb_get` | Retrieve specific records by using partition keys, clustering keys, or secondary indexes. | +| `scalardb_scan` | Scan records with flexible filtering, ordering, and pagination capabilities. | +| `scalardb_insert` | Insert new records with automatic conflict detection. | +| `scalardb_update` | Update existing records with conditional operations. | +| `scalardb_upsert` | Insert new records or update existing ones (insert if they don't exist; update if they do exist). | +| `scalardb_delete` | Delete records by using primary keys or conditional logic. | + +## Transaction management tools + +Control ACID transactions by using the ScalarDB Java client SDK with proper isolation and consistency guarantees. Available in CRUD mode. + +| Tool | Description | +|------|-------------| +| `scalardb_begin_transaction` | Start a new read-write transaction with ACID guarantees. | +| `scalardb_begin_readonly_transaction` | Start an optimized read-only transaction for queries. | +| `scalardb_commit_transaction` | Commit a transaction and make all changes permanent. | +| `scalardb_rollback_transaction` | Roll back a transaction and undo all changes. | + +## SQL tools (ScalarDB Cluster only) + +Execute SQL commands directly through the ScalarDB SQL interface. The following tool is available in SQL mode. + +| Tool | Description | +|------|-------------| +| `scalardb_execute_sql` | Execute SQL queries directly (`SELECT`, `INSERT`, `UPDATE`, `DELETE`) with full SQL syntax support. | + +## Coordinator tools + +Manage distributed transaction Coordinator tables for multi-database consistency. These tools are available in CRUD mode. + +| Tool | Description | +|------|-------------| +| `scalardb_create_coordinator_tables` | Create Coordinator tables required for distributed transactions. | +| `scalardb_drop_coordinator_tables` | Drop Coordinator tables when no longer needed. | +| `scalardb_truncate_coordinator_tables` | Clear Coordinator tables while preserving structure. | + +## Tool availability by mode + +Different tools are available depending on the operational mode you choose. + +### SQL mode + +- **Connection tools:** Monitor connection status and health. +- **SQL tools:** Execute SQL queries directly through the ScalarDB SQL interface. +- **Use case:** Best for ScalarDB Cluster deployments when you prefer using SQL syntax. + +### CRUD mode + +- **Connection tools:** Monitor connection status and health. +- **Schema management tools:** Create and manage namespaces, tables, and indexes. +- **CRUD operation tools:** Perform data manipulation with the ScalarDB Java client SDK. +- **Transaction management tools:** Control ACID transactions programmatically. +- **Coordinator tools:** Manage distributed transaction coordination. +- **Use case:** Required for ScalarDB Core. diff --git a/sidebars.js b/sidebars.js index 3ae0c0b8..ecf36e05 100644 --- a/sidebars.js +++ b/sidebars.js @@ -589,6 +589,23 @@ const sidebars = { }, ], }, + { + type: 'category', + label: 'ScalarDB MCP Server', + collapsible: true, + items: [ + { + type: 'doc', + id: 'scalardb-mcp-server/getting-started-with-scalardb-mcp-server', + label: 'Use ScalarDB MCP Server', + }, + { + type: 'doc', + id: 'scalardb-mcp-server/tools-reference', + label: 'ScalarDB MCP Server Tools Reference', + }, + ], + }, ], }, ],