ivcap-lambda 0.7.25__py3-none-any.whl → 0.8.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
ivcap_lambda/executor.py CHANGED
@@ -155,7 +155,12 @@ class Executor(Generic[T]):
155
155
  raise Exception(f"unexpected function parameter '{k}'")
156
156
 
157
157
  async def execute(
158
- self, param: Any, job_id: str, req: Request, report_result=True
158
+ self,
159
+ param: Any,
160
+ job_id: str,
161
+ req: Request,
162
+ report_result: bool = True,
163
+ reporter: EventReporter | None = None,
159
164
  ) -> asyncio.Queue[T | ExecutionError]:
160
165
  """
161
166
  Execute the function with the given parameter in a thread and return a queue with the result.
@@ -163,7 +168,13 @@ class Executor(Generic[T]):
163
168
  Args:
164
169
  param: Any The parameter to pass to the function
165
170
  job_id: str ID of this job
166
- req: Request FastAPI's request object
171
+ req: Request FastAPI's request object (or any duck-typed object
172
+ exposing a `.headers.get(...)` mapping, e.g. an MCP request shim)
173
+ report_result: whether to push the result back to the IVCAP sidecar
174
+ reporter: optional `EventReporter` instance to use for this invocation
175
+ instead of the one produced by the globally configured event-reporter
176
+ factory (e.g. `SidecarReporter`). Used to bridge progress reporting to
177
+ non-REST transports such as MCP.
167
178
 
168
179
  Returns:
169
180
  An asyncio Queue that will contain either the result of type T or an ExecutionError
@@ -200,7 +211,9 @@ class Executor(Generic[T]):
200
211
  jctxt = JobContext(
201
212
  job_id=job_id,
202
213
  job_authorization=authorization,
203
- report=create_event_reporter(
214
+ report=reporter
215
+ if reporter is not None
216
+ else create_event_reporter(
204
217
  job_id=job_id, job_authorization=authorization
205
218
  ),
206
219
  )
ivcap_lambda/mcp.py CHANGED
@@ -3,261 +3,292 @@
3
3
  # Use of this source code is governed by a BSD-style license that can be
4
4
  # found in the LICENSE file. See the AUTHORS file for names of contributors.
5
5
  #
6
- import asyncio
7
- import json
8
- from typing import Any, Literal
6
+ """Model Context Protocol (MCP) support for ivcap-lambda.
9
7
 
