snowsyncmd-mcp 1.0.0__tar.gz

snowsyncmd_mcp-1.0.0/.gitignore

@@ -0,0 +1,19 @@
+# Credentials
+.env
+*.env
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+env/
+
+# Output
+output/md/
+
+# OS
+.DS_Store

snowsyncmd_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: snowsyncmd-mcp
+Version: 1.0.0
+Summary: MCP server for the SnowSyncMD Snowflake Native App — exposes schema docs as Claude tools
+Project-URL: Homepage, https://github.com/your-org/snowsyncmd
+Project-URL: PyPI, https://pypi.org/project/snowsyncmd-mcp
+License: MIT
+Keywords: claude,documentation,mcp,schema,snowflake
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: snowflake-connector-python>=3.0.0
+Description-Content-Type: text/markdown
+
+# SnowSyncMD MCP Server
+
+Connects Claude Code directly to your SnowSyncMD app so Claude can read
+Snowflake schema documentation automatically — no copy-pasting, no manual downloads.
+
+## How it works
+
+```
+You ask Claude: "Write a query joining ORDERS to CUSTOMERS"
+       ↓
+Claude calls MCP tool: snowflake_get_schema("MY_DB", "SALES", "ORDERS")
+Claude calls MCP tool: snowflake_get_schema("MY_DB", "SALES", "CUSTOMERS")
+       ↓
+Claude gets the column list from SnowSyncMD
+       ↓
+Claude writes the correct query with real column names
+```
+
+No live Snowflake queries. No manual schema exports. Claude reads the
+pre-built Markdown files that SnowSyncMD keeps up to date every 10 minutes.
+
+---
+
+## Installation
+
+```bash
+pip install mcp snowflake-connector-python python-dotenv
+```
+
+---
+
+## Configuration
+
+Add to your Claude Code settings (`~/.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "snowsyncmd": {
+      "command": "python3",
+      "args": ["/path/to/snowsyncmd_mcp.py"],
+      "env": {
+        "SNOWFLAKE_ACCOUNT":  "your-account-identifier",
+        "SNOWFLAKE_USER":     "your_username",
+        "SNOWFLAKE_PASSWORD": "your_password",
+        "SNOWFLAKE_ROLE":     "ACCOUNTADMIN",
+        "SNOWFLAKE_WAREHOUSE": "COMPUTE_WH",
+        "SNOWSYNCMD_APP":     "snowsyncmd"
+      }
+    }
+  }
+}
+```
+
+> **Tip:** Set credentials via a `.env` file in the same directory instead
+> of hardcoding them in settings.json.
+
+---
+
+## Available tools
+
+Claude sees these tools and calls them automatically:
+
+| Tool | What it does |
+|---|---|
+| `snowflake_get_schema` | Returns the full MD doc for one object (table, view, function…) |
+| `snowflake_search_schema` | Searches by keyword across all schema docs |
+| `snowflake_list_objects` | Lists every tracked object with DB/schema/type |
+| `snowflake_get_status` | Shows sync health, registered databases, last sync time |
+| `snowflake_sync` | Triggers an immediate sync (all DBs or one) |
+
+---
+
+## Example conversations
+
+```
+You:    "What columns does the FACT_ORDERS table have?"
+Claude: [calls snowflake_get_schema] → returns column list with types
+Claude: "FACT_ORDERS has 14 columns: ORDER_SK (NUMBER), ORDER_ID (NUMBER), ..."
+
+You:    "Write a query to show monthly revenue by channel"
+Claude: [calls snowflake_search_schema "revenue"] → finds FACT_ORDERS, V_DAILY_SALES
+Claude: [calls snowflake_get_schema for V_DAILY_SALES]
+Claude: "Here's a query using V_DAILY_SALES which already aggregates by channel: ..."
+
+You:    "Is the schema documentation up to date?"
+Claude: [calls snowflake_get_status]
+Claude: "Last synced 3 minutes ago. 180 objects tracked across 2 databases."
+
+You:    "I just added a new table — refresh the docs"
+Claude: [calls snowflake_sync]
+Claude: "Sync complete. 1 new object found and documented."
+```
+
+---
+
+## Using with Claude Code hooks (optional)
+
+Add a `UserPromptSubmit` hook to auto-check sync status before each session:
+
+`~/.claude/settings.json`:
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Bash",
+      "hooks": [{
+        "type": "command",
+        "command": "echo 'Snowflake schema docs available via snowsyncmd MCP tools'"
+      }]
+    }]
+  }
+}
+```
+
+---
+
+## Requirements
+
+- SnowSyncMD installed from Snowflake Marketplace
+- ACCOUNTADMIN or app_admin role on the SnowSyncMD app
+- Python 3.11+
+- `mcp`, `snowflake-connector-python`, `python-dotenv`

snowsyncmd_mcp-1.0.0/README.md

@@ -0,0 +1,123 @@
+# SnowSyncMD MCP Server
+
+Connects Claude Code directly to your SnowSyncMD app so Claude can read
+Snowflake schema documentation automatically — no copy-pasting, no manual downloads.
+
+## How it works
+
+```
+You ask Claude: "Write a query joining ORDERS to CUSTOMERS"
+       ↓
+Claude calls MCP tool: snowflake_get_schema("MY_DB", "SALES", "ORDERS")
+Claude calls MCP tool: snowflake_get_schema("MY_DB", "SALES", "CUSTOMERS")
+       ↓
+Claude gets the column list from SnowSyncMD
+       ↓
+Claude writes the correct query with real column names
+```
+
+No live Snowflake queries. No manual schema exports. Claude reads the
+pre-built Markdown files that SnowSyncMD keeps up to date every 10 minutes.
+
+---
+
+## Installation
+
+```bash
+pip install mcp snowflake-connector-python python-dotenv
+```
+
+---
+
+## Configuration
+
+Add to your Claude Code settings (`~/.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "snowsyncmd": {
+      "command": "python3",
+      "args": ["/path/to/snowsyncmd_mcp.py"],
+      "env": {
+        "SNOWFLAKE_ACCOUNT":  "your-account-identifier",
+        "SNOWFLAKE_USER":     "your_username",
+        "SNOWFLAKE_PASSWORD": "your_password",
+        "SNOWFLAKE_ROLE":     "ACCOUNTADMIN",
+        "SNOWFLAKE_WAREHOUSE": "COMPUTE_WH",
+        "SNOWSYNCMD_APP":     "snowsyncmd"
+      }
+    }
+  }
+}
+```
+
+> **Tip:** Set credentials via a `.env` file in the same directory instead
+> of hardcoding them in settings.json.
+
+---
+
+## Available tools
+
+Claude sees these tools and calls them automatically:
+
+| Tool | What it does |
+|---|---|
+| `snowflake_get_schema` | Returns the full MD doc for one object (table, view, function…) |
+| `snowflake_search_schema` | Searches by keyword across all schema docs |
+| `snowflake_list_objects` | Lists every tracked object with DB/schema/type |
+| `snowflake_get_status` | Shows sync health, registered databases, last sync time |
+| `snowflake_sync` | Triggers an immediate sync (all DBs or one) |
+
+---
+
+## Example conversations
+
+```
+You:    "What columns does the FACT_ORDERS table have?"
+Claude: [calls snowflake_get_schema] → returns column list with types
+Claude: "FACT_ORDERS has 14 columns: ORDER_SK (NUMBER), ORDER_ID (NUMBER), ..."
+
+You:    "Write a query to show monthly revenue by channel"
+Claude: [calls snowflake_search_schema "revenue"] → finds FACT_ORDERS, V_DAILY_SALES
+Claude: [calls snowflake_get_schema for V_DAILY_SALES]
+Claude: "Here's a query using V_DAILY_SALES which already aggregates by channel: ..."
+
+You:    "Is the schema documentation up to date?"
+Claude: [calls snowflake_get_status]
+Claude: "Last synced 3 minutes ago. 180 objects tracked across 2 databases."
+
+You:    "I just added a new table — refresh the docs"
+Claude: [calls snowflake_sync]
+Claude: "Sync complete. 1 new object found and documented."
+```
+
+---
+
+## Using with Claude Code hooks (optional)
+
+Add a `UserPromptSubmit` hook to auto-check sync status before each session:
+
+`~/.claude/settings.json`:
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Bash",
+      "hooks": [{
+        "type": "command",
+        "command": "echo 'Snowflake schema docs available via snowsyncmd MCP tools'"
+      }]
+    }]
+  }
+}
+```
+
+---
+
+## Requirements
+
+- SnowSyncMD installed from Snowflake Marketplace
+- ACCOUNTADMIN or app_admin role on the SnowSyncMD app
+- Python 3.11+
+- `mcp`, `snowflake-connector-python`, `python-dotenv`

