adcirc-mcp 0.1.0__tar.gz

adcirc_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_*

adcirc_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.

adcirc_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: adcirc-mcp
+Version: 0.1.0
+Summary: MCP server for ADCIRC model setup debugging, parameter lookup, and configuration validation
+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

adcirc_mcp-0.1.0/README.md

@@ -0,0 +1,65 @@
+# adcirc-mcp
+
+<!-- mcp-name: io.github.mansurjisan/adcirc-mcp -->
+
+MCP server for ADCIRC model setup debugging, parameter lookup, and configuration validation.
+
+Unlike the other ocean-mcp servers that query remote NOAA APIs, adcirc-mcp **parses local model input files** and provides **embedded domain knowledge** to help debug and understand ADCIRC configurations.
+
+## Tools (10)
+
+### Parameter Reference
+- **`adcirc_explain_parameter`** — Look up any fort.15 parameter, NWS value, tidal constituent, or nodal attribute
+- **`adcirc_list_parameters`** — List all parameters grouped by category
+
+### File Parsing
+- **`adcirc_parse_fort15`** — Parse fort.15 control file into structured summary
+- **`adcirc_parse_fort14`** — Parse fort.14 mesh file header (node/element counts, boundaries)
+- **`adcirc_parse_fort13`** — Parse fort.13 nodal attributes (names, defaults, non-default counts)
+- **`adcirc_parse_fort22`** — Parse fort.22 meteorological forcing header
+
+### Validation & Debugging
+- **`adcirc_validate_config`** — Comprehensive validation with CFL check and cross-file verification
+- **`adcirc_diagnose_error`** — Match error text against known ADCIRC failure patterns
+
+### Documentation
+- **`adcirc_fetch_docs`** — Fetch pages from the ADCIRC wiki
+- **`adcirc_search_docs`** — Search the ADCIRC wiki
+
+## Installation
+
+```bash
+# Using uvx (recommended)
+uvx adcirc-mcp
+
+# Or install from source
+cd servers/adcirc-mcp
+uv sync
+```
+
+## Configuration
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "adcirc": {
+      "command": "uvx",
+      "args": ["adcirc-mcp"]
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+cd servers/adcirc-mcp
+uv sync --group dev
+uv run pytest tests/ --ignore=tests/test_live.py --ignore=tests/test_mcp_protocol.py -v
+```
+
+## License
+
+MIT

adcirc_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "adcirc-mcp"
+version = "0.1.0"
+description = "MCP server for ADCIRC model setup debugging, parameter lookup, and configuration validation"
+requires-python = ">=3.11"
+dependencies = [
+    "mcp[cli]>=1.0.0",
+    "httpx>=0.27.0",
+    "pydantic>=2.0.0",
+]
+
+[project.scripts]
+adcirc-mcp = "adcirc_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",
+]

adcirc_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/adcirc-mcp",
+  "title": "ADCIRC Model Setup MCP Server",
+  "description": "ADCIRC 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": "adcirc-mcp",
+      "version": "0.1.0",
+      "runtimeHint": "uvx",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

adcirc_mcp-0.1.0/smithery.yaml

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

adcirc_mcp-0.1.0/src/adcirc_mcp/__main__.py

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

adcirc_mcp-0.1.0/src/adcirc_mcp/client.py

@@ -0,0 +1,118 @@
+"""Dual-purpose client: local file reader + ADCIRC wiki documentation fetcher."""
+
+import re
+
+import httpx
+
+ADCIRC_WIKI_BASE = "https://wiki.adcirc.org"
+WIKI_API_URL = f"{ADCIRC_WIKI_BASE}/w/api.php"
+
+MAX_FILE_SIZE = 100 * 1024 * 1024  # 100 MB
+
+
+class ADCIRCClientError(Exception):
+    """Custom exception for ADCIRC client errors."""
+
+    pass
+
+
+class ADCIRCClient:
+    """Async client for local file reading and ADCIRC wiki 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 ADCIRCClientError(
+                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_wiki_page(self, page_title: str) -> str:
+        """Fetch a wiki page and return its content as plain text."""
+        client = await self._get_client()
+        params = {
+            "action": "parse",
+            "page": page_title,
+            "prop": "text",
+            "format": "json",
+        }
+        response = await client.get(WIKI_API_URL, params=params)
+        response.raise_for_status()
+        data = response.json()
+
+        if "error" in data:
+            raise ADCIRCClientError(
+                f"Wiki page not found: {data['error'].get('info', page_title)}"
+            )
+
+        html = data.get("parse", {}).get("text", {}).get("*", "")
+        return strip_html_to_text(html)
+
+    async def search_wiki(self, query: str, limit: int = 10) -> list[dict]:
+        """Search the ADCIRC wiki and return matching pages."""
+        client = await self._get_client()
+        params = {
+            "action": "query",
+            "list": "search",
+            "srsearch": query,
+            "srlimit": str(limit),
+            "format": "json",
+        }
+        response = await client.get(WIKI_API_URL, params=params)
+        response.raise_for_status()
+        data = response.json()
+
+        results = []
+        for item in data.get("query", {}).get("search", []):
+            results.append(
+                {
+                    "title": item.get("title", ""),
+                    "snippet": strip_html_to_text(item.get("snippet", "")),
+                    "url": f"{ADCIRC_WIKI_BASE}/wiki/{item.get('title', '').replace(' ', '_')}",
+                }
+            )
+        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