agentbill-mcp 0.1.0__tar.gz

agentbill_mcp-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+# Environment — never commit real credentials
+.env
+.env.local
+
+# Dependencies
+node_modules/
+sdk/node/node_modules/
+
+# Build output
+dist/
+sdk/node/dist/
+
+# macOS
+.DS_Store
+
+# Logs
+*.log
+npm-debug.log*

agentbill_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: agentbill-mcp
+Version: 0.1.0
+Summary: AgentBill MCP server. Add spend controls and billing to any AI agent in 3 lines.
+Project-URL: Homepage, https://agentbill.dev
+Project-URL: Repository, https://github.com/marketinglior-pixel/agentbill
+Project-URL: Documentation, https://github.com/marketinglior-pixel/agentbill#readme
+Author-email: AgentBill <marketinglior@gmail.com>
+License: MIT
+Keywords: agent-billing,ai-agents,billing,claude,langchain,llm,mcp,preflight,spend-ceiling,usage-based
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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.9
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp[cli]>=1.0.0
+Description-Content-Type: text/markdown
+
+# agentbill-mcp
+
+AgentBill MCP server. Add spend controls and usage billing to any AI agent in 3 lines.
+
+## What it does
+
+Exposes two tools to any MCP-compatible agent host (Claude Code, Cursor, Windsurf, etc.):
+
+- `preflight(agent_id, customer_id, estimated_units, ceiling)` — check if a customer has budget before starting work. Blocks if exhausted.
+- `record_event(agent_id, units, customer_id, metadata)` — bill a customer after work completes. Idempotent.
+
+## Install
+
+```bash
+uvx agentbill-mcp
+```
+
+No install needed. `uvx` runs it directly.
+
+## Configure
+
+### Claude Code
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "agentbill": {
+      "command": "uvx",
+      "args": ["agentbill-mcp"],
+      "env": {
+        "AGENTBILL_API_KEY": "sk_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Cursor / Windsurf / other MCP clients
+
+Add to your MCP config:
+
+```json
+{
+  "agentbill": {
+    "command": "uvx",
+    "args": ["agentbill-mcp"],
+    "env": {
+      "AGENTBILL_API_KEY": "sk_live_your_key_here"
+    }
+  }
+}
+```
+
+Get your API key at [agentbill.dev/dashboard](https://agentbill.dev/dashboard).
+
+## Usage
+
+Once configured, any agent using this MCP server can:
+
+```
+# Before running a task:
+preflight(agent_id="research_agent", customer_id="user_123", estimated_units=5)
+
+# After completing the task:
+record_event(agent_id="research_agent", units=5, customer_id="user_123")
+```
+
+The server blocks the run if the customer has no remaining budget. No code changes needed in your agent.
+
+## Environment variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `AGENTBILL_API_KEY` | Yes | — | Your AgentBill API key |
+| `AGENTBILL_BASE_URL` | No | `https://agentbill.fly.dev` | Override for self-hosted |
+
+## Links
+
+- Docs: [agentbill.dev](https://agentbill.dev)
+- Python SDK: `pip install agentbill-sdk`
+- GitHub: [github.com/marketinglior-pixel/agentbill](https://github.com/marketinglior-pixel/agentbill)

agentbill_mcp-0.1.0/README.md

@@ -0,0 +1,83 @@
+# agentbill-mcp
+
+AgentBill MCP server. Add spend controls and usage billing to any AI agent in 3 lines.
+
+## What it does
+
+Exposes two tools to any MCP-compatible agent host (Claude Code, Cursor, Windsurf, etc.):
+
+- `preflight(agent_id, customer_id, estimated_units, ceiling)` — check if a customer has budget before starting work. Blocks if exhausted.
+- `record_event(agent_id, units, customer_id, metadata)` — bill a customer after work completes. Idempotent.
+
+## Install
+
+```bash
+uvx agentbill-mcp
+```
+
+No install needed. `uvx` runs it directly.
+
+## Configure
+
+### Claude Code
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "agentbill": {
+      "command": "uvx",
+      "args": ["agentbill-mcp"],
+      "env": {
+        "AGENTBILL_API_KEY": "sk_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Cursor / Windsurf / other MCP clients
+
+Add to your MCP config:
+
+```json
+{
+  "agentbill": {
+    "command": "uvx",
+    "args": ["agentbill-mcp"],
+    "env": {
+      "AGENTBILL_API_KEY": "sk_live_your_key_here"
+    }
+  }
+}
+```
+
+Get your API key at [agentbill.dev/dashboard](https://agentbill.dev/dashboard).
+
+## Usage
+
+Once configured, any agent using this MCP server can:
+
+```
+# Before running a task:
+preflight(agent_id="research_agent", customer_id="user_123", estimated_units=5)
+
+# After completing the task:
+record_event(agent_id="research_agent", units=5, customer_id="user_123")
+```
+
+The server blocks the run if the customer has no remaining budget. No code changes needed in your agent.
+
+## Environment variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `AGENTBILL_API_KEY` | Yes | — | Your AgentBill API key |
+| `AGENTBILL_BASE_URL` | No | `https://agentbill.fly.dev` | Override for self-hosted |
+
+## Links
+
+- Docs: [agentbill.dev](https://agentbill.dev)
+- Python SDK: `pip install agentbill-sdk`
+- GitHub: [github.com/marketinglior-pixel/agentbill](https://github.com/marketinglior-pixel/agentbill)

agentbill_mcp-0.1.0/agentbill_mcp/server.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+import os
+import uuid
+from typing import Optional
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP(
+    "agentbill",
+    instructions=(
+        "AgentBill is billing infrastructure for AI agents. "
+        "Call preflight() before starting any agent work to check if the customer has budget. "
+        "Call record_event() after work completes to bill the customer. "
+        "Set AGENTBILL_API_KEY in your environment before use."
+    ),
+)
+
+BASE_URL = os.getenv("AGENTBILL_BASE_URL", "https://agentbill.fly.dev")
+
+
+def _headers() -> dict:
+    api_key = os.getenv("AGENTBILL_API_KEY")
+    if not api_key:
+        raise ValueError(
+            "AGENTBILL_API_KEY environment variable is not set. "
+            "Get your key at agentbill.dev/dashboard"
+        )
+    return {"Authorization": f"Bearer {api_key}"}
+
+
+@mcp.tool()
+def preflight(
+    agent_id: str,
+    customer_id: str = "default",
+    estimated_units: int = 1,
+    ceiling: Optional[int] = None,
+) -> dict:
+    """
+    Check if an agent is allowed to run before starting work.
+
+    Call this at the start of every agent invocation. Returns approved=True when
+    the customer has remaining budget. Returns approved=False with a reason when
+    the run should be blocked (budget_exhausted, ceiling_exceeded, free_tier_exceeded).
+
+    Args:
+        agent_id: Identifier for this agent or task type (e.g. "research_agent").
+        customer_id: Your internal customer identifier. Defaults to "default".
+        estimated_units: How many units this run is expected to consume. Used for ceiling check.
+        ceiling: Max units allowed per single run. Run is blocked if estimated_units exceeds this.
+    """
+    payload: dict = {"agent_id": agent_id, "customer_id": customer_id}
+    if estimated_units is not None:
+        payload["estimated_units"] = estimated_units
+    if ceiling is not None:
+        payload["ceiling"] = ceiling
+
+    with httpx.Client(timeout=5) as client:
+        resp = client.post(f"{BASE_URL}/preflight", json=payload, headers=_headers())
+
+    data = resp.json()
+
+    if not data.get("approved", True):
+        reason = data.get("reason", "unknown")
+        return {
+            "approved": False,
+            "reason": reason,
+            "remaining_units": data.get("remaining_units"),
+            "upgrade_url": data.get("upgrade_url"),
+            "message": _blocked_message(reason, data),
+        }
+
+    return {
+        "approved": True,
+        "remaining_units": data.get("remaining_units"),
+        "estimated_units": data.get("estimated_units"),
+    }
+
+
+@mcp.tool()
+def record_event(
+    agent_id: str,
+    units: int = 1,
+    customer_id: str = "default",
+    metadata: Optional[dict] = None,
+) -> dict:
+    """
+    Record a billable event after agent work is complete.
+
+    Call this once per unit of work completed. Safe to call from retried or
+    parallel workflows — duplicate submissions are ignored automatically.
+
+    Args:
+        agent_id: Identifier for this agent or task type. Appears in the dashboard.
+        units: Number of billable units this event represents. Default is 1.
+        customer_id: Your internal customer identifier. Defaults to "default".
+        metadata: Optional key-value pairs stored with the event (e.g. model name, latency).
+    """
+    payload: dict = {
+        "customer_id": customer_id,
+        "event_type": agent_id,
+        "idempotency_key": f"{agent_id}-{uuid.uuid4()}",
+        "units": units,
+    }
+    if metadata:
+        payload["metadata"] = metadata
+
+    with httpx.Client(timeout=5) as client:
+        resp = client.post(f"{BASE_URL}/events", json=payload, headers=_headers())
+
+    if resp.status_code == 402:
+        data = resp.json()
+        return {
+            "recorded": False,
+            "reason": "budget_exhausted",
+            "message": data.get("message", "Customer budget is exhausted."),
+        }
+
+    resp.raise_for_status()
+    data = resp.json()
+
+    return {
+        "recorded": True,
+        "event_id": data.get("event_id"),
+        "status": data.get("status"),
+        "customer_remaining_units": data.get("customer_remaining_units"),
+    }
+
+
+def _blocked_message(reason: str, data: dict) -> str:
+    if reason == "ceiling_exceeded":
+        return (
+            f"Run blocked: estimated {data.get('estimated_units')} units "
+            f"exceeds per-request ceiling of {data.get('ceiling')}."
+        )
+    if reason == "budget_exhausted":
+        return "Run blocked: customer budget is exhausted."
+    if reason == "free_tier_exceeded":
+        url = data.get("upgrade_url", "agentbill.dev/dashboard")
+        return f"Run blocked: free tier limit reached. Upgrade at {url}"
+    return f"Run blocked: {reason}"
+
+
+def main():
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

agentbill_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentbill-mcp"
+version = "0.1.0"
+description = "AgentBill MCP server. Add spend controls and billing to any AI agent in 3 lines."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+dependencies = [
+    "mcp[cli]>=1.0.0",
+    "httpx>=0.27",
+]
+authors = [
+    { name = "AgentBill", email = "marketinglior@gmail.com" }
+]
+keywords = [
+    "mcp",
+    "ai-agents",
+    "billing",
+    "llm",
+    "agent-billing",
+    "spend-ceiling",
+    "preflight",
+    "usage-based",
+    "langchain",
+    "claude",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://agentbill.dev"
+Repository = "https://github.com/marketinglior-pixel/agentbill"
+Documentation = "https://github.com/marketinglior-pixel/agentbill#readme"
+
+[project.scripts]
+agentbill-mcp = "agentbill_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["agentbill_mcp"]