What is Textql Mcp

textql-mcp is a standalone Model Context Protocol (MCP) server that translates natural language into SQL/GraphQL queries and executes them, providing a standardized interface for AI models and agents to interact with databases.

Use cases

Use cases for textql-mcp include generating SQL queries from user questions in business applications, enabling chatbots to retrieve data from databases, and allowing analysts to query data using natural language without needing to know SQL.

How to use

To use textql-mcp, you need to create a schema provider that defines your database schema, then create and start the MCP server using the provided API. You can also customize the server by implementing interfaces for schema provision, query execution, and ambiguity detection.

Key features

Key features of textql-mcp include natural language to SQL/GraphQL translation, query execution capabilities, automatic schema support for query refinement, an extensible design for easy integration, and adherence to the MCP standard for seamless AI agent integration.

Where to use

textql-mcp can be used in various fields such as data analysis, business intelligence, customer support, and any application requiring natural language processing to interact with databases.

TextQL MCP Server

A standalone Model Context Protocol (MCP) server implementation that exposes tools for translating natural language to * Query Language (*QL) and executing *QL queries.

Overview

This library provides a standardized interface for AI models and agents to interact with SQL/Graph databases using the Model Context Protocol. The server exposes tools for sending *QL queries and retrieving structured responses.

Features

• Natural Language to *hQL Translation: Convert natural language questions to SQL/GraphQL queries
• Query Execution: Execute SQL/GraphQL queries against your database
• Schema Support: Automatically fetch and use relevant schema information for query refinement
• Extensible Design: Easily integrate with your own database and schema providers
• MCP Standard: Built on the Model Context Protocol for seamless integration with AI agents

Installation

Option 1: Using Conda (Recommended)

1. Clone the repository:

   git clone https://github.com/your-username/textql-mcp.git
   cd textql-mcp
   

2. Set up the conda environment (requires conda to be installed):

   source setup_env.sh
   

   This will create a new conda environment named textql with all required dependencies.

Option 2: Using pip

1. Clone the repository:

   git clone https://github.com/your-username/textql-mcp.git
   cd textql-mcp
   

2. Install the required packages:

   pip install -r requirements.txt
   

Quick Start

import asyncio
from textql_mcp import create_mcp_server
from textql_mcp.schemas import SimpleSchemaProvider

# Create a schema provider
schema_provider = SimpleSchemaProvider("path/to/schema.sql")

# Create and start the MCP server
server = create_mcp_server(
    schema_provider=schema_provider,
    port=8000
)

server.run()

Advanced Usage

See the examples/ directory for complete examples of how to use the TextQL MCP Server with different database backends.

Customization

You can customize the server by implementing these interfaces:

• SchemaProvider: Provides schema information for queries
• QueryExecutor: Executes queries against your database
• AmbiguityDetector: Detects ambiguities in natural language queries

API Reference

Tools

translate_to_gql

Translate a natural language query into a GraphQL query.

Parameters:

• natural_language_query (str): The natural language question to translate
• agent_type (str, optional): The agent type identifier (default: “default”)

Returns:

• Dictionary containing the generated GraphQL query and related metadata

query_graph

Execute a query against the database.

Parameters:

• gql_query (str): The query to execute
• agent_type (str, optional): The agent type identifier (default: “default”)

Returns:

• Dictionary containing the query results and metadata

process_natural_language_query

Process a natural language query by translating it to *QL and executing it.

Parameters:

• natural_language_query (str): The natural language question to process
• agent_type (str, optional): The agent type identifier (default: “default”)
• max_attempts (int, optional): Maximum number of query refinement attempts (default: 3)

Returns:

• Dictionary containing the final results and execution history

License

Apache 2.0 License