jmd-mcp-sql 0.4__py3-none-any.whl

jmd_mcp_sql/__init__.py

@@ -0,0 +1,4 @@
+"""JMD MCP server for SQLite."""
+from .server import main
+
+__all__ = ["main"]

jmd_mcp_sql/schema.py

@@ -0,0 +1,125 @@
+"""SQLite schema introspection — table and column metadata.
+
+This module is intentionally kept separate from the SQL-translation layer
+so that schema changes (e.g. tables created at runtime) can be picked up
+by constructing a fresh SchemaInspector without touching translation logic.
+"""
+from __future__ import annotations
+
+import sqlite3
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ColumnInfo:
+    """Metadata for a single column in a SQLite table or view."""
+
+    name: str
+    type: str          # SQLite declared type, e.g. "TEXT", "INTEGER", "REAL"
+    primary_key: bool
+    nullable: bool     # True when the column has no NOT NULL constraint
+
+
+@dataclass
+class TableInfo:
+    """Metadata for a single table or view."""
+
+    name: str
+    is_view: bool = False
+    columns: list[ColumnInfo] = field(default_factory=list)
+
+    @property
+    def primary_keys(self) -> list[str]:
+        """Return the names of all primary-key columns."""
+        return [c.name for c in self.columns if c.primary_key]
+
+
+class SchemaInspector:
+    """Lazily loads and caches the database schema.
+
+    The cache is invalidated (replaced) whenever the server modifies the
+    schema (CREATE TABLE, ALTER TABLE, DROP TABLE).  Pass a fresh
+    SchemaInspector instance to SQLTranslator after any DDL operation.
+    """
+
+    def __init__(self, conn: sqlite3.Connection) -> None:
+        """Store the connection and initialise the lazy cache."""
+        self._conn = conn
+        # None means "not yet loaded"; an empty dict means "loaded, no tables".
+        self._cache: dict[str, TableInfo] | None = None
+
+    def tables(self) -> dict[str, TableInfo]:
+        """Return all user tables and views, keyed by exact name."""
+        if self._cache is None:
+            self._cache = self._load()
+        return self._cache
+
+    def resolve(self, label: str) -> TableInfo | None:
+        """Map a JMD document label to a table, case-insensitively.
+
+        JMD labels are written by an LLM which may use any capitalisation
+        or pluralisation.  This method tries several candidate spellings so
+        that ``# Order``, ``# Orders``, and ``# orders`` all resolve to the
+        same underlying table.
+
+        Args:
+            label: The heading label from the JMD document, e.g. ``"Order"``.
+
+        Returns:
+            The matching TableInfo, or None if no table matches.
+        """
+        tables = self.tables()
+
+        # Build candidate spellings: original, lower-case, with/without a
+        # trailing "s".  This covers the most common singular/plural mismatch
+        # between LLM-generated labels and actual table names.
+        stripped = (
+            label[:-1] if label.endswith("s") and len(label) > 1 else None
+        )
+        stripped_lower = (
+            label.lower()[:-1]
+            if label.lower().endswith("s") and len(label) > 1
+            else None
+        )
+        candidates = [
+            label,
+            label.lower(),
+            label + "s",
+            label.lower() + "s",
+            *(([stripped, stripped_lower]) if stripped else []),
+        ]
+        for name in candidates:
+            if name in tables:
+                return tables[name]
+        return None
+
+    def _load(self) -> dict[str, TableInfo]:
+        """Query sqlite_master and PRAGMA table_info for every object."""
+        cur = self._conn.cursor()
+
+        # Fetch all user-defined tables and views; skip SQLite internals.
+        cur.execute("""
+            SELECT name, type FROM sqlite_master
+            WHERE type IN ('table', 'view') AND name NOT LIKE 'sqlite_%'
+            ORDER BY name
+        """)
+        result = {}
+        for (table_name, obj_type) in cur.fetchall():
+            # PRAGMA table_info returns one row per column:
+            # (cid, name, type, notnull, dflt_value, pk)
+            cur.execute(f'PRAGMA table_info("{table_name}")')
+            columns = [
+                ColumnInfo(
+                    name=row[1],
+                    type=row[2],
+                    primary_key=bool(row[5]),  # pk > 0 means part of PK
+                    nullable=not row[3],        # notnull=1 → not nullable
+                )
+                for row in cur.fetchall()
+            ]
+            result[table_name] = TableInfo(
+                name=table_name,
+                is_view=(obj_type == "view"),
+                columns=columns,
+            )
+        return result

