schism-mcp 0.1.0__tar.gz

schism_mcp-0.1.0/.gitignore

@@ -0,0 +1,45 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Linting
+.ruff_cache/
+.mypy_cache/
+
+# Lock files (each server manages its own)
+uv.lock
+
+# Environment
+.env
+.env.local
+
+# Registry tokens
+.mcpregistry_*

schism_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Mansur Ali Jisan
+
+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.

schism_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: schism-mcp
+Version: 0.1.0
+Summary: MCP server for SCHISM model setup debugging, parameter lookup, and configuration validation
+Author-email: Mansur Ali Jisan <mansur.jisan@noaa.gov>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Description-Content-Type: text/markdown
+
+# schism-mcp
+
+<!-- mcp-name: io.github.mansurjisan/schism-mcp -->
+
+MCP server for SCHISM model setup debugging, parameter lookup, and configuration validation.
+
+Unlike the other ocean-mcp servers that query remote NOAA APIs, schism-mcp **parses local model input files** and provides **embedded domain knowledge** to help debug and understand SCHISM configurations.
+
+## Tools (10)
+
+### Parameter Reference
+- **`schism_explain_parameter`** — Look up any param.nml parameter, tidal constituent, vertical grid type, or BC type
+- **`schism_list_parameters`** — List all parameters grouped by section (CORE, OPT, SCHOUT)
+
+### File Parsing
+- **`schism_parse_param_nml`** — Parse FORTRAN namelist file into structured summary
+- **`schism_parse_hgrid`** — Parse hgrid.gr3 header (node/element counts, bounding box, boundaries)
+- **`schism_parse_vgrid`** — Parse vgrid.in (LSC2/SZ type, level count, layer distribution)
+- **`schism_parse_bctides`** — Parse bctides.in (tidal constituents, boundary segments)
+
+### Validation & Debugging
+- **`schism_validate_config`** — Comprehensive validation with cross-file checks
+- **`schism_diagnose_error`** — Match error text against known SCHISM failure patterns
+
+### Documentation
+- **`schism_fetch_docs`** — Fetch pages from the SCHISM documentation site
+- **`schism_search_docs`** — Search SCHISM documentation
+
+## Installation
+
+```bash
+# Using uvx (recommended)
+uvx schism-mcp
+
+# Or install from source
+cd servers/schism-mcp
+uv sync
+```
+
+## Configuration
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "schism": {
+      "command": "uvx",
+      "args": ["schism-mcp"]
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+cd servers/schism-mcp
+uv sync --group dev
+uv run pytest tests/ --ignore=tests/test_live.py --ignore=tests/test_mcp_protocol.py -v
+```
+
+## License
+
+MIT

schism_mcp-0.1.0/README.md

@@ -0,0 +1,65 @@
+# schism-mcp
+
+<!-- mcp-name: io.github.mansurjisan/schism-mcp -->
+
+MCP server for SCHISM model setup debugging, parameter lookup, and configuration validation.
+
+Unlike the other ocean-mcp servers that query remote NOAA APIs, schism-mcp **parses local model input files** and provides **embedded domain knowledge** to help debug and understand SCHISM configurations.
+
+## Tools (10)
+
+### Parameter Reference
+- **`schism_explain_parameter`** — Look up any param.nml parameter, tidal constituent, vertical grid type, or BC type
+- **`schism_list_parameters`** — List all parameters grouped by section (CORE, OPT, SCHOUT)
+
+### File Parsing
+- **`schism_parse_param_nml`** — Parse FORTRAN namelist file into structured summary
+- **`schism_parse_hgrid`** — Parse hgrid.gr3 header (node/element counts, bounding box, boundaries)
+- **`schism_parse_vgrid`** — Parse vgrid.in (LSC2/SZ type, level count, layer distribution)
+- **`schism_parse_bctides`** — Parse bctides.in (tidal constituents, boundary segments)
+
+### Validation & Debugging
+- **`schism_validate_config`** — Comprehensive validation with cross-file checks
+- **`schism_diagnose_error`** — Match error text against known SCHISM failure patterns
+
+### Documentation
+- **`schism_fetch_docs`** — Fetch pages from the SCHISM documentation site
+- **`schism_search_docs`** — Search SCHISM documentation
+
+## Installation
+
+```bash
+# Using uvx (recommended)
+uvx schism-mcp
+
+# Or install from source
+cd servers/schism-mcp
+uv sync
+```
+
+## Configuration
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "schism": {
+      "command": "uvx",
+      "args": ["schism-mcp"]
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+cd servers/schism-mcp
+uv sync --group dev
+uv run pytest tests/ --ignore=tests/test_live.py --ignore=tests/test_mcp_protocol.py -v
+```
+
+## License
+
+MIT

schism_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "schism-mcp"
+version = "0.1.0"
+description = "MCP server for SCHISM model setup debugging, parameter lookup, and configuration validation"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    {name = "Mansur Ali Jisan", email = "mansur.jisan@noaa.gov"},
+]
+dependencies = [
+    "mcp[cli]>=1.0.0",
+    "httpx>=0.27.0",
+    "pydantic>=2.0.0",
+]
+
+[project.scripts]
+schism-mcp = "schism_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+    "respx>=0.22.0",
+]

