sqlserver-mcp-tools 0.1.0__py3-none-any.whl

mcp_sqlserver/connection.py

@@ -0,0 +1,146 @@
+import os
+from pathlib import Path
+import pyodbc
+from dotenv import load_dotenv
+
+_RAIZ_MCP = Path(__file__).resolve().parent.parent.parent
+
+# Se MSSQL_ENV_FILE estiver definida, carrega o arquivo indicado
+_env_explicito = os.getenv("MSSQL_ENV_FILE", "")
+if _env_explicito:
+    _caminho_explicito = Path(_env_explicito)
+    if _caminho_explicito.exists():
+        load_dotenv(_caminho_explicito, override=True)
+
+# Caminhos automaticos (CWD e raiz do MCP)
+_caminhos_env = [
+    _RAIZ_MCP / ".env",          # menor prioridade (fallback)
+    Path.cwd() / ".." / ".env",  # prioridade media
+    Path.cwd() / ".env",         # maior prioridade (CWD)
+]
+for _caminho in _caminhos_env:
+    if _caminho.exists():
+        load_dotenv(_caminho, override=True)
+
+_CONNECTION_STRING = os.getenv("MSSQL_CONNECTION_STRING", "")
+_CONNECTION = None
+
+
+def get_connection_string() -> str:
+    if not _CONNECTION_STRING:
+        raise ValueError(
+            "MSSQL_CONNECTION_STRING nao definida. "
+            "Configure a variavel de ambiente ou crie um arquivo .env "
+            "baseado no .env.example."
+        )
+    return _CONNECTION_STRING
+
+
+def connection_string_configurada() -> bool:
+    """Indica se a string de conexao esta configurada, sem levantar excecao."""
+    return bool(_CONNECTION_STRING)
+
+
+_PADROES_ERRO_DRIVER = [
+    "can't open lib",
+    "file not found",
+    "data source name not found",
+    "no default driver",
+    "im002",
+    "sqlallochandle",
+]
+
+
+def _eh_erro_driver_odbc(mensagem: str) -> bool:
+    m = mensagem.lower()
+    return any(padrao in m for padrao in _PADROES_ERRO_DRIVER)
+
+
+def conectar_pyodbc(conn_str: str, timeout: int = None):
+    """Abre uma conexao pyodbc, traduzindo erro de driver ODBC ausente em
+    uma mensagem clara para o usuario/LLM."""
+    try:
+        if timeout is None:
+            return pyodbc.connect(conn_str)
+        return pyodbc.connect(conn_str, timeout=timeout)
+    except Exception as e:
+        if _eh_erro_driver_odbc(str(e)):
+            raise RuntimeError(
+                "DRIVER ODBC NAO ENCONTRADO: instale o 'ODBC Driver 18 for SQL Server' "
+                "e reinicie o servidor (macOS: brew install msodbcsql18). "
+                "Erro original: " + str(e)
+            ) from e
+        raise
+
+
+def get_connection():
+    global _CONNECTION
+    conn_str = get_connection_string()
+    if _CONNECTION is not None:
+        try:
+            cursor = _CONNECTION.cursor()
+            cursor.execute("SELECT 1")
+            cursor.close()
+            return _CONNECTION
+        except Exception:
+            try:
+                _CONNECTION.close()
+            except Exception:
+                pass
+            _CONNECTION = None
+    if _CONNECTION is None:
+        _CONNECTION = conectar_pyodbc(conn_str)
+        _CONNECTION.autocommit = False
+        cursor = _CONNECTION.cursor()
+        cursor.execute("SET XACT_ABORT ON")
+        cursor.close()
+    return _CONNECTION
+
+
+def close_connection():
+    global _CONNECTION
+    if _CONNECTION is not None:
+        _CONNECTION.close()
+        _CONNECTION = None
+
+
+_PERMISSAO_ESCRITA_CACHE = None
+
+
+def usuario_tem_permissao_escrita() -> bool:
+    """Detecta se o usuario da conexao tem permissao de escrita no SQL Server.
+
+    Verifica roles de escrita no nivel do servidor (sysadmin) e no banco
+    padrao da conexao (db_owner, db_datawriter, db_ddladmin).
+
+    Fail-safe: se a deteccao falhar por qualquer motivo (banco inacessivel,
+    timeout, sem permissao ate para consultar roles), assume somente leitura
+    (retorna False), nunca expondo ferramentas de escrita por engano.
+
+    O resultado e cacheado na primeira chamada.
+    """
+    global _PERMISSAO_ESCRITA_CACHE
+    if _PERMISSAO_ESCRITA_CACHE is not None:
+        return _PERMISSAO_ESCRITA_CACHE
+
+    _PERMISSAO_ESCRITA_CACHE = False
+    try:
+        conn = get_connection()
+        cursor = conn.cursor()
+        try:
+            cursor.execute(
+                "SELECT "
+                "CAST(IS_SRVROLEMEMBER('sysadmin') AS BIT), "
+                "CAST(IS_MEMBER('db_owner') AS BIT), "
+                "CAST(IS_MEMBER('db_datawriter') AS BIT), "
+                "CAST(IS_MEMBER('db_ddladmin') AS BIT)"
+            )
+            row = cursor.fetchone()
+            if row:
+                _PERMISSAO_ESCRITA_CACHE = any(bool(v) for v in row)
+        finally:
+            cursor.close()
+    except Exception:
+        _PERMISSAO_ESCRITA_CACHE = False
+
+    return _PERMISSAO_ESCRITA_CACHE

