agent-interface-standard 0.1.0__tar.gz

agent_interface_standard-0.1.0/.gitignore

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

agent_interface_standard-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: agent-interface-standard
+Version: 0.1.0
+Summary: Schema.org for AI agents — the open standard for how businesses describe their services to AI agents
+Project-URL: Homepage, https://github.com/AiAgentKarl/agent-interface-standard
+Project-URL: Repository, https://github.com/AiAgentKarl/agent-interface-standard
+Author: AiAgentKarl
+License: MIT
+Keywords: agent-interface,ai-agents,business,mcp,protocol,schema,standard
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Description-Content-Type: text/markdown
+
+# Agent Interface Standard 🌐
+
+**Schema.org for AI Agents** — the open standard for how businesses describe their services to AI agents.
+
+## The Vision
+
+Schema.org made websites machine-readable for search engines. **Agent Interface Standard** makes businesses machine-readable for AI agents.
+
+Businesses publish a simple JSON spec at `/.well-known/agent-interface.json` describing what services they offer and how agents can interact with them.
+
+## Installation
+
+```bash
+pip install agent-interface-standard
+```
+
+```json
+{"mcpServers": {"agent-interface": {"command": "uvx", "args": ["agent-interface-standard"]}}}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_spec_template` | Get a blank template to fill out |
+| `get_example_spec` | See a complete example (restaurant) |
+| `validate_interface_spec` | Check your spec for errors |
+| `register_business` | Register a business in the directory |
+| `search_businesses` | Find agent-accessible businesses |
+| `get_business_capabilities` | See what a business offers |
+| `fetch_remote_spec` | Fetch a spec from a URL |
+
+## The Spec Format
+
+```json
+{
+  "agent_interface": "0.1.0",
+  "business": {
+    "name": "My Business",
+    "description": "What we do",
+    "category": "e_commerce"
+  },
+  "capabilities": [
+    {
+      "name": "search_products",
+      "description": "Search our product catalog",
+      "type": "search",
+      "endpoint": "https://api.mybusiness.com/search",
+      "method": "GET",
+      "parameters": [...]
+    }
+  ],
+  "auth": {"type": "api_key"},
+  "pricing": {"model": "freemium"}
+}
+```
+
+## Why This Matters
+
+When AI agents become primary customers (not just humans), businesses need a standard way to be "agent-accessible." This is that standard.
+
+## License
+
+MIT

agent_interface_standard-0.1.0/README.md

@@ -0,0 +1,64 @@
+# Agent Interface Standard 🌐
+
+**Schema.org for AI Agents** — the open standard for how businesses describe their services to AI agents.
+
+## The Vision
+
+Schema.org made websites machine-readable for search engines. **Agent Interface Standard** makes businesses machine-readable for AI agents.
+
+Businesses publish a simple JSON spec at `/.well-known/agent-interface.json` describing what services they offer and how agents can interact with them.
+
+## Installation
+
+```bash
+pip install agent-interface-standard
+```
+
+```json
+{"mcpServers": {"agent-interface": {"command": "uvx", "args": ["agent-interface-standard"]}}}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_spec_template` | Get a blank template to fill out |
+| `get_example_spec` | See a complete example (restaurant) |
+| `validate_interface_spec` | Check your spec for errors |
+| `register_business` | Register a business in the directory |
+| `search_businesses` | Find agent-accessible businesses |
+| `get_business_capabilities` | See what a business offers |
+| `fetch_remote_spec` | Fetch a spec from a URL |
+
+## The Spec Format
+
+```json
+{
+  "agent_interface": "0.1.0",
+  "business": {
+    "name": "My Business",
+    "description": "What we do",
+    "category": "e_commerce"
+  },
+  "capabilities": [
+    {
+      "name": "search_products",
+      "description": "Search our product catalog",
+      "type": "search",
+      "endpoint": "https://api.mybusiness.com/search",
+      "method": "GET",
+      "parameters": [...]
+    }
+  ],
+  "auth": {"type": "api_key"},
+  "pricing": {"model": "freemium"}
+}
+```
+
+## Why This Matters
+
+When AI agents become primary customers (not just humans), businesses need a standard way to be "agent-accessible." This is that standard.
+
+## License
+
+MIT

agent_interface_standard-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agent-interface-standard"
+version = "0.1.0"
+description = "Schema.org for AI agents — the open standard for how businesses describe their services to AI agents"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [{name = "AiAgentKarl"}]
+keywords = ["mcp", "agent-interface", "schema", "standard", "business", "ai-agents", "protocol"]
+dependencies = ["mcp>=1.0.0", "httpx>=0.27.0", "pydantic>=2.0.0"]
+
+[project.urls]
+Homepage = "https://github.com/AiAgentKarl/agent-interface-standard"
+Repository = "https://github.com/AiAgentKarl/agent-interface-standard"
+
+[project.scripts]
+agent-interface = "src.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src"]

