Synechron Text2SQL MCP Server
Proporciona acceso en lenguaje natural a bases de datos relacionales utilizando modelos de lenguaje avanzados, con soporte para múltiples tipos de bases de datos.
GitHub
5
Prueba este MCPPatrocinadoDocumentación
Servidor MCP Synechron Text2SQL
El Servidor MCP Text2SQL de Synechron es un servidor del Protocolo de Contexto de Modelos (MCP). Proporciona a clientes MCP como Cursor, VSCode y Claude Desktop acceso en lenguaje natural a bases de datos relacionales de diversos tipos, lo que permite a los usuarios hacer preguntas sobre sus datos utilizando capacidades de lenguaje natural.
El servidor optimiza la calidad de los resultados que genera mediante una combinación de búsqueda semántica consciente del esquema y de las filas. Los esquemas y una muestra de filas se indexan, lo que permite al servidor generar consultas adecuadas de manera más efectiva.
Características y Capacidades
El servidor MCP Text2SQL proporciona las siguientes capacidades:
- Lenguaje Natural a SQL: Las preguntas en lenguaje natural se convierten en consultas SQL optimizadas utilizando modelos de lenguaje avanzados.
- Soporte Multi-Base de Datos: Compatibilidad con bases de datos PostgreSQL, MySQL, SQLite y Microsoft Fabric.
- Generación Aumentada por Recuperación (RAG): Generación de consultas mejorada al combinar metadatos de esquema y contenido de filas muestreadas.
- Indexación de Tablas: Habilita la incrustación de esquemas de bases de datos y datos de muestra, mejorando la relevancia de las consultas.
- Síntesis de Respuestas: Genera resúmenes en lenguaje natural de los resultados de las consultas.
- Formato Markdown: Crea respuestas más legibles.
- Soporte de Múltiples Modelos: Funciona con modelos de OpenAI, Azure OpenAI, AWS Bedrock y Ollama.
Datos de Muestra
El servidor incluye dos conjuntos de datos de ejemplo.
- Amenazas Cibernéticas
- Calificaciones ESG
Cliente de Muestra
También se incluye un REPL de muestra.
Inicio Rápido con Docker
Nota: Para usar sus propias bases de datos, se requiere configuración adicional; consulte la sección Configuración a continuación.
Ejecutar el Servidor con Docker
docker run -it -p8000:8000 \
-v ~/.aws:/home/appuser/.aws:ro \
-e MODEL_API_TYPE=Bedrock \
-e AWS_PROFILE=AWSAdministratorAccess-880502554482 \
-e FASTMCP_HOST=0.0.0.0 \
709825985650.dkr.ecr.us-east-1.amazonaws.com/synechron/mcp-text2sql:0.0.10-2025.07.04-rc3 server
Running the Sample Client with Docker
docker run -it \
-v ~/.aws:/home/appuser/.aws:ro \
-e AWS_PROFILE=AWSAdministratorAccess-880502554482 \
-e BEDROCK_MODEL_ID=us.anthropic.claude-3-7-sonnet-20250219-v1:0 \
-e BEDROCK_API_VERSION=2025-01-01-preview \
-e MCP_SERVER_HOST=host.docker.internal \
709825985650.dkr.ecr.us-east-1.amazonaws.com/synechron/mcp-text2sql:0.0.10-2025.07.04-rc3 client
Ejemplo de Uso del Cliente
Connected to server with tools: ['Text2Sql_Cyber_Threats', 'Text2Sql_ESG_Ratings']
MCP Client Started!
Type your queries or 'quit' to exit.
Query: What kind of data is in the Cyber Threat datasource?
The Cyber Threat datasource contains comprehensive information about cybersecurity incidents with the following data fields:
1. country - The country where the cyber attack took place
2. year - The year when the cyber attack occurred
3. attack_type - The type of cyber attack (e.g., Phishing, Ransomware, DDoS, Man-in-the-Middle, SQL Injection)
4. target_industry - The industry that was targeted (e.g., Education, Retail, IT, Telecommunications, Healthcare, Government, Banking)
5. financial_loss_(in_million_$) - The financial impact of the attack in millions of dollars
6. number_of_affected_users - How many users were affected by the attack
7. attack_source - Where the attack originated from (e.g., Hacker Group, Nation-state, Insider, Unknown)
8. security_vulnerability_type - The type of security vulnerability exploited (e.g., Unpatched Software, Weak Passwords, Social Engineering)
9. defense_mechanism_used - What defense was in place (e.g., VPN, Firewall, Antivirus, AI-based Detection)
10. incident_resolution_time_(in_hours) - How long it took to resolve the incident in hours
The database tracks cybersecurity incidents across different countries, industries, and years, including details about attack methods, financial impact, affected users, vulnerabilities exploited, and resolution times.
Usar el Servidor con un Cliente MCP Existente
El servidor debe ejecutarse con Docker. Use cualquiera de las siguientes configuraciones para agregarlo a un cliente MCP:
{
"servers": {
"text2sql": {
"type": "streamable-http",
"url": "http://localhost:8000/mcp"
}
}
}
{
"mcpServers": {
"text2sql": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--env-file",
".env",
"709825985650.dkr.ecr.us-east-1.amazonaws.com/synechron/mcp-text2sql:0.0.10-2025.07.04-rc3",
"server"
]
}
}
}
Configuración
El servidor MCP Text2SQL se puede configurar con una combinación de variables de entorno y configuración JSON.
Configuración del Servidor
| Configuración de Válvulas | Variable de Entorno | Predeterminado | Descripción |
|---|---|---|---|
| ENABLED | False | Habilitar herramienta | |
| ENABLE_RAG | True | Usar IA para sintetizar una respuesta utilizando los datos recopilados. | |
| ENABLE_MARKDOWN | False | Formatear respuesta en Markdown | |
| ENABLE_PANDAS | True | Usar pandas para ejecutar y analizar consultas SQL; de lo contrario, usar llama_index | |
| ENABLE_TABLE_INDEXING | True | Usar recuperador de tablas para crear incrustaciones del esquema de la base de datos y datos de muestra para optimizar el contexto para el LLM | |
| FORCE_REINDEXING | False | Forzar a la herramienta a regenerar índices vectoriales para tablas y datos de muestra | |
| DATABASE_CONFIG | DB_CONFIG | Configuración de db predeterminada | Configuración de herramienta en formato JSON con cadena de conexión de base de datos, tablas, contexto y avisos |
| IGNORE_SCHEMA | Tablas del sistema predeterminadas | Lista separada por comas de esquemas a ignorar | |
| CREDENTIAL_SERVICE | CREDENTIAL_SERVICE | Seleccionar tipo de autenticación (Azure, AWS, Google, None) | |
| MODEL_API_TYPE / MODEL_TYPE | MODEL_TYPE | OpenAI | Seleccionar tipo de API de modelo (OpenAI, Azure OpenAI, Bedrock, Ollama) |
| API_ENDPOINT | OPENAI_ENDPOINT | http://litellm-proxy:4000 | Punto de conexión de la API de OpenAI |
| API_ID | API_ACCESS_ID | ID de clave de acceso | |
| API_KEY | OPENAI_API_KEY | Clave de API de OpenAI | |
| API_REGION | AWS_REGION | us-east-1 | Región para modelos alojados en la nube |
| API_VERSION | 2025-01-01-preview | Versión de la API de OpenAI | |
| LLM_MODEL_NAME | gpt-4.1-mini | Modelo de texto a SQL | |
| EMBED_MODEL_NAME | text-embedding-3-small | Modelo de incrustación | |
| MAX_RETRY | 3 | Número máximo de reintentos para consultas fallidas | |
| MAX_RESULTS | 200 | Número máximo de filas en una respuesta | |
| MAX_DATAFRAME | 1000 | Número máximo de filas en un dataframe enviado al LLM para sintetizar una respuesta | |
| SAMPLE_RATIO | 0.0001 | Porcentaje del conjunto de datos a indexar. Valores más altos tardarán más en indexarse pero darán mejores resultados. | |
| SAMPLE_MAX_SIZE | 50 | Número máximo de filas a muestrear. Reemplaza a SAMPLE_RATIO | |
| DEBUG | False | Modo de depuración | |
| MODE | MODE | stdio | Modo en el que debe operar el servidor MCP. Use shttp para HTTP Streamable. |
| AUTH_ENABLED | AUTH_ENABLED | false | Si se requiere o no que los clientes MCP estén autenticados. |
| AUTH_ISSUER | AUTH_ISSUER | Requerido si AUTH_ENABLED es true. | |
| AUTH_JWKS_URI | AUTH_JWKS_URI | Requerido si AUTH_ENABLED es true. | |
| AWS_ACCESS_KEY_ID | AWS_ACCESS_KEY_ID | Requerido si se usa AWS Bedrock para incrustaciones | |
| AWS_SECRET_ACCESS_KEY | AWS_SECRET_ACCESS_KEY | Requerido si se usa AWS Bedrock para incrustaciones | |
| LOG_LEVEL | LOG_LEVEL | INFO | Nivel de registro (DEBUG, INFO, WARNING, ERROR). |
| MCP_SERVER_API_KEY | MCP_SERVER_API_KEY | Clave de API para acceso a LLM / Incrustaciones. Configurar con AWS_SECRET_ACCESS_KEY, clave LiteLLM o clave de API de OpenAI. | |
| MCP_SERVER_DATA | MCP_SERVER_DATA | data | Directorio para archivos de datos temporales |
| TEXT2SQL_VALVES_JSON | TEXT2SQL_VALVES_JSON | valves.json | Ruta completa al JSON de configuración; ver ejemplo arriba. |
Ejemplo de Archivo .env
LOG_LEVEL=INFO
PYTHONUNBUFFERED=1
TEXT2SQL_VALVES_JSON=/home/appuser/config/config.json
MODE=shttp
FASTMCP_HOST=0.0.0.0
FASTMCP_PORT=8000
AUTH_ENABLED=true
AUTH_JWKS_URI=https://cognito-idp.us-east-1.amazonaws.com/us-east-1_/.well-known/jwks.json
AUTH_ISSUER=https://cognito-idp.us-east-1.amazonaws.com/us-east-1_
AWS_PROFILE=default
Ejemplo de TEXT2SQL_VALVES_JSON (valves.json)
El servidor MCP Text2SQL debe configurarse utilizando un archivo JSON que especifique conexiones de base de datos, configuraciones de modelo y otros parámetros. Aquí hay un ejemplo de configuración:
{
"ENABLED": true,
"ENABLE_RAG": false,
"ENABLE_MARKDOWN": true,
"ENABLE_PANDAS": true,
"ENABLE_TABLE_INDEXING": true,
"FORCE_REINDEXING": false,
"DATABASE_CONFIG": {
"Cyber_Threats": {
"description": "A comprehensive dataset tracking cybersecurity incidents, attack vectors, threat types, and affected countries.",
"topics": [
"Cyber Threats",
"Attacks",
"Targets"
],
"url": "sqlite:///file:/home/appuser/config/cyber_threats.db?uri=true",
"tables": {
"cyber_threats": "The Global Cybersecurity Threats Dataset (2015-2024) provides extensive data on cyberattacks, malware types, targeted industries, and affected countries."
},
"prompts": [
{
"name": "biggest_cyber_threat",
"description": "Which type of cyber threat has caused the biggest financial loss?"
}
]
},
"ESG_Ratings": {
"description": "S&P 500 Companies ESG Insights & Risk Scores for Informed Decisions.",
"topics": [
"ESG Ratings",
"ESG Risk",
"Sustainability"
],
"url": "sqlite:///file:/home/appuser/config/esg_ratings.db?uri=true",
"tables": {
"esg_ratings": "A comprehensive dataset tracking ESG ratings for S&P 500 companies."
}
}
},
"IGNORE_SCHEMA": "information_schema, INFORMATION_SCHEMA, _rsc, db_accessadmin, db_backupoperator, db_datareader, db_datawriter, db_ddladmin, db_denydatareader, db_denydatawriter, db_owner, db_securityadmin, guest, queryinsights, sys, pg_catalog",
"MODEL_API_TYPE": "Bedrock",
"AWS_PROFILE": "default",
"API_VERSION": "2025-01-01-preview",
"LLM_MODEL_NAME": "us.anthropic.claude-3-7-sonnet-20250219-v1:0",
"EMBED_MODEL_NAME": "amazon.titan-embed-text-v2:0",
"MAX_RETRY": 3,
"MAX_RESULTS": 100,
"MAX_DATAFRAME": 2000,
"LOG_LEVEL": "INFO"
}
Configuración del Cliente
Las siguientes variables de entorno se pueden proporcionar al cliente MCP de muestra:
| Opción | Predeterminado | Descripción |
|---|---|---|
JWT_ACCESS_TOKEN | false | Token utilizado para autenticar al cliente con el servidor si el servidor tiene AUTH_ENABLED true |
MCP_SERVER_HOST | Host para el servidor MCP. Para un servidor que se ejecuta en Docker en el mismo host, use host.docker.internal | |
MCP_SERVER_PORT | 8000 | Puerto para el servidor MCP. |
BEDROCK_MODEL_ID | Requerido si se usa AWS Bedrock, p. ej. us.anthropic.claude-3-7-sonnet-20250219-v1:0 | |
BEDROCK_API_VERSION | Requerido si se usa AWS Bedrock, p. ej. 2023-06-01-preview | |
AWS_PROFILE | Requerido si se usa AWS Bedrock, p. ej. default | |
AZURE_DEPLOYMENT_MODEL | Requerido si se usa Azure OpenAI. Se ignora si BEDROCK_MODEL_ID está configurado. Para la autenticación de Azure, consulte DefaultAzureCredential. | |
AZURE_API_VERSION | Requerido si se usa Azure OpenAI. Se ignora si BEDROCK_MODEL_ID está configurado. | |
OTEL_SDK_DISABLED | false | Habilitar telemetría para el cliente de Crew.AI. |
CREWAI_DISABLE_TELEMETRY | false | Habilitar telemetría para el cliente de Crew.AI. |
Herramientas
El servidor MCP Text2SQL crea dinámicamente herramientas y prompts de MCP para las bases de datos configuradas en el siguiente formato:
- Text2Sql_DatabaseName: Consultar una base de datos específica usando lenguaje natural
- Parámetros:
query: Consulta en lenguaje natural para ejecutar contra la base de datos
- Parámetros:
Licencia
Este proyecto está licenciado bajo la Licencia MIT.