10
- from fastapi import FastAPI, Request, Response, status
11
- from ivcap_service import ExecutionError, IvcapResult, getLogger
12
- from pydantic import BaseModel
8
+ Exposes every tool registered via `@ivcap_lambda(...)` as a spec-compliant MCP
9
+ server (Streamable HTTP transport), built on top of the official `mcp` Python
10
+ SDK (https://github.com/modelcontextprotocol/python-sdk).
13
11
 
14
- from .builder import ToolDescription, tools
12
+ Each registered tool is re-registered, unchanged, as an MCP tool: the same
13
+ Pydantic request/result models and docstring used for the REST endpoint are
14
+ reused to build the MCP tool's input/output schema and description. Progress
15
+ reported via `jobCtxt.report.step(...)` (the `EventReporter` API) is bridged
16
+ to native MCP `notifications/progress` messages when a tool is invoked over
17
+ MCP - no changes are required in tool code.
15
18
 
16
- logger = getLogger("mcp")
19
+ Requires the optional `mcp` package: `pip install ivcap-lambda[mcp]`.
20
+ """
17
21
 
22
+ # NOTE: intentionally no `from __future__ import annotations` here. Tool
23
+ # wrappers are built dynamically with a *local variable* (`input_model`) as a
24
+ # parameter annotation (see `_make_mcp_tool`); the MCP SDK resolves string
25
+ # annotations via `typing.get_type_hints()`/`eval_str=True` against the
26
+ # function's `__globals__`, which would fail to find a local variable name.
18
27
 
19
- class Notification(BaseModel):
20
- type: str = "notification"
21
- message: str
22
-
23
-
24
- # {
25
- # "jsonrpc": "2.0",
26
- # "id": 5,
27
- # "result": {
28
- # "content": [
29
- # {
30
- # "type": "text",
31
- # "text": "{\"temperature\": 22.5, \"conditions\": \"Partly cloudy\", \"humidity\": 65}"
32
- # }
33
- # ],
34
- # "structuredContent": {
35
- # "temperature": 22.5,
36
- # "conditions": "Partly cloudy",
37
- # "humidity": 65
38
- # }
39
- # }
40
- # }
41
- class Result(BaseModel):
42
- type: str = "result"
43
- data: Any
44
-
45
-
46
- class JsonRpcRequest(BaseModel):
47
- """
48
- Pydantic model for a JSON-RPC 2.0 request object.
49
- """
50
-
51
- jsonrpc: Literal["2.0"]
52
- method: str
53
- params: dict[str, Any] | list[Any] | None = None
54
- id: int | str | None = None
28
+ import asyncio
29
+ from contextlib import asynccontextmanager
30
+
31
+ from fastapi import FastAPI
32
+ from ivcap_service import (
33
+ EventReporter,
34
+ ExecutionError,
35
+ IvcapResult,
36
+ get_function_return_type,
37
+ getLogger,
38
+ )
39
+ from pydantic import BaseModel
40
+ from uuid6 import uuid6
55
41
 
42
+ from .builder import ToolDescription, tools
56
43
 
57
- class JsonRpcSuccessResponse(BaseModel):
58
- """
59
- Pydantic model for a JSON-RPC 2.0 success response.
60
- """
44
+ logger = getLogger("mcp")
61
45
 
62
- jsonrpc: Literal["2.0"]
63
- result: Any
64
- id: int | str | None
46
+ try:
47
+ from mcp.server.mcpserver import Context, MCPServer
48
+ from mcp.server.mcpserver.exceptions import ToolError
49
+ from mcp.server.transport_security import TransportSecuritySettings
65
50
 
51
+ _MCP_SDK_AVAILABLE = True
52
+ except ImportError: # pragma: no cover - exercised when extra isn't installed
53
+ _MCP_SDK_AVAILABLE = False
66
54
 
67
- class JsonRpcErrorObject(BaseModel):
68
- """
69
- Pydantic model for the error object in a JSON-RPC 2.0 error response.
70
- """
55
+ # Max. time to wait for a tool invoked over MCP to complete. MCP's base
56
+ # `tools/call` is a single request/response round-trip (progress is streamed
57
+ # as notifications on the same call, not a separate poll), so - unlike the
58
+ # REST "try-later" protocol - there is no fallback to defer the result.
59
+ MCP_CALL_TIMEOUT = 600.0
71
60
 
72
- code: int
73
- message: str
74
- data: Any | None = None
75
61
 
62
+ class _MCPRequestShim:
63
+ """Minimal stand-in for `fastapi.Request` used when invoking a tool's
64
+ `Executor` from within an MCP tool call.
76
65
 
77
- class JsonRpcErrorResponse(BaseModel):
78
- """
79
- Pydantic model for a JSON-RPC 2.0 error response.
66
+ `Executor.execute()` only ever calls `req.headers.get(...)`, so a plain
67
+ object carrying a header mapping is sufficient here; it avoids requiring a
68
+ real `starlette.requests.Request` (MCP clients speak a different
69
+ transport/protocol than IVCAP's REST job submission, so there is no
70
+ equivalent "job-id"/"authorization" header convention to rely on beyond
71
+ whatever the MCP transport happened to carry).
80
72
  """
81
73
 
82
- jsonrpc: Literal["2.0"]
83
- error: JsonRpcErrorObject
84
- id: int | str | None
74
+ def __init__(self, headers: dict[str, str] | None):
75
+ self.headers: dict[str, str] = headers or {}
85
76
 
86
77
 
87
- # JsonRpcResponse = JsonRpcSuccessResponse | JsonRpcErrorResponse
78
+ def _event_message(event) -> str:
79
+ """Best-effort extraction of a human-readable message from an
80
+ `ivcap_service.events.BaseEvent` for forwarding as an MCP progress
81
+ notification's `message`."""
82
+ options = getattr(event, "options", None)
83
+ if options and options.get("message"):
84
+ return str(options["message"])
85
+ error = getattr(event, "error", None)
86
+ if error:
87
+ return str(error)
88
+ name = getattr(event, "name", None)
89
+ return str(name) if name else event.__class__.__name__
88
90
 
89
91
 
90
- # === Tool Runner (non-streaming path) ===
91
- async def run_tool_once(
92
- req_id: str, tool_name: str, input: dict, httpReq: Request
93
- ) -> Result:
94
- tool = next((t for t in tools if t.name == tool_name), None)
95
- if not tool:
96
- return Result(type="error", data=f"Tool '{tool_name}' not found")
97
-
92
+ def _log_progress_delivery_error(future) -> None:
98
93
  try:
99
- input_model = tool.input[0]
100
- if input_model:
101
- # verify parameters
102
- m = input_model(**input)
103
- else:
104
- m = input # type: ignore[assignment]
105
- queue = await tool.executor.execute(
106
- m, f"urn:mcp:{req_id}", httpReq, report_result=False
107
- )
108
- result = await asyncio.wait_for(queue.get(), timeout=600)
109
- queue.task_done()
110
- except (asyncio.CancelledError, GeneratorExit):
111
- # allow cooperative shutdown; propagate cancellation cleanly
112
- raise
113
- except Exception as e:
114
- return Result(type="error", data=str(e))
115
-
116
- if isinstance(result, IvcapResult):
117
- if isinstance(result.raw, BaseModel):
118
- try:
119
- data = result.raw.model_dump()
120
- return Result(type="result", data=data)
121
- except Exception:
122
- pass
94
+ future.result()
95
+ except Exception as ex: # pragma: no cover - best-effort logging only
96
+ logger.debug(f"failed to deliver MCP progress notification - {ex}")
97
+
98
+
99
+ class McpEventReporter(EventReporter):
100
+ """Bridges `jobCtxt.report` calls (the `EventReporter` API used by tool
101
+ code) to native MCP `notifications/progress` messages, so that a tool
102
+ written against `jobCtxt.report.step(...)` gets progress reporting
103
+ whether it is invoked over REST (sidecar events) or MCP - with no changes
104
+ required in tool code.
105
+
106
+ `EventReporter` methods are synchronous and are invoked from the
107
+ `Executor`'s worker thread, while MCP's `ctx.report_progress()` is a
108
+ coroutine that must run on the event loop owning the MCP session. This
109
+ reporter schedules it there via `asyncio.run_coroutine_threadsafe()`,
110
+ best-effort: a failure to deliver a progress notification never breaks
111
+ the tool call itself.
112
+ """
123
113
 
114
+ def __init__(
115
+ self,
116
+ job_id: str,
117
+ job_authorization: str | None,
118
+ ctx: "Context",
119
+ loop: asyncio.AbstractEventLoop,
120
+ ):
121
+ super().__init__(job_id, job_authorization)
122
+ self._ctx = ctx
123
+ self._loop = loop
124
+ self._progress = 0.0
125
+
126
+ def _send(self, event) -> None:
127
+ # Always log locally too (matches the base EventReporter's behaviour).
128
+ super()._send(event)
124
129
  try:
125
- data = str(result.content) # type: ignore[assignment]
126
- return Result(type="result", data=data)
127
- except Exception as ex:
128
- result = ExecutionError(
129
- error=f"while converting result to string - {ex}", type=""
130
+ self._progress += 1.0
131
+ message = _event_message(event)
132
+ future = asyncio.run_coroutine_threadsafe(
133
+ self._ctx.report_progress(self._progress, message=message),
134
+ self._loop,
130
135
  )
131
-
132
- if not isinstance(result, ExecutionError):
133
- # this should never happen
134
- logger.error(f"expected 'ExecutionError' but got {type(result)}")
135
- result = ExecutionError(
136
- error="please report unexpected internal error - expected 'ExecutionError' but got {type(result)}",
137
- type="internal_error",
138
- )
139
- return Result(type="error", data=str(result.error))
136
+ future.add_done_callback(_log_progress_delivery_error)
137
+ except Exception as ex: # pragma: no cover - defensive, must not raise
138
+ logger.debug(f"{self.job_id}: failed to forward event to MCP - {ex}")
140
139
 
141
140
 
142
- async def handle_tools_call(req_id, params, req: JsonRpcRequest, httpReq: Request):
143
- tool_name = params["name"]
144
- tool_args = params.get("arguments", {})
141
+ def _make_mcp_tool(td: ToolDescription):
142
+ """Builds an async function suitable for `MCPServer.add_tool()` that
143
+ delegates to the same `Executor` (and hence the same worker-thread pool,
144
+ job cache, and OTEL instrumentation) used by `td`'s REST endpoint.
145
145
 
146
- message = await run_tool_once(req_id, tool_name, tool_args, httpReq)
147
- mtype = message.type
148
- if mtype == "error":
149
- data = message.data or "???"
150
- error = JsonRpcErrorObject(code=1000, message=str(data), data=data)
151
- return JsonRpcErrorResponse(id=req_id, error=error, jsonrpc="2.0")
152
-
153
- elif mtype == "notification":
154
- # Not expected in non-streaming mode; treat as no-op
155
- error = JsonRpcErrorObject(
156
- code=1001,
157
- message="Unexpected notification message type in non-streaming mode",
146
+ The wrapper's signature is `(req: <input_model>, ctx: Context) ->
147
+ <output_model | Any>` - the exact same shape `@ivcap_lambda` already
148
+ expects from tool functions - so the MCP SDK derives the tool's input and
149
+ output JSON schemas from the very same Pydantic models used for the REST
150
+ `POST`/`GET` endpoints.
151
+ """
152
+ input_model, _ = td.input
153
+ if input_model is None:
154
+ raise ValueError(
155
+ f"cannot expose tool '{td.name}' over MCP: it has no Pydantic "
156
+ "input model (first argument must be a `pydantic.BaseModel`)"
158
157
  )
159
- return JsonRpcErrorResponse(id=req_id, error=error, jsonrpc="2.0")
160
-
161
- elif mtype == "result":
162
- return _result_response(req_id, message)
163
-
164
- else:
165
- error = JsonRpcErrorObject(
166
- code=1002,
167
- message=f"Unknown message type `{mtype}' received from tool",
158
+ output_model = get_function_return_type(td.worker_fn)
159
+
160
+ async def _tool(req: input_model, ctx: Context): # type: ignore[valid-type]
161
+ job_id = f"mcp:{uuid6()}"
162
+ headers = dict(ctx.headers) if ctx.headers else {}
163
+ shim_req = _MCPRequestShim(headers)
164
+ loop = asyncio.get_running_loop()
165
+ authorization = headers.get("authorization")
166
+ reporter = McpEventReporter(job_id, authorization, ctx, loop)
167
+
168
+ queue = await td.executor.execute(
169
+ req,
170
+ job_id,
171
+ shim_req, # type: ignore[arg-type]
172
+ report_result=False,
173
+ reporter=reporter,
174
+ )
175
+ try:
176
+ result = await asyncio.wait_for(queue.get(), timeout=MCP_CALL_TIMEOUT)
177
+ queue.task_done()
178
+ except TimeoutError as ex:
179
+ raise ToolError(
180
+ f"tool '{td.name}' did not complete within "
181
+ f"{MCP_CALL_TIMEOUT:.0f} seconds"
182
+ ) from ex
183
+
184
+ if isinstance(result, ExecutionError):
185
+ raise ToolError(result.error)
186
+ if isinstance(result, IvcapResult):
187
+ if isinstance(result.raw, BaseModel):
188
+ return result.raw
189
+ return result.content
190
+ return result
191
+
192
+ _tool.__name__ = td.worker_fn.__name__
193
+ _tool.__doc__ = td.worker_fn.__doc__
194
+ if output_model is not None:
195
+ _tool.__annotations__["return"] = output_model
196
+ return _tool
197
+
198
+
199
+ def _require_mcp_sdk() -> None:
200
+ if not _MCP_SDK_AVAILABLE:
201
+ raise ImportError(
202
+ "MCP support requires the optional 'mcp' package. Install it with "
203
+ "`pip install ivcap-lambda[mcp]` (or `poetry add ivcap-lambda -E mcp`)."
168
204
  )
169
- return JsonRpcErrorResponse(id=req_id, error=error, jsonrpc="2.0")
170
-
171
-
172
- def _result_response(req_id, message):
173
- # If result is not a string, convert to string
174
- data = message.data or ""
175
- result = {}
176
- if not isinstance(data, str):
177
- text = json.dumps(data)
178
- result["structuredContent"] = data
179
- else:
180
- text = data
181
-
182
- result["content"] = [{"type": "text", "text": text}]
183
- return JsonRpcSuccessResponse(id=req_id, result=result, jsonrpc="2.0")
184
205
 
185
206
 
186
- def register_mcp(app: FastAPI, path_prefix: str = "/mcp"):
187
- """
188
- Register the MCP JSON-RPC handler on the given FastAPI app and path_prefix.
189
- This replaces the @app.post(...) decorator usage.
190
- The worker_fn and executor parameters are accepted for API symmetry but are not
191
- directly used by the MCP route.
207
+ def _build_mcp_server(name: str, version: str = "") -> "MCPServer":
208
+ """Build an `MCPServer` registering every tool from `@ivcap_lambda(...)`,
209
+ shared by both the HTTP (`register_mcp`) and stdio (`run_mcp_stdio`)
210
+ entry points so tool registration logic lives in exactly one place.
192
211
  """
212
+ _require_mcp_sdk()
213
+
214
+ mcp_server = MCPServer(name or "ivcap-lambda", version=version or "")
215
+ for td in tools:
216
+ mcp_server.add_tool(
217
+ _make_mcp_tool(td),
218
+ name=td.name,
219
+ description=td.worker_fn.__doc__,
220
+ )
221
+ return mcp_server
193
222
 
194
- async def handle_rpc(
195
- rpcReq: JsonRpcRequest, httpReq: Request
196
- ) -> JsonRpcSuccessResponse | JsonRpcErrorResponse | Response:
197
- method = rpcReq.method
198
- req_id = rpcReq.id
199
- params = rpcReq.params
200
-
201
- if method == "tools/call":
202
- return await handle_tools_call(req_id, params, rpcReq, httpReq)
203
-
204
- elif method == "tools/list":
205
- return await handle_tools_list(req_id)
206
-
207
- elif method == "initialize":
208
- return await handle_initialize(req_id, app)
209
-
210
- elif method == "notifications/initialized":
211
- return Response(status_code=status.HTTP_204_NO_CONTENT)
212
223
 
213
- return await handle_unknown_method(req_id)
224
+ def register_mcp(app: FastAPI, path_prefix: str = "/mcp") -> "MCPServer":
225
+ """Build an MCP server from every tool registered via `@ivcap_lambda(...)`
226
+ and mount it onto `app` at `path_prefix` (Streamable HTTP transport).
214
227
 
215
- app.add_api_route(
216
- path_prefix,
217
- handle_rpc,
218
- methods=["POST"],
219
- response_model=None,
220
- response_model_exclude_none=True,
221
- response_model_by_alias=True,
222
- )
223
- logger.info(f"Added MCP endpoint at '{path_prefix}'")
228
+ Requires the optional `mcp` package: `pip install ivcap-lambda[mcp]`.
224
229
 
230
+ Args:
231
+ app (FastAPI): The FastAPI app to mount the MCP server on.
232
+ path_prefix (str): The path to mount the MCP endpoint at. Defaults to "/mcp".
225
233
 
226
- async def handle_unknown_method(req_id):
227
- return JsonRpcErrorResponse(
228
- jsonrpc="2.0",
229
- id=req_id,
230
- error=JsonRpcErrorObject(code=-32601, message="Unknown method"),
234
+ Returns:
235
+ The underlying `mcp.server.mcpserver.MCPServer` instance, e.g. for use
236
+ with `mcp.Client(mcp_server)` in tests (no network required).
237
+ """
238
+ mcp_server = _build_mcp_server(app.title, app.version)
239
+
240
+ mcp_asgi_app = mcp_server.streamable_http_app(
241
+ streamable_http_path=path_prefix,
242
+ # The service is typically deployed behind an IVCAP ingress/proxy under
243
+ # an arbitrary hostname, not `localhost`; the default DNS-rebinding
244
+ # protection would otherwise reject every request with a 421.
245
+ transport_security=TransportSecuritySettings(
246
+ enable_dns_rebinding_protection=False
247
+ ),
231
248
  )
232
-
233
-
234
- async def handle_tools_list(req_id) -> JsonRpcSuccessResponse:
235
- def f(td: ToolDescription):
236
- _, description = ((td.worker_fn.__doc__ or "").lstrip() + "\n").split("\n", 1)
237
- input_type = td.input[0]
238
- return {
239
- "name": td.name,
240
- "description": description.strip(),
241
- "inputSchema": input_type.model_json_schema() if input_type else {},
242
- }
243
-
244
- tl = [f(t) for t in tools]
245
- result = {"tools": tl, "isLast": True} # "nextCursor": None }
246
- return JsonRpcSuccessResponse(id=req_id, result=result, jsonrpc="2.0")
247
-
248
-
249
- async def handle_initialize(req_id, app) -> JsonRpcSuccessResponse:
250
- result = {
251
- "protocolVersion": "2024-11-05",
252
- "serverInfo": {"name": f"MCP Server for {app.title}", "version": app.version},
253
- "capabilities": {
254
- "tools": {"listChanged": False},
255
- # "resources": {},
256
- # "prompts": {},
257
- "toolProvider": {
258
- "version": "1.0.0",
259
- "toolInvocationModes": ["standard", "streaming"],
260
- },
261
- },
262
- }
263
- return JsonRpcSuccessResponse(id=req_id, result=result, jsonrpc="2.0")
249
+ # Mount at the application root ("") rather than at `path_prefix` itself:
250
+ # `mcp_asgi_app` already serves its one route at `streamable_http_path`, so
251
+ # mounting it again under `path_prefix` would require clients to hit
252
+ # `{path_prefix}{path_prefix}` and trips Starlette's trailing-slash
253
+ # redirect when `path_prefix` is mounted verbatim as a sub-app.
254
+ app.mount("", mcp_asgi_app)
255
+
256
+ # `streamable_http_app()` returns a Starlette app whose own lifespan must
257
+ # be entered for the session manager's background work to run. FastAPI's
258
+ # router already owns a `lifespan_context`; wrap it so both run.
259
+ previous_lifespan = app.router.lifespan_context
260
+
261
+ @asynccontextmanager
262
+ async def combined_lifespan(app: FastAPI):
263
+ async with previous_lifespan(app):
264
+ async with mcp_server.session_manager.run():
265
+ yield
266
+
267
+ app.router.lifespan_context = combined_lifespan
268
+
269
+ logger.info(f"Added MCP endpoint at '{path_prefix}' ({len(tools)} tool(s))")
270
+ return mcp_server
271
+
272
+
273
+ def run_mcp_stdio(name: str, version: str = "") -> None:
274
+ """Run every tool registered via `@ivcap_lambda(...)` as an MCP server
275
+ over the **stdio** transport instead of HTTP.
276
+
277
+ This is a blocking call (it owns the process's stdin/stdout for as long
278
+ as the MCP host keeps the connection open) intended for local
279
+ development with stdio-based MCP clients/hosts (Claude Desktop, Cline,
280
+ the MCP Inspector, etc.) that launch the tool as a subprocess rather than
281
+ connecting over HTTP - useful for iterating on a tool without deploying
282
+ it or running the full FastAPI/uvicorn HTTP server.
283
+
284
+ Requires the optional `mcp` package: `pip install ivcap-lambda[mcp]`.
285
+
286
+ Args:
287
+ name (str): Name to report to the MCP client as `serverInfo.name`.
288
+ version (str): Version to report to the MCP client as `serverInfo.version`.
289
+ """
290
+ mcp_server = _build_mcp_server(name, version)
291
+ logger.info(f"Starting MCP stdio server ({len(tools)} tool(s))")
292
+ # `mcp_server.run()` is synchronous (it owns the event loop via `anyio.run`
293
+ # internally) and blocks until the client disconnects/EOF on stdin.
294
+ mcp_server.run(transport="stdio")
ivcap_lambda/server.py CHANGED
@@ -98,6 +98,15 @@ def start_lambda_server(
98
98
  "--with-telemetry", action="store_true", help="Initialise OpenTelemetry"
99
99
  )
100
100
  parser.add_argument("--with-mcp", action="store_true", help="Add an MCP endpoint")
101
+ parser.add_argument(
102
+ "--with-mcp-stdio",
103
+ action="store_true",
104
+ help=(
105
+ "Run as an MCP server over stdio instead of starting the HTTP "
106
+ "server (for local development with stdio-based MCP clients, "
107
+ "e.g. Claude Desktop, Cline). Requires the 'mcp' extra."
108
+ ),
109
+ )
101
110
  parser.add_argument(
102
111
  "--print-service-description",
103
112
  type=str,
@@ -122,6 +131,9 @@ def start_lambda_server(
122
131
  else:
123
132
  args = parser.parse_args()
124
133
 
134
+ if args.with_mcp_stdio and args.with_mcp:
135
+ parser.error("--with-mcp-stdio and --with-mcp are mutually exclusive")
136
+
125
137
  if args.print_tool_description:
126
138
  tool = next((t for t in tools if t.name == args.print_tool_description), None)
127
139
  if tool is None:
@@ -152,6 +164,29 @@ def start_lambda_server(
152
164
  f"{title} - {os.getenv('VERSION')} - v{get_version()}|v{get_service_version()}"
153
165
  )
154
166
 
167
+ # print(f">>>> OTEL_EXPORTER_OTLP_ENDPOINT: {os.environ.get('OTEL_EXPORTER_OTLP_ENDPOINT')}")
168
+ set_event_reporter_factory(SidecarReporter) # type: ignore[arg-type]
169
+
170
+ def get_context():
171
+ jctxt = get_job_context()
172
+ if jctxt is None or jctxt.job_id is None:
173
+ logger.warning("missing job context in thread")
174
+ return None
175
+ return jctxt
176
+
177
+ set_context(get_context)
178
+
179
+ if args.with_mcp_stdio:
180
+ # Run as a stdio MCP server instead of the HTTP/uvicorn server: no
181
+ # FastAPI app involved, so there is nothing to instrument there, but
182
+ # outbound httpx/requests calls (e.g. via JobContext.ivcap) are still
183
+ # instrumented the same way as for the HTTP server.
184
+ from .mcp import run_mcp_stdio
185
+
186
+ otel_instrument(with_telemetry, None, logger)
187
+ run_mcp_stdio(service.name, app.version)
188
+ return
189
+
155
190
  # Check for '_healtz' service
156
191
  healtz = find_first(app.routes, lambda r: r.path == "/_healtz")
157
192
  if healtz is None:
@@ -165,18 +200,6 @@ def start_lambda_server(
165
200
 
166
201
  register_mcp(app, "/mcp")
167
202
 
168
- # print(f">>>> OTEL_EXPORTER_OTLP_ENDPOINT: {os.environ.get('OTEL_EXPORTER_OTLP_ENDPOINT')}")
169
- set_event_reporter_factory(SidecarReporter) # type: ignore[arg-type]
170
-
171
- def get_context():
172
- jctxt = get_job_context()
173
- if jctxt is None or jctxt.job_id is None:
174
- logger.warning("missing job context in thread")
175
- return None
176
- return jctxt
177
-
178
- set_context(get_context)
179
-
180
203
  otel_instrument(
181
204
  with_telemetry, lambda _: FastAPIInstrumentor.instrument_app(app), logger
182
205
  )