org-cost-mcp 0.0.12__tar.gz

org_cost_mcp-0.0.12/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/

org_cost_mcp-0.0.12/Dockerfile

@@ -0,0 +1,16 @@
+# syntax=docker/dockerfile:1
+
+FROM python:3.12-slim
+WORKDIR /app
+RUN adduser --disabled-password --gecos "" app
+COPY pyproject.toml README.md ./
+COPY org_cost_mcp ./org_cost_mcp
+RUN pip install --no-cache-dir . \
+	&& chown -R app:app /app
+USER app
+EXPOSE 8090
+ENV CHAT_HOST=0.0.0.0
+ENV CHAT_PORT=8090
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+	CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8090/v1/chat/health')" || exit 1
+CMD ["org-cost-chat"]

org_cost_mcp-0.0.12/Dockerfile.mcp

@@ -0,0 +1,15 @@
+# syntax=docker/dockerfile:1
+
+FROM python:3.12-slim
+WORKDIR /app
+RUN adduser --disabled-password --gecos "" app
+COPY pyproject.toml README.md ./
+COPY org_cost_mcp ./org_cost_mcp
+RUN pip install --no-cache-dir . \
+	&& chown -R app:app /app
+USER app
+EXPOSE 8000
+ENV MCP_TRANSPORT=streamable-http
+ENV MCP_HOST=0.0.0.0
+ENV MCP_PORT=8000
+CMD ["org-cost-mcp"]