agent_interface_standard-0.1.0/src/schema.py

@@ -0,0 +1,173 @@
+"""Agent Interface Schema — der offene Standard für agent-lesbare Business-Beschreibungen.
+
+Definiert das JSON-Format das Unternehmen veröffentlichen können,
+damit AI-Agents ihre Services automatisch verstehen und nutzen können.
+Vergleichbar mit Schema.org für Suchmaschinen, aber für AI-Agents.
+"""
+
+import json
+import sqlite3
+from pathlib import Path
+from datetime import datetime
+
+DB_PATH = Path.home() / ".agent-interface" / "registry.db"
+
+# Die Standard-Spec Version
+SPEC_VERSION = "0.1.0"
+
+# Beispiel einer Agent Interface Spec
+EXAMPLE_SPEC = {
+    "agent_interface": SPEC_VERSION,
+    "business": {
+        "name": "Example Restaurant",
+        "description": "Italian restaurant with delivery",
+        "category": "food_delivery",
+        "website": "https://example-restaurant.com",
+        "location": {"city": "Berlin", "country": "DE"},
+    },
+    "capabilities": [
+        {
+            "name": "view_menu",
+            "description": "Browse the restaurant menu",
+            "type": "read",
+            "endpoint": "https://api.example-restaurant.com/menu",
+            "method": "GET",
+            "parameters": [
+                {"name": "category", "type": "string", "required": False,
+                 "description": "Filter by category (pizza, pasta, salad)"}
+            ],
+            "returns": "List of menu items with prices",
+            "auth_required": False,
+            "rate_limit": "60/min",
+        },
+        {
+            "name": "place_order",
+            "description": "Place a delivery order",
+            "type": "transaction",
+            "endpoint": "https://api.example-restaurant.com/orders",
+            "method": "POST",
+            "parameters": [
+                {"name": "items", "type": "array", "required": True,
+                 "description": "List of item IDs and quantities"},
+                {"name": "delivery_address", "type": "string", "required": True,
+                 "description": "Full delivery address"},
+                {"name": "payment_method", "type": "string", "required": True,
+                 "description": "Payment method (card, cash, x402)"},
+            ],
+            "returns": "Order confirmation with estimated delivery time",
+            "auth_required": True,
+            "cost": {"currency": "EUR", "estimate": "10-30"},
+            "confirmation_required": True,
+        },
+        {
+            "name": "track_order",
+            "description": "Track an existing order status",
+            "type": "read",
+            "endpoint": "https://api.example-restaurant.com/orders/{order_id}",
+            "method": "GET",
+            "parameters": [
+                {"name": "order_id", "type": "string", "required": True,
+                 "description": "The order ID from place_order"}
+            ],
+            "returns": "Order status and estimated delivery time",
+            "auth_required": True,
+        },
+    ],
+    "auth": {
+        "type": "api_key",
+        "header": "X-API-Key",
+        "registration_url": "https://example-restaurant.com/developers",
+    },
+    "pricing": {
+        "model": "per_transaction",
+        "details": "Menu browsing is free. Orders are charged at menu prices.",
+    },
+    "contact": {
+        "support_email": "api@example-restaurant.com",
+        "docs_url": "https://docs.example-restaurant.com",
+    },
+}
+
+# Template-Spezifikation die Unternehmen ausfüllen können
+BUSINESS_TEMPLATE = {
+    "agent_interface": SPEC_VERSION,
+    "business": {
+        "name": "",
+        "description": "",
+        "category": "",
+        "website": "",
+        "location": {"city": "", "country": ""},
+    },
+    "capabilities": [],
+    "auth": {"type": "none"},
+    "pricing": {"model": "free"},
+    "contact": {},
+}
+
+# Bekannte Business-Kategorien
+CATEGORIES = [
+    "e_commerce", "food_delivery", "travel_booking", "financial_services",
+    "healthcare", "real_estate", "transportation", "education",
+    "entertainment", "professional_services", "saas", "marketplace",
+    "government", "utilities", "insurance", "logistics",
+]
+
+# Capability-Typen
+CAPABILITY_TYPES = [
+    "read",          # Daten lesen (GET)
+    "write",         # Daten schreiben (POST/PUT)
+    "transaction",   # Kostenpflichtige Aktion
+    "search",        # Suche
+    "booking",       # Reservierung/Buchung
+    "subscription",  # Abo-Verwaltung
+    "notification",  # Benachrichtigungen
+]
+
+
+def _get_db():
+    """Datenbank für registrierte Business-Interfaces."""
+    DB_PATH.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(str(DB_PATH))
+    conn.row_factory = sqlite3.Row
+    conn.execute("""
+        CREATE TABLE IF NOT EXISTS interfaces (
+            id TEXT PRIMARY KEY,
+            business_name TEXT NOT NULL,
+            description TEXT DEFAULT '',
+            category TEXT DEFAULT '',
+            spec_json TEXT NOT NULL,
+            capabilities_count INTEGER DEFAULT 0,
+            website TEXT DEFAULT '',
+            registered_at TEXT NOT NULL
+        )
+    """)
+    conn.commit()
+    return conn
+
+
+def validate_spec(spec: dict) -> list[str]:
+    """Agent Interface Spec validieren. Gibt Liste von Fehlern zurück."""
+    errors = []
+
+    if "agent_interface" not in spec:
+        errors.append("Missing 'agent_interface' version field")
+
+    business = spec.get("business", {})
+    if not business.get("name"):
+        errors.append("Missing 'business.name'")
+    if not business.get("description"):
+        errors.append("Missing 'business.description'")
+
+    capabilities = spec.get("capabilities", [])
+    if not capabilities:
+        errors.append("No capabilities defined — at least one required")
+
+    for i, cap in enumerate(capabilities):
+        if not cap.get("name"):
+            errors.append(f"Capability {i}: missing 'name'")
+        if not cap.get("description"):
+            errors.append(f"Capability {i}: missing 'description'")
+        if not cap.get("endpoint"):
+            errors.append(f"Capability {i}: missing 'endpoint'")
+
+    return errors

agent_interface_standard-0.1.0/src/server.py

@@ -0,0 +1,24 @@
+"""Agent Interface Standard — Schema.org for AI Agents."""
+
+from mcp.server.fastmcp import FastMCP
+from src.tools.standard_tools import register_standard_tools
+
+mcp = FastMCP(
+    "Agent Interface Standard",
+    instructions=(
+        "The open standard for how businesses describe their services to AI agents. "
+        "Like Schema.org made websites machine-readable for search engines, "
+        "Agent Interface Standard makes businesses machine-readable for AI agents. "
+        "Create, validate, register and discover agent-accessible business interfaces."
+    ),
+)
+
+register_standard_tools(mcp)
+
+
+def main():
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

agent_interface_standard-0.1.0/src/tools/standard_tools.py

@@ -0,0 +1,217 @@
+"""Standard-Tools — Agent Interface Specs erstellen, validieren und nutzen."""
+
+import json
+import httpx
+from datetime import datetime
+from mcp.server.fastmcp import FastMCP
+
+from src.schema import (
+    SPEC_VERSION, EXAMPLE_SPEC, BUSINESS_TEMPLATE,
+    CATEGORIES, CAPABILITY_TYPES, validate_spec, _get_db,
+)
+
+
+def register_standard_tools(mcp: FastMCP):
+
+    @mcp.tool()
+    async def get_spec_template(category: str = "") -> dict:
+        """Get a blank Agent Interface spec template for a business.
+
+        Returns a template that businesses can fill out to make
+        their services accessible to AI agents. Like Schema.org markup
+        but for AI agents.
+
+        Args:
+            category: Business category for relevant examples (optional)
+        """
+        return {
+            "spec_version": SPEC_VERSION,
+            "template": BUSINESS_TEMPLATE,
+            "available_categories": CATEGORIES,
+            "capability_types": CAPABILITY_TYPES,
+            "instructions": (
+                "Fill out the template with your business details and capabilities. "
+                "Each capability describes one action an AI agent can take. "
+                "Use validate_spec to check your spec before publishing."
+            ),
+        }
+
+    @mcp.tool()
+    async def get_example_spec() -> dict:
+        """Get a complete example Agent Interface spec.
+
+        Shows a fully filled-out spec for a restaurant with
+        menu browsing, ordering, and order tracking capabilities.
+        Use this as a reference when creating your own spec.
+        """
+        return {
+            "description": "Complete example spec for a restaurant business",
+            "spec": EXAMPLE_SPEC,
+            "note": "This shows all supported fields. Not all fields are required.",
+        }
+
+    @mcp.tool()
+    async def validate_interface_spec(spec_json: str) -> dict:
+        """Validate an Agent Interface spec for correctness.
+
+        Checks that all required fields are present and properly formatted.
+        Returns a list of errors if the spec is invalid.
+
+        Args:
+            spec_json: The spec as a JSON string
+        """
+        try:
+            spec = json.loads(spec_json)
+        except json.JSONDecodeError as e:
+            return {"valid": False, "errors": [f"Invalid JSON: {e}"]}
+
+        errors = validate_spec(spec)
+
+        if errors:
+            return {"valid": False, "errors": errors, "error_count": len(errors)}
+
+        caps = spec.get("capabilities", [])
+        return {
+            "valid": True,
+            "spec_version": spec.get("agent_interface", "unknown"),
+            "business": spec.get("business", {}).get("name", ""),
+            "capabilities_count": len(caps),
+            "message": "Spec is valid and ready to publish.",
+        }
+
+    @mcp.tool()
+    async def register_business(spec_json: str, business_id: str = "") -> dict:
+        """Register a business interface spec in the local directory.
+
+        Makes the business discoverable by agents through search_businesses.
+        The spec is stored locally and persists between sessions.
+
+        Args:
+            spec_json: The complete Agent Interface spec as JSON
+            business_id: Custom ID (auto-generated from business name if empty)
+        """
+        try:
+            spec = json.loads(spec_json)
+        except json.JSONDecodeError as e:
+            return {"error": f"Invalid JSON: {e}"}
+
+        errors = validate_spec(spec)
+        if errors:
+            return {"error": "Invalid spec", "errors": errors}
+
+        business = spec.get("business", {})
+        name = business.get("name", "Unknown")
+
+        if not business_id:
+            business_id = name.lower().replace(" ", "-").replace(".", "-")[:50]
+
+        conn = _get_db()
+        conn.execute("""
+            INSERT OR REPLACE INTO interfaces
+            (id, business_name, description, category, spec_json,
+             capabilities_count, website, registered_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        """, (
+            business_id, name, business.get("description", ""),
+            business.get("category", ""),
+            json.dumps(spec), len(spec.get("capabilities", [])),
+            business.get("website", ""), datetime.utcnow().isoformat(),
+        ))
+        conn.commit()
+
+        return {
+            "status": "registered",
+            "business_id": business_id,
+            "name": name,
+            "capabilities": len(spec.get("capabilities", [])),
+        }
+
+    @mcp.tool()
+    async def search_businesses(query: str, category: str = "") -> dict:
+        """Search for agent-accessible businesses.
+
+        Find businesses that have published Agent Interface specs,
+        making their services available to AI agents.
+
+        Args:
+            query: Search term (e.g. "restaurant", "booking", "delivery")
+            category: Filter by category (optional)
+        """
+        conn = _get_db()
+        q = f"%{query.lower()}%"
+
+        if category:
+            rows = conn.execute("""
+                SELECT id, business_name, description, category, capabilities_count, website
+                FROM interfaces
+                WHERE (LOWER(business_name) LIKE ? OR LOWER(description) LIKE ?)
+                  AND LOWER(category) LIKE ?
+                ORDER BY business_name LIMIT 20
+            """, (q, q, f"%{category.lower()}%")).fetchall()
+        else:
+            rows = conn.execute("""
+                SELECT id, business_name, description, category, capabilities_count, website
+                FROM interfaces
+                WHERE LOWER(business_name) LIKE ? OR LOWER(description) LIKE ?
+                ORDER BY business_name LIMIT 20
+            """, (q, q)).fetchall()
+
+        results = [dict(r) for r in rows]
+        return {"query": query, "results_count": len(results), "businesses": results}
+
+    @mcp.tool()
+    async def get_business_capabilities(business_id: str) -> dict:
+        """Get all capabilities of a registered business.
+
+        Returns the full spec including all available actions
+        an agent can take with this business.
+
+        Args:
+            business_id: Business ID (from search_businesses)
+        """
+        conn = _get_db()
+        row = conn.execute(
+            "SELECT * FROM interfaces WHERE id = ?", (business_id,)
+        ).fetchone()
+
+        if not row:
+            return {"error": f"Business '{business_id}' not found"}
+
+        spec = json.loads(row["spec_json"])
+        return {
+            "business_id": business_id,
+            "business": spec.get("business", {}),
+            "capabilities": spec.get("capabilities", []),
+            "auth": spec.get("auth", {}),
+            "pricing": spec.get("pricing", {}),
+            "contact": spec.get("contact", {}),
+        }
+
+    @mcp.tool()
+    async def fetch_remote_spec(url: str) -> dict:
+        """Fetch an Agent Interface spec from a remote URL.
+
+        Businesses can host their spec at a well-known URL
+        (e.g. example.com/.well-known/agent-interface.json).
+        This tool fetches and validates it.
+
+        Args:
+            url: URL to the Agent Interface spec JSON
+        """
+        async with httpx.AsyncClient(timeout=15) as client:
+            resp = await client.get(url)
+            resp.raise_for_status()
+            spec = resp.json()
+
+        errors = validate_spec(spec)
+        business = spec.get("business", {})
+
+        return {
+            "url": url,
+            "valid": len(errors) == 0,
+            "errors": errors if errors else None,
+            "business_name": business.get("name", "Unknown"),
+            "capabilities_count": len(spec.get("capabilities", [])),
+            "spec": spec if len(errors) == 0 else None,
+            "hint": "Use register_business to add this to your local directory." if not errors else None,
+        }