langgraph-api 0.18.0.dev9__tar.gz → 0.18.0.dev10__tar.gz

{langgraph_api-0.18.0.dev9 → langgraph_api-0.18.0.dev10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langgraph-api
-Version: 0.18.0.dev9
+Version: 0.18.0.dev10
 Author-email: Will Fu-Hinthorn <will@langchain.dev>, Josh Rogers <josh@langchain.dev>, Parker Rule <parker@langchain.dev>
 License: Elastic-2.0
 License-File: LICENSE
@@ -21,11 +21,13 @@ Requires-Dist: langgraph-runtime-inmem<0.39.0.dev0,>=0.38.0.dev0
 Requires-Dist: langgraph-sdk>=0.4.4
 Requires-Dist: langgraph<2,>=0.4.10
 Requires-Dist: langsmith[otel]>=0.6.3
+Requires-Dist: mcp<3,>=2.3.0
 Requires-Dist: opentelemetry-api>=0.0.1
 Requires-Dist: opentelemetry-exporter-otlp-proto-http>=0.0.1
 Requires-Dist: opentelemetry-exporter-prometheus<0.64,>=0.63b1
 Requires-Dist: opentelemetry-sdk>=0.0.1
 Requires-Dist: orjson>=3.9.7
+Requires-Dist: packaging>=23.2
 Requires-Dist: prometheus-client>=0.0.1
 Requires-Dist: protobuf<7.0.0,>=6.32.1
 Requires-Dist: pyjwt>=2.15.0

langgraph_api-0.18.0.dev10/langgraph_api/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.18.0.dev10"

langgraph_api-0.18.0.dev10/langgraph_api/api/mcp/__init__.py

@@ -0,0 +1,21 @@
+import structlog
+
+from langgraph_api.api.mcp._sdk import InstalledSdk
+from langgraph_api.config import MCP_ENABLED
+
+__all__ = ["MCP_SERVED", "mcp_routes"]
+
+logger = structlog.stdlib.get_logger(__name__)
+SDK = InstalledSdk.find()
+MCP_SERVED = MCP_ENABLED and SDK.is_supported
+
+if SDK.is_supported:
+    from langgraph_api.api.mcp._routes import mcp_routes
+else:
+    mcp_routes = []
+    if MCP_ENABLED:
+        logger.error(
+            "MCP endpoint disabled: the installed MCP SDK is not supported",
+            required=str(SDK.required.specifier),
+            installed=SDK.installed,
+        )

langgraph_api-0.18.0.dev10/langgraph_api/api/mcp/_calls.py

@@ -0,0 +1,6 @@
+import mcp_types as types
+from pydantic import JsonValue
+
+
+class ToolCallParams(types.CallToolRequestParams):
+    context: dict[str, JsonValue] | None = None

langgraph_api-0.18.0.dev10/langgraph_api/api/mcp/_constants.py

@@ -0,0 +1,11 @@
+MAX_ASSISTANTS = 1000
+DEFAULT_PAGE_SIZE = 100
+MAX_PAGE_OFFSET = 2**63 - 1
+MAX_CURSOR_LENGTH = len(str(MAX_PAGE_OFFSET))
+
+PAUSED_TOOL_MESSAGE = (
+    "This tool paused to ask for human input, and this client can't answer it."
+)
+RUN_FAILED_MESSAGE = "The tool's run failed."
+INVALID_CURSOR_MESSAGE = "Invalid cursor"
+INTERNAL_ERROR_MESSAGE = "Internal server error"

langgraph_api-0.18.0.dev10/langgraph_api/api/mcp/_routes.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from http import HTTPStatus
+from typing import TYPE_CHECKING
+
+from starlette.responses import Response
+
+from langgraph_api.api.mcp._origins import OriginPolicy
+from langgraph_api.api.mcp._server import serve
+from langgraph_api.config import CORS_SETTINGS
+from langgraph_api.route import ApiRequest, ApiResponse, ApiRoute
+
+if TYPE_CHECKING:
+    from starlette.types import ASGIApp
+
+__all__ = ["mcp_routes"]
+
+ORIGIN_POLICY = OriginPolicy.of(CORS_SETTINGS)
+
+
+async def handle_mcp_endpoint(request: ApiRequest) -> ASGIApp:
+    if not ORIGIN_POLICY.allows(request.headers.get("origin")):
+        return ApiResponse(
+            {"error": "Origin is not allowed"}, status_code=HTTPStatus.FORBIDDEN
+        )
+    if request.method != "POST":
+        return Response(
+            status_code=HTTPStatus.METHOD_NOT_ALLOWED, headers={"Allow": "POST"}
+        )
+    return serve
+
+
+mcp_routes = [
+    ApiRoute("/mcp", handle_mcp_endpoint, methods=["GET", "POST", "DELETE"]),
+]

{langgraph_api-0.18.0.dev9 → langgraph_api-0.18.0.dev10}/langgraph_api/api/mcp/_sanitizers.py

@@ -1,6 +1,9 @@
 import re
+from collections.abc import Iterable
 from typing import Any
 
+from mcp.shared.inbound import X_MCP_HEADER_KEY
+
 # MCP tool name constraints per the 2025-11-25 spec.
 # Valid characters: ASCII letters, digits, underscore, hyphen, dot.
 # Length: 1-128 characters.
@@ -72,6 +75,46 @@ def simplify_mcp_schema_inplace(schema: dict[str, Any]) -> None:
             }
 
 
