lcp-mcp-server 1.0.0__tar.gz

lcp_mcp_server-1.0.0/.gitignore

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

lcp_mcp_server-1.0.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.5
+Name: lcp-mcp-server
+Version: 1.0.0
+Summary: LCP (Lead Context Protocol) MCP server — thin adapter wrapping LCP REST endpoints as agent tools.
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: jsonschema>=4.20.0
+Requires-Dist: lcp-sdk>=1.0.0
+Requires-Dist: mcp<2.1.0,>=1.28.1
+Requires-Dist: referencing>=0.35.0

lcp_mcp_server-1.0.0/README.md

@@ -0,0 +1,91 @@
+# LCP MCP Server — Reference Implementation
+
+A thin MCP (Model Context Protocol) adapter that exposes LCP REST endpoints
+as agent tools. The core protocol is REST+JSON; this server wraps it so AI
+agents can interact with any LCP-compliant endpoint via MCP. It does not
+host an LCP platform, persist leads, receive webhooks, or run auctions.
+
+> **Architecture:** The LCP core never depends on MCP. This server is a
+> stateless adapter — it translates MCP tool calls into HTTP requests and
+> HTTP responses into MCP tool results. It works with any LCP-compliant
+> endpoint (any LCP-compliant REST API).
+
+## Tools
+
+| Tool | LCP Endpoint | Description |
+|---|---|---|
+| `submit_lead` | `POST /v1/lcp/leads` | Submit a lead message |
+| `submit_call` | `POST /v1/lcp/calls` | Submit a call lead message |
+| `query_lead_status` | `GET /v1/lcp/leads/{lead_id}` | Query lead status and lifecycle |
+| `get_schema` | `GET /v1/lcp/schemas/{name}` | Retrieve a JSON Schema (envelope, core, message type, offer, vertical) |
+| `get_capabilities` | `GET /v1/lcp/capabilities` | Discover endpoint capabilities (versions, verticals, countries) |
+| `list_offers` | `GET /v1/lcp/offers` | List active offers for the authenticated sender |
+| `submit_bid` | `POST /v1/lcp/bids` | Submit a bid in response to a ping |
+
+## Setup
+
+```bash
+# From the repository root while packages are unreleased.
+python3 -m pip install -e implementations/sdk/python -e implementations/mcp-server
+
+# After the packages are published, install the adapter and its shared SDK.
+python3 -m pip install lcp-mcp-server lcp-sdk
+```
+
+The adapter delegates HTTP, HMAC signing, retries, and raw-body security
+primitives to `lcp-sdk`; it only provides the MCP tool binding and local schema
+fallback.
+
+## Configuration
+
+The server reads its target endpoint from environment variables:
+
+| Variable | Default | Description |
+|---|---|---|
+| `LCP_ENDPOINT` | `http://localhost:8000` | Base URL of the LCP-compliant REST API |
+| `LCP_API_KEY` | (none) | Bearer token for authentication |
+| `LCP_HMAC_SECRET` | (none) | HMAC shared secret (if using HMAC auth instead of API key) |
+| `LCP_SENDER_ID` | (none) | Sender ID to use in outgoing messages and read requests |
+
+## Authentication profile
+
+HMAC requests use the canonical signing input:
+
+```text
+<timestamp>\n<idempotency-key>\n<raw-request-body>
+```
+
+The adapter sends `X-LCP-Sender-Id`, `X-LCP-Timestamp`,
+`X-LCP-Idempotency-Key` for mutating requests, and `X-LCP-Signature`. Bearer
+requests use `Authorization: Bearer <token>`.
+
+## Run
+
+```bash
+# Stdio transport (for MCP clients like Claude Desktop, Hermes)
+lcp-mcp-server
+
+# Or via Python module
+python -m lcp_mcp_server.server
+```
+
+## MCP Client Configuration
+
+Add to your MCP client config (e.g. Claude Desktop `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "lcp": {
+      "command": "lcp-mcp-server",
+      "env": {
+        "LCP_ENDPOINT": "https://api.example.com",
+        "LCP_API_KEY": "your-api-key",
+        "LCP_SENDER_ID": "your-sender-id"
+      }
+    }
+  }
+}
+```
+
+## LicenseApache 2.0 — same as the LCP specification. See the [SDK support policy](../../docs/SDK-ROADMAP.md) for the MCP relationship and package compatibility.

lcp_mcp_server-1.0.0/lcp_mcp_server/__init__.py

@@ -0,0 +1,5 @@
+"""LCP MCP Server package."""
+
+from .server import main
+
+__all__ = ["main"]

lcp_mcp_server-1.0.0/lcp_mcp_server/client.py

@@ -0,0 +1,87 @@
+"""LCP HTTP client compatibility wrapper for the MCP adapter.
+
+The MCP package intentionally delegates authentication, retries, and HTTP
+transport to the standalone lcp-sdk package. This wrapper preserves the MCP
+adapter's historical ``post``/``get`` response shape, including ``_ok`` and
+``_status_code`` metadata.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from lcp_sdk import LCPClient as SDKLCPClient
+from lcp_sdk import LCPHTTPError
+
+
+class LCPClient:
+    """MCP-facing compatibility wrapper around :class:`lcp_sdk.LCPClient`."""
+
+    def __init__(
+        self,
+        endpoint: str | None = None,
+        api_key: str | None = None,
+        hmac_secret: str | None = None,
+        sender_id: str | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self._client = SDKLCPClient(
+            endpoint or os.environ.get("LCP_ENDPOINT", "http://localhost:8000"),
+            sender_id=sender_id or os.environ.get("LCP_SENDER_ID", ""),
+            api_key=api_key or os.environ.get("LCP_API_KEY"),
+            hmac_secret=hmac_secret or os.environ.get("LCP_HMAC_SECRET"),
+            timeout=timeout,
+        )
+
+    @property
+    def endpoint(self) -> str:
+        return self._client.endpoint
+
+    @property
+    def sender_id(self) -> str | None:
+        return self._client.sender_id
+
+    def post(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        """POST an LCP envelope, preserving the legacy MCP response shape."""
+        try:
+            data = self._client.request("POST", path, payload=payload)
+            return _with_metadata(data, 200, True)
+        except LCPHTTPError as exc:
+            body = exc.body if isinstance(exc.body, dict) else {"raw": exc.body}
+            return _with_metadata(body, exc.status_code, False)
+
+    def get(self, path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        """GET from the LCP endpoint, preserving the legacy response shape."""
+        try:
+            data = self._client.request("GET", path, params=params)
+            return _with_metadata(data, 200, True)
+        except LCPHTTPError as exc:
+            body = exc.body if isinstance(exc.body, dict) else {"raw": exc.body}
+            return _with_metadata(body, exc.status_code, False)
+
+    def submit_lead(self, envelope: dict[str, Any]) -> dict[str, Any]:
+        return self.post("/v1/lcp/leads", envelope)
+
+    def submit_call(self, envelope: dict[str, Any]) -> dict[str, Any]:
+        return self.post("/v1/lcp/calls", envelope)
+
+    def query_lead_status(self, lead_id: str) -> dict[str, Any]:
+        return self.get(f"/v1/lcp/leads/{lead_id}")
+
+    def get_schema(self, name: str) -> dict[str, Any]:
+        return self.get(f"/v1/lcp/schemas/{name}")
+
+    def get_capabilities(self) -> dict[str, Any]:
+        return self.get("/v1/lcp/capabilities")
+
+    def list_offers(self, vertical: str | None = None) -> dict[str, Any]:
+        params = {"vertical": vertical} if vertical else None
+        return self.get("/v1/lcp/offers", params=params)
+
+
+def _with_metadata(data: dict[str, Any], status_code: int, ok: bool) -> dict[str, Any]:
+    result = dict(data)
+    result["_status_code"] = status_code
+    result["_ok"] = ok
+    return result

lcp_mcp_server-1.0.0/lcp_mcp_server/schema_loader.py

@@ -0,0 +1,47 @@
+"""Schema loader — reads JSON Schemas from the LCP repo.
+
+When the REST endpoint is unavailable (e.g. local development), the MCP server
+can serve schemas directly from the repo's schemas/ and verticals/ directories.
+
+LCP — Lead Context Protocol. Created by Spear Systems (a Spear company).
+Open standard — Apache 2.0, free to implement.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+# implementations/mcp-server/ -> ../../schemas, ../../verticals
+_REPO_ROOT = Path(__file__).resolve().parents[3]
+SCHEMAS_DIR = _REPO_ROOT / "schemas"
+VERTICALS_DIR = _REPO_ROOT / "verticals"
+
+
+def list_schemas() -> list[str]:
+    """List all available schema names."""
+    names: list[str] = []
+    if SCHEMAS_DIR.exists():
+        names.extend(f.stem for f in SCHEMAS_DIR.glob("*.json"))
+    if VERTICALS_DIR.exists():
+        names.extend(f"verticals/{f.stem}" for f in VERTICALS_DIR.glob("*.json"))
+    return sorted(names)
+
+
+def load_schema(name: str) -> dict[str, Any] | None:
+    """Load a schema by name. Returns None if not found.
+
+    Core/message schemas: name -> schemas/{name}.json
+    Vertical schemas: verticals/{name} -> verticals/{name}.json
+    """
+    if name.startswith("verticals/"):
+        path = VERTICALS_DIR / f"{name.removeprefix('verticals/')}.json"
+    else:
+        path = SCHEMAS_DIR / f"{name}.json"
+
+    if not path.exists():
+        return None
+
+    with open(path) as f:
+        return json.load(f)

lcp_mcp_server-1.0.0/lcp_mcp_server/server.py

@@ -0,0 +1,258 @@
+"""LCP MCP Server — thin adapter wrapping LCP REST endpoints as MCP tools.
+
+Tools map 1:1 to LCP REST endpoints per SPEC.md §10:
+  submit_lead       -> POST /v1/lcp/leads
+  submit_call       -> POST /v1/lcp/calls
+  query_lead_status -> GET  /v1/lcp/leads/{lead_id}
+  get_schema        -> GET  /v1/lcp/schemas/{name}  (falls back to local repo)
+  get_capabilities  -> GET  /v1/lcp/capabilities
+  list_offers       -> GET  /v1/lcp/offers
+
+The server is stateless — it creates a fresh HTTP client per tool call.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import mcp.types as types
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from lcp_sdk import build_envelope
+
+from .client import LCPClient
+from .schema_loader import list_schemas, load_schema
+
+app: Server
+
+def _make_envelope(msg_type: str, sender_id: str, receiver_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+    """Wrap a payload using the shared Python SDK envelope builder."""
+    return build_envelope(msg_type, sender_id, receiver_id, payload)
+
+
+def _tool_result(data: dict[str, Any]) -> list[types.TextContent]:
+    """Format a dict as an MCP text content response."""
+    return [types.TextContent(type="text", text=json.dumps(data, indent=2))]
+
+
+def _error_result(message: str, code: str = "LCP-500") -> list[types.TextContent]:
+    """Format an error as an MCP text content response."""
+    return _tool_result({"errors": [{"code": code, "message": message}]})
+
+
+# ─── Tool definitions ────────────────────────────────────────────────────────
+
+async def _list_tools() -> list[types.Tool]:
+    return [
+        types.Tool(
+            name="submit_lead",
+            description="Submit a lead to an LCP-compliant endpoint. The payload should contain lead fields (consumer, location, compliance, attributes, channel, etc.). The server wraps it in an LCP envelope.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "receiver_id": {"type": "string", "description": "LCP receiver ID (e.g. 'spx')."},
+                    "payload": {
+                        "type": "object",
+                        "description": "Lead payload — consumer, location, compliance, provenance, attributes, channel, etc. See LCP lead schema.",
+                    },
+                },
+                "required": ["receiver_id", "payload"],
+            },
+        ),
+        types.Tool(
+            name="submit_call",
+            description="Submit a call lead to an LCP-compliant endpoint. The payload should contain call fields (call block, consumer, location, compliance, attributes).",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "receiver_id": {"type": "string", "description": "LCP receiver ID."},
+                    "payload": {
+                        "type": "object",
+                        "description": "Call payload — call block (call_id, status, durations, recording, etc.), consumer, location, compliance, attributes. See LCP call schema.",
+                    },
+                },
+                "required": ["receiver_id", "payload"],
+            },
+        ),
+        types.Tool(
+            name="query_lead_status",
+            description="Query the status and lifecycle of a previously submitted lead.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "lead_id": {"type": "string", "description": "The lead ID to query."},
+                },
+                "required": ["lead_id"],
+            },
+        ),
+        types.Tool(
+            name="get_schema",
+            description="Retrieve a JSON Schema by name. Core schemas: envelope, core, lead, call, ping, post, ack, event, bid, offer. Vertical schemas: 'verticals/mortgage', etc. Falls back to local repo files if the REST endpoint is unavailable.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "name": {
+                        "type": "string",
+                        "description": "Schema name (e.g. 'envelope', 'lead', 'verticals/mortgage').",
+                    },
+                },
+                "required": ["name"],
+            },
+        ),
+        types.Tool(
+            name="get_capabilities",
+            description="Discover the capabilities of the LCP endpoint — supported versions, message types, verticals, countries, auth methods, events, conformance level.",
+            inputSchema={
+                "type": "object",
+                "properties": {},
+            },
+        ),
+        types.Tool(
+            name="list_offers",
+            description="List active offers available to the authenticated sender. Optionally filter by vertical.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "vertical": {
+                        "type": "string",
+                        "description": "Filter offers by vertical (e.g. 'mortgage').",
+                    },
+                },
+            },
+        ),
+        types.Tool(
+            name="submit_bid",
+            description="Submit a bid in response to a ping. The platform collects all bids and selects the winner. The winner receives a post with full PII.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "ping_id": {"type": "string", "description": "ID of the ping being responded to."},
+                    "decision": {"type": "string", "enum": ["accept", "reject", "pass"], "description": "accept = bid for the lead; reject = do not want; pass = decline to bid."},
+                    "bid_price_cents": {"type": "integer", "minimum": 0, "description": "Bid price in cents. Required when decision = accept."},
+                    "currency": {"type": "string", "description": "ISO 4217 currency code (e.g. AUD, USD)."},
+                    "estimated_contact_seconds": {"type": "integer", "minimum": 0, "description": "Estimated time-to-contact in seconds."},
+                    "buyer_reference": {"type": "string", "description": "Buyer's internal tracking reference."},
+                    "reject_reason": {"type": "string", "description": "Why rejected (optional)."},
+                },
+                "required": ["ping_id", "decision"],
+            },
+        ),
+    ]
+
+
+# ─── Tool call handler ───────────────────────────────────────────────────────
+
+async def _call_tool(name: str, arguments: dict[str, Any]) -> list[types.TextContent]:
+    client = LCPClient()
+
+    if name == "submit_lead":
+        receiver_id = arguments.get("receiver_id", "")
+        payload = arguments.get("payload", {})
+        envelope = _make_envelope("lead", client.sender_id, receiver_id, payload)
+        result = client.submit_lead(envelope)
+        return _tool_result(result)
+
+    elif name == "submit_call":
+        receiver_id = arguments.get("receiver_id", "")
+        payload = arguments.get("payload", {})
+        envelope = _make_envelope("call", client.sender_id, receiver_id, payload)
+        result = client.submit_call(envelope)
+        return _tool_result(result)
+
+    elif name == "query_lead_status":
+        lead_id = arguments.get("lead_id", "")
+        result = client.query_lead_status(lead_id)
+        return _tool_result(result)
+
+    elif name == "get_schema":
+        schema_name = arguments.get("name", "")
+        # Try the REST endpoint first
+        try:
+            result = client.get_schema(schema_name)
+            if result.get("_ok"):
+                return _tool_result(result)
+        except Exception:
+            pass  # Fall back to local repo
+        # Fall back to local repo files
+        schema = load_schema(schema_name)
+        if schema:
+            return _tool_result(schema)
+        available = list_schemas()
+        return _error_result(
+            f"Schema '{schema_name}' not found. Available: {', '.join(available)}",
+            code="LCP-007",
+        )
+
+    elif name == "get_capabilities":
+        result = client.get_capabilities()
+        return _tool_result(result)
+
+    elif name == "list_offers":
+        vertical = arguments.get("vertical")
+        result = client.list_offers(vertical)
+        return _tool_result(result)
+
+    elif name == "submit_bid":
+        ping_id = arguments.get("ping_id", "")
+        decision = arguments.get("decision", "pass")
+        bid_price = arguments.get("bid_price_cents", 0)
+        currency = arguments.get("currency", "USD")
+        payload = {
+            "ping_id": ping_id,
+            "decision": decision,
+            "bid_price_cents": bid_price,
+            "currency": currency,
+        }
+        for opt_field in ["estimated_contact_seconds", "buyer_reference", "reject_reason"]:
+            if opt_field in arguments:
+                payload[opt_field] = arguments[opt_field]
+        receiver_id = "platform"  # bids go to the platform, not a buyer
+        envelope = _make_envelope("bid", client.sender_id, receiver_id, payload)
+        result = client.post("/v1/lcp/bids", envelope)
+        return _tool_result(result)
+
+    else:
+        return _error_result(f"Unknown tool: {name}", code="LCP-006")
+
+
+# ─── MCP SDK compatibility ───────────────────────────────────────────────────
+
+# MCP 1.x exposed decorator methods on Server; MCP 2.x accepts callbacks in
+# the constructor. Keep the adapter compatible with both supported API shapes
+# while the dependency range transitions to the 2.x server implementation.
+if hasattr(Server, "list_tools"):
+    legacy_app = Server("lcp-mcp-server")
+    list_tools = legacy_app.list_tools()(_list_tools)
+    call_tool = legacy_app.call_tool()(_call_tool)
+    app = legacy_app
+else:
+    async def list_tools(_context: Any, _params: Any) -> types.ListToolsResult:
+        return types.ListToolsResult(tools=await _list_tools())
+
+    async def call_tool(_context: Any, params: types.CallToolRequestParams) -> types.CallToolResult:
+        content = await _call_tool(params.name, params.arguments or {})
+        return types.CallToolResult(content=content)
+
+    app = Server(
+        "lcp-mcp-server",
+        on_list_tools=list_tools,
+        on_call_tool=call_tool,
+    )
+
+
+# ─── Entrypoint ──────────────────────────────────────────────────────────────
+
+async def _run() -> None:
+    async with stdio_server() as (read_stream, write_stream):
+        await app.run(read_stream, write_stream, app.create_initialization_options())
+
+
+def main() -> None:
+    """Entrypoint for the lcp-mcp-server command."""
+    import asyncio
+    asyncio.run(_run())
+
+
+if __name__ == "__main__":
+    main()

lcp_mcp_server-1.0.0/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "lcp-mcp-server"
+version = "1.0.0"
+description = "LCP (Lead Context Protocol) MCP server — thin adapter wrapping LCP REST endpoints as agent tools."
+license = "Apache-2.0"
+requires-python = ">=3.10"
+dependencies = [
+    "mcp>=1.28.1,<2.1.0",
+    "lcp-sdk>=1.0.0",
+    "httpx>=0.27.0",
+    "jsonschema>=4.20.0",
+    "referencing>=0.35.0",
+]
+
+[project.scripts]
+lcp-mcp-server = "lcp_mcp_server.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["lcp_mcp_server"]