snowsyncmd_mcp-1.0.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "snowsyncmd-mcp"
+version = "1.0.0"
+description = "MCP server for the SnowSyncMD Snowflake Native App — exposes schema docs as Claude tools"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+keywords = ["snowflake", "mcp", "claude", "schema", "documentation"]
+
+dependencies = [
+    "mcp>=1.0.0",
+    "snowflake-connector-python>=3.0.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.scripts]
+snowsyncmd-mcp = "snowsyncmd_mcp:main"
+
+[project.urls]
+Homepage   = "https://github.com/your-org/snowsyncmd"
+PyPI       = "https://pypi.org/project/snowsyncmd-mcp"
+
+[build-system]
+requires      = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["snowsyncmd_mcp"]

snowsyncmd_mcp-1.0.0/snowsyncmd_mcp/__init__.py

@@ -0,0 +1,13 @@
+"""snowsyncmd-mcp — MCP server for the SnowSyncMD Native App."""
+
+from .client import SnowSyncMDClient, SchemaObject, SyncStatus
+from .server import create_server, run
+import asyncio
+
+
+def main():
+    """Entry point for the `snowsyncmd-mcp` CLI command."""
+    asyncio.run(run())
+
+
+__all__ = ["SnowSyncMDClient", "SchemaObject", "SyncStatus", "create_server", "main"]

snowsyncmd_mcp-1.0.0/snowsyncmd_mcp/client.py

@@ -0,0 +1,238 @@
+"""
+client.py
+=========
+SnowSyncMDClient — thin wrapper around the Native App's stored procedures.
+
+This is the ONLY class that talks to Snowflake.
+The MCP server (server.py) uses this class exclusively.
+
+Usage:
+    client = SnowSyncMDClient.from_env()          # reads from environment
+    client = SnowSyncMDClient(                     # explicit
+        account="myaccount",
+        user="myuser",
+        password="mypassword",
+        app_name="snowsyncmd",
+    )
+
+    doc  = client.get_schema("MY_DB", "SALES", "ORDERS")
+    hits = client.search("customer")
+    objs = client.list_objects(database="MY_DB")
+    st   = client.get_status()
+    res  = client.sync(database="MY_DB")  # optional write
+"""
+
+import json
+import os
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class SchemaObject:
+    database:    str
+    schema:      str
+    object_name: str
+    object_type: str = ""
+    size_bytes:  int = 0
+
+    @property
+    def full_name(self) -> str:
+        return f"{self.database}.{self.schema}.{self.object_name}"
+
+
+@dataclass
+class SyncStatus:
+    task_state:           str
+    total_objects:        int
+    md_files_present:     int
+    dirty_count:          int
+    last_scan_at:         Optional[str]
+    databases:            list = field(default_factory=list)
+
+
+class SnowSyncMDClient:
+    """
+    Wraps all calls to the SnowSyncMD Native App stored procedures.
+
+    Responsibilities:
+    - Manage the Snowflake connection lifecycle
+    - Call api.* procedures and parse VARIANT responses
+    - Read MD files directly from @core.md_stage
+    - Provide typed return values (no raw SQL in server.py)
+    """
+
+    def __init__(
+        self,
+        account:   str,
+        user:      str,
+        password:  str,
+        app_name:  str  = "snowsyncmd",
+        role:      str  = "ACCOUNTADMIN",
+        warehouse: str  = "",
+    ):
+        self._conn_params = dict(
+            account=account, user=user, password=password,
+            role=role, warehouse=warehouse,
+        )
+        self.app = app_name
+
+    # ── constructor helpers ───────────────────────────────────────────────────
+
+    @classmethod
+    def from_env(cls) -> "SnowSyncMDClient":
+        """Build a client from standard environment variables."""
+        return cls(
+            account=os.environ["SNOWFLAKE_ACCOUNT"],
+            user=os.environ["SNOWFLAKE_USER"],
+            password=os.environ["SNOWFLAKE_PASSWORD"],
+            app_name=os.environ.get("SNOWSYNCMD_APP", "snowsyncmd"),
+            role=os.environ.get("SNOWFLAKE_ROLE", "ACCOUNTADMIN"),
+            warehouse=os.environ.get("SNOWFLAKE_WAREHOUSE", ""),
+        )
+
+    def _connect(self):
+        import snowflake.connector
+        return snowflake.connector.connect(**self._conn_params)
+
+    # ── internal helpers ──────────────────────────────────────────────────────
+
+    def _call(self, proc: str, *args) -> dict | list:
+        """Call a stored procedure and return the parsed JSON response."""
+        conn = self._connect()
+        try:
+            cur = conn.cursor()
+            escaped = ", ".join(
+                "NULL" if a is None else f"'{str(a).replace(chr(39), chr(39)*2)}'"
+                for a in args
+            )
+            cur.execute(f"CALL {self.app}.api.{proc}({escaped})")
+            row = cur.fetchone()
+            if not row:
+                return {}
+            val = row[0]
+            if isinstance(val, str):
+                try:
+                    return json.loads(val)
+                except Exception:
+                    return {"raw": val}
+            return val or {}
+        finally:
+            conn.close()
+
+    def _call_varchar(self, proc: str, *args) -> str | None:
+        """Call a stored procedure that returns VARCHAR (not VARIANT)."""
+        conn = self._connect()
+        try:
+            cur = conn.cursor()
+            escaped = ", ".join(
+                "NULL" if a is None else f"'{str(a).replace(chr(39), chr(39)*2)}'"
+                for a in args
+            )
+            cur.execute(f"CALL {self.app}.api.{proc}({escaped})")
+            row = cur.fetchone()
+            return row[0] if row else None
+        finally:
+            conn.close()
+
+    def _list_stage(self, database: str | None = None) -> list[SchemaObject]:
+        """LIST the stage and return typed SchemaObject entries."""
+        conn = self._connect()
+        try:
+            cur = conn.cursor()
+            prefix = f"@{self.app}.core.md_stage/"
+            if database:
+                prefix += f"{database.upper()}/"
+            cur.execute(f"LIST {prefix}")
+            rows = cur.fetchall()
+            objects = []
+            for r in rows:
+                parts = r[0].split("/")   # md_stage/DB/SCHEMA/OBJECT.md
+                if len(parts) >= 4:
+                    objects.append(SchemaObject(
+                        database=parts[1],
+                        schema=parts[2],
+                        object_name=parts[3].replace(".md", ""),
+                        size_bytes=int(r[1]) if r[1] else 0,
+                    ))
+            return objects
+        finally:
+            conn.close()
+
+    # ── public API ────────────────────────────────────────────────────────────
+
+    def get_schema(self, database: str, schema: str, object_name: str) -> str | None:
+        """
+        Return the full Markdown documentation for one Snowflake object,
+        or None if not found / error.
+        """
+        result = self._call_varchar(
+            "get_schema_doc",
+            database.upper(), schema.upper(), object_name.upper(),
+        )
+        if result and not result.startswith("Error reading") and not result.startswith("No documentation"):
+            return result
+        return None
+
+    def search(self, query: str, database: str | None = None) -> list[SchemaObject]:
+        """
+        Keyword search across all tracked objects.
+        Matches on object name, schema name, or database name.
+        """
+        q = query.lower()
+        objects = self._list_stage(database)
+        return [
+            obj for obj in objects
+            if q in obj.object_name.lower()
+            or q in obj.schema.lower()
+            or q in obj.database.lower()
+        ]
+
+    def list_objects(
+        self,
+        database: str | None = None,
+        object_type: str | None = None,
+    ) -> list[SchemaObject]:
+        """
+        List all tracked objects, optionally filtered by database or type.
+        Type filter requires the list_md_files API (has type info).
+        """
+        result = self._call("list_md_files", database or "")
+        files  = result.get("files", []) if isinstance(result, dict) else []
+
+        objects = []
+        for f in files:
+            obj = SchemaObject(
+                database=f.get("database_name", ""),
+                schema=f.get("schema_name", ""),
+                object_name=f.get("object_name", ""),
+                object_type=f.get("object_type", ""),
+                size_bytes=f.get("file_size", 0),
+            )
+            objects.append(obj)
+
+        if object_type:
+            objects = [o for o in objects if o.object_type.upper() == object_type.upper()]
+
+        return objects
+
+    def get_status(self) -> SyncStatus:
+        """Return current sync health as a typed SyncStatus."""
+        raw = self._call("get_status")
+        return SyncStatus(
+            task_state=raw.get("task_state", "UNKNOWN"),
+            total_objects=raw.get("total_objects_tracked", 0),
+            md_files_present=raw.get("md_files_present", 0),
+            dirty_count=raw.get("dirty_count", 0),
+            last_scan_at=raw.get("last_scan_at"),
+            databases=raw.get("databases", []),
+        )
+
+    def sync(self, database: str | None = None) -> dict:
+        """
+        Trigger an immediate sync.
+        Returns the raw sync result dict from the Native App.
+        """
+        if database:
+            return self._call("sync_database", database.upper())
+        return self._call("sync_now")

snowsyncmd_mcp-1.0.0/snowsyncmd_mcp/server.py

@@ -0,0 +1,182 @@
+"""
+server.py
+=========
+MCP server — translates Claude's tool calls into SnowSyncMDClient calls.
+
+This module knows nothing about Snowflake directly.
+All Snowflake logic lives in client.py.
+"""
+
+import asyncio
+from typing import Any
+
+import mcp.server.stdio
+import mcp.types as types
+from mcp.server import Server
+
+from .client import SnowSyncMDClient
+
+
+def create_server(client: SnowSyncMDClient) -> Server:
+    server = Server("snowsyncmd")
+
+    # ── tool definitions ──────────────────────────────────────────────────────
+
+    @server.list_tools()
+    async def list_tools() -> list[types.Tool]:
+        return [
+            types.Tool(
+                name="snowflake_get_schema",
+                description=(
+                    "Get the full Markdown schema doc for a specific Snowflake object "
+                    "(table, view, function, procedure, stage, etc.). "
+                    "Call this before writing SQL to get accurate column names and types."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "database":    {"type": "string"},
+                        "schema":      {"type": "string"},
+                        "object_name": {"type": "string"},
+                    },
+                    "required": ["database", "schema", "object_name"],
+                },
+            ),
+            types.Tool(
+                name="snowflake_search_schema",
+                description=(
+                    "Search all schema docs by keyword. Use when you don't know "
+                    "the exact table/view name. Returns matching object names."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "query":    {"type": "string", "description": "e.g. 'customer', 'order', 'payment'"},
+                        "database": {"type": "string", "description": "Limit to one database (optional)"},
+                    },
+                    "required": ["query"],
+                },
+            ),
+            types.Tool(
+                name="snowflake_list_objects",
+                description="List all tracked Snowflake objects with their database, schema, and type.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "database":    {"type": "string"},
+                        "object_type": {"type": "string", "description": "TABLE, VIEW, FUNCTION, PROCEDURE, STAGE, etc."},
+                    },
+                },
+            ),
+            types.Tool(
+                name="snowflake_get_status",
+                description="Check SnowSyncMD sync health: registered databases, object counts, last sync time.",
+                inputSchema={"type": "object", "properties": {}},
+            ),
+            types.Tool(
+                name="snowflake_sync",
+                description="Trigger an immediate schema sync. Use after DDL changes.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "database": {"type": "string", "description": "Sync one DB only (optional)"},
+                    },
+                },
+            ),
+        ]
+
+    # ── tool handlers ─────────────────────────────────────────────────────────
+
+    @server.call_tool()
+    async def call_tool(name: str, arguments: dict[str, Any]) -> list[types.TextContent]:
+
+        if name == "snowflake_get_schema":
+            doc = client.get_schema(
+                arguments["database"],
+                arguments["schema"],
+                arguments["object_name"],
+            )
+            text = doc if doc else (
+                f"No documentation found for "
+                f"{arguments['database']}.{arguments['schema']}.{arguments['object_name']}. "
+                "Run snowflake_sync to regenerate, or verify the object exists."
+            )
+            return [types.TextContent(type="text", text=text)]
+
+        if name == "snowflake_search_schema":
+            hits = client.search(arguments["query"], arguments.get("database"))
+            if not hits:
+                return [types.TextContent(
+                    type="text",
+                    text=f"No objects matching '{arguments['query']}'.",
+                )]
+            lines = [f"Found {len(hits)} match(es) for '{arguments['query']}':\n"]
+            for h in hits[:20]:
+                lines.append(f"  • {h.full_name}")
+            if len(hits) > 20:
+                lines.append(f"  … {len(hits) - 20} more")
+            lines.append("\nUse snowflake_get_schema to read the full doc for any object.")
+            return [types.TextContent(type="text", text="\n".join(lines))]
+
+        if name == "snowflake_list_objects":
+            objs = client.list_objects(
+                arguments.get("database"),
+                arguments.get("object_type"),
+            )
+            if not objs:
+                return [types.TextContent(
+                    type="text", text="No objects tracked yet. Run snowflake_sync first."
+                )]
+            by_db: dict = {}
+            for o in objs:
+                by_db.setdefault(f"{o.database}.{o.schema}", []).append(o.object_name)
+            lines = [f"Tracked objects ({len(objs)} total):\n"]
+            for group, names in sorted(by_db.items()):
+                lines.append(f"\n📁 {group} ({len(names)} objects)")
+                for n in sorted(names):
+                    lines.append(f"   • {n}")
+            return [types.TextContent(type="text", text="\n".join(lines))]
+
+        if name == "snowflake_get_status":
+            s = client.get_status()
+            lines = [
+                "SnowSyncMD Status",
+                f"  Task:     {s.task_state}",
+                f"  Objects:  {s.total_objects}",
+                f"  MD files: {s.md_files_present}",
+                f"  Pending:  {s.dirty_count}",
+                f"  Last sync: {s.last_scan_at or 'Never'}",
+                "\nDatabases:",
+            ]
+            for db in s.databases:
+                icon = "✅" if db.get("is_enabled") else "⛔"
+                lines.append(
+                    f"  {icon} {db['database_name']} "
+                    f"[{db['priority']}]  {db['object_count']} objects"
+                )
+            return [types.TextContent(type="text", text="\n".join(lines))]
+
+        if name == "snowflake_sync":
+            result = client.sync(arguments.get("database"))
+            db_label = arguments.get("database", "all databases").upper()
+            scan_r = result.get("scan") or {}
+            gen_r  = result.get("generate") or {}
+            text = (
+                f"Sync complete for {db_label}.\n"
+                f"  Scanned:   {scan_r.get('objects_scanned', 0)}\n"
+                f"  Changed:   {scan_r.get('objects_changed', 0)}\n"
+                f"  MD files:  {gen_r.get('md_files_written', 0)}\n"
+                f"  Duration:  {result.get('total_duration_seconds', '?')}s"
+            )
+            return [types.TextContent(type="text", text=text)]
+
+        return [types.TextContent(type="text", text=f"Unknown tool: {name}")]
+
+    return server
+
+
+async def run():
+    client = SnowSyncMDClient.from_env()
+    server = create_server(client)
+    async with mcp.server.stdio.stdio_server() as (read, write):
+        await server.run(read, write, server.create_initialization_options())