jmd_mcp_sql/server.py

@@ -0,0 +1,355 @@
+"""JMD MCP server for SQLite.
+
+This module wires together the MCP framework (FastMCP), the SQL translator,
+and the database connection.  It exposes three tools that an LLM can call:
+
+    read   — query records, filter with QBE, or describe table schemas
+    write  — insert/replace records or create/extend tables
+    delete — remove records or drop tables
+
+The server can be started against any SQLite database file by passing its
+path as a command-line argument.  When no argument is given, it uses the
+bundled Northwind demo database, creating it automatically from the SQL
+dump (``northwind.sql``) on the first run.
+
+Usage::
+
+    # Against a custom database
+    python -m jmd_mcp_sql.server /path/to/mydb.db
+
+    # Against the Northwind demo
+    python -m jmd_mcp_sql.server
+"""
+from __future__ import annotations
+
+import argparse
+import sqlite3
+from pathlib import Path
+
+from jmd import serialize
+from mcp.server.fastmcp import FastMCP
+
+from .translator import SQLTranslator
+
+_INSTRUCTIONS = """
+This server exposes a SQLite database through three tools —
+read, write, delete — using JMD (JSON Markdown) as the data format.
+
+## JMD document syntax
+
+Every document starts with a heading line that sets the document type
+and table name, followed by key: value pairs (one per line):
+
+  # Product          → data document   (exact lookup / insert-or-replace)
+  #? Product         → query document  (filter / list)
+  #! Product         → schema document (describe / create / drop table)
+  #- Product         → delete document (delete matching records)
+
+  key: value         → string, integer, or float — inferred automatically
+  key: true/false    → boolean
+
+## Discovering the database
+
+To see which tables exist, read each table's schema:
+
+  read("#! Customers")
+
+This returns a #! document with column names, JMD types, and modifiers
+(readonly = primary key, optional = nullable).
+
+## Typical workflows
+
+**List all rows (small tables only):**
+  read("#? Orders")
+
+**Filter rows — equality:**
+  read("#? Orders\nstatus: shipped")
+
+**Filter rows — comparison:**
+  read("#? Orders\nFreight: > 50")
+
+**Filter rows — alternation (OR):**
+  read("#? Orders\nShipCountry: Germany|France|UK")
+
+**Filter rows — contains (case-insensitive substring):**
+  read("#? Customers\nCompanyName: ~Corp")
+
+**Filter rows — regex pattern:**
+  read("#? Products\nProductName: ^Chai.*")
+
+**Filter rows — negation (composes with any operator):**
+  read("#? Orders\nShipCountry: !Germany")
+  read("#? Products\nProductName: !^LEGACY.*")
+
+**Look up one record:**
+  read("# Customers\nid: 42")
+
+**Insert or replace a record:**
+  write("# Orders\nid: 1\nstatus: pending\ntotal: 99.90")
+
+**Create a table:**
+  write("#! Products\nid: integer readonly\nname: string\n"
+        "price: float optional")
+
+**Delete a record:**
+  delete("#- Orders\nid: 1")
+
+**Drop a table:**
+  delete("#! OldTable")
+
+## Pagination
+
+IMPORTANT: Always use pagination when querying tables that may contain many
+rows. Without pagination, large result sets will exceed your context window.
+
+Use frontmatter fields before the #? heading to control pagination:
+
+  read("page-size: 50\npage: 1\n\n#? Orders")
+
+The response carries pagination metadata as frontmatter —
+before the root heading:
+
+  total: 830
+  page: 1
+  pages: 17
+  page-size: 50
+
+  # Orders
+  ## data[]
+  - OrderID: 10248
+    ...
+
+Use `total` and `pages` to determine whether to fetch more pages.
+
+**Count only** (no rows returned):
+  read("count: true\n\n#? Orders")
+
+Returns: `count: 830\n\n# Orders`
+
+**Rule of thumb:** Use `page-size: 50` for any table you haven't inspected before.
+For tables with fewer than ~20 rows (e.g. Categories, Shippers) pagination is
+optional.
+
+## Field projection
+
+Use `select:` frontmatter to return only specific columns — reduces response
+size and keeps context windows clean.
+
+  select: OrderID, EmployeeID
+
+  #? Orders
+
+Works with `#` (data) and `#?` (query) documents, including aggregation
+(where `select:` filters the result columns after the GROUP BY).
+
+## Joins
+
+Use `join:` frontmatter to query across multiple tables in one call.
+The value is `<TableName> on <JoinColumn>` (INNER JOIN, equi-join).
+
+  join: Order Details on OrderID
+  sum: UnitPrice * Quantity * (1 - Discount) as revenue
+  group: EmployeeID
+  sort: revenue desc
+
+  #? Orders
+
+Multiple joins: comma-separated in a single `join:` value.
+
+  join: Order Details on OrderID, Employees on EmployeeID
+
+**Expression syntax in aggregation with joins:**
+Use `<expression> as <alias>` to compute derived values:
+
+  sum: UnitPrice * Quantity * (1 - Discount) as revenue
+
+The alias becomes the result column name. Without `as`, the default alias
+`<func>_<field>` applies (e.g. `sum_Freight`).
+
+Only column names, numeric literals, and arithmetic operators
+(`+`, `-`, `*`, `/`) are allowed in expressions — no subqueries.
+
+## Aggregation
+
+Aggregation is expressed as frontmatter before the #? heading.
+QBE filter fields narrow rows *before* aggregation (SQL WHERE).
+The `having:` key filters *after* aggregation (SQL HAVING).
+
+| Key               | SQL           | Result column name                  |
+| group: f1, f2     | GROUP BY      | (grouping keys pass through)        |
+| sum: field        | SUM(field)    | sum_field                           |
+| avg: field        | AVG(field)    | avg_field                           |
+| min: field        | MIN(field)    | min_field                           |
+| max: field        | MAX(field)    | max_field                           |
+| count             | COUNT(*)      | count                               |
+
+Multiple fields per function: `sum: Freight, Total`
+→ `sum_Freight`, `sum_Total`.
+
+  sort: sum_revenue desc, EmployeeID asc    → ORDER BY (multiple columns, mixed)
+  having: count > 5                         → HAVING COUNT(*) > 5
+  having: sum_Freight > 1000, count > 2     → HAVING ... AND ... (comma = AND)
+
+`having:` supports: >, >=, <, <=, =
+`sort:` references any result column — grouping keys or aggregate aliases.
+`page-size:` and `page:` apply to the aggregated result set.
+
+**Example — top 3 employees by revenue:**
+  read("group: EmployeeID\nsum: revenue\nsort: sum_revenue desc\n"
+       "page-size: 3\n\n#? OrderDetails")
+
+## Error handling
+
+All tools return a `# Error` document on failure:
+
+  # Error
+  status: 400
+  code: not_found
+  message: No records found in Orders
+
+Check the `code` field to decide how to proceed.
+"""
+
+# Global FastMCP instance.  Tool functions are registered via @mcp.tool()
+# decorators below and become available to the MCP host on connection.
+mcp = FastMCP("jmd-mcp-sql", instructions=_INSTRUCTIONS)
+
+# Set by main() before mcp.run(); None while the module is imported without
+# a running server (e.g. during tests or type-checking).
+_translator: SQLTranslator | None = None
+
+
+def _t() -> SQLTranslator:
+    """Return the active SQLTranslator, raising if the server is not running."""
+    if _translator is None:
+        raise RuntimeError("Server not initialized — call main() first")
+    return _translator
+
+
+@mcp.tool()
+def read(document: str) -> str:
+    """Read records or table schema using a JMD document.
+
+    Data document (# Label): look up records by exact field values.
+    Returns a single record if exactly one matches, a list otherwise.
+
+        # Order
+        id: 42
+
+    Query-by-Example document (#? Label): filter records by field values.
+    Omitted fields match any value. Always returns a list.
+
+        #? Order
+        status: pending
+
+    Schema document (#! Label): describe the table structure.
+    Returns a #! document with column names, types, and modifiers.
+
+        #! Order
+    """
+    try:
+        return _t().read(document)
+    except Exception as e:
+        return serialize(
+            {"status": 400, "code": "read_failed", "message": str(e)},
+            label="Error",
+        )
+
+
+@mcp.tool()
+def write(document: str) -> str:
+    """Write a record or define a table schema using a JMD document.
+
+    Data document (# Label): insert or replace a record.
+    If a record with the same primary key exists, it is replaced.
+    Returns the written record as confirmed by the database.
+
+        # Order
+        id: 42
+        status: shipped
+        total: 149.99
+
+    Schema document (#! Label): create or extend a table.
+    If the table does not exist, it is created. If it exists, new
+    columns are added. Existing columns are never modified or removed.
+
+        #! Order
+        id: integer readonly
+        status: string
+        total: float optional
+    """
+    try:
+        return _t().write(document)
+    except Exception as e:
+        return serialize(
+            {"status": 400, "code": "write_failed", "message": str(e)},
+            label="Error",
+        )
+
+
+@mcp.tool()
+def delete(document: str) -> str:
+    """Delete records or drop a table using a JMD document.
+
+    Delete document (#- Label): delete matching records.
+    All fields act as filters. At least one field is required.
+    Returns the number of deleted records.
+
+        #- Order
+        id: 42
+
+    Schema document (#! Label): drop the entire table.
+
+        #! Order
+    """
+    try:
+        return _t().delete(document)
+    except Exception as e:
+        return serialize(
+            {"status": 400, "code": "delete_failed", "message": str(e)},
+            label="Error",
+        )
+
+
+def main() -> None:
+    """Entry point: parse arguments, open the database, and start the server."""
+    parser = argparse.ArgumentParser(description="JMD MCP server for SQLite")
+    parser.add_argument(
+        "db",
+        nargs="?",
+        default=None,
+        help="Path to SQLite database file (default: Northwind demo)",
+    )
+    args = parser.parse_args()
+
+    if args.db:
+        db_path = Path(args.db)
+        if not db_path.exists():
+            raise SystemExit(f"Database not found: {db_path}")
+    else:
+        db_path = Path(__file__).parent / "northwind.db"
+        if not db_path.exists():
+            # The demo database ships as a plain-text SQL dump.  Create the
+            # binary .db from it on first run and reuse it on subsequent runs.
+            sql_path = Path(__file__).parent / "northwind.sql"
+            if not sql_path.exists():
+                raise SystemExit(
+                    "Northwind demo database not found. "
+                    "northwind.sql is missing from the "
+                    "jmd_mcp_sql/ package directory."
+                )
+            conn = sqlite3.connect(str(db_path))
+            conn.executescript(sql_path.read_text(encoding="utf-8"))
+            conn.close()
+
+    global _translator
+    # check_same_thread=False is safe here because FastMCP processes one
+    # request at a time over stdio; there is no concurrent access.
+    conn = sqlite3.connect(str(db_path), check_same_thread=False)
+    _translator = SQLTranslator(conn)
+
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()