gauge-mcp 0.1.0__tar.gz

gauge_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: ci
+on: [push, pull_request]
+permissions:
+  contents: read
+jobs:
+  test:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv venv -p ${{ matrix.python }} && uv pip install -e '.[dev]'
+      - run: .venv/bin/pytest -q
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Identifier scan
+        env:
+          IDENTIFIER_PATTERNS: ${{ secrets.IDENTIFIER_PATTERNS }}
+        run: python3 scripts/scan_identifiers.py .

gauge_mcp-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.env
+.env.*

gauge_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+Gauge follows [semantic versioning](https://semver.org). Modules added after 0.1 ship switched off.
+
+## 0.1.0 — unreleased
+
+- First release as one bundle with two modules: `umami` (web analytics) and `resend` (email).
+- `gauge_modules` discovery tool: which modules are on, which settings are missing, what each tool does.
+- Every tool returns structured data with a published output schema.
+- `umami_metrics` gives real ranked breakdowns (top pages, referrers, countries, browsers and more), with `limit`, `offset` and `search`.
+- Umami Cloud supported through an API key, as well as a self-hosted login.
+- `resend_send` previews by default. Sending needs the person's approval: asked through MCP elicitation, or given ahead of time with `GAUGE_RESEND_ALLOWED_RECIPIENTS` or `GAUGE_RESEND_REQUIRE_CONFIRM=false`. The assistant's own `confirm=true` is never enough. The sender comes from settings, never from code.
+- Runs over stdio or streamable HTTP. Starts with no settings and reports what is missing when a tool is called.

gauge_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Seaynic Labs
+
+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.

gauge_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.5
+Name: gauge-mcp
+Version: 0.1.0
+Summary: MCP bundle for people running a small website: web analytics (Umami) and email (Resend) in one server.
+Project-URL: Repository, https://github.com/seayniclabs/gauge
+Author: Seaynic Labs
+License-Expression: MIT
+License-File: LICENSE
+Keywords: analytics,email,mcp,model-context-protocol,resend,umami
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp[cli]<2,>=1.27
+Requires-Dist: pydantic>=2.7
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Gauge
+
+<!-- mcp-name: io.github.seayniclabs/gauge -->
+
+Gauge is an MCP server for people running a small website. It lets an AI assistant read your site's analytics and send email, from one install.
+
+It is a **bundle**: one server made of modules. You switch on the modules you use. New modules arrive switched off, so an update never changes what your assistant can do until you choose to.
+
+| Module | What it does | Status |
+|---|---|---|
+| `umami` | Web analytics from [Umami](https://umami.is), self-hosted or Umami Cloud: sites, totals, time series, top pages, referrers, countries, browsers | 0.1 |
+| `resend` | Email through [Resend](https://resend.com): send (preview first), list sent mail, list sending domains | 0.1 |
+
+Gauge works with any MCP client: Claude Desktop, Claude Code, Cursor, VS Code, Sonique, Hermes, OpenClaw and others. It runs on your computer and stores nothing; your data stays in Umami and Resend.
+
+## Install
+
+Gauge needs Python 3.11 or newer. With [uv](https://docs.astral.sh/uv/) you don't install anything ahead of time:
+
+```bash
+uvx gauge-mcp --version
+```
+
+Or with pip:
+
+```bash
+pip install gauge-mcp
+```
+
+## Settings
+
+Set these as environment variables in your MCP client's config, or put them in a config file (see below). You only need the settings for the modules you use. Gauge starts without any of them and tells you what's missing when you call a tool.
+
+| Variable | Module | What it is |
+|---|---|---|
+| `GAUGE_UMAMI_URL` | umami | Your Umami address, e.g. `https://analytics.example.com` |
+| `GAUGE_UMAMI_USERNAME` / `GAUGE_UMAMI_PASSWORD` | umami | A self-hosted Umami login. A view-only user is enough. |
+| `GAUGE_UMAMI_API_KEY` | umami | Umami Cloud API key (instead of a login). `GAUGE_UMAMI_URL` defaults to Umami Cloud when this is set. |
+| `GAUGE_RESEND_API_KEY` | resend | Resend API key |
+| `GAUGE_RESEND_FROM` | resend | Sender address on a domain you verified in Resend |
+| `GAUGE_RESEND_FROM_NAME` | resend | Optional sender display name |
+| `GAUGE_RESEND_ALLOWED_RECIPIENTS` | resend | Optional. Comma-separated addresses or `@domains` the assistant may send to without asking you each time, e.g. `me@example.com,@example.com` |
+| `GAUGE_RESEND_REQUIRE_CONFIRM` | resend | `true` by default: you approve each send. `false` lets the assistant send on its own. |
+| `GAUGE_<MODULE>_ENABLED` | any | `false` turns a module off, e.g. `GAUGE_RESEND_ENABLED=false` |
+
+**Config file (optional).** Gauge also reads `~/.config/gauge/config.toml`, or the file named by `GAUGE_CONFIG`. Environment variables win over the file.
+
+```toml
+[umami]
+url = "https://analytics.example.com"
+username = "viewer"
+password = "change-me"
+
+[resend]
+enabled = false
+```
+
+## Add it to your MCP client
+
+Most clients use the same JSON shape. Put it where your client keeps MCP servers:
+
+```json
+{
+  "mcpServers": {
+    "gauge": {
+      "command": "uvx",
+      "args": ["gauge-mcp"],
+      "env": {
+        "GAUGE_UMAMI_URL": "https://analytics.example.com",
+        "GAUGE_UMAMI_USERNAME": "viewer",
+        "GAUGE_UMAMI_PASSWORD": "change-me",
+        "GAUGE_RESEND_API_KEY": "re_your_key",
+        "GAUGE_RESEND_FROM": "hello@example.com"
+      }
+    }
+  }
+}
+```
+
+| Client | Where the config goes |
+|---|---|
+| Claude Desktop | `claude_desktop_config.json` (Settings → Developer → Edit Config) |
+| Claude Code | `claude mcp add gauge -- uvx gauge-mcp`, then add the `env` values, or a project `.mcp.json` |
+| Cursor | `~/.cursor/mcp.json`, or `.cursor/mcp.json` in a project |
+| VS Code | `.vscode/mcp.json`, using `"servers"` instead of `"mcpServers"` |
+| Sonique, Hermes, OpenClaw, others | Any client that launches a stdio MCP server: command `uvx`, args `["gauge-mcp"]`, plus the env values |
+
+**Over HTTP.** For clients that connect to a URL instead of launching a process:
+
+```bash
+gauge-mcp --transport http --port 8765
+```
+
+It serves streamable HTTP at `http://127.0.0.1:8765/mcp`. It listens only on your own machine by default. Put authentication in front of it before exposing it anywhere else.
+
+## Tools
+
+| Tool | What it returns |
+|---|---|
+| `gauge_modules` | Which modules are on, which settings are missing, and what each tool does. Call this first. |
+| `umami_websites` | Tracked websites, paged |
+| `umami_stats` | Pageviews, visitors, visits, bounces and bounce rate for a date range |
+| `umami_pageviews` | Pageviews and sessions over time |
+| `umami_metrics` | A ranked breakdown: `type` = `path` (top pages), `referrer`, `country`, `browser`, `os`, `device` and more |
+| `resend_send` | Sends an email after you approve it. Without `confirm=true` it only returns a preview. |
+| `resend_emails` | Sent emails, paged with a cursor |
+| `resend_domains` | Sending domains and whether each is verified |
+
+Every tool returns structured data with a published schema, so an assistant can write code against the results instead of reading text. Date ranges take `days` (default 7) or ISO 8601 `start` and `end`. Errors always look like `gauge.<module>.<code>: <message> Fix: <hint>`.
+
+## Safety
+
+- Gauge only calls the services you configure. It sends nothing anywhere else and keeps no data.
+- `resend_send` sends real email, so **you** approve each one, not the assistant. When the assistant asks to send, Gauge asks you directly through your MCP client (MCP elicitation) and shows the sender, recipients and subject. The assistant can't answer that question for you.
+- Some MCP clients can't ask you questions yet. In those, Gauge refuses to send unless you've pre-approved the recipients with `GAUGE_RESEND_ALLOWED_RECIPIENTS`, or turned approval off with `GAUGE_RESEND_REQUIRE_CONFIRM=false`.
+- Give Gauge the least access it needs: a view-only Umami user, and a Resend key limited to sending if you don't need the other email tools.
+
+## Develop
+
+```bash
+uv venv && uv pip install -e '.[dev]'
+.venv/bin/pytest
+```
+
+## License
+
+MIT. Published by Seaynic Labs.

gauge_mcp-0.1.0/README.md

@@ -0,0 +1,127 @@
+# Gauge
+
+<!-- mcp-name: io.github.seayniclabs/gauge -->
+
+Gauge is an MCP server for people running a small website. It lets an AI assistant read your site's analytics and send email, from one install.
+
+It is a **bundle**: one server made of modules. You switch on the modules you use. New modules arrive switched off, so an update never changes what your assistant can do until you choose to.
+
+| Module | What it does | Status |
+|---|---|---|
+| `umami` | Web analytics from [Umami](https://umami.is), self-hosted or Umami Cloud: sites, totals, time series, top pages, referrers, countries, browsers | 0.1 |
+| `resend` | Email through [Resend](https://resend.com): send (preview first), list sent mail, list sending domains | 0.1 |
+
+Gauge works with any MCP client: Claude Desktop, Claude Code, Cursor, VS Code, Sonique, Hermes, OpenClaw and others. It runs on your computer and stores nothing; your data stays in Umami and Resend.
+
+## Install
+
+Gauge needs Python 3.11 or newer. With [uv](https://docs.astral.sh/uv/) you don't install anything ahead of time:
+
+```bash
+uvx gauge-mcp --version
+```
+
+Or with pip:
+
+```bash
+pip install gauge-mcp
+```
+
+## Settings
+
+Set these as environment variables in your MCP client's config, or put them in a config file (see below). You only need the settings for the modules you use. Gauge starts without any of them and tells you what's missing when you call a tool.
+
+| Variable | Module | What it is |
+|---|---|---|
+| `GAUGE_UMAMI_URL` | umami | Your Umami address, e.g. `https://analytics.example.com` |
+| `GAUGE_UMAMI_USERNAME` / `GAUGE_UMAMI_PASSWORD` | umami | A self-hosted Umami login. A view-only user is enough. |
+| `GAUGE_UMAMI_API_KEY` | umami | Umami Cloud API key (instead of a login). `GAUGE_UMAMI_URL` defaults to Umami Cloud when this is set. |
+| `GAUGE_RESEND_API_KEY` | resend | Resend API key |
+| `GAUGE_RESEND_FROM` | resend | Sender address on a domain you verified in Resend |
+| `GAUGE_RESEND_FROM_NAME` | resend | Optional sender display name |
+| `GAUGE_RESEND_ALLOWED_RECIPIENTS` | resend | Optional. Comma-separated addresses or `@domains` the assistant may send to without asking you each time, e.g. `me@example.com,@example.com` |
+| `GAUGE_RESEND_REQUIRE_CONFIRM` | resend | `true` by default: you approve each send. `false` lets the assistant send on its own. |
+| `GAUGE_<MODULE>_ENABLED` | any | `false` turns a module off, e.g. `GAUGE_RESEND_ENABLED=false` |
+
+**Config file (optional).** Gauge also reads `~/.config/gauge/config.toml`, or the file named by `GAUGE_CONFIG`. Environment variables win over the file.
+
+```toml
+[umami]
+url = "https://analytics.example.com"
+username = "viewer"
+password = "change-me"
+
+[resend]
+enabled = false
+```
+
+## Add it to your MCP client
+
+Most clients use the same JSON shape. Put it where your client keeps MCP servers:
+
+```json
+{
+  "mcpServers": {
+    "gauge": {
+      "command": "uvx",
+      "args": ["gauge-mcp"],
+      "env": {
+        "GAUGE_UMAMI_URL": "https://analytics.example.com",
+        "GAUGE_UMAMI_USERNAME": "viewer",
+        "GAUGE_UMAMI_PASSWORD": "change-me",
+        "GAUGE_RESEND_API_KEY": "re_your_key",
+        "GAUGE_RESEND_FROM": "hello@example.com"
+      }
+    }
+  }
+}
+```
+
+| Client | Where the config goes |
+|---|---|
+| Claude Desktop | `claude_desktop_config.json` (Settings → Developer → Edit Config) |
+| Claude Code | `claude mcp add gauge -- uvx gauge-mcp`, then add the `env` values, or a project `.mcp.json` |
+| Cursor | `~/.cursor/mcp.json`, or `.cursor/mcp.json` in a project |
+| VS Code | `.vscode/mcp.json`, using `"servers"` instead of `"mcpServers"` |
+| Sonique, Hermes, OpenClaw, others | Any client that launches a stdio MCP server: command `uvx`, args `["gauge-mcp"]`, plus the env values |
+
+**Over HTTP.** For clients that connect to a URL instead of launching a process:
+
+```bash
+gauge-mcp --transport http --port 8765
+```
+
+It serves streamable HTTP at `http://127.0.0.1:8765/mcp`. It listens only on your own machine by default. Put authentication in front of it before exposing it anywhere else.
+
+## Tools
+
+| Tool | What it returns |
+|---|---|
+| `gauge_modules` | Which modules are on, which settings are missing, and what each tool does. Call this first. |
+| `umami_websites` | Tracked websites, paged |
+| `umami_stats` | Pageviews, visitors, visits, bounces and bounce rate for a date range |
+| `umami_pageviews` | Pageviews and sessions over time |
+| `umami_metrics` | A ranked breakdown: `type` = `path` (top pages), `referrer`, `country`, `browser`, `os`, `device` and more |
+| `resend_send` | Sends an email after you approve it. Without `confirm=true` it only returns a preview. |
+| `resend_emails` | Sent emails, paged with a cursor |
+| `resend_domains` | Sending domains and whether each is verified |
+
+Every tool returns structured data with a published schema, so an assistant can write code against the results instead of reading text. Date ranges take `days` (default 7) or ISO 8601 `start` and `end`. Errors always look like `gauge.<module>.<code>: <message> Fix: <hint>`.
+
+## Safety
+
+- Gauge only calls the services you configure. It sends nothing anywhere else and keeps no data.
+- `resend_send` sends real email, so **you** approve each one, not the assistant. When the assistant asks to send, Gauge asks you directly through your MCP client (MCP elicitation) and shows the sender, recipients and subject. The assistant can't answer that question for you.
+- Some MCP clients can't ask you questions yet. In those, Gauge refuses to send unless you've pre-approved the recipients with `GAUGE_RESEND_ALLOWED_RECIPIENTS`, or turned approval off with `GAUGE_RESEND_REQUIRE_CONFIRM=false`.
+- Give Gauge the least access it needs: a view-only Umami user, and a Resend key limited to sending if you don't need the other email tools.
+
+## Develop
+
+```bash
+uv venv && uv pip install -e '.[dev]'
+.venv/bin/pytest
+```
+
+## License
+
+MIT. Published by Seaynic Labs.

gauge_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "gauge-mcp"
+version = "0.1.0"
+description = "MCP bundle for people running a small website: web analytics (Umami) and email (Resend) in one server."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Seaynic Labs" }]
+# mcp is capped below 2: 2.x removed FastMCP, and unpinned installs crash.
+dependencies = [
+    "mcp[cli]>=1.27,<2",
+    "httpx>=0.27",
+    "pydantic>=2.7",
+]
+keywords = ["mcp", "model-context-protocol", "umami", "resend", "analytics", "email"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Repository = "https://github.com/seayniclabs/gauge"
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.scripts]
+gauge-mcp = "gauge_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gauge_mcp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

gauge_mcp-0.1.0/scripts/scan_identifiers.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""Fail if any tracked file contains a forbidden string.
+
+The patterns are not stored in this repository. Pass them in with
+``--patterns FILE`` or the ``IDENTIFIER_PATTERNS`` environment variable
+(one case-insensitive regular expression per line; ``#`` starts a comment).
+A line starting with ``!`` is an allowed exception: a match that also matches
+an exception is ignored.
+
+Usage:  python scripts/scan_identifiers.py --patterns ~/patterns.txt [path ...]
+Exit status 0 = clean, 1 = hits found, 2 = no patterns given.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+
+def load(text: str) -> tuple[list[re.Pattern], list[re.Pattern]]:
+    block, allow = [], []
+    for line in text.splitlines():
+        line = line.split(" #", 1)[0].strip()
+        if not line or line.startswith("#"):
+            continue
+        (allow if line.startswith("!") else block).append(re.compile(line.lstrip("!"), re.I))
+    return block, allow
+
+
+def tracked_files(root: Path) -> list[Path]:
+    try:
+        out = subprocess.run(["git", "ls-files", "-co", "--exclude-standard"], cwd=root,
+                             capture_output=True, text=True, check=True).stdout
+        return [root / p for p in out.splitlines()]
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        skip = {".git", ".venv", "venv", "node_modules", "__pycache__", "dist", "build"}
+        return [p for p in root.rglob("*") if p.is_file() and not skip & set(p.parts)]
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--patterns", help="file of patterns (default: $IDENTIFIER_PATTERNS)")
+    ap.add_argument("paths", nargs="*", default=["."])
+    args = ap.parse_args()
+
+    text = Path(args.patterns).expanduser().read_text() if args.patterns else os.environ.get("IDENTIFIER_PATTERNS", "")
+    block, allow = load(text)
+    if not block:
+        print("scan_identifiers: no patterns given (use --patterns or IDENTIFIER_PATTERNS)", file=sys.stderr)
+        return 2
+
+    hits = 0
+    for root in map(Path, args.paths):
+        for f in tracked_files(root) if root.is_dir() else [root]:
+            try:
+                lines = f.read_text(errors="ignore").splitlines()
+            except OSError:
+                continue
+            for n, line in enumerate(lines, 1):
+                for pat in block:
+                    for m in pat.finditer(line):
+                        if any(a.search(line) for a in allow):
+                            continue
+                        hits += 1
+                        # Print where, not the line itself: the line may hold the thing we're hiding.
+                        print(f"{f}:{n}: matches pattern #{block.index(pat) + 1}")
+    print(f"scan_identifiers: {hits} hit(s)", file=sys.stderr)
+    return 1 if hits else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

gauge_mcp-0.1.0/server.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.seayniclabs/gauge",
+  "description": "Website analytics (Umami) and email (Resend) for an AI assistant, as one MCP bundle.",
+  "repository": {
+    "url": "https://github.com/seayniclabs/gauge",
+    "source": "github"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "gauge-mcp",
+      "version": "0.1.0",
+      "transport": { "type": "stdio" },
+      "environmentVariables": [
+        { "name": "GAUGE_UMAMI_URL", "description": "Your Umami address", "isRequired": false },
+        { "name": "GAUGE_UMAMI_USERNAME", "description": "Self-hosted Umami login", "isRequired": false },
+        { "name": "GAUGE_UMAMI_PASSWORD", "description": "Password for that login", "isRequired": false, "isSecret": true },
+        { "name": "GAUGE_UMAMI_API_KEY", "description": "Umami Cloud API key", "isRequired": false, "isSecret": true },
+        { "name": "GAUGE_RESEND_API_KEY", "description": "Resend API key", "isRequired": false, "isSecret": true },
+        { "name": "GAUGE_RESEND_FROM", "description": "Sender address on a verified domain", "isRequired": false }
+      ]
+    }
+  ]
+}

gauge_mcp-0.1.0/src/gauge_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Gauge: an MCP bundle for people running a small website."""
+
+__version__ = "0.1.0"

gauge_mcp-0.1.0/src/gauge_mcp/config.py

@@ -0,0 +1,56 @@
+"""Settings come from environment variables, then an optional TOML file.
+
+Environment variables win. The file is ``$GAUGE_CONFIG`` if set, otherwise
+``$XDG_CONFIG_HOME/gauge/config.toml`` (``~/.config/gauge/config.toml``).
+Each module reads its own ``[<module>]`` table; ``GAUGE_<MODULE>_<KEY>`` overrides
+any key in it. Nothing here assumes a particular MCP client.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from pathlib import Path
+from typing import Mapping
+
+TRUE = {"1", "true", "yes", "on"}
+FALSE = {"0", "false", "no", "off"}
+
+
+def config_path(env: Mapping[str, str]) -> Path:
+    if env.get("GAUGE_CONFIG"):
+        return Path(env["GAUGE_CONFIG"]).expanduser()
+    base = env.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    return Path(base) / "gauge" / "config.toml"
+
+
+class Config:
+    def __init__(self, env: Mapping[str, str] | None = None, file_data: dict | None = None):
+        self.env = dict(os.environ if env is None else env)
+        if file_data is None:
+            path = config_path(self.env)
+            file_data = tomllib.loads(path.read_text()) if path.is_file() else {}
+        self.file = file_data
+
+    def get(self, module: str, key: str, default: str | None = None) -> str | None:
+        value = self.env.get(f"GAUGE_{module.upper()}_{key.upper()}")
+        if value not in (None, ""):
+            return value
+        value = self.file.get(module, {}).get(key)
+        if value not in (None, ""):
+            return str(value)
+        return default
+
+    def flag(self, module: str, key: str, default: bool) -> bool:
+        value = self.get(module, key)
+        if value is None:
+            return default
+        value = value.strip().lower()
+        if value in TRUE:
+            return True
+        if value in FALSE:
+            return False
+        return default
+
+    def enabled(self, module: str, default: bool) -> bool:
+        return self.flag(module, "enabled", default)

gauge_mcp-0.1.0/src/gauge_mcp/errors.py

@@ -0,0 +1,26 @@
+"""One error shape for every module, so scripts can rely on it.
+
+Every failure a tool reports reads: ``gauge.<module>.<code>: <message> Fix: <hint>``.
+"""
+
+from mcp.server.fastmcp.exceptions import ToolError
+
+
+class GaugeError(ToolError):
+    def __init__(self, module: str, code: str, message: str, hint: str = ""):
+        self.module = module
+        self.code = code
+        text = f"gauge.{module}.{code}: {message}"
+        if hint:
+            text += f" Fix: {hint}"
+        super().__init__(text)
+
+
+def not_configured(module: str, missing: list[str]) -> GaugeError:
+    return GaugeError(
+        module,
+        "not_configured",
+        f"missing setting(s) {', '.join(missing)}.",
+        "set them as environment variables or in the [" + module + "] section of the "
+        "config file, then restart the server. Call gauge_modules to see every setting.",
+    )

gauge_mcp-0.1.0/src/gauge_mcp/modules/__init__.py

@@ -0,0 +1,71 @@
+"""Module contract and registry.
+
+A module is one integration (Umami, Resend, ...). It declares its settings and
+registers its tools on the shared server. Adding a module = adding a file here and
+listing it in ``MODULES``. Modules added after 0.1 must set ``default_enabled = False``
+so an update never turns on something the user did not choose.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+from ..config import Config
+from ..errors import not_configured
+
+ClientFactory = Callable[[], httpx.AsyncClient]
+
+
+def default_client_factory() -> httpx.AsyncClient:
+    return httpx.AsyncClient(timeout=10.0)
+
+
+@dataclass(frozen=True)
+class Setting:
+    key: str
+    help: str
+    secret: bool = False
+    required: bool = True
+
+    def env_var(self, module: str) -> str:
+        return f"GAUGE_{module.upper()}_{self.key.upper()}"
+
+
+@dataclass
+class Module:
+    name: str
+    summary: str
+    settings: list[Setting]
+    default_enabled: bool = True
+    tools: dict[str, str] = field(default_factory=dict)  # tool name -> one-line purpose
+
+    def missing(self, config: Config) -> list[str]:
+        return [
+            s.env_var(self.name)
+            for s in self.settings
+            if s.required and not config.get(self.name, s.key)
+        ]
+
+    def require(self, config: Config, *keys: str) -> dict[str, str]:
+        """Return the named settings, or raise a not_configured error naming the env vars."""
+        values = {k: config.get(self.name, k) for k in keys}
+        absent = [
+            s.env_var(self.name) for s in self.settings if s.key in keys and not values[s.key]
+        ]
+        if absent:
+            raise not_configured(self.name, absent)
+        return values  # type: ignore[return-value]
+
+    def register(self, mcp: FastMCP, config: Config, client_factory: ClientFactory) -> None:
+        raise NotImplementedError
+
+
+def all_modules() -> list[Module]:
+    from .resend import ResendModule
+    from .umami import UmamiModule
+
+    return [UmamiModule(), ResendModule()]