alp-server 0.7.0__tar.gz

alp_server-0.7.0/.gitignore

@@ -0,0 +1,65 @@
+# =============================================================================
+# ALP — Agent Load Protocol
+# .gitignore
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# Python — local installs inside reference server
+# -----------------------------------------------------------------------------
+reference/server/python/Lib/
+reference/server/python/Scripts/
+reference/server/python/__pycache__/
+reference/server/python/*.pyc
+reference/server/python/*.pyo
+reference/server/python/get-pip.py
+
+# -----------------------------------------------------------------------------
+# Python — general
+# -----------------------------------------------------------------------------
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+.venv/
+venv/
+env/
+ENV/
+
+# -----------------------------------------------------------------------------
+# Node — local installs inside reference server
+# -----------------------------------------------------------------------------
+reference/server/node/node_modules/
+
+# -----------------------------------------------------------------------------
+# Environment variables — never commit secrets
+# -----------------------------------------------------------------------------
+.env
+.env.local
+.env.*.local
+*.env
+
+# -----------------------------------------------------------------------------
+# OS files
+# -----------------------------------------------------------------------------
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# -----------------------------------------------------------------------------
+# Editor files
+# -----------------------------------------------------------------------------
+.vscode/settings.json
+.idea/
+*.swp
+*.swo
+
+# -----------------------------------------------------------------------------
+# Logs
+# -----------------------------------------------------------------------------
+*.log
+logs/

alp_server-0.7.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: alp-server
+Version: 0.7.0
+Summary: Agent Load Protocol — drop-in MCP/SSE middleware for any Python server
+Project-URL: Homepage, https://github.com/RodrigoMvs123/agent-load-protocol
+Project-URL: Repository, https://github.com/RodrigoMvs123/agent-load-protocol
+Project-URL: Documentation, https://github.com/RodrigoMvs123/agent-load-protocol/blob/main/SPEC.md
+Project-URL: Bug Tracker, https://github.com/RodrigoMvs123/agent-load-protocol/issues
+License: MIT
+Keywords: agent,alp,claude,fastapi,kiro,llm,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.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.111.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: uvicorn[standard]>=0.29.0
+Provides-Extra: dev
+Requires-Dist: httpx; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Provides-Extra: flask
+Requires-Dist: flask>=3.0.0; extra == 'flask'
+Description-Content-Type: text/markdown
+
+# alp-server
+
+> Agent Load Protocol — drop-in MCP/SSE middleware for any Python server.
+
+Add Kiro / Claude Code / MCP connectivity to any existing FastAPI or Flask app in 3 lines.
+
+## Install
+
+```bash
+pip install alp-server
+```
+
+## FastAPI
+
+```python
+from fastapi import FastAPI
+from alp import ALPRouter
+
+app = FastAPI()
+
+# Adds /mcp, /agent, /tools, /persona, /agents, /health, /agent/refresh
+alp = ALPRouter(card_path="agent.alp.json")
+app.include_router(alp.router)
+
+# Your existing routes — untouched
+@app.get("/your/existing/route")
+async def your_route():
+    return {"ok": True}
+```
+
+```bash
+uvicorn main:app --port 8000
+```
+
+## Flask
+
+```bash
+pip install alp-server[flask]
+```
+
+```python
+from flask import Flask
+from alp.flask import ALPBlueprint
+
+app = Flask(__name__)
+
+alp = ALPBlueprint(card_path="agent.alp.json")
+app.register_blueprint(alp.blueprint)
+```
+
+## Custom tool registration
+
+Register Python functions as tool handlers instead of using proxy URLs:
+
+```python
+from fastapi import FastAPI
+from alp import ALPRouter
+
+app = FastAPI()
+alp = ALPRouter(card_path="agent.alp.json")
+
+@alp.tool("greet")
+async def greet(input_data: dict) -> dict:
+    name = input_data.get("name", "stranger")
+    return {"message": f"Hello, {name}!"}
+
+@alp.tool("search")
+async def search(input_data: dict) -> dict:
+    results = my_search_function(input_data["query"])
+    return {"results": results}
+
+app.include_router(alp.router)
+```
+
+## Remote card (v0.6.0)
+
+Load the Agent Card from a public GitHub URL:
+
+```python
+alp = ALPRouter(
+    card_url="https://raw.githubusercontent.com/YOUR-ORG/YOUR-REPO/main/agent.alp.json"
+)
+```
+
+Or via environment variable:
+
+```bash
+AGENT_CARD_URL=https://raw.githubusercontent.com/YOUR-ORG/YOUR-REPO/main/agent.alp.json
+```
+
+## Connect to Kiro
+
+Add to `.kiro/settings/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "my-agent": {
+      "url": "http://localhost:8000/mcp"
+    }
+  }
+}
+```
+
+## Endpoints added
+
+| Endpoint | Description |
+|---|---|
+| `GET /mcp` | MCP SSE stream — Kiro connects here |
+| `POST /mcp` | MCP JSON-RPC receiver |
+| `GET /agent` | Agent Card JSON |
+| `GET /agent/refresh` | Re-fetch remote card |
+| `GET /persona` | Agent persona for system prompt |
+| `GET /tools` | Tool list |
+| `POST /tools/{name}` | Execute a tool |
+| `GET /agents` | All hosted cards |
+| `GET /health` | Status check |
+
+## Protocol
+
+Part of the [Agent Load Protocol](https://github.com/RodrigoMvs123/agent-load-protocol).
+
+## License
+
+MIT

alp_server-0.7.0/README.md

@@ -0,0 +1,125 @@
+# alp-server
+
+> Agent Load Protocol — drop-in MCP/SSE middleware for any Python server.
+
+Add Kiro / Claude Code / MCP connectivity to any existing FastAPI or Flask app in 3 lines.
+
+## Install
+
+```bash
+pip install alp-server
+```
+
+## FastAPI
+
+```python
+from fastapi import FastAPI
+from alp import ALPRouter
+
+app = FastAPI()
+
+# Adds /mcp, /agent, /tools, /persona, /agents, /health, /agent/refresh
+alp = ALPRouter(card_path="agent.alp.json")
+app.include_router(alp.router)
+
+# Your existing routes — untouched
+@app.get("/your/existing/route")
+async def your_route():
+    return {"ok": True}
+```
+
+```bash
+uvicorn main:app --port 8000
+```
+
+## Flask
+
+```bash
+pip install alp-server[flask]
+```
+
+```python
+from flask import Flask
+from alp.flask import ALPBlueprint
+
+app = Flask(__name__)
+
+alp = ALPBlueprint(card_path="agent.alp.json")
+app.register_blueprint(alp.blueprint)
+```
+
+## Custom tool registration
+
+Register Python functions as tool handlers instead of using proxy URLs:
+
+```python
+from fastapi import FastAPI
+from alp import ALPRouter
+
+app = FastAPI()
+alp = ALPRouter(card_path="agent.alp.json")
+
+@alp.tool("greet")
+async def greet(input_data: dict) -> dict:
+    name = input_data.get("name", "stranger")
+    return {"message": f"Hello, {name}!"}
+
+@alp.tool("search")
+async def search(input_data: dict) -> dict:
+    results = my_search_function(input_data["query"])
+    return {"results": results}
+
+app.include_router(alp.router)
+```
+
+## Remote card (v0.6.0)
+
+Load the Agent Card from a public GitHub URL:
+
+```python
+alp = ALPRouter(
+    card_url="https://raw.githubusercontent.com/YOUR-ORG/YOUR-REPO/main/agent.alp.json"
+)
+```
+
+Or via environment variable:
+
+```bash
+AGENT_CARD_URL=https://raw.githubusercontent.com/YOUR-ORG/YOUR-REPO/main/agent.alp.json
+```
+
+## Connect to Kiro
+
+Add to `.kiro/settings/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "my-agent": {
+      "url": "http://localhost:8000/mcp"
+    }
+  }
+}
+```
+
+## Endpoints added
+
+| Endpoint | Description |
+|---|---|
+| `GET /mcp` | MCP SSE stream — Kiro connects here |
+| `POST /mcp` | MCP JSON-RPC receiver |
+| `GET /agent` | Agent Card JSON |
+| `GET /agent/refresh` | Re-fetch remote card |
+| `GET /persona` | Agent persona for system prompt |
+| `GET /tools` | Tool list |
+| `POST /tools/{name}` | Execute a tool |
+| `GET /agents` | All hosted cards |
+| `GET /health` | Status check |
+
+## Protocol
+
+Part of the [Agent Load Protocol](https://github.com/RodrigoMvs123/agent-load-protocol).
+
+## License
+
+MIT

alp_server-0.7.0/alp/__init__.py

@@ -0,0 +1,28 @@
+"""
+alp-server
+----------
+Agent Load Protocol — drop-in MCP/SSE middleware for any Python server.
+
+Quick start (FastAPI):
+
+    from fastapi import FastAPI
+    from alp import ALPRouter
+
+    app = FastAPI()
+    alp = ALPRouter(card_path="agent.alp.json")
+    app.include_router(alp.router)
+
+Quick start (Flask):
+
+    from flask import Flask
+    from alp.flask import ALPBlueprint
+
+    app = Flask(__name__)
+    alp = ALPBlueprint(card_path="agent.alp.json")
+    app.register_blueprint(alp.blueprint)
+"""
+
+from .fastapi import ALPRouter
+
+__all__ = ["ALPRouter"]
+__version__ = "0.7.0"

alp_server-0.7.0/alp/card.py

@@ -0,0 +1,75 @@
+"""
+alp.card
+--------
+Agent Card loader + validator.
+Supports local file (card_path) and remote URL (card_url).
+Includes in-memory cache with refresh support.
+"""
+
+import json
+from pathlib import Path
+from typing import Optional
+
+import httpx
+
+
+_cache: dict[str, dict] = {}
+
+
+def load_local(card_path: str) -> dict:
+    """Load an Agent Card from a local file."""
+    path = Path(card_path)
+    if not path.exists():
+        raise FileNotFoundError(f"Agent card not found: {card_path}")
+    with open(path) as f:
+        return json.load(f)
+
+
+async def load_remote(url: str) -> dict:
+    """Load an Agent Card from a public URL."""
+    try:
+        async with httpx.AsyncClient() as client:
+            response = await client.get(url, timeout=10.0)
+            response.raise_for_status()
+            return response.json()
+    except httpx.HTTPStatusError as exc:
+        raise RuntimeError(
+            f"Failed to fetch card from '{url}': HTTP {exc.response.status_code}"
+        )
+    except httpx.RequestError as exc:
+        raise RuntimeError(
+            f"Connection error fetching card from '{url}': {str(exc)}"
+        )
+
+
+async def get_card(
+    card_path: str = "agent.alp.json",
+    card_url: Optional[str] = None,
+    cache_key: str = "__primary__",
+    use_cache: bool = True,
+) -> dict:
+    """
+    Return an Agent Card.
+    Priority: card_url (remote) > card_path (local file).
+    Results are cached in memory; pass use_cache=False to force reload.
+    """
+    if use_cache and cache_key in _cache:
+        return _cache[cache_key]
+
+    if card_url:
+        card = await load_remote(card_url)
+    else:
+        card = load_local(card_path)
+
+    _cache[cache_key] = card
+    return card
+
+
+def invalidate(cache_key: str = "__primary__") -> None:
+    """Remove a card from the cache so it will be reloaded on next access."""
+    _cache.pop(cache_key, None)
+
+
+def get_all_cached() -> dict[str, dict]:
+    """Return all cached cards."""
+    return dict(_cache)

alp_server-0.7.0/alp/fastapi.py

@@ -0,0 +1,198 @@
+"""
+alp.fastapi
+-----------
+Drop-in FastAPI router. Mounts all ALP + MCP endpoints on any FastAPI app.
+
+Usage (3 lines):
+
+    from fastapi import FastAPI
+    from alp import ALPRouter
+
+    app = FastAPI()
+    alp = ALPRouter(card_path="agent.alp.json")
+    app.include_router(alp.router)
+
+Custom tool registration:
+
+    alp = ALPRouter(card_path="agent.alp.json")
+
+    @alp.tool("greet")
+    async def greet(input_data: dict) -> dict:
+        return {"message": f"Hello, {input_data.get('name', 'stranger')}!"}
+
+    app.include_router(alp.router)
+"""
+
+import os
+from typing import Any, Callable, Optional
+
+from fastapi import APIRouter, HTTPException, Request
+from fastapi.responses import JSONResponse, StreamingResponse
+from pydantic import BaseModel
+
+from . import card as card_module
+from . import mcp as mcp_module
+from . import sse as sse_module
+from . import tools as tools_module
+
+
+class ALPRouter:
+    """
+    ALP FastAPI router.
+    Mount on any FastAPI app to add /mcp, /agent, /tools, /persona, /agents,
+    /health, /agent/refresh endpoints.
+    """
+
+    def __init__(
+        self,
+        card_path: str = "agent.alp.json",
+        card_url: Optional[str] = None,
+        port: int = None,
+        prefix: str = "",
+    ):
+        self.card_path = card_url or os.environ.get("AGENT_CARD_URL") or card_path
+        self.card_url = card_url or os.environ.get("AGENT_CARD_URL")
+        self.port = port or int(os.environ.get("PORT", 8000))
+        self.router = APIRouter(prefix=prefix)
+        self._register_routes()
+
+    def tool(self, tool_name: str) -> Callable:
+        """Decorator to register a local Python function as a tool handler."""
+        def decorator(fn: Callable) -> Callable:
+            tools_module.register(tool_name, fn)
+            return fn
+        return decorator
+
+    async def _get_card(self) -> dict:
+        return await card_module.get_card(
+            card_path=self.card_path,
+            card_url=self.card_url,
+        )
+
+    def _register_routes(self) -> None:
+
+        router = self.router
+
+        # --- Health ---
+
+        @router.get("/health")
+        async def health():
+            return {"status": "ok", "alp_version": "0.7.0"}
+
+        # --- Agent Card ---
+
+        @router.get("/agent")
+        async def get_agent():
+            try:
+                return await self._get_card()
+            except Exception as e:
+                raise HTTPException(status_code=404, detail=str(e))
+
+        @router.get("/agent/refresh")
+        async def refresh_agent():
+            if not self.card_url:
+                raise HTTPException(
+                    status_code=400,
+                    detail="card_url is not set — nothing to refresh"
+                )
+            card_module.invalidate()
+            try:
+                card = await self._get_card()
+                return {
+                    "refreshed": True,
+                    "id": card.get("id"),
+                    "name": card.get("name"),
+                    "alp_version": card.get("alp_version"),
+                    "source": self.card_url,
+                }
+            except Exception as exc:
+                raise HTTPException(status_code=502, detail=str(exc))
+
+        # --- Persona ---
+
+        @router.get("/persona")
+        async def get_persona():
+            card = await self._get_card()
+            persona = card.get("persona")
+            if not persona:
+                raise HTTPException(status_code=404, detail="No persona defined")
+            return {"persona": persona, "id": card.get("id"), "name": card.get("name")}
+
+        # --- Agents catalog ---
+
+        @router.get("/agents")
+        async def list_agents():
+            card = await self._get_card()
+            all_cached = card_module.get_all_cached()
+            cards = [v for k, v in all_cached.items() if k != "__primary__"]
+            if not cards:
+                cards = [card]
+            return {"agents": cards}
+
+        # --- Tools ---
+
+        @router.get("/tools")
+        async def list_tools():
+            card = await self._get_card()
+            return {"tools": card.get("tools", [])}
+
+        class ToolInput(BaseModel):
+            input: dict[str, Any] = {}
+
+        @router.post("/tools/{tool_name}")
+        async def execute_tool(tool_name: str, body: ToolInput):
+            card = await self._get_card()
+            try:
+                result = await tools_module.execute(tool_name, body.input, card)
+                return result
+            except KeyError as e:
+                raise HTTPException(status_code=404, detail=str(e))
+            except RuntimeError as e:
+                raise HTTPException(status_code=502, detail=str(e))
+
+        # --- MCP SSE ---
+
+        @router.get("/mcp")
+        async def mcp_sse(request: Request):
+            """MCP SSE transport — Kiro connects here."""
+            card = await self._get_card()
+            session_id, queue = sse_module.create_session()
+            post_url = f"http://localhost:{self.port}/mcp?session_id={session_id}"
+            stream = sse_module.event_stream(session_id, queue, post_url)
+            return StreamingResponse(
+                stream,
+                media_type="text/event-stream",
+                headers={
+                    "Cache-Control": "no-cache",
+                    "Connection": "keep-alive",
+                    "X-Accel-Buffering": "no",
+                },
+            )
+
+        @router.post("/mcp")
+        async def mcp_post(request: Request):
+            """MCP JSON-RPC receiver — Kiro POSTs here."""
+            card = await self._get_card()
+            session_id = request.query_params.get("session_id")
+            try:
+                body = await request.json()
+            except Exception:
+                return JSONResponse({"error": "invalid JSON"}, status_code=400)
+
+            messages = body if isinstance(body, list) else [body]
+            last_response = None
+
+            for msg in messages:
+                response = await mcp_module.handle(msg, card)
+                if response is None:
+                    continue
+                if session_id:
+                    pushed = await sse_module.push(session_id, response)
+                    if not pushed:
+                        last_response = response
+                else:
+                    last_response = response
+
+            if last_response:
+                return JSONResponse(last_response)
+            return JSONResponse({"ok": True})

alp_server-0.7.0/alp/flask.py

@@ -0,0 +1,203 @@
+"""
+alp.flask
+---------
+Drop-in Flask blueprint. Mounts all ALP + MCP endpoints on any Flask app.
+
+Usage (3 lines):
+
+    from flask import Flask
+    from alp.flask import ALPBlueprint
+
+    app = Flask(__name__)
+    alp = ALPBlueprint(card_path="agent.alp.json")
+    app.register_blueprint(alp.blueprint)
+
+Note: SSE requires an async-capable Flask setup (Flask 2.x + asgiref or gevent).
+For pure sync Flask, the /mcp SSE endpoint uses threading.
+"""
+
+import asyncio
+import json
+import os
+import queue
+import threading
+from typing import Any, Callable, Optional
+
+from . import card as card_module
+from . import mcp as mcp_module
+from . import tools as tools_module
+
+
+def _run_async(coro):
+    """Run an async coroutine from sync Flask context."""
+    try:
+        loop = asyncio.get_event_loop()
+        if loop.is_running():
+            import concurrent.futures
+            with concurrent.futures.ThreadPoolExecutor() as pool:
+                future = pool.submit(asyncio.run, coro)
+                return future.result()
+        return loop.run_until_complete(coro)
+    except RuntimeError:
+        return asyncio.run(coro)
+
+
+class ALPBlueprint:
+    """
+    ALP Flask blueprint.
+    Register on any Flask app to add /mcp, /agent, /tools, /persona,
+    /agents, /health, /agent/refresh endpoints.
+    """
+
+    def __init__(
+        self,
+        card_path: str = "agent.alp.json",
+        card_url: Optional[str] = None,
+        port: int = None,
+        url_prefix: str = "",
+    ):
+        try:
+            from flask import Blueprint
+        except ImportError:
+            raise ImportError(
+                "Flask is not installed. Run: pip install flask"
+            )
+
+        self.card_path = card_path
+        self.card_url = card_url or os.environ.get("AGENT_CARD_URL")
+        self.port = port or int(os.environ.get("PORT", 8000))
+        self.blueprint = Blueprint("alp", __name__, url_prefix=url_prefix)
+        self._sse_clients: dict[str, queue.Queue] = {}
+        self._register_routes()
+
+    def tool(self, tool_name: str) -> Callable:
+        """Decorator to register a local Python function as a tool handler."""
+        def decorator(fn: Callable) -> Callable:
+            tools_module.register(tool_name, fn)
+            return fn
+        return decorator
+
+    def _get_card(self) -> dict:
+        return _run_async(
+            card_module.get_card(
+                card_path=self.card_path,
+                card_url=self.card_url,
+            )
+        )
+
+    def _register_routes(self) -> None:
+        from flask import request, jsonify, Response
+
+        bp = self.blueprint
+
+        @bp.get("/health")
+        def health():
+            return jsonify({"status": "ok", "alp_version": "0.7.0"})
+
+        @bp.get("/agent")
+        def get_agent():
+            try:
+                return jsonify(self._get_card())
+            except Exception as e:
+                return jsonify({"error": str(e)}), 404
+
+        @bp.get("/agent/refresh")
+        def refresh_agent():
+            if not self.card_url:
+                return jsonify({"error": "card_url is not set"}), 400
+            card_module.invalidate()
+            try:
+                card = self._get_card()
+                return jsonify({
+                    "refreshed": True,
+                    "id": card.get("id"),
+                    "name": card.get("name"),
+                    "alp_version": card.get("alp_version"),
+                    "source": self.card_url,
+                })
+            except Exception as exc:
+                return jsonify({"error": str(exc)}), 502
+
+        @bp.get("/persona")
+        def get_persona():
+            card = self._get_card()
+            persona = card.get("persona")
+            if not persona:
+                return jsonify({"error": "No persona defined"}), 404
+            return jsonify({"persona": persona, "id": card.get("id"), "name": card.get("name")})
+
+        @bp.get("/agents")
+        def list_agents():
+            card = self._get_card()
+            return jsonify({"agents": [card]})
+
+        @bp.get("/tools")
+        def list_tools():
+            card = self._get_card()
+            return jsonify({"tools": card.get("tools", [])})
+
+        @bp.post("/tools/<tool_name>")
+        def execute_tool(tool_name):
+            card = self._get_card()
+            body = request.get_json(silent=True) or {}
+            input_data = body.get("input", body)
+            try:
+                result = _run_async(tools_module.execute(tool_name, input_data, card))
+                return jsonify(result)
+            except KeyError as e:
+                return jsonify({"error": str(e)}), 404
+            except RuntimeError as e:
+                return jsonify({"error": str(e)}), 502
+
+        @bp.get("/mcp")
+        def mcp_sse():
+            import uuid
+            session_id = str(uuid.uuid4())
+            q: queue.Queue = queue.Queue()
+            self._sse_clients[session_id] = q
+
+            def stream():
+                try:
+                    post_url = f"http://localhost:{self.port}/mcp?session_id={session_id}"
+                    yield f"event: endpoint\ndata: {post_url}\n\n"
+                    while True:
+                        try:
+                            msg = q.get(timeout=15)
+                            yield f"event: message\ndata: {json.dumps(msg)}\n\n"
+                        except queue.Empty:
+                            yield ": ping\n\n"
+                finally:
+                    self._sse_clients.pop(session_id, None)
+
+            return Response(
+                stream(),
+                mimetype="text/event-stream",
+                headers={
+                    "Cache-Control": "no-cache",
+                    "X-Accel-Buffering": "no",
+                },
+            )
+
+        @bp.post("/mcp")
+        def mcp_post():
+            card = self._get_card()
+            session_id = request.args.get("session_id")
+            body = request.get_json(silent=True)
+            if body is None:
+                return jsonify({"error": "invalid JSON"}), 400
+
+            messages = body if isinstance(body, list) else [body]
+            last_response = None
+
+            for msg in messages:
+                response = _run_async(mcp_module.handle(msg, card))
+                if response is None:
+                    continue
+                if session_id and session_id in self._sse_clients:
+                    self._sse_clients[session_id].put(response)
+                else:
+                    last_response = response
+
+            if last_response:
+                return jsonify(last_response)
+            return jsonify({"ok": True})

alp_server-0.7.0/alp/mcp.py

@@ -0,0 +1,79 @@
+"""
+alp.mcp
+-------
+MCP JSON-RPC 2.0 message handler.
+Supports: initialize, tools/list, tools/call, notifications/*.
+"""
+
+import json
+from typing import Optional
+
+from . import tools as tool_registry
+
+
+async def handle(msg: dict, card: dict) -> Optional[dict]:
+    """
+    Handle a single MCP JSON-RPC 2.0 message.
+    Returns the response dict, or None for notifications.
+    """
+    method = msg.get("method", "")
+    msg_id = msg.get("id")
+    params = msg.get("params", {})
+
+    # initialize
+    if method == "initialize":
+        return {
+            "jsonrpc": "2.0",
+            "id": msg_id,
+            "result": {
+                "protocolVersion": "2024-11-05",
+                "capabilities": {"tools": {}},
+                "serverInfo": {
+                    "name": card.get("name", "ALP Agent"),
+                    "version": card.get("alp_version", "0.7.0"),
+                },
+            },
+        }
+
+    # tools/list
+    if method == "tools/list":
+        return {
+            "jsonrpc": "2.0",
+            "id": msg_id,
+            "result": {"tools": tool_registry.list_mcp(card)},
+        }
+
+    # tools/call
+    if method == "tools/call":
+        tool_name = params.get("name", "")
+        tool_input = params.get("arguments", params.get("input", {}))
+        try:
+            result = await tool_registry.execute(tool_name, tool_input, card)
+            return {
+                "jsonrpc": "2.0",
+                "id": msg_id,
+                "result": {
+                    "content": [{"type": "text", "text": json.dumps(result)}],
+                    "isError": False,
+                },
+            }
+        except Exception as exc:
+            return {
+                "jsonrpc": "2.0",
+                "id": msg_id,
+                "result": {
+                    "content": [{"type": "text", "text": str(exc)}],
+                    "isError": True,
+                },
+            }
+
+    # notifications — no response
+    if method.startswith("notifications/"):
+        return None
+
+    # unknown method
+    return {
+        "jsonrpc": "2.0",
+        "id": msg_id,
+        "error": {"code": -32601, "message": f"Method not found: {method}"},
+    }

alp_server-0.7.0/alp/sse.py

@@ -0,0 +1,68 @@
+"""
+alp.sse
+-------
+SSE (Server-Sent Events) transport layer for MCP.
+Manages per-session queues and the event stream generator.
+"""
+
+import asyncio
+import json
+import uuid
+from typing import AsyncGenerator
+
+
+# session_id -> asyncio.Queue
+_clients: dict[str, asyncio.Queue] = {}
+
+
+def create_session() -> tuple[str, asyncio.Queue]:
+    """Create a new SSE session. Returns (session_id, queue)."""
+    session_id = str(uuid.uuid4())
+    queue: asyncio.Queue = asyncio.Queue()
+    _clients[session_id] = queue
+    return session_id, queue
+
+
+def remove_session(session_id: str) -> None:
+    """Remove a session from the client registry."""
+    _clients.pop(session_id, None)
+
+
+def get_queue(session_id: str) -> asyncio.Queue | None:
+    """Return the queue for a session, or None if not found."""
+    return _clients.get(session_id)
+
+
+async def push(session_id: str, message: dict) -> bool:
+    """Push a message to a session's SSE queue. Returns False if session not found."""
+    queue = get_queue(session_id)
+    if queue is None:
+        return False
+    await queue.put(message)
+    return True
+
+
+async def event_stream(
+    session_id: str,
+    queue: asyncio.Queue,
+    post_url: str,
+    ping_interval: float = 15.0,
+) -> AsyncGenerator[str, None]:
+    """
+    Async generator that yields SSE-formatted strings.
+    Sends the endpoint event first, then relays queued messages with heartbeat pings.
+    """
+    try:
+        # MCP endpoint discovery event
+        yield f"event: endpoint\ndata: {post_url}\n\n"
+
+        while True:
+            try:
+                message = await asyncio.wait_for(queue.get(), timeout=ping_interval)
+                yield f"event: message\ndata: {json.dumps(message)}\n\n"
+            except asyncio.TimeoutError:
+                yield ": ping\n\n"
+    except asyncio.CancelledError:
+        pass
+    finally:
+        remove_session(session_id)

alp_server-0.7.0/alp/tools.py

@@ -0,0 +1,87 @@
+"""
+alp.tools
+---------
+Tool registry + proxy executor.
+
+- Tools with a full URL endpoint are proxied via HTTP (v0.5.0)
+- Tools with a relative endpoint are executed via registered Python functions
+- The @alp.tool() decorator registers local Python functions as tools
+"""
+
+from typing import Any, Callable, Optional
+import httpx
+
+
+# Global tool function registry: tool_name -> async callable
+_tool_registry: dict[str, Callable] = {}
+
+
+def register(tool_name: str, fn: Callable) -> None:
+    """Register a Python function as the handler for a named tool."""
+    _tool_registry[tool_name] = fn
+
+
+def get_registered(tool_name: str) -> Optional[Callable]:
+    """Return the registered function for a tool, or None."""
+    return _tool_registry.get(tool_name)
+
+
+def list_mcp(card: dict) -> list[dict]:
+    """Return the MCP-formatted tool list from an Agent Card."""
+    return [
+        {
+            "name": t["name"],
+            "description": t.get("description", ""),
+            "inputSchema": t.get("input_schema", {"type": "object", "properties": {}}),
+        }
+        for t in card.get("tools", [])
+    ]
+
+
+async def execute(tool_name: str, input_data: dict, card: dict) -> Any:
+    """
+    Execute a tool.
+
+    Resolution order:
+    1. Registered Python function (@alp.tool decorator)
+    2. Full URL endpoint → proxy via HTTP (v0.5.0)
+    3. Relative endpoint → stub response
+    """
+    tools = {t["name"]: t for t in card.get("tools", [])}
+
+    if tool_name not in tools:
+        raise KeyError(f"Tool '{tool_name}' not found in Agent Card")
+
+    # 1. Registered local function
+    fn = get_registered(tool_name)
+    if fn is not None:
+        return await fn(input_data)
+
+    tool = tools[tool_name]
+    endpoint = tool.get("endpoint", "")
+
+    # 2. Proxy execution (v0.5.0)
+    if endpoint.startswith("http://") or endpoint.startswith("https://"):
+        try:
+            async with httpx.AsyncClient() as client:
+                response = await client.post(
+                    endpoint,
+                    json={"input": input_data},
+                    timeout=30.0,
+                )
+                response.raise_for_status()
+                return response.json()
+        except httpx.HTTPStatusError as exc:
+            raise RuntimeError(
+                f"Proxy error from '{endpoint}': HTTP {exc.response.status_code}"
+            )
+        except httpx.RequestError as exc:
+            raise RuntimeError(
+                f"Proxy connection error to '{endpoint}': {str(exc)}"
+            )
+
+    # 3. Local stub — override by registering a function with @alp.tool()
+    return {
+        "result": f"Tool '{tool_name}' executed with input: {input_data}",
+        "error": None,
+    }

alp_server-0.7.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "alp-server"
+version = "0.7.0"
+description = "Agent Load Protocol — drop-in MCP/SSE middleware for any Python server"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+keywords = ["mcp", "agent", "alp", "fastapi", "llm", "kiro", "claude"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "fastapi>=0.111.0",
+    "uvicorn[standard]>=0.29.0",
+    "httpx>=0.27.0",
+    "python-dotenv>=1.0.1",
+]
+
+[project.optional-dependencies]
+flask = ["flask>=3.0.0"]
+dev = ["pytest", "pytest-asyncio", "httpx"]
+
+[project.urls]
+Homepage = "https://github.com/RodrigoMvs123/agent-load-protocol"
+Repository = "https://github.com/RodrigoMvs123/agent-load-protocol"
+Documentation = "https://github.com/RodrigoMvs123/agent-load-protocol/blob/main/SPEC.md"
+"Bug Tracker" = "https://github.com/RodrigoMvs123/agent-load-protocol/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["alp"]