mcp_sqlserver/server.py

@@ -0,0 +1,462 @@
+import sys
+import logging
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import Tool
+
+from . import tools
+from .connection import (
+    close_connection,
+    connection_string_configurada,
+    usuario_tem_permissao_escrita,
+)
+
+logging.basicConfig(level=logging.INFO, stream=sys.stderr)
+logger = logging.getLogger("mcp-sqlserver")
+
+servidor = Server("mcp-sqlserver")
+
+_NOMES_FERRAMENTAS_ESCRITA = {
+    "executar_procedure",
+    "executar_update",
+    "criar_indice",
+    "alterar_procedure",
+    "executar_ddl",
+}
+
+
+@servidor.list_tools()
+async def listar_ferramentas():
+    ferramentas = [
+        Tool(
+            name="consulta",
+            description="Executa uma consulta SELECT (somente leitura) no SQL Server. "
+                        "Use notacao de tres niveis para acessar outros bancos: "
+                        "banco.esquema.tabela. "
+                        "Operacoes DDL/DML (INSERT, UPDATE, DELETE, DROP, etc.) sao bloqueadas.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "sql": {
+                        "type": "string",
+                        "description": "Query SQL do tipo SELECT.",
+                    },
+                    "timeout_segundos": {
+                        "type": "integer",
+                        "description": "Tempo maximo de execucao em segundos (default: 120).",
+                        "default": 120,
+                    },
+                },
+                "required": ["sql"],
+            },
+        ),
+        Tool(
+            name="listar_bancos",
+            description="Lista todos os bancos de dados acessiveis no servidor.",
+            inputSchema={
+                "type": "object",
+                "properties": {},
+            },
+        ),
+        Tool(
+            name="listar_tabelas",
+            description="Lista todas as tabelas e views de um banco de dados.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "banco": {
+                        "type": "string",
+                        "description": "Nome do banco de dados (opcional). "
+                                       "Se nao informado, usa o banco padrao da conexao.",
+                        "default": "",
+                    },
+                },
+            },
+        ),
+        Tool(
+            name="descrever_tabela",
+            description="Descreve a estrutura de uma tabela: colunas, tipos, "
+                        "nulabilidade e chave primaria.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "tabela": {
+                        "type": "string",
+                        "description": "Nome da tabela. Use 'schema.nome' ou apenas 'nome' (default: dbo).",
+                    },
+                    "banco": {
+                        "type": "string",
+                        "description": "Nome do banco de dados (opcional).",
+                        "default": "",
+                    },
+                },
+                "required": ["tabela"],
+            },
+        ),
+        Tool(
+            name="listar_indices",
+            description="Lista todos os indices de uma tabela especifica.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "tabela": {
+                        "type": "string",
+                        "description": "Nome da tabela. Use 'schema.nome' ou apenas 'nome'.",
+                    },
+                    "banco": {
+                        "type": "string",
+                        "description": "Nome do banco de dados (opcional).",
+                        "default": "",
+                    },
+                },
+                "required": ["tabela"],
+            },
+        ),
+        Tool(
+            name="listar_procedures",
+            description="Lista todas as stored procedures de um banco de dados.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "banco": {
+                        "type": "string",
+                        "description": "Nome do banco de dados (opcional).",
+                        "default": "",
+                    },
+                },
+            },
+        ),
+        Tool(
+            name="ler_procedure",
+            description="Retorna o codigo-fonte completo de uma stored procedure.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "nome": {
+                        "type": "string",
+                        "description": "Nome da procedure. Use 'schema.nome' ou apenas 'nome'.",
+                    },
+                    "banco": {
+                        "type": "string",
+                        "description": "Nome do banco de dados (opcional).",
+                        "default": "",
+                    },
+                },
+                "required": ["nome"],
+            },
+        ),
+        Tool(
+            name="plano_execucao",
+            description="Exibe o plano de execucao estimado para uma query, sem executa-la. "
+                        "Util para analisar performance.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "sql": {
+                        "type": "string",
+                        "description": "Query SQL para analisar o plano de execucao.",
+                    },
+                },
+                "required": ["sql"],
+            },
+        ),
+        Tool(
+            name="listar_constraints",
+            description="Lista todas as constraints de uma tabela (PK, FK, UNIQUE, CHECK, DEFAULT).",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "tabela": {
+                        "type": "string",
+                        "description": "Nome da tabela. Use 'schema.nome' ou apenas 'nome'.",
+                    },
+                    "banco": {
+                        "type": "string",
+                        "description": "Nome do banco de dados (opcional).",
+                        "default": "",
+                    },
+                },
+                "required": ["tabela"],
+            },
+        ),
+        Tool(
+            name="estatisticas_tabela",
+            description="Exibe estatisticas de uma tabela: numero estimado de linhas, "
+                        "tamanho em disco e uso de dados.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "tabela": {
+                        "type": "string",
+                        "description": "Nome da tabela. Use 'schema.nome' ou apenas 'nome'.",
+                    },
+                    "banco": {
+                        "type": "string",
+                        "description": "Nome do banco de dados (opcional).",
+                        "default": "",
+                    },
+                },
+                "required": ["tabela"],
+            },
+        ),
+        Tool(
+            name="listar_funcoes",
+            description="Lista todas as funcoes (scalar e table-valued) de um banco de dados.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "banco": {
+                        "type": "string",
+                        "description": "Nome do banco de dados (opcional).",
+                        "default": "",
+                    },
+                },
+            },
+        ),
+        Tool(
+            name="ler_funcao",
+            description="Retorna o codigo-fonte completo de uma funcao.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "nome": {
+                        "type": "string",
+                        "description": "Nome da funcao. Use 'schema.nome' ou apenas 'nome'.",
+                    },
+                    "banco": {
+                        "type": "string",
+                        "description": "Nome do banco de dados (opcional).",
+                        "default": "",
+                    },
+                },
+                "required": ["nome"],
+            },
+        ),
+        Tool(
+            name="status_jobs",
+            description="Retorna o status da ultima execucao de jobs do SQL Server Agent. "
+                        "Recebe uma lista de nomes de jobs separados por virgula e retorna "
+                        "inicio, fim, duracao, resultado e mensagem de cada job.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "nomes": {
+                        "type": "string",
+                        "description": "Nomes dos jobs separados por virgula. "
+                                       "Exemplo: 'Job A, Job B, Job C'",
+                    },
+                },
+                "required": ["nomes"],
+            },
+        ),
+    ]
+
+    if usuario_tem_permissao_escrita():
+        ferramentas.extend([
+            Tool(
+                name="executar_procedure",
+                description="Executa uma stored procedure. "
+                            "ATENCAO: o usuario DEVE ser questionado e confirmar antes de cada execucao. "
+                            "Nunca execute procedures sem permissao explicita.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "nome": {
+                            "type": "string",
+                            "description": "Nome da procedure. Use 'schema.nome' ou apenas 'nome'.",
+                        },
+                        "banco": {
+                            "type": "string",
+                            "description": "Nome do banco de dados (opcional).",
+                            "default": "",
+                        },
+                        "parametros": {
+                            "type": "string",
+                            "description": "Parametros no formato SQL: 'valor1, valor2, @param=valor'.",
+                            "default": "",
+                        },
+                        "timeout_segundos": {
+                            "type": "integer",
+                            "description": "Tempo maximo de execucao em segundos (default: 120).",
+                            "default": 120,
+                        },
+                    },
+                    "required": ["nome"],
+                },
+            ),
+            Tool(
+                name="executar_update",
+                description="Executa um comando UPDATE no SQL Server. "
+                            "ATENCAO: o usuario DEVE ser questionado e confirmar antes de cada execucao. "
+                            "Nunca execute updates sem permissao explicita. "
+                            "A clausula WHERE e obrigatoria para evitar alteracoes em massa.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "sql": {
+                            "type": "string",
+                            "description": "Comando SQL UPDATE completo. Deve incluir clausula WHERE.",
+                        },
+                    },
+                    "required": ["sql"],
+                },
+            ),
+            Tool(
+                name="criar_indice",
+                description="Executa um comando CREATE INDEX no SQL Server. "
+                            "ATENCAO: o usuario DEVE ser questionado e confirmar antes de cada execucao. "
+                            "Nunca crie indices sem permissao explicita. "
+                            "DML e DDL destrutivo (INSERT, UPDATE, DELETE, DROP, ALTER, etc.) sao bloqueados.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "comando": {
+                            "type": "string",
+                            "description": "Comando SQL CREATE INDEX completo.",
+                        },
+                        "banco": {
+                            "type": "string",
+                            "description": "Nome do banco de dados onde criar o indice (opcional).",
+                            "default": "",
+                        },
+                    },
+                    "required": ["comando"],
+                },
+            ),
+            Tool(
+                name="alterar_procedure",
+                description="Altera uma stored procedure com backup previo do codigo original. "
+                            "ATENCAO: o usuario DEVE ser questionado e confirmar antes de cada execucao. "
+                            "Nunca altere procedures sem permissao explicita. "
+                            "Fluxo: 1) le o codigo atual, 2) salva backup no arquivo indicado, "
+                            "3) verifica o backup, 4) executa o ALTER PROCEDURE.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "nome": {
+                            "type": "string",
+                            "description": "Nome da procedure. Use 'schema.nome' ou apenas 'nome'.",
+                        },
+                        "script": {
+                            "type": "string",
+                            "description": "Script ALTER PROCEDURE completo.",
+                        },
+                        "backup_arquivo": {
+                            "type": "string",
+                            "description": "Caminho absoluto do arquivo onde sera salvo o backup do codigo original.",
+                        },
+                        "banco": {
+                            "type": "string",
+                            "description": "Nome do banco de dados (opcional).",
+                            "default": "",
+                        },
+                    },
+                    "required": ["nome", "script", "backup_arquivo"],
+                },
+            ),
+            Tool(
+                name="executar_ddl",
+                description="Executa um comando DDL (ALTER TABLE, ALTER VIEW, DROP, CREATE, "
+                            "sp_update_jobstep, etc.) com backup obrigatorio do script de reversao. "
+                            "ATENCAO: o usuario DEVE ser questionado e confirmar antes de cada execucao. "
+                            "Nunca execute DDL sem permissao explicita. "
+                            "O chamador e responsavel por montar o script de reversao adequado.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "sql": {
+                            "type": "string",
+                            "description": "Comando SQL DDL completo (ALTER TABLE, ALTER VIEW, DROP, CREATE, etc.).",
+                        },
+                        "backup_arquivo": {
+                            "type": "string",
+                            "description": "Caminho absoluto do arquivo onde sera salvo o script de reversao.",
+                        },
+                        "banco": {
+                            "type": "string",
+                            "description": "Nome do banco de dados (opcional).",
+                            "default": "",
+                        },
+                        "timeout_segundos": {
+                            "type": "integer",
+                            "description": "Tempo maximo de execucao em segundos (default: 600).",
+                            "default": 600,
+                        },
+                    },
+                    "required": ["sql", "backup_arquivo"],
+                },
+            ),
+        ])
+
+    return ferramentas
+
+
+@servidor.call_tool()
+async def chamar_ferramenta(name: str, arguments: dict):
+    logger.info(f"Ferramenta chamada: {name} com argumentos: {arguments}")
+
+    if name in _NOMES_FERRAMENTAS_ESCRITA and not usuario_tem_permissao_escrita():
+        return [{
+            "type": "text",
+            "text": "OPERACAO BLOQUEADA: O usuario da conexao nao possui permissao de escrita no SQL Server.",
+        }]
+
+    mapeamento = {
+        "consulta": tools.consulta,
+        "listar_bancos": tools.listar_bancos,
+        "listar_tabelas": tools.listar_tabelas,
+        "descrever_tabela": tools.descrever_tabela,
+        "listar_indices": tools.listar_indices,
+        "listar_procedures": tools.listar_procedures,
+        "ler_procedure": tools.ler_procedure,
+        "executar_procedure": tools.executar_procedure,
+        "plano_execucao": tools.plano_execucao,
+        "listar_constraints": tools.listar_constraints,
+        "estatisticas_tabela": tools.estatisticas_tabela,
+        "listar_funcoes": tools.listar_funcoes,
+        "ler_funcao": tools.ler_funcao,
+        "status_jobs": tools.status_jobs,
+        "executar_update": tools.executar_update,
+        "alterar_procedure": tools.alterar_procedure,
+        "criar_indice": tools.criar_indice,
+        "executar_ddl": tools.executar_ddl,
+    }
+
+    func = mapeamento.get(name)
+    if func is None:
+        return [{"type": "text", "text": f"Ferramenta desconhecida: {name}"}]
+
+    if not connection_string_configurada():
+        return [{
+            "type": "text",
+            "text": (
+                "CONEXAO NAO CONFIGURADA: Defina a variavel de ambiente "
+                "MSSQL_CONNECTION_STRING (ou MSSQL_ENV_FILE apontando para um "
+                ".env) no ambiente do servidor antes de usar as ferramentas."
+            ),
+        }]
+
+    try:
+        resultado = func(**arguments)
+    except Exception as e:
+        resultado = f"ERRO: {str(e)}"
+    return [{"type": "text", "text": resultado}]
+
+
+async def executar():
+    async with stdio_server() as (read_stream, write_stream):
+        await servidor.run(read_stream, write_stream, servidor.create_initialization_options())
+
+
+def main():
+    import asyncio
+    try:
+        asyncio.run(executar())
+    except KeyboardInterrupt:
+        pass
+    finally:
+        close_connection()
+
+
+if __name__ == "__main__":
+    main()