text2sql-mcp 0.1.0__tar.gz

text2sql_mcp-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+
+# Tooling
+.python-version
+.pytest_cache/
+.ruff_cache/
+
+# OS / editors
+.DS_Store
+.idea/
+.vscode/
+
+# Local-only files
+HANDOFF.md

text2sql_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cooper Penniman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

text2sql_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: text2sql-mcp
+Version: 0.1.0
+Summary: MCP server for text2sql-framework. Lets any MCP-compatible assistant (Claude Desktop, Cursor, Goose, etc.) ask a SQL database questions in natural language.
+Project-URL: Homepage, https://github.com/cpenniman12/text2sql-mcp
+Project-URL: Repository, https://github.com/cpenniman12/text2sql-mcp
+Project-URL: Bug Tracker, https://github.com/cpenniman12/text2sql-mcp/issues
+Project-URL: text2sql-framework, https://github.com/cpenniman12/text2sql-framework
+Author: Cooper Penniman
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,claude,database,goose,llm,mcp,natural-language,sql,text-to-sql
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: langchain-anthropic>=0.3
+Requires-Dist: mcp>=1.0
+Requires-Dist: text2sql-framework>=0.3
+Provides-Extra: openai
+Requires-Dist: langchain-openai>=0.3; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# text2sql-mcp
+
+MCP server for [text2sql-framework](https://github.com/cpenniman12/text2sql-framework). Plugs into Claude Desktop, Cursor, Goose, or any other MCP-compatible assistant and lets it ask a SQL database questions in natural language.
+
+The agent explores the schema, writes SQL, executes it against the real DB, and self-corrects on errors — no RAG layer, no schema descriptions, no pre-computed embeddings.
+
+## Install
+
+```bash
+pip install text2sql-mcp
+# or
+uvx text2sql-mcp
+```
+
+## Configure
+
+Set environment variables in your MCP client config:
+
+| Variable | Required | Description |
+| --- | --- | --- |
+| `TEXT2SQL_DATABASE_URL` | yes | SQLAlchemy URL, e.g. `sqlite:///mydb.db`, `postgresql://user:pass@host/db` |
+| `ANTHROPIC_API_KEY` *or* `OPENAI_API_KEY` | yes | LLM provider key |
+| `TEXT2SQL_MODEL` | no | LangChain model id (default: `anthropic:claude-sonnet-4-6`) |
+| `TEXT2SQL_INSTRUCTIONS` | no | Business rules / hints, e.g. "Revenue = net of refunds." |
+| `TEXT2SQL_EXAMPLES` | no | Path to a scenarios.md file for the agent's `lookup_example` tool |
+
+### Claude Desktop / Cursor / generic MCP
+
+```json
+{
+  "mcpServers": {
+    "text2sql": {
+      "command": "uvx",
+      "args": ["text2sql-mcp"],
+      "env": {
+        "TEXT2SQL_DATABASE_URL": "sqlite:///mydb.db",
+        "ANTHROPIC_API_KEY": "sk-ant-..."
+      }
+    }
+  }
+}
+```
+
+### Goose CLI
+
+```bash
+goose configure
+# Add Extension → Command-line Extension
+# Name: text2sql
+# Command: uvx text2sql-mcp
+# Env: TEXT2SQL_DATABASE_URL, ANTHROPIC_API_KEY
+```
+
+## Tools
+
+- **`query(question, max_rows=100)`** — ask the database a natural-language question. Returns `{sql, data, error, row_count, tool_calls_made}`.
+
+## How it works
+
+Under the hood this is a thin wrapper around [text2sql-framework](https://github.com/cpenniman12/text2sql-framework), which uses LangChain Deep Agents to do iterative tool-calling against a single `execute_sql` tool. See the framework README for benchmarks (19/20 on Spider zero-shot across 80 tables) and architecture details.
+
+## License
+
+MIT

text2sql_mcp-0.1.0/README.md

@@ -0,0 +1,64 @@
+# text2sql-mcp
+
+MCP server for [text2sql-framework](https://github.com/cpenniman12/text2sql-framework). Plugs into Claude Desktop, Cursor, Goose, or any other MCP-compatible assistant and lets it ask a SQL database questions in natural language.
+
+The agent explores the schema, writes SQL, executes it against the real DB, and self-corrects on errors — no RAG layer, no schema descriptions, no pre-computed embeddings.
+
+## Install
+
+```bash
+pip install text2sql-mcp
+# or
+uvx text2sql-mcp
+```
+
+## Configure
+
+Set environment variables in your MCP client config:
+
+| Variable | Required | Description |
+| --- | --- | --- |
+| `TEXT2SQL_DATABASE_URL` | yes | SQLAlchemy URL, e.g. `sqlite:///mydb.db`, `postgresql://user:pass@host/db` |
+| `ANTHROPIC_API_KEY` *or* `OPENAI_API_KEY` | yes | LLM provider key |
+| `TEXT2SQL_MODEL` | no | LangChain model id (default: `anthropic:claude-sonnet-4-6`) |
+| `TEXT2SQL_INSTRUCTIONS` | no | Business rules / hints, e.g. "Revenue = net of refunds." |
+| `TEXT2SQL_EXAMPLES` | no | Path to a scenarios.md file for the agent's `lookup_example` tool |
+
+### Claude Desktop / Cursor / generic MCP
+
+```json
+{
+  "mcpServers": {
+    "text2sql": {
+      "command": "uvx",
+      "args": ["text2sql-mcp"],
+      "env": {
+        "TEXT2SQL_DATABASE_URL": "sqlite:///mydb.db",
+        "ANTHROPIC_API_KEY": "sk-ant-..."
+      }
+    }
+  }
+}
+```
+
+### Goose CLI
+
+```bash
+goose configure
+# Add Extension → Command-line Extension
+# Name: text2sql
+# Command: uvx text2sql-mcp
+# Env: TEXT2SQL_DATABASE_URL, ANTHROPIC_API_KEY
+```
+
+## Tools
+
+- **`query(question, max_rows=100)`** — ask the database a natural-language question. Returns `{sql, data, error, row_count, tool_calls_made}`.
+
+## How it works
+
+Under the hood this is a thin wrapper around [text2sql-framework](https://github.com/cpenniman12/text2sql-framework), which uses LangChain Deep Agents to do iterative tool-calling against a single `execute_sql` tool. See the framework README for benchmarks (19/20 on Spider zero-shot across 80 tables) and architecture details.
+
+## License
+
+MIT

text2sql_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "text2sql-mcp"
+version = "0.1.0"
+description = "MCP server for text2sql-framework. Lets any MCP-compatible assistant (Claude Desktop, Cursor, Goose, etc.) ask a SQL database questions in natural language."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Cooper Penniman" },
+]
+keywords = ["mcp", "sql", "llm", "text-to-sql", "ai", "database", "natural-language", "goose", "claude"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "mcp>=1.0",
+    "text2sql-framework>=0.3",
+    "langchain-anthropic>=0.3",
+]
+
+[project.optional-dependencies]
+openai = ["langchain-openai>=0.3"]
+
+[project.scripts]
+text2sql-mcp = "text2sql_mcp.server:main"
+
+[project.urls]
+Homepage = "https://github.com/cpenniman12/text2sql-mcp"
+Repository = "https://github.com/cpenniman12/text2sql-mcp"
+"Bug Tracker" = "https://github.com/cpenniman12/text2sql-mcp/issues"
+"text2sql-framework" = "https://github.com/cpenniman12/text2sql-framework"
+
+[tool.hatch.build.targets.wheel]
+packages = ["text2sql_mcp"]

text2sql_mcp-0.1.0/text2sql_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""MCP server for text2sql-framework."""
+
+__version__ = "0.1.0"

text2sql_mcp-0.1.0/text2sql_mcp/server.py

@@ -0,0 +1,94 @@
+"""MCP server exposing text2sql-framework as a single `query` tool.
+
+Configuration is read from environment variables:
+  TEXT2SQL_DATABASE_URL  (required)  SQLAlchemy URL, e.g. sqlite:///mydb.db
+  TEXT2SQL_MODEL         (optional)  LangChain model id (default: anthropic:claude-sonnet-4-6)
+  TEXT2SQL_INSTRUCTIONS  (optional)  Free-text business rules / hints
+  TEXT2SQL_EXAMPLES      (optional)  Path to a scenarios.md file
+
+Plus the usual provider key — ANTHROPIC_API_KEY or OPENAI_API_KEY —
+which text2sql-framework reads via LangChain.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+_engine = None
+
+
+def _get_engine():
+    """Lazily build the TextSQL engine on first use."""
+    global _engine
+    if _engine is not None:
+        return _engine
+
+    db_url = os.environ.get("TEXT2SQL_DATABASE_URL")
+    if not db_url:
+        raise RuntimeError(
+            "TEXT2SQL_DATABASE_URL is not set. "
+            "Provide a SQLAlchemy connection string, e.g. sqlite:///mydb.db"
+        )
+
+    from text2sql import TextSQL
+
+    kwargs: dict[str, Any] = {}
+    if model := os.environ.get("TEXT2SQL_MODEL"):
+        kwargs["model"] = model
+    if instructions := os.environ.get("TEXT2SQL_INSTRUCTIONS"):
+        kwargs["instructions"] = instructions
+    if examples := os.environ.get("TEXT2SQL_EXAMPLES"):
+        kwargs["examples"] = examples
+
+    _engine = TextSQL(db_url, **kwargs)
+    return _engine
+
+
+mcp = FastMCP("text2sql")
+
+
+@mcp.tool()
+def query(question: str, max_rows: int = 100) -> dict:
+    """Ask the database a natural-language question.
+
+    The agent explores the schema, writes SQL, executes it, and self-corrects
+    on errors before returning. Read-only — only SELECT-style statements.
+
+    Args:
+        question: The natural-language question, e.g. "top 5 customers by revenue".
+        max_rows: Cap on rows returned in `data`. Defaults to 100.
+
+    Returns:
+        dict with:
+          sql:    the final verified SQL
+          data:   list of row dicts (capped at max_rows)
+          error:  error message if execution failed, else None
+          row_count:        number of rows in `data`
+          tool_calls_made:  how many SQL calls the agent made while exploring
+    """
+    engine = _get_engine()
+    result = engine.ask(question, max_rows=max_rows)
+    return {
+        "sql": result.sql,
+        "data": result.data,
+        "error": result.error,
+        "row_count": len(result.data),
+        "tool_calls_made": result.tool_calls_made,
+    }
+
+
+def main() -> None:
+    """Entry point for the `text2sql-mcp` console script."""
+    try:
+        mcp.run()
+    except Exception as exc:
+        print(f"text2sql-mcp failed: {exc}", file=sys.stderr)
+        raise
+
+
+if __name__ == "__main__":
+    main()