snowsyncmd_mcp-1.0.0/snowsyncmd_mcp.py

@@ -0,0 +1,369 @@
+#!/usr/bin/env python3
+"""
+SnowSyncMD MCP Server
+=====================
+Exposes the SnowSyncMD Native App as MCP tools so Claude Code can
+automatically read Snowflake schema documentation without live queries.
+
+Claude sees these tools:
+  snowflake_get_schema    – fetch the MD doc for one object
+  snowflake_search_schema – full-text search across all schema docs
+  snowflake_list_objects  – list every tracked object (filter by DB / type)
+  snowflake_get_status    – show sync health and registered databases
+  snowflake_sync          – trigger an immediate sync (optional)
+
+Setup (consumer side):
+  pip install mcp snowflake-connector-python python-dotenv
+  python mcp/snowsyncmd_mcp.py
+
+Then add to Claude Code settings (~/.claude/settings.json):
+  {
+    "mcpServers": {
+      "snowsyncmd": {
+        "command": "python3",
+        "args": ["/path/to/snowsyncmd_mcp.py"],
+        "env": {
+          "SNOWFLAKE_ACCOUNT":  "...",
+          "SNOWFLAKE_USER":     "...",
+          "SNOWFLAKE_PASSWORD": "...",
+          "SNOWFLAKE_ROLE":     "ACCOUNTADMIN",
+          "SNOWSYNCMD_APP":     "snowsyncmd"
+        }
+      }
+    }
+  }
+
+Claude then uses these tools automatically whenever you ask:
+  "What columns does ORDERS have?"
+  "Write a query joining CUSTOMERS to ORDERS"
+  "Which tables track payments?"
+"""
+
+import asyncio
+import json
+import os
+import sys
+from typing import Any
+
+# ── MCP SDK ──────────────────────────────────────────────────────────────────
+try:
+    import mcp.server.stdio
+    import mcp.types as types
+    from mcp.server import Server
+except ImportError:
+    print("Install the MCP SDK:  pip install mcp", file=sys.stderr)
+    sys.exit(1)
+
+# ── Snowflake connector ───────────────────────────────────────────────────────
+try:
+    import snowflake.connector
+except ImportError:
+    print("Install Snowflake connector:  pip install snowflake-connector-python",
+          file=sys.stderr)
+    sys.exit(1)
+
+try:
+    from dotenv import load_dotenv
+    load_dotenv()
+except ImportError:
+    pass
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Snowflake helpers
+# ─────────────────────────────────────────────────────────────────────────────
+
+APP = os.environ.get("SNOWSYNCMD_APP", "snowsyncmd")
+
+
+def _connect():
+    return snowflake.connector.connect(
+        account=os.environ["SNOWFLAKE_ACCOUNT"],
+        user=os.environ["SNOWFLAKE_USER"],
+        password=os.environ["SNOWFLAKE_PASSWORD"],
+        warehouse=os.environ.get("SNOWFLAKE_WAREHOUSE", ""),
+        role=os.environ.get("SNOWFLAKE_ROLE", "ACCOUNTADMIN"),
+    )
+
+
+def _call_proc(proc: str, *args) -> Any:
+    """Call a SnowSyncMD stored procedure and return parsed JSON."""
+    conn = _connect()
+    try:
+        cur = conn.cursor()
+        placeholders = ", ".join(["'%s'" % str(a).replace("'", "''") for a in args])
+        sql = f"CALL {APP}.api.{proc}({placeholders})"
+        cur.execute(sql)
+        row = cur.fetchone()
+        if row:
+            val = row[0]
+            if isinstance(val, str):
+                try:
+                    return json.loads(val)
+                except Exception:
+                    return {"raw": val}
+            return val
+        return {}
+    finally:
+        conn.close()
+
+
+def _get_md_file(database: str, schema: str, object_name: str) -> str | None:
+    """Read one MD file directly from the stage."""
+    conn = _connect()
+    try:
+        cur = conn.cursor()
+        stage_path = f"@{APP}.core.md_stage/{database}/{schema}/{object_name}.md"
+        cur.execute(
+            f"SELECT $1 FROM {stage_path} "
+            f"(FILE_FORMAT => (TYPE='CSV', FIELD_DELIMITER='NONE', RECORD_DELIMITER='\\n'))"
+        )
+        lines = [r[0] for r in cur.fetchall() if r[0] is not None]
+        return "\n".join(lines) if lines else None
+    except Exception:
+        return None
+    finally:
+        conn.close()
+
+
+def _list_stage_files(database: str | None = None) -> list[dict]:
+    """List MD files in the stage."""
+    conn = _connect()
+    try:
+        cur = conn.cursor()
+        prefix = f"@{APP}.core.md_stage/"
+        if database:
+            prefix += f"{database.upper()}/"
+        cur.execute(f"LIST {prefix}")
+        rows = cur.fetchall()
+        result = []
+        for r in rows:
+            name = r[0]   # md_stage/DB/SCHEMA/OBJECT.md
+            parts = name.split("/")
+            if len(parts) >= 4:
+                result.append({
+                    "database":    parts[1],
+                    "schema":      parts[2],
+                    "object_name": parts[3].replace(".md", ""),
+                    "stage_path":  name,
+                    "size_bytes":  r[1],
+                })
+        return result
+    finally:
+        conn.close()
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# MCP Server
+# ─────────────────────────────────────────────────────────────────────────────
+
+server = Server("snowsyncmd")
+
+
+@server.list_tools()
+async def list_tools() -> list[types.Tool]:
+    return [
+        types.Tool(
+            name="snowflake_get_schema",
+            description=(
+                "Get the full Markdown schema documentation for a specific Snowflake "
+                "object (table, view, function, procedure, etc.). "
+                "Use this whenever you need column names, data types, or metadata "
+                "about a specific object before writing a SQL query."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "database":    {"type": "string", "description": "Database name (uppercase)"},
+                    "schema":      {"type": "string", "description": "Schema name (uppercase)"},
+                    "object_name": {"type": "string", "description": "Object name (uppercase)"},
+                },
+                "required": ["database", "schema", "object_name"],
+            },
+        ),
+        types.Tool(
+            name="snowflake_search_schema",
+            description=(
+                "Search across all SnowSyncMD schema documentation. "
+                "Returns a list of objects whose names or descriptions match the query. "
+                "Use this to discover tables/views when you don't know the exact name."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "query":    {"type": "string", "description": "Search term (e.g. 'customer', 'order', 'payment')"},
+                    "database": {"type": "string", "description": "Limit to this database (optional)"},
+                },
+                "required": ["query"],
+            },
+        ),
+        types.Tool(
+            name="snowflake_list_objects",
+            description=(
+                "List all Snowflake objects tracked by SnowSyncMD. "
+                "Returns database, schema, object name, and object type. "
+                "Use this to explore what's available before asking for specific schemas."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "database":    {"type": "string", "description": "Filter by database (optional)"},
+                    "object_type": {"type": "string", "description": "Filter by type: TABLE, VIEW, FUNCTION, PROCEDURE, STAGE, PIPE, SEQUENCE, FILE_FORMAT, TASK, STREAM (optional)"},
+                },
+            },
+        ),
+        types.Tool(
+            name="snowflake_get_status",
+            description=(
+                "Get the SnowSyncMD sync status: registered databases, object counts, "
+                "last sync time, and task state. Use this to check if documentation "
+                "is up to date before answering schema questions."
+            ),
+            inputSchema={"type": "object", "properties": {}},
+        ),
+        types.Tool(
+            name="snowflake_sync",
+            description=(
+                "Trigger an immediate schema sync for one or all databases. "
+                "Use this when the user wants fresh documentation after a DDL change."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "database": {"type": "string", "description": "Database to sync (optional — omit to sync all)"},
+                },
+            },
+        ),
+    ]
+
+
+@server.call_tool()
+async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
+
+    # ── snowflake_get_schema ──────────────────────────────────────────────────
+    if name == "snowflake_get_schema":
+        db  = arguments["database"].upper()
+        sc  = arguments["schema"].upper()
+        obj = arguments["object_name"].upper()
+        md  = _get_md_file(db, sc, obj)
+        if md:
+            return [types.TextContent(type="text", text=md)]
+        return [types.TextContent(
+            type="text",
+            text=f"No schema documentation found for {db}.{sc}.{obj}. "
+                 "Run snowflake_sync to regenerate, or check the object name."
+        )]
+
+    # ── snowflake_search_schema ───────────────────────────────────────────────
+    elif name == "snowflake_search_schema":
+        query    = arguments["query"].lower()
+        database = arguments.get("database")
+        files    = _list_stage_files(database)
+
+        # Simple keyword match on object name
+        matches = [
+            f for f in files
+            if query in f["object_name"].lower()
+            or query in f["schema"].lower()
+            or query in f["database"].lower()
+        ]
+
+        if not matches:
+            return [types.TextContent(
+                type="text",
+                text=f"No objects matching '{query}' found in schema documentation."
+            )]
+
+        lines = [f"Found {len(matches)} object(s) matching '{query}':\n"]
+        for m in matches[:20]:  # cap at 20
+            lines.append(
+                f"  • {m['database']}.{m['schema']}.{m['object_name']}"
+            )
+        if len(matches) > 20:
+            lines.append(f"  … and {len(matches) - 20} more")
+        lines.append(
+            "\nUse snowflake_get_schema to read the full documentation for any of these."
+        )
+        return [types.TextContent(type="text", text="\n".join(lines))]
+
+    # ── snowflake_list_objects ────────────────────────────────────────────────
+    elif name == "snowflake_list_objects":
+        database    = arguments.get("database")
+        object_type = arguments.get("object_type", "").upper()
+
+        result = _call_proc("list_md_files", database or "")
+        files  = result.get("files", []) if isinstance(result, dict) else []
+
+        if object_type:
+            # Filter by checking the object snapshot via status
+            pass  # Simplified: show all, type filtering would need snapshot query
+
+        if not files:
+            return [types.TextContent(type="text", text="No schema documentation available. Run snowflake_sync first.")]
+
+        by_db: dict = {}
+        for f in files:
+            key = f"{f.get('database_name','?')}.{f.get('schema_name','?')}"
+            by_db.setdefault(key, []).append(f.get("object_name", "?"))
+
+        lines = [f"Tracked objects ({len(files)} total):\n"]
+        for group, objs in sorted(by_db.items()):
+            lines.append(f"\n📁 {group} ({len(objs)} objects)")
+            for o in sorted(objs):
+                lines.append(f"   • {o}")
+        return [types.TextContent(type="text", text="\n".join(lines))]
+
+    # ── snowflake_get_status ──────────────────────────────────────────────────
+    elif name == "snowflake_get_status":
+        status = _call_proc("get_status")
+        lines = ["SnowSyncMD Status\n"]
+        lines.append(f"Task state:      {status.get('task_state', '?')}")
+        lines.append(f"Objects tracked: {status.get('total_objects_tracked', 0)}")
+        lines.append(f"MD files:        {status.get('md_files_present', 0)}")
+        lines.append(f"Last scan:       {status.get('last_scan_at', 'Never')}")
+        lines.append(f"Pending regen:   {status.get('dirty_count', 0)}")
+        lines.append("\nDatabases:")
+        for db in status.get("databases", []):
+            enabled = "✅" if db.get("is_enabled") else "⛔"
+            lines.append(
+                f"  {enabled} {db['database_name']}  "
+                f"priority={db['priority']}  "
+                f"objects={db['object_count']}"
+            )
+        return [types.TextContent(type="text", text="\n".join(lines))]
+
+    # ── snowflake_sync ────────────────────────────────────────────────────────
+    elif name == "snowflake_sync":
+        database = arguments.get("database")
+        if database:
+            result = _call_proc("sync_database", database.upper())
+            msg = f"Sync complete for {database.upper()}."
+        else:
+            result = _call_proc("sync_now")
+            msg = "Sync complete for all databases."
+
+        if isinstance(result, dict):
+            scan_r = result.get("scan") or {}
+            gen_r  = result.get("generate") or {}
+            msg += (
+                f"\n  Scanned:  {scan_r.get('objects_scanned', 0)}"
+                f"\n  Changed:  {scan_r.get('objects_changed', 0)}"
+                f"\n  MD files: {gen_r.get('md_files_written', 0)}"
+                f"\n  Duration: {result.get('total_duration_seconds', '?')}s"
+            )
+        return [types.TextContent(type="text", text=msg)]
+
+    return [types.TextContent(type="text", text=f"Unknown tool: {name}")]
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Entry point
+# ─────────────────────────────────────────────────────────────────────────────
+
+async def main():
+    async with mcp.server.stdio.stdio_server() as (read, write):
+        await server.run(read, write, server.create_initialization_options())
+
+
+if __name__ == "__main__":
+    asyncio.run(main())