schism_mcp-0.1.0/server.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.mansurjisan/schism-mcp",
+  "title": "SCHISM Model Setup MCP Server",
+  "description": "SCHISM model configuration debugging, parameter lookup, and validation",
+  "version": "0.1.0",
+  "repository": {
+    "url": "https://github.com/mansurjisan/ocean-mcp",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "schism-mcp",
+      "version": "0.1.0",
+      "runtimeHint": "uvx",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

schism_mcp-0.1.0/smithery.yaml

@@ -0,0 +1,8 @@
+startCommand:
+  type: stdio
+  configSchema:
+    type: object
+    required: []
+    properties: {}
+  commandFunction: |-
+    (config) => ({ command: 'uvx', args: ['schism-mcp'] })

schism_mcp-0.1.0/src/schism_mcp/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running with python -m schism_mcp."""
+
+from .server import main
+
+main()

schism_mcp-0.1.0/src/schism_mcp/client.py

@@ -0,0 +1,191 @@
+"""Dual-purpose client: local file reader + SCHISM documentation fetcher."""
+
+import re
+
+import httpx
+
+SCHISM_DOCS_BASE = "https://schism-dev.github.io/schism"
+SCHISM_REPO_URL = "https://raw.githubusercontent.com/schism-dev/schism/master"
+
+MAX_FILE_SIZE = 100 * 1024 * 1024  # 100 MB
+
+
+class SchismClientError(Exception):
+    """Custom exception for SCHISM client errors."""
+
+    pass
+
+
+class SchismClient:
+    """Async client for local file reading and SCHISM documentation access."""
+
+    def __init__(self) -> None:
+        self._client: httpx.AsyncClient | None = None
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None or self._client.is_closed:
+            self._client = httpx.AsyncClient(timeout=30.0)
+        return self._client
+
+    @staticmethod
+    def read_file(file_path: str) -> str:
+        """Read a local file with size limit."""
+        import os
+
+        size = os.path.getsize(file_path)
+        if size > MAX_FILE_SIZE:
+            raise SchismClientError(
+                f"File too large ({size / 1024 / 1024:.1f} MB). "
+                f"Max is {MAX_FILE_SIZE / 1024 / 1024:.0f} MB."
+            )
+        with open(file_path) as f:
+            return f.read()
+
+    @staticmethod
+    def read_file_header(file_path: str, max_lines: int = 100) -> str:
+        """Read only the first N lines of a file."""
+        lines = []
+        with open(file_path) as f:
+            for i, line in enumerate(f):
+                if i >= max_lines:
+                    break
+                lines.append(line)
+        return "".join(lines)
+
+    async def fetch_doc_page(self, path: str) -> str:
+        """Fetch a documentation page from SCHISM docs site."""
+        client = await self._get_client()
+        url = f"{SCHISM_DOCS_BASE}/{path}"
+        response = await client.get(url)
+        response.raise_for_status()
+        html = response.text
+        return strip_html_to_text(html)
+
+    async def search_docs(self, query: str) -> list[dict]:
+        """Search SCHISM documentation by fetching the search index.
+
+        Since SCHISM docs are static (GitHub Pages), we search known page titles.
+        """
+        query_lower = query.lower()
+        known_pages = [
+            {
+                "title": "Getting Started",
+                "path": "getting-started/overview.html",
+                "description": "Overview and quick start guide",
+            },
+            {
+                "title": "Input Files",
+                "path": "input-output/input-files.html",
+                "description": "All SCHISM input files reference",
+            },
+            {
+                "title": "param.nml",
+                "path": "input-output/param.nml.html",
+                "description": "Main parameter namelist reference",
+            },
+            {
+                "title": "hgrid.gr3",
+                "path": "input-output/hgrid.html",
+                "description": "Horizontal grid format",
+            },
+            {
+                "title": "vgrid.in",
+                "path": "input-output/vgrid.html",
+                "description": "Vertical grid format",
+            },
+            {
+                "title": "bctides.in",
+                "path": "input-output/bctides.html",
+                "description": "Tidal boundary condition file",
+            },
+            {
+                "title": "Output Files",
+                "path": "input-output/output-files.html",
+                "description": "Output file descriptions",
+            },
+            {
+                "title": "Troubleshooting",
+                "path": "getting-started/troubleshooting.html",
+                "description": "Common issues and solutions",
+            },
+            {
+                "title": "SCHOUT",
+                "path": "input-output/schout.html",
+                "description": "SCHISM output control",
+            },
+            {
+                "title": "WWM",
+                "path": "modules/wwm.html",
+                "description": "Wind Wave Model coupling",
+            },
+            {
+                "title": "SED",
+                "path": "modules/sed.html",
+                "description": "Sediment transport module",
+            },
+            {
+                "title": "ICM",
+                "path": "modules/icm.html",
+                "description": "Water quality module",
+            },
+            {
+                "title": "Vertical Grid",
+                "path": "mesh-generation/vertical-grid.html",
+                "description": "Vertical grid generation",
+            },
+            {
+                "title": "Horizontal Grid",
+                "path": "mesh-generation/horizontal-grid.html",
+                "description": "Mesh generation guide",
+            },
+            {
+                "title": "Pre-processing",
+                "path": "getting-started/pre-processing.html",
+                "description": "Pre-processing tools",
+            },
+            {
+                "title": "Hotstart",
+                "path": "input-output/hotstart.html",
+                "description": "Hot start and restart",
+            },
+        ]
+
+        results = []
+        for page in known_pages:
+            score = 0
+            for word in query_lower.split():
+                if word in page["title"].lower():
+                    score += 2
+                if word in page["description"].lower():
+                    score += 1
+            if score > 0:
+                results.append(
+                    {
+                        "title": page["title"],
+                        "url": f"{SCHISM_DOCS_BASE}/{page['path']}",
+                        "description": page["description"],
+                        "score": score,
+                    }
+                )
+
+        results.sort(key=lambda x: x["score"], reverse=True)
+        return results
+
+    async def close(self) -> None:
+        if self._client and not self._client.is_closed:
+            await self._client.aclose()
+
+
+def strip_html_to_text(html: str) -> str:
+    """Strip HTML tags and decode entities to plain text."""
+    text = re.sub(r"<script[^>]*>.*?</script>", "", html, flags=re.DOTALL)
+    text = re.sub(r"<style[^>]*>.*?</style>", "", text, flags=re.DOTALL)
+    text = re.sub(r"<[^>]+>", " ", text)
+    text = text.replace("&amp;", "&")
+    text = text.replace("&lt;", "<")
+    text = text.replace("&gt;", ">")
+    text = text.replace("&quot;", '"')
+    text = text.replace("&#039;", "'")
+    text = text.replace("&nbsp;", " ")
+    text = re.sub(r"\s+", " ", text).strip()
+    return text