org_cost_mcp-0.0.12/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.5
+Name: org-cost-mcp
+Version: 0.0.12
+Summary: MCP server for AWS Org Cost Explorer (read-only dashboard API tools)
+Project-URL: Homepage, https://github.com/kaskol10/org-cost-api
+Project-URL: Documentation, https://github.com/kaskol10/org-cost-api#readme
+Project-URL: Repository, https://github.com/kaskol10/org-cost-api
+Project-URL: Issues, https://github.com/kaskol10/org-cost-api/issues
+Author: org-cost-api contributors
+License: MIT
+Keywords: aws,cost-explorer,finops,hermes,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: litellm>=1.55.0
+Requires-Dist: mcp<2,>=1.2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: uvicorn[standard]>=0.32.0
+Provides-Extra: dev
+Requires-Dist: httpx; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# org-cost-api MCP server
+
+Read-only [Model Context Protocol](https://modelcontextprotocol.io) server for [Hermes Agent](https://github.com/nousresearch/hermes-agent), Cursor, and other MCP hosts. Wraps the Go dashboard API so agents can explain AWS org costs **without AWS credentials in the LLM process**.
+
+## Install (PyPI)
+
+```bash
+pip install org-cost-mcp
+```
+
+## Quick start
+
+```bash
+# Point at a running API (demo or production)
+export ORG_COST_API_URL=http://localhost:8080
+# When API auth is enabled:
+# export ORG_COST_API_TOKEN=your-token
+
+org-cost-mcp
+```
+
+**Try without AWS:** run the demo API first:
+
+```bash
+docker compose -f docker-compose.demo.yml up --build
+export ORG_COST_API_URL=http://localhost:8080
+org-cost-mcp
+```
+
+## Development install
+
+```bash
+cd mcp-server
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+See **[docs/integrate-quickstart.md](../docs/integrate-quickstart.md)** (15 min) · details: **[docs/mcp-setup.md](../docs/mcp-setup.md)**
+
+Public demo API: `https://org-cost-api-demo.fly.dev` (no AWS, no token).
+
+## Transport
+
+| Mode | Command / endpoint |
+|------|---------------------|
+| **stdio** (default) | `org-cost-mcp` — Cursor, Hermes, Claude Desktop |
+| **SSE** | `MCP_TRANSPORT=sse org-cost-mcp` → `http://host:8000/sse` |
+| **Streamable HTTP** | `MCP_TRANSPORT=streamable-http org-cost-mcp` → `http://host:8000/mcp` |
+
+Remote HTTP: `docker compose -f docker-compose.mcp-http.yml up` — see [mcp-setup.md § Remote MCP](../docs/mcp-setup.md#9-remote-mcp-httpsse).
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `check_mcp_alive` | Ping MCP process only (no API call) |
+| `check_api_health` | API health, readiness, demo flag, and auth (when token set) |
+| `check_chat_health` | Ask / LLM config status (no LLM call) |
+| `list_accounts` | Configured account names and IDs |
+| `get_org_summary` | Org totals + top services |
+| `get_cost_trends` | Current vs prior period (history-first) |
+| `get_cost_anomalies` | Daily spikes/drops vs 14-day baseline, account attribution |
+| `get_forecast` | Projected end-of-month spend vs budgets |
+| `get_cost_suggestions` | Ranked cost optimization suggestions |
+| `get_cost_report` | Markdown + Mermaid; writes `~/.org-cost/reports/latest.html` |
+| `get_account_costs` | One account's spend and top services |
+| `get_waste_signals` | Unattached EBS, snapshots by account |
+| `get_service_detail` | Region / usage type / tag Name breakdown |
+| `get_service_tag_delta` | Tag-bucket spend changes vs prior period |
+| `get_service_tag_totals` | Top tag buckets for a service |
+| `ask_cost_question` | Natural-language Q&A (same API as browser Ask tab) |
+
+**CE discipline:** default `refresh=false`. Use refresh sparingly — each refresh can trigger live AWS API calls in production mode.
+
+## Conversational Ask (`org-cost-chat`)
+
+HTTP chat agent for multi-turn browser Ask. Supports **org LiteLLM proxy**, **direct vLLM**, or any OpenAI-compatible endpoint:
+
+```bash
+# LiteLLM org proxy (default)
+export ORG_COST_API_URL=http://localhost:8080
+export LLM_BASE_URL=https://litellm.internal/v1
+export LLM_API_KEY=your-key
+export LLM_MODEL=claude-sonnet-4-20250514
+
+# Or local vLLM
+export LLM_PROVIDER=vllm
+export LLM_MODEL=meta-llama/Meta-Llama-3-8B-Instruct
+export VLLM_BASE_URL=http://localhost:8000/v1
+
+org-cost-chat
+```
+
+Frontend: `VITE_CHAT_URL=http://localhost:8090`. Full guide: [docs/chat-setup.md](../docs/chat-setup.md).
+
+Docker: `docker compose -f docker-compose.chat.yml up --build`
+
+## Environment
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ORG_COST_API_URL` | `http://localhost:8080` | Go API base URL |
+| `ORG_COST_API_TOKEN` | (empty) | Bearer token when API auth is on |
+| `ORG_COST_API_TIMEOUT_SECONDS` | `120` | Read timeout for slow dashboard builds |
+| `MCP_TRANSPORT` | `stdio` | `stdio`, `sse`, or `streamable-http` |
+| `MCP_HOST` | `127.0.0.1` | Bind address (`0.0.0.0` for HTTP transports) |
+| `MCP_PORT` | `8000` | Port for HTTP transports |
+| `MCP_ALLOWED_HOSTS` | (empty) | Comma-separated public Host headers for Streamable HTTP behind a proxy |
+
+## Agent setup (Hermes / Cursor)
+
+See **[docs/integrate-quickstart.md](../docs/integrate-quickstart.md)** — 15-minute MCP wiring for Hermes and Cursor.
+Details: **[docs/mcp-setup.md](../docs/mcp-setup.md)** ([Hermes](../docs/mcp-setup.md#3-hermes-setup), [Cursor](../docs/mcp-setup.md#4-cursor-setup), [Remote MCP](../docs/mcp-setup.md#9-remote-mcp-httpsse)).
+
+Org-hosted Hermes: [docs/hermes-nous-deployment.md](../docs/hermes-nous-deployment.md).
+
+## License
+
+MIT — see [LICENSE](../LICENSE).

org_cost_mcp-0.0.12/README.md

@@ -0,0 +1,121 @@
+# org-cost-api MCP server
+
+Read-only [Model Context Protocol](https://modelcontextprotocol.io) server for [Hermes Agent](https://github.com/nousresearch/hermes-agent), Cursor, and other MCP hosts. Wraps the Go dashboard API so agents can explain AWS org costs **without AWS credentials in the LLM process**.
+
+## Install (PyPI)
+
+```bash
+pip install org-cost-mcp
+```
+
+## Quick start
+
+```bash
+# Point at a running API (demo or production)
+export ORG_COST_API_URL=http://localhost:8080
+# When API auth is enabled:
+# export ORG_COST_API_TOKEN=your-token
+
+org-cost-mcp
+```
+
+**Try without AWS:** run the demo API first:
+
+```bash
+docker compose -f docker-compose.demo.yml up --build
+export ORG_COST_API_URL=http://localhost:8080
+org-cost-mcp
+```
+
+## Development install
+
+```bash
+cd mcp-server
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+See **[docs/integrate-quickstart.md](../docs/integrate-quickstart.md)** (15 min) · details: **[docs/mcp-setup.md](../docs/mcp-setup.md)**
+
+Public demo API: `https://org-cost-api-demo.fly.dev` (no AWS, no token).
+
+## Transport
+
+| Mode | Command / endpoint |
+|------|---------------------|
+| **stdio** (default) | `org-cost-mcp` — Cursor, Hermes, Claude Desktop |
+| **SSE** | `MCP_TRANSPORT=sse org-cost-mcp` → `http://host:8000/sse` |
+| **Streamable HTTP** | `MCP_TRANSPORT=streamable-http org-cost-mcp` → `http://host:8000/mcp` |
+
+Remote HTTP: `docker compose -f docker-compose.mcp-http.yml up` — see [mcp-setup.md § Remote MCP](../docs/mcp-setup.md#9-remote-mcp-httpsse).
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `check_mcp_alive` | Ping MCP process only (no API call) |
+| `check_api_health` | API health, readiness, demo flag, and auth (when token set) |
+| `check_chat_health` | Ask / LLM config status (no LLM call) |
+| `list_accounts` | Configured account names and IDs |
+| `get_org_summary` | Org totals + top services |
+| `get_cost_trends` | Current vs prior period (history-first) |
+| `get_cost_anomalies` | Daily spikes/drops vs 14-day baseline, account attribution |
+| `get_forecast` | Projected end-of-month spend vs budgets |
+| `get_cost_suggestions` | Ranked cost optimization suggestions |
+| `get_cost_report` | Markdown + Mermaid; writes `~/.org-cost/reports/latest.html` |
+| `get_account_costs` | One account's spend and top services |
+| `get_waste_signals` | Unattached EBS, snapshots by account |
+| `get_service_detail` | Region / usage type / tag Name breakdown |
+| `get_service_tag_delta` | Tag-bucket spend changes vs prior period |
+| `get_service_tag_totals` | Top tag buckets for a service |
+| `ask_cost_question` | Natural-language Q&A (same API as browser Ask tab) |
+
+**CE discipline:** default `refresh=false`. Use refresh sparingly — each refresh can trigger live AWS API calls in production mode.
+
+## Conversational Ask (`org-cost-chat`)
+
+HTTP chat agent for multi-turn browser Ask. Supports **org LiteLLM proxy**, **direct vLLM**, or any OpenAI-compatible endpoint:
+
+```bash
+# LiteLLM org proxy (default)
+export ORG_COST_API_URL=http://localhost:8080
+export LLM_BASE_URL=https://litellm.internal/v1
+export LLM_API_KEY=your-key
+export LLM_MODEL=claude-sonnet-4-20250514
+
+# Or local vLLM
+export LLM_PROVIDER=vllm
+export LLM_MODEL=meta-llama/Meta-Llama-3-8B-Instruct
+export VLLM_BASE_URL=http://localhost:8000/v1
+
+org-cost-chat
+```
+
+Frontend: `VITE_CHAT_URL=http://localhost:8090`. Full guide: [docs/chat-setup.md](../docs/chat-setup.md).
+
+Docker: `docker compose -f docker-compose.chat.yml up --build`
+
+## Environment
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ORG_COST_API_URL` | `http://localhost:8080` | Go API base URL |
+| `ORG_COST_API_TOKEN` | (empty) | Bearer token when API auth is on |
+| `ORG_COST_API_TIMEOUT_SECONDS` | `120` | Read timeout for slow dashboard builds |
+| `MCP_TRANSPORT` | `stdio` | `stdio`, `sse`, or `streamable-http` |
+| `MCP_HOST` | `127.0.0.1` | Bind address (`0.0.0.0` for HTTP transports) |
+| `MCP_PORT` | `8000` | Port for HTTP transports |
+| `MCP_ALLOWED_HOSTS` | (empty) | Comma-separated public Host headers for Streamable HTTP behind a proxy |
+
+## Agent setup (Hermes / Cursor)
+
+See **[docs/integrate-quickstart.md](../docs/integrate-quickstart.md)** — 15-minute MCP wiring for Hermes and Cursor.
+Details: **[docs/mcp-setup.md](../docs/mcp-setup.md)** ([Hermes](../docs/mcp-setup.md#3-hermes-setup), [Cursor](../docs/mcp-setup.md#4-cursor-setup), [Remote MCP](../docs/mcp-setup.md#9-remote-mcp-httpsse)).
+
+Org-hosted Hermes: [docs/hermes-nous-deployment.md](../docs/hermes-nous-deployment.md).
+
+## License
+
+MIT — see [LICENSE](../LICENSE).

org_cost_mcp-0.0.12/org_cost_mcp/__init__.py

@@ -0,0 +1 @@
+"""Read-only MCP tools for the AWS Org Cost Explorer Go API."""

org_cost_mcp-0.0.12/org_cost_mcp/account_costs.py

@@ -0,0 +1,28 @@
+"""Account cost JSON shaping for MCP tools."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def shape_account_costs(acct: dict[str, Any]) -> dict[str, Any]:
+    """Map /api/account-costs (or dashboard account) JSON to MCP output."""
+    costs = acct.get("costs") or {}
+    period = acct.get("period") or {"start": costs.get("start"), "end": costs.get("end")}
+    return {
+        "account_id": acct.get("account_id"),
+        "account_name": acct.get("account_name"),
+        "period": period,
+        "all_services_total_usd": costs.get("all_total"),
+        "ec2_other_usd": costs.get("total"),
+        "other_services_usd": costs.get("other_services_total"),
+        "top_services": costs.get("by_service") or [],
+        "usage_categories": [
+            {
+                "id": c.get("id"),
+                "label": c.get("label"),
+                "amount": c.get("amount"),
+            }
+            for c in (costs.get("usage_categories") or [])[:8]
+        ],
+    }

org_cost_mcp-0.0.12/org_cost_mcp/agent.py

@@ -0,0 +1,169 @@
+"""LiteLLM tool-calling agent loop for conversational Ask."""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from typing import Any
+
+import litellm
+
+from org_cost_mcp.llm_config import llm_completion_kwargs
+from org_cost_mcp.tools import TOOL_SCHEMAS, ce_calls_in_result, execute_tool
+
+SYSTEM_PROMPT = """You are a read-only AWS organization cost assistant.
+
+Rules:
+- Always call tools before stating dollar amounts or trends.
+- Default refresh=false; only pass refresh=true when the user explicitly asks for live AWS data.
+- Cite the reporting period and data source when answering.
+- Be concise; use markdown lists for breakdowns.
+- For follow-up questions, use conversation context but re-fetch data when amounts may have changed.
+"""
+
+
+def _env_int(name: str, default: int) -> int:
+    raw = os.environ.get(name, "").strip()
+    if raw:
+        try:
+            return int(raw)
+        except ValueError:
+            pass
+    return default
+
+
+@dataclass
+class AgentResult:
+    content: str = ""
+    tools_called: list[str] = field(default_factory=list)
+    ce_calls_used: int = 0
+
+
+@dataclass
+class AgentEvent:
+    kind: str
+    data: dict[str, Any] = field(default_factory=dict)
+
+
+def _message_content(msg: dict[str, Any]) -> str:
+    content = msg.get("content")
+    if content is None:
+        return ""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts: list[str] = []
+        for block in content:
+            if isinstance(block, dict) and block.get("type") == "text":
+                parts.append(str(block.get("text", "")))
+        return "".join(parts)
+    return str(content)
+
+
+def _tool_calls(msg: dict[str, Any]) -> list[dict[str, Any]]:
+    raw = msg.get("tool_calls")
+    if not raw:
+        return []
+    return list(raw)
+
+
+def run_agent(
+    messages: list[dict[str, Any]],
+    *,
+    default_refresh: bool = False,
+    stream: bool = False,
+) -> AgentResult | Iterator[AgentEvent]:
+    if stream:
+        return _run_agent_stream(messages, default_refresh=default_refresh)
+    return _run_agent_sync(messages, default_refresh=default_refresh)
+
+
+def _apply_default_refresh(args: dict[str, Any], default_refresh: bool) -> dict[str, Any]:
+    out = dict(args)
+    if "refresh" not in out and default_refresh:
+        out["refresh"] = True
+    return out
+
+
+def _run_agent_sync(
+    messages: list[dict[str, Any]],
+    *,
+    default_refresh: bool,
+) -> AgentResult:
+    working = [{"role": "system", "content": SYSTEM_PROMPT}, *messages]
+    max_rounds = _env_int("CHAT_MAX_TOOL_ROUNDS", 8)
+    tools_called: list[str] = []
+    ce_total = 0
+    llm_kwargs = llm_completion_kwargs()
+
+    for _ in range(max_rounds):
+        response = litellm.completion(
+            messages=working,
+            tools=TOOL_SCHEMAS,
+            tool_choice="auto",
+            stream=False,
+            **llm_kwargs,
+        )
+        choice = response.choices[0].message
+        assistant_msg = choice.model_dump(exclude_none=True)
+        working.append(assistant_msg)
+
+        calls = _tool_calls(assistant_msg)
+        if not calls:
+            return AgentResult(
+                content=_message_content(assistant_msg),
+                tools_called=tools_called,
+                ce_calls_used=ce_total,
+            )
+
+        for call in calls:
+            fn = call.get("function") or {}
+            name = fn.get("name", "")
+            raw_args = fn.get("arguments") or "{}"
+            try:
+                args = json.loads(raw_args) if isinstance(raw_args, str) else raw_args
+            except json.JSONDecodeError:
+                args = {}
+            if not isinstance(args, dict):
+                args = {}
+            args = _apply_default_refresh(args, default_refresh)
+            tools_called.append(name)
+            result = execute_tool(name, args)
+            ce_total += ce_calls_in_result(result)
+            working.append(
+                {
+                    "role": "tool",
+                    "tool_call_id": call.get("id"),
+                    "name": name,
+                    "content": result,
+                }
+            )
+
+    return AgentResult(
+        content="I reached the tool-call limit. Please try a narrower question.",
+        tools_called=tools_called,
+        ce_calls_used=ce_total,
+    )
+
+
+def _run_agent_stream(
+    messages: list[dict[str, Any]],
+    *,
+    default_refresh: bool,
+) -> Iterator[AgentEvent]:
+    result = _run_agent_sync(messages, default_refresh=default_refresh)
+    if result.tools_called:
+        for name in result.tools_called:
+            yield AgentEvent("tool_end", {"name": name})
+    # v1: emit full answer as one delta (LiteLLM streaming + tools is complex)
+    if result.content:
+        yield AgentEvent("delta", {"text": result.content})
+    yield AgentEvent(
+        "done",
+        {
+            "tools_called": result.tools_called,
+            "ce_calls_used": result.ce_calls_used,
+        },
+    )