geneva-mcp 1.0.2__tar.gz

geneva_mcp-1.0.2/.gitignore

@@ -0,0 +1,89 @@
+# ─── Secrets & credentials ─────────────────────────────────────────
+.env
+.env.*
+!.env.example
+admin_key.txt
+
+# ─── Databases ─────────────────────────────────────────────────────
+*.db
+*.db-journal
+*.sqlite
+*.sqlite3
+
+# ─── Python ────────────────────────────────────────────────────────
+venv/
+.venv/
+batch-venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.egg
+.pytest_cache/
+
+# ─── Node.js ───────────────────────────────────────────────────────
+node_modules/
+.next/
+.vite/
+dist-ssr/
+*.local
+*.tsbuildinfo
+
+# ─── Compiled binaries & static libraries ──────────────────────────
+*.a
+*.o
+*.so
+*.dylib
+testintel
+testsparc
+
+# ─── Build & output ───────────────────────────────────────────────
+out/
+
+# ─── Benchmark output (generated images & logs) ───────────────────
+benchmarks/single_forecast_benchmarks/
+benchmarks/batch_benchmarks/
+benchmarks/logs/
+benchmarks/forecast_visualization.png
+
+# ─── Engine output files (generated during local runs) ────────────
+engine/genfit.txt
+engine/genhist.txt
+engine/genparam.txt
+engine/genplan.txt
+engine/genseas.txt
+engine/load_data.txt
+
+# ─── OS files ──────────────────────────────────────────────────────
+.DS_Store
+Thumbs.db
+
+# ─── Editor & IDE ─────────────────────────────────────────────────
+.vscode/*
+!.vscode/extensions.json
+!.vscode/settings.json
+.idea/
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# ─── Docker ────────────────────────────────────────────────────────
+# Keep Dockerfiles, ignore runtime artifacts
+*.log
+
+# ─── On-Prem Engine ────────────────────────────────────────────────
+# Ed25519 private keys — NEVER commit these
+on-prem-engine/private/keys/*.pem
+# License key files (generated per-client)
+on-prem-engine/client/license.key
+# On-prem venvs
+on-prem-engine/client/venv/
+on-prem-engine/private/venv/
+# On-prem benchmark logs
+benchmarks/on-prem-bench/logs/
+
+# ─── Misc ──────────────────────────────────────────────────────────
+*.docx

geneva_mcp-1.0.2/DEPLOYMENT.md

@@ -0,0 +1,307 @@
+# Geneva MCP Server — Production Deployment Guide
+
+> **Goal:** Make `geneva-mcp` available to the world via PyPI, `uvx`, and the official MCP ecosystem.
+
+---
+
+## Table of Contents
+
+1. [Current Status & What's Done](#1-current-status--whats-done)
+2. [Code Fixes Required Before Publishing](#2-code-fixes-required-before-publishing)
+3. [Publish to PyPI](#3-publish-to-pypi)
+4. [Register in the MCP Ecosystem](#4-register-in-the-mcp-ecosystem)
+5. [Post-Publish Checklist](#5-post-publish-checklist)
+
+---
+
+## 1. Current Status & What's Done
+
+### ✅ Already Production-Ready
+
+| Area | Status |
+|---|---|
+| Core `forecast` tool | ✅ Complete — full Expert System + Holt-Winters fallback |
+| Multimodal output | ✅ Text (markdown) + Image (base64 PNG) |
+| Error handling | ✅ Connection errors, API errors (429/403), generic fallback |
+| Headless charting | ✅ `matplotlib.use("Agg")` — safe for stdio |
+| Agent compatibility | ✅ Claude, ChatGPT, Cursor, Windsurf documented |
+| Security model | ✅ API key via env var, never in chat context |
+| Lazy client singleton | ✅ Thread-safe, no startup cost |
+| README documentation | ✅ Comprehensive with all agent configs |
+
+### ⚠️ Needs Work Before Publishing
+
+| Issue | Impact | Section |
+|---|---|---|
+| Missing `LICENSE` file | PyPI won't include license text | [§2a](#2a-add-license-file) |
+| Missing `[project.scripts]` entry point | `uvx geneva-mcp` won't work | [§2b](#2b-add-cli-entry-point) |
+| `__main__.py` needs `main()` function | Required for script entry point | [§2b](#2b-add-cli-entry-point) |
+| `forecast_horizon` param in server.py | Should use `horizon` to match SDK | [§2c](#2c-fix-parameter-name) |
+| `pyproject.toml` URLs point to `geneva.ai` | Domain doesn't exist | [§2d](#2d-fix-urls-and-metadata) |
+| `geneva-forecast` dependency too loose | Should pin `>=1.0.0` | [§2d](#2d-fix-urls-and-metadata) |
+| Version should be `1.0.0` | First public release | [§2d](#2d-fix-urls-and-metadata) |
+| No `py.typed` marker | Breaks type checking for consumers | [§2e](#2e-add-typing-marker) |
+
+---
+
+## 2. Code Fixes Required Before Publishing
+
+### 2a. Add LICENSE File
+
+Create `mcp-server/LICENSE` — identical MIT license as the SDK:
+
+```
+MIT License
+Copyright (c) 2026 RoadMap Technologies, Inc.
+...
+```
+
+### 2b. Add CLI Entry Point
+
+The `[project.scripts]` entry in `pyproject.toml` lets users run the server with `uvx geneva-mcp` — the **standard way** MCP servers are launched.
+
+**Update `pyproject.toml`:**
+
+```toml
+[project.scripts]
+geneva-mcp = "geneva_mcp.__main__:main"
+```
+
+**Update `__main__.py`:**
+
+```python
+"""Entry point for `python -m geneva_mcp` and `geneva-mcp` CLI."""
+
+from .server import mcp
+
+def main():
+    mcp.run()
+
+if __name__ == "__main__":
+    main()
+```
+
+### 2c. Fix Parameter Name
+
+The `forecast` tool exposes `forecast_horizon` as its parameter name, but the SDK now uses `horizon`. The MCP server also passes `forecast_horizon` directly to the client, which is the raw API field name — this works but is inconsistent with the SDK's public interface.
+
+**In `server.py`:** Change the tool parameter from `forecast_horizon` to `horizon`, and update the kwarg passed to the client:
+
+```python
+# Tool parameter
+def forecast(
+    data: list[float],
+    horizon: int | None = None,  # ← renamed
+    ...
+```
+
+```python
+# Inside the function body
+if horizon is not None:
+    base_kwargs["horizon"] = horizon  # ← SDK handles translation
+```
+
+### 2d. Fix URLs and Metadata
+
+**Update `pyproject.toml`:**
+
+```toml
+[project]
+name = "geneva-mcp"
+version = "1.0.0"
+...
+dependencies = [
+    "mcp>=1.0",
+    "geneva-forecast>=1.0.0",
+    "matplotlib>=3.7",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    ...
+]
+
+[project.urls]
+Homepage = "https://portal.roadmap-tech.com"
+Documentation = "https://portal.roadmap-tech.com/docs"
+```
+
+### 2e. Add Typing Marker
+
+Create `geneva_mcp/py.typed`:
+
+```
+# Marker file for PEP 561.
+```
+
+---
+
+## 3. Publish to PyPI
+
+Once all fixes from §2 are applied:
+
+### 3a. Build
+
+```bash
+cd geneva/mcp-server
+rm -rf dist/
+python3 -m build
+twine check dist/*
+```
+
+### 3b. Upload to PyPI
+
+```bash
+twine upload dist/*
+# Username: __token__
+# Password: your PyPI API token (same one used for geneva-forecast)
+```
+
+### 3c. Verify
+
+```bash
+# Test pip install
+pip install geneva-mcp
+
+# Test uvx (zero-install launch — this is how most users will run it)
+uvx geneva-mcp
+```
+
+Your package will be live at: **https://pypi.org/project/geneva-mcp/**
+
+---
+
+## 4. Register in the MCP Ecosystem
+
+There are **three channels** to get discovered, in order of impact:
+
+### 4a. Official MCP Server Registry (High Priority)
+
+The official registry at [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io) is where tools like Claude Desktop and other clients discover MCP servers programmatically.
+
+**Steps:**
+
+- [ ] Install the publisher CLI: `npm install -g @anthropic/mcp-publisher`
+- [ ] Run `mcp-publisher init` in the `mcp-server/` directory to generate `server.json`
+- [ ] Authenticate: `mcp-publisher login github`
+- [ ] Publish: `mcp-publisher publish`
+
+> **Important:** The registry requires your tool to have `readOnlyHint` annotations. Since `forecast` only reads data and returns results (no side effects), add this annotation to the tool registration when the `mcp` SDK supports it.
+
+### 4b. Anthropic Connectors Directory (High Priority)
+
+The curated directory on `claude.ai/integrations` is Anthropic's reviewed catalog shown to Claude users.
+
+**Steps:**
+
+- [ ] Fill out the **Connectors Directory review form** at [claude.com/connectors](https://claude.com/connectors)
+- [ ] Provide:
+  - Package name: `geneva-mcp`
+  - Install command: `pip install geneva-mcp` or `uvx geneva-mcp`
+  - Category: **Data Analysis / Forecasting**
+  - Security docs: API key via env var, read-only operations
+  - Support channel: your support email
+- [ ] Wait for Anthropic review (they manually review all submissions)
+
+### 4c. Community Lists & Smithery (Medium Priority)
+
+**awesome-mcp-servers (GitHub):**
+
+- [ ] Fork [github.com/modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers)
+- [ ] Add Geneva to the appropriate category in `README.md`
+- [ ] Submit a PR with: name, description, link to PyPI/repo
+
+**Smithery.ai:**
+
+Smithery is a community MCP server registry with a web UI. However, it requires **HTTP transport** (your server uses stdio), so this is lower priority unless you add an HTTP adapter later.
+
+### 4d. Update Developer Portal Docs
+
+- [ ] Add an "MCP Server" section to the SDK docs page
+- [ ] Show `pip install geneva-mcp` install command
+- [ ] Show `uvx geneva-mcp` as the zero-install option
+- [ ] Include agent config examples for Claude, Cursor, Windsurf, ChatGPT
+
+---
+
+## 5. Post-Publish Checklist
+
+### Pre-Publish (Code)
+
+- [x] `LICENSE` file created
+- [x] `[project.scripts]` entry point added
+- [x] `__main__.py` updated with `main()` function
+- [x] `forecast_horizon` → `horizon` in server.py
+- [x] `pyproject.toml` URLs fixed to `portal.roadmap-tech.com`
+- [x] `geneva-forecast>=1.0.0` dependency pinned
+- [x] Version bumped to `1.0.0`
+- [x] `py.typed` marker added
+- [x] `__init__.py` version synced
+
+### Build & Upload
+
+- [ ] `python -m build` succeeds
+- [ ] `twine check dist/*` passes
+- [ ] Uploaded to PyPI
+- [ ] `pip install geneva-mcp` works from clean env
+- [ ] `uvx geneva-mcp` launches the server
+
+### Ecosystem
+
+- [ ] MCP Registry (`mcp-publisher publish`)
+- [ ] Anthropic Connectors Directory (review form submitted)
+- [ ] awesome-mcp-servers PR submitted
+- [ ] Developer portal docs updated
+
+---
+
+## Architecture Note — No Dev/Prod Split Needed
+
+The MCP server is a **single lightweight package** that works identically in development and production. The only difference is the environment variables:
+
+| Setting | Local Dev | Production |
+|---|---|---|
+| `GENEVA_API_URL` | `http://localhost:8000` | `https://api.roadmap-tech.com` |
+| `GENEVA_API_KEY` | Local dev key | Production API key |
+
+The server itself is stateless, produces no side effects beyond temp chart files in `/tmp/geneva-mcp-charts/`, and has no build step or environment-specific code paths.
+
+---
+
+## Troubleshooting
+
+### `No module named geneva_mcp`
+
+**Cause:** The Python binary in your MCP config doesn't have `geneva_mcp` installed.
+
+**Fix:**
+```bash
+# Find which Python your config points to
+# Install into that specific environment:
+/path/to/your/.venv/bin/pip install geneva-mcp
+```
+
+### `GENEVA_API_KEY environment variable is not set`
+
+**Cause:** The `env` block in your MCP config is missing or the key is empty.
+
+**Fix:** Add a valid API key to the `env` section of your agent's config.
+
+### `Server transport closed unexpectedly`
+
+**Cause:** The Python process crashed on startup before the MCP handshake.
+
+**Debug:**
+```bash
+# Run the server manually to see the error:
+GENEVA_API_KEY=gva_test GENEVA_API_URL=http://localhost:8000 \
+  python -m geneva_mcp
+```
+
+### Chart generation fails
+
+**Cause:** `matplotlib` backend issue.
+
+**Fix:** The server hard-codes `matplotlib.use("Agg")` (headless). If you see display errors:
+```bash
+pip install matplotlib --force-reinstall
+```

geneva_mcp-1.0.2/LICENSE

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