+_SUBSCHEMA_KEYWORDS = frozenset(
+    {
+        "items",
+        "contains",
+        "unevaluatedItems",
+        "additionalProperties",
+        "propertyNames",
+        "unevaluatedProperties",
+        "not",
+        "if",
+        "then",
+        "else",
+        "contentSchema",
+    }
+)
+_SUBSCHEMA_LIST_KEYWORDS = frozenset({"allOf", "anyOf", "oneOf", "prefixItems"})
+_SUBSCHEMA_MAP_KEYWORDS = frozenset(
+    {"properties", "patternProperties", "dependentSchemas", "$defs", "definitions"}
+)
+
+
+def drop_mcp_param_headers_inplace(schema: object) -> None:
+    if not isinstance(schema, dict):
+        return
+    schema.pop(X_MCP_HEADER_KEY, None)
+    for keyword, value in schema.items():
+        for subschema in _subschemas(keyword, value):
+            drop_mcp_param_headers_inplace(subschema)
+
+
+def _subschemas(keyword: object, value: object) -> Iterable[object]:
+    if keyword in _SUBSCHEMA_KEYWORDS:
+        return (value,)
+    if keyword in _SUBSCHEMA_LIST_KEYWORDS and isinstance(value, list):
+        return value
+    if keyword in _SUBSCHEMA_MAP_KEYWORDS and isinstance(value, dict):
+        return value.values()
+    return ()
+
+
 def normalize_name(name: str) -> str:
     """Convert an assistant name to a valid MCP tool name.
 

langgraph_api-0.18.0.dev10/langgraph_api/api/mcp/_sdk.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from importlib.metadata import PackageNotFoundError, requires, version
+
+from packaging.requirements import Requirement
+
+SERVER_DISTRIBUTION = "langgraph-api"
+SDK_DISTRIBUTION = "mcp"
+
+
+@dataclass(frozen=True, slots=True)
+class InstalledSdk:
+    required: Requirement
+    installed: str | None
+
+    @classmethod
+    def find(cls) -> InstalledSdk:
+        return cls(_declared_requirement(), _installed_version())
+
+    @property
+    def is_supported(self) -> bool:
+        return self.installed is not None and self.required.specifier.contains(
+            self.installed, prereleases=True
+        )
+
+
+def _declared_requirement() -> Requirement:
+    return next(
+        requirement
+        for requirement in map(Requirement, requires(SERVER_DISTRIBUTION) or ())
+        if requirement.name == SDK_DISTRIBUTION
+    )
+
+
+def _installed_version() -> str | None:
+    try:
+        return version(SDK_DISTRIBUTION)
+    except PackageNotFoundError:
+        return None

langgraph_api-0.18.0.dev10/langgraph_api/api/mcp/_server.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from mcp.server.caching import CacheHint
+from mcp.server.lowlevel import Server
+from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
+
+from langgraph_api import __version__
+from langgraph_api.api.mcp._calls import ToolCallParams
+from langgraph_api.api.mcp._tools import AssistantTools
+from langgraph_api.config import HTTP_MAX_REQUEST_BODY_BYTES
+
+if TYPE_CHECKING:
+    import mcp_types as types
+    from mcp.server.context import ServerRequestContext
+    from starlette.types import Receive, Scope, Send
+
+UNCACHED = CacheHint(ttl_ms=0, scope="private")
+HTTP_WHITESPACE = b" \t"
+
+
+async def _list_tools(
+    ctx: ServerRequestContext, params: types.PaginatedRequestParams | None
+) -> types.ListToolsResult:
+    return await AssistantTools.of(ctx).list(params.cursor if params else None)
+
+
+async def _call_tool(
+    ctx: ServerRequestContext, params: ToolCallParams
+) -> types.CallToolResult:
+    return await AssistantTools.of(ctx).call(params)
+
+
+def _tools_declare_no_param_headers(_tool_name: str) -> None:
+    return None
+
+
+SERVER = Server(
+    "LangGraph",
+    version=__version__,
+    cache_hints={"server/discover": UNCACHED, "tools/list": UNCACHED},
+    get_tool_input_schema=_tools_declare_no_param_headers,
+    on_list_tools=_list_tools,
+)
+SERVER.add_request_handler("tools/call", ToolCallParams, _call_tool)
+
+
+async def serve(scope: Scope, receive: Receive, send: Send) -> None:
+    manager = StreamableHTTPSessionManager(
+        SERVER,
+        stateless=True,
+        json_response=True,
+        max_request_body_size=HTTP_MAX_REQUEST_BODY_BYTES,
+    )
+    async with manager.run():
+        await manager.handle_request(_with_trimmed_headers(scope), receive, send)
+
+
+def _with_trimmed_headers(scope: Scope) -> Scope:
+    return {
+        **scope,
+        "headers": [
+            (name, value.strip(HTTP_WHITESPACE)) for name, value in scope["headers"]
+        ],
+    }

langgraph_api-0.18.0.dev10/langgraph_api/api/mcp/_tools.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import functools
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, assert_never
+
+import httpx
+import mcp_types as types
+import structlog
+from langgraph_sdk.client import LangGraphClient, get_client
+from mcp.shared.exceptions import MCPError
+from starlette.requests import Request
+
+from langgraph_api.api.mcp import _sanitizers
+from langgraph_api.api.mcp._constants import (
+    DEFAULT_PAGE_SIZE,
+    INTERNAL_ERROR_MESSAGE,
+    INVALID_CURSOR_MESSAGE,
+    MAX_ASSISTANTS,
+    MAX_CURSOR_LENGTH,
+    MAX_PAGE_OFFSET,
+    PAUSED_TOOL_MESSAGE,
+)
+from langgraph_api.api.mcp._outcome import (
+    Completed,
+    Failed,
+    Paused,
+    RunOutcome,
+    parse_outcome,
+)
+from langgraph_api.serde import json_dumpb
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Iterable, Mapping
+
+    from langgraph_sdk.schema import Assistant
+    from mcp.server.context import ServerRequestContext
+
+    from langgraph_api.api.mcp._calls import ToolCallParams
+
+logger = structlog.stdlib.get_logger(__name__)
+
+_CURSOR_DIGITS = re.compile(rf"[0-9]{{1,{MAX_CURSOR_LENGTH}}}")
+_ANNOTATIONS = types.ToolAnnotations(
+    read_only_hint=False,
+    destructive_hint=False,
+    idempotent_hint=False,
+    open_world_hint=True,
+)
+
+
+@functools.lru_cache(maxsize=1)
+def _client() -> LangGraphClient:
+    return get_client(url=None)
+
+
+@contextlib.asynccontextmanager
+async def _failures_as_mcp_errors() -> AsyncIterator[None]:
+    try:
+        yield
+    except MCPError:
+        raise
+    except Exception as error:
+        mcp_error = _mcp_error(error)
+        if mcp_error.code == types.INTERNAL_ERROR:
+            await logger.aexception("MCP tool request failed")
+        raise mcp_error from error
+
+
+def _mcp_error(error: Exception) -> MCPError:
+    match error:
+        case httpx.HTTPStatusError(response=response) if response.is_client_error:
+            return MCPError(types.INVALID_PARAMS, _detail(response))
+        case _:
+            return MCPError(types.INTERNAL_ERROR, INTERNAL_ERROR_MESSAGE)
+
+
+def _detail(response: httpx.Response) -> str:
+    with contextlib.suppress(ValueError):
+        match response.json():
+            case {"detail": str() as detail} if detail:
+                return detail
+    return response.reason_phrase
+
+
+@dataclass(frozen=True, slots=True)
+class AssistantTools:
+    client: LangGraphClient
+    headers: Mapping[str, str]
+
+    @classmethod
+    def of(cls, ctx: ServerRequestContext) -> AssistantTools:
+        if not isinstance(ctx.request, Request):
+            raise TypeError("Assistant tools are served over HTTP only")
+        return cls(_client(), ctx.request.headers)
+
+    @_failures_as_mcp_errors()
+    async def list(self, cursor: str | None) -> types.ListToolsResult:
+        offset = _page_offset(cursor)
+        assistants = await self.client.assistants.search(
+            offset=offset, limit=DEFAULT_PAGE_SIZE, headers=self.headers
+        )
+        named = await _first_per_name(assistants)
+        tools = await asyncio.gather(
+            *(self._tool(assistant, name) for name, assistant in named.items())
+        )
+        return types.ListToolsResult(
+            tools=[tool for tool in tools if tool is not None],
+            next_cursor=str(offset + DEFAULT_PAGE_SIZE)
+            if len(assistants) == DEFAULT_PAGE_SIZE
+            else None,
+        )
+
+    @_failures_as_mcp_errors()
+    async def call(self, params: ToolCallParams) -> types.CallToolResult:
+        value = await self.client.runs.wait(
+            thread_id=None,
+            assistant_id=await self._assistant_serving(params.name),
+            input=params.arguments or {},
+            context=params.context,
+            headers=self.headers,
+            raise_error=False,
+        )
+        return _tool_result(parse_outcome(value))
+
+    async def _tool(self, assistant: Assistant, name: str) -> types.Tool | None:
+        try:
+            schemas = await self.client.assistants.get_schemas(
+                assistant["assistant_id"], headers=self.headers
+            )
+            input_schema = schemas.get("input_schema", {})
+            if input_schema is None:
+                raise ValueError("Input schema generation failed")
+            if input_schema:
+                _sanitizers.simplify_mcp_schema_inplace(input_schema)
+                _sanitizers.drop_mcp_param_headers_inplace(input_schema)
+            input_schema.setdefault("type", "object")
+            return types.Tool(
+                name=name,
+                title=assistant["name"],
+                description=assistant.get("description")
+                or f"Tool based on the {assistant['name']} assistant",
+                input_schema=input_schema,
+                annotations=_ANNOTATIONS,
+            )
+        except Exception as e:
+            await logger.awarning(
+                "Failed to get schema for assistant, skipping from MCP tools list",
+                assistant_id=assistant["assistant_id"],
+                assistant_name=assistant["name"],
+                error=str(e),
+            )
+            return None
+
+    async def _assistant_serving(self, tool_name: str) -> str:
+        assistants = await self.client.assistants.search(
+            limit=MAX_ASSISTANTS, headers=self.headers
+        )
+        match [
+            assistant["assistant_id"]
+            for assistant in assistants
+            if _sanitizers.normalize_name(assistant["name"]) == tool_name
+        ]:
+            case [assistant_id]:
+                return assistant_id
+            case []:
+                raise MCPError(types.INVALID_PARAMS, f"Unknown tool: {tool_name}")
+            case _:
+                raise MCPError(
+                    types.INVALID_PARAMS, "Multiple tools found with the same name."
+                )
+
+
+async def _first_per_name(assistants: Iterable[Assistant]) -> dict[str, Assistant]:
+    named: dict[str, Assistant] = {}
+    for assistant in assistants:
+        name = _sanitizers.normalize_name(assistant["name"])
+        if name in named:
+            await logger.awarning(
+                f"Duplicate assistant name found {assistant['name']}",
+                name=assistant["name"],
+                normalized=name,
+            )
+        else:
+            named[name] = assistant
+    return named
+
+
+def _page_offset(cursor: str | None) -> int:
+    if cursor is None:
+        return 0
+    if not _CURSOR_DIGITS.fullmatch(cursor) or int(cursor) > MAX_PAGE_OFFSET:
+        raise MCPError(types.INVALID_PARAMS, INVALID_CURSOR_MESSAGE)
+    return int(cursor)
+
+
+def _tool_result(outcome: RunOutcome) -> types.CallToolResult:
+    match outcome:
+        case Completed(output=output):
+            return types.CallToolResult(content=[_text(json_dumpb(output).decode())])
+        case Failed(message=message):
+            return types.CallToolResult(content=[_text(message)], is_error=True)
+        case Paused(interrupts=interrupts):
+            return types.CallToolResult(
+                content=[
+                    _text(PAUSED_TOOL_MESSAGE),
+                    _text(json_dumpb(interrupts).decode()),
+                ],
+                is_error=True,
+            )
+        case _:
+            assert_never(outcome)
+
+
+def _text(text: str) -> types.TextContent:
+    return types.TextContent(type="text", text=text)

{langgraph_api-0.18.0.dev9 → langgraph_api-0.18.0.dev10}/langgraph_api/api/meta.py

@@ -4,6 +4,7 @@ from prometheus_client import CONTENT_TYPE_LATEST, generate_latest
 from starlette.responses import JSONResponse, PlainTextResponse
 
 from langgraph_api import __version__, config, metadata
+from langgraph_api.api.mcp import MCP_SERVED
 from langgraph_api.feature_flags import IS_POSTGRES_OR_GRPC_BACKEND
 from langgraph_api.http_metrics import HTTP_METRICS_COLLECTOR
 from langgraph_api.route import ApiRequest
@@ -80,6 +81,7 @@ async def meta_info(request: ApiRequest):
                 and bool(config.TRACING),
                 "langsmith_tracing_replicas": True,
                 "langsmith_tracing_session_on_runs": True,
+                "mcp": MCP_SERVED,
             },
             "host": {
                 "kind": metadata.HOST,

{langgraph_api-0.18.0.dev9 → langgraph_api-0.18.0.dev10}/langgraph_api/api/openapi.py

@@ -6,6 +6,7 @@ from functools import lru_cache
 import orjson
 
 from langgraph_api import config
+from langgraph_api.api.mcp import MCP_SERVED
 from langgraph_api.graph import GRAPHS
 from langgraph_api.metadata import USER_API_URL
 from langgraph_api.validation import openapi
@@ -107,10 +108,8 @@ def get_openapi_spec() -> bytes:
     elif config.MOUNT_PREFIX:
         final["servers"] = [{"url": config.MOUNT_PREFIX}]
 
-    if not config.MCP_ENABLED:
-        # Remove the MCP paths from the OpenAPI spec
+    if not MCP_SERVED:
         final["paths"].pop("/mcp/", None)
-        # Remove the MCP tag definition
         final["tags"] = [t for t in final.get("tags", []) if t.get("name") != "MCP"]
 
     if not config.A2A_ENABLED: