openapi-mcpforge 0.1.0__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.
Files changed (92) hide show
  1. mcpforge/__init__.py +8 -0
  2. mcpforge/__main__.py +6 -0
  3. mcpforge/auth/__init__.py +28 -0
  4. mcpforge/auth/models.py +25 -0
  5. mcpforge/auth/providers.py +72 -0
  6. mcpforge/auth/redaction.py +47 -0
  7. mcpforge/auth/resolver.py +42 -0
  8. mcpforge/cli/__init__.py +1 -0
  9. mcpforge/cli/app.py +45 -0
  10. mcpforge/cli/commands/__init__.py +13 -0
  11. mcpforge/cli/commands/import_spec.py +41 -0
  12. mcpforge/cli/commands/init.py +42 -0
  13. mcpforge/cli/commands/inspect.py +56 -0
  14. mcpforge/cli/commands/run.py +44 -0
  15. mcpforge/cli/commands/serve.py +31 -0
  16. mcpforge/cli/commands/test.py +60 -0
  17. mcpforge/cli/commands/validate.py +41 -0
  18. mcpforge/cli/context.py +14 -0
  19. mcpforge/cli/output.py +31 -0
  20. mcpforge/cli/scaffold.py +71 -0
  21. mcpforge/config/__init__.py +37 -0
  22. mcpforge/config/loader.py +44 -0
  23. mcpforge/config/merger.py +25 -0
  24. mcpforge/config/models.py +182 -0
  25. mcpforge/config/secrets.py +94 -0
  26. mcpforge/domain/__init__.py +37 -0
  27. mcpforge/domain/enums.py +42 -0
  28. mcpforge/domain/errors.py +13 -0
  29. mcpforge/domain/models.py +142 -0
  30. mcpforge/domain/parameters.py +33 -0
  31. mcpforge/domain/schemas.py +6 -0
  32. mcpforge/execution/__init__.py +36 -0
  33. mcpforge/execution/client.py +55 -0
  34. mcpforge/execution/engine.py +199 -0
  35. mcpforge/execution/errors.py +83 -0
  36. mcpforge/execution/limits.py +31 -0
  37. mcpforge/execution/request_builder.py +87 -0
  38. mcpforge/execution/response.py +64 -0
  39. mcpforge/execution/retry.py +69 -0
  40. mcpforge/filtering/__init__.py +7 -0
  41. mcpforge/filtering/evaluator.py +26 -0
  42. mcpforge/filtering/policies.py +44 -0
  43. mcpforge/filtering/selectors.py +31 -0
  44. mcpforge/generation/__init__.py +19 -0
  45. mcpforge/generation/collisions.py +24 -0
  46. mcpforge/generation/descriptions.py +15 -0
  47. mcpforge/generation/input_schema.py +53 -0
  48. mcpforge/generation/models.py +32 -0
  49. mcpforge/generation/naming.py +54 -0
  50. mcpforge/generation/service.py +64 -0
  51. mcpforge/ingestion/__init__.py +26 -0
  52. mcpforge/ingestion/errors.py +23 -0
  53. mcpforge/ingestion/loaders/__init__.py +7 -0
  54. mcpforge/ingestion/loaders/file.py +48 -0
  55. mcpforge/ingestion/loaders/remote.py +83 -0
  56. mcpforge/ingestion/normalization/__init__.py +23 -0
  57. mcpforge/ingestion/normalization/operation.py +83 -0
  58. mcpforge/ingestion/normalization/parameters.py +119 -0
  59. mcpforge/ingestion/normalization/references.py +57 -0
  60. mcpforge/ingestion/normalization/schemas.py +76 -0
  61. mcpforge/ingestion/parsers/__init__.py +8 -0
  62. mcpforge/ingestion/parsers/base.py +14 -0
  63. mcpforge/ingestion/parsers/manual.py +82 -0
  64. mcpforge/ingestion/parsers/openapi.py +87 -0
  65. mcpforge/ingestion/parsers/swagger.py +95 -0
  66. mcpforge/ingestion/service.py +84 -0
  67. mcpforge/ingestion/source.py +50 -0
  68. mcpforge/mcp/__init__.py +39 -0
  69. mcpforge/mcp/adapter.py +88 -0
  70. mcpforge/mcp/errors.py +25 -0
  71. mcpforge/mcp/server.py +46 -0
  72. mcpforge/mcp/tools.py +110 -0
  73. mcpforge/mcp/transports.py +51 -0
  74. mcpforge/observability/__init__.py +23 -0
  75. mcpforge/observability/diagnostics.py +45 -0
  76. mcpforge/observability/events.py +58 -0
  77. mcpforge/observability/logging.py +45 -0
  78. mcpforge/runtime/__init__.py +15 -0
  79. mcpforge/runtime/application.py +82 -0
  80. mcpforge/runtime/dependencies.py +77 -0
  81. mcpforge/runtime/lifecycle.py +50 -0
  82. mcpforge/security/__init__.py +40 -0
  83. mcpforge/security/hosts.py +32 -0
  84. mcpforge/security/redaction.py +60 -0
  85. mcpforge/security/safety.py +39 -0
  86. mcpforge/security/ssrf.py +77 -0
  87. mcpforge/security/validation.py +36 -0
  88. openapi_mcpforge-0.1.0.dist-info/METADATA +1566 -0
  89. openapi_mcpforge-0.1.0.dist-info/RECORD +92 -0
  90. openapi_mcpforge-0.1.0.dist-info/WHEEL +4 -0
  91. openapi_mcpforge-0.1.0.dist-info/entry_points.txt +2 -0
  92. openapi_mcpforge-0.1.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,33 @@
1
+ """Utilities for normalized endpoint parameters."""
2
+
3
+ from collections.abc import Iterable, Iterator
4
+ from dataclasses import dataclass
5
+
6
+ from mcpforge.domain.enums import ParameterLocation
7
+ from mcpforge.domain.models import Parameter
8
+
9
+
10
+ @dataclass(frozen=True, slots=True)
11
+ class ParameterCollection:
12
+ """Immutable indexed view over endpoint parameters."""
13
+
14
+ items: tuple[Parameter, ...]
15
+
16
+ @classmethod
17
+ def from_iterable(cls, parameters: Iterable[Parameter]) -> "ParameterCollection":
18
+ return cls(tuple(parameters))
19
+
20
+ def __iter__(self) -> Iterator[Parameter]:
21
+ return iter(self.items)
22
+
23
+ def __len__(self) -> int:
24
+ return len(self.items)
25
+
26
+ def by_location(self, location: ParameterLocation) -> tuple[Parameter, ...]:
27
+ return tuple(parameter for parameter in self.items if parameter.location is location)
28
+
29
+ def required(self) -> tuple[Parameter, ...]:
30
+ return tuple(parameter for parameter in self.items if parameter.required)
31
+
32
+ def names(self) -> frozenset[str]:
33
+ return frozenset(parameter.name for parameter in self.items)
@@ -0,0 +1,6 @@
1
+ """JSON-compatible type aliases."""
2
+
3
+ from typing import TypeAlias
4
+
5
+ JsonValue: TypeAlias = None | bool | int | float | str | list["JsonValue"] | dict[str, "JsonValue"]
6
+ JsonObject: TypeAlias = dict[str, JsonValue]
@@ -0,0 +1,36 @@
1
+ """Async HTTP execution primitives."""
2
+
3
+ from mcpforge.execution.client import HTTPClient
4
+ from mcpforge.execution.engine import ExecutionEngine
5
+ from mcpforge.execution.errors import (
6
+ ExecutionError,
7
+ ExecutionFailure,
8
+ error_for_status,
9
+ )
10
+ from mcpforge.execution.limits import (
11
+ enforce_request_limit,
12
+ enforce_response_limit,
13
+ )
14
+ from mcpforge.execution.request_builder import BuiltRequest, build_request
15
+ from mcpforge.execution.response import parse_response
16
+ from mcpforge.execution.retry import (
17
+ is_retryable_status,
18
+ retry_delay,
19
+ run_with_retries,
20
+ )
21
+
22
+ __all__ = [
23
+ "BuiltRequest",
24
+ "ExecutionEngine",
25
+ "ExecutionError",
26
+ "ExecutionFailure",
27
+ "HTTPClient",
28
+ "build_request",
29
+ "enforce_request_limit",
30
+ "enforce_response_limit",
31
+ "error_for_status",
32
+ "is_retryable_status",
33
+ "parse_response",
34
+ "retry_delay",
35
+ "run_with_retries",
36
+ ]
@@ -0,0 +1,55 @@
1
+ """Shared lifecycle-managed HTTPX client."""
2
+
3
+ from collections.abc import AsyncIterator
4
+ from contextlib import asynccontextmanager
5
+
6
+ import httpx
7
+
8
+
9
+ class HTTPClient:
10
+ """Own one reusable asynchronous HTTP client."""
11
+
12
+ def __init__(
13
+ self,
14
+ *,
15
+ timeout_seconds: float = 30.0,
16
+ verify_tls: bool = True,
17
+ ) -> None:
18
+ self._timeout = httpx.Timeout(timeout_seconds)
19
+ self._verify_tls = verify_tls
20
+ self._client: httpx.AsyncClient | None = None
21
+
22
+ async def start(self) -> None:
23
+ """Open the shared client."""
24
+
25
+ if self._client is None:
26
+ self._client = httpx.AsyncClient(
27
+ timeout=self._timeout,
28
+ verify=self._verify_tls,
29
+ follow_redirects=False,
30
+ )
31
+
32
+ async def close(self) -> None:
33
+ """Close the shared client."""
34
+
35
+ if self._client is not None:
36
+ await self._client.aclose()
37
+ self._client = None
38
+
39
+ @property
40
+ def client(self) -> httpx.AsyncClient:
41
+ """Return the active client."""
42
+
43
+ if self._client is None:
44
+ raise RuntimeError("HTTPClient has not been started")
45
+ return self._client
46
+
47
+ @asynccontextmanager
48
+ async def lifecycle(self) -> AsyncIterator["HTTPClient"]:
49
+ """Start and close the client around an async context."""
50
+
51
+ await self.start()
52
+ try:
53
+ yield self
54
+ finally:
55
+ await self.close()
@@ -0,0 +1,199 @@
1
+ """Async HTTP execution engine."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import logging
6
+ from time import perf_counter
7
+ from typing import Any
8
+ from urllib.parse import urlparse
9
+
10
+ from mcpforge.auth.resolver import resolve_auth
11
+ from mcpforge.config.models import ProjectConfig
12
+ from mcpforge.domain.errors import ConfigurationError
13
+ from mcpforge.domain.models import Endpoint
14
+ from mcpforge.execution.client import HTTPClient
15
+ from mcpforge.execution.errors import ExecutionError, ExecutionFailure
16
+ from mcpforge.execution.request_builder import build_request
17
+ from mcpforge.execution.response import parse_response
18
+ from mcpforge.execution.retry import run_with_retries
19
+ from mcpforge.observability.events import ExecutionEvent
20
+ from mcpforge.observability.logging import log_event
21
+ from mcpforge.security.validation import validate_endpoint_request
22
+
23
+
24
+ class ExecutionEngine:
25
+ """Build, validate, and execute normalized endpoint requests."""
26
+
27
+ def __init__(
28
+ self,
29
+ config: ProjectConfig,
30
+ client: HTTPClient,
31
+ *,
32
+ logger: logging.Logger | None = None,
33
+ ) -> None:
34
+ self.config = config
35
+ self.client = client
36
+ self.logger = logger or logging.getLogger("mcpforge.execution")
37
+
38
+ def _base_url(self) -> str:
39
+ """Resolve the upstream API base URL from project configuration."""
40
+
41
+ configured = self.config.source.base_url
42
+ if configured is not None:
43
+ return str(configured).rstrip("/")
44
+
45
+ source_location = self.config.source.location
46
+ parsed = urlparse(source_location)
47
+
48
+ if parsed.scheme in {"http", "https"} and parsed.hostname:
49
+ origin = f"{parsed.scheme}://{parsed.netloc}"
50
+ return origin.rstrip("/")
51
+
52
+ raise ExecutionFailure(
53
+ ExecutionError(
54
+ category="configuration_error",
55
+ message=(
56
+ "No API base URL is configured. Set source.base_url "
57
+ "before executing an endpoint."
58
+ ),
59
+ retryable=False,
60
+ )
61
+ )
62
+
63
+ def _request_limit(self) -> int:
64
+ """Return the configured request-body limit.
65
+
66
+ Part 1 exposes one payload limit, so it is applied consistently to
67
+ request and response payloads until a separate request limit exists.
68
+ """
69
+
70
+ return self.config.security.max_response_bytes
71
+
72
+ async def execute(
73
+ self,
74
+ endpoint: Endpoint,
75
+ arguments: dict[str, Any],
76
+ ) -> dict[str, Any]:
77
+ """Execute one endpoint invocation and return a normalized result."""
78
+
79
+ started = perf_counter()
80
+
81
+ try:
82
+ auth = resolve_auth(self.config)
83
+ request = build_request(
84
+ endpoint=endpoint,
85
+ base_url=self._base_url(),
86
+ arguments=arguments,
87
+ auth=auth,
88
+ max_request_bytes=self._request_limit(),
89
+ )
90
+ except ConfigurationError as exc:
91
+ raise ExecutionFailure(
92
+ ExecutionError(
93
+ category="authentication_configuration_error",
94
+ message=str(exc),
95
+ retryable=False,
96
+ )
97
+ ) from exc
98
+ except ValueError as exc:
99
+ raise ExecutionFailure(
100
+ ExecutionError(
101
+ category="request_validation_error",
102
+ message=str(exc),
103
+ retryable=False,
104
+ )
105
+ ) from exc
106
+
107
+ async def send() -> dict[str, Any]:
108
+ try:
109
+ # Perform the network-policy checks for every attempt so a
110
+ # changing DNS answer cannot bypass the configured policy.
111
+ validate_endpoint_request(
112
+ endpoint=endpoint,
113
+ url=request.url,
114
+ config=self.config.security,
115
+ )
116
+
117
+ response = await self.client.client.request(
118
+ method=request.method,
119
+ url=request.url,
120
+ params=request.params,
121
+ headers=request.headers,
122
+ cookies=request.cookies,
123
+ content=request.content,
124
+ auth=request.auth,
125
+ )
126
+
127
+ return parse_response(
128
+ response,
129
+ max_response_bytes=self.config.security.max_response_bytes,
130
+ )
131
+ except PermissionError as exc:
132
+ raise ExecutionFailure(
133
+ ExecutionError(
134
+ category="host_blocked",
135
+ message="The request was blocked by the security policy.",
136
+ retryable=False,
137
+ )
138
+ ) from exc
139
+
140
+ log_event(
141
+ self.logger,
142
+ ExecutionEvent.create(
143
+ "request_started",
144
+ operation_id=endpoint.operation_id,
145
+ method=request.method,
146
+ path=endpoint.path,
147
+ ).as_dict(),
148
+ )
149
+
150
+ try:
151
+ result = await run_with_retries(send, self.config.http.retry)
152
+ except ExecutionFailure as exc:
153
+ log_event(
154
+ self.logger,
155
+ ExecutionEvent.create(
156
+ "request_failed",
157
+ operation_id=endpoint.operation_id,
158
+ method=request.method,
159
+ path=endpoint.path,
160
+ duration_ms=(perf_counter() - started) * 1000,
161
+ details={"category": exc.error.category},
162
+ ).as_dict(),
163
+ level=logging.WARNING,
164
+ )
165
+ raise
166
+ except Exception as exc:
167
+ error = ExecutionError(
168
+ category="execution_failed",
169
+ message="The upstream request could not be completed.",
170
+ retryable=False,
171
+ details={"type": type(exc).__name__},
172
+ )
173
+ log_event(
174
+ self.logger,
175
+ ExecutionEvent.create(
176
+ "request_failed",
177
+ operation_id=endpoint.operation_id,
178
+ method=request.method,
179
+ path=endpoint.path,
180
+ duration_ms=(perf_counter() - started) * 1000,
181
+ details={"category": error.category},
182
+ ).as_dict(),
183
+ level=logging.ERROR,
184
+ )
185
+ raise ExecutionFailure(error) from exc
186
+
187
+ log_event(
188
+ self.logger,
189
+ ExecutionEvent.create(
190
+ "request_completed",
191
+ operation_id=endpoint.operation_id,
192
+ method=request.method,
193
+ path=endpoint.path,
194
+ status_code=result.get("status_code"),
195
+ duration_ms=(perf_counter() - started) * 1000,
196
+ ).as_dict(),
197
+ )
198
+
199
+ return result
@@ -0,0 +1,83 @@
1
+ """Structured execution errors."""
2
+
3
+ from dataclasses import dataclass
4
+ from typing import Any
5
+
6
+
7
+ @dataclass(frozen=True, slots=True)
8
+ class ExecutionError:
9
+ """An LLM-friendly normalized execution failure."""
10
+
11
+ category: str
12
+ message: str
13
+ status_code: int | None = None
14
+ retryable: bool = False
15
+ details: dict[str, Any] | None = None
16
+
17
+ def as_dict(self) -> dict[str, Any]:
18
+ """Serialize the error into a stable response shape."""
19
+
20
+ result: dict[str, Any] = {
21
+ "ok": False,
22
+ "error": {
23
+ "category": self.category,
24
+ "message": self.message,
25
+ "status_code": self.status_code,
26
+ "retryable": self.retryable,
27
+ },
28
+ }
29
+ if self.details:
30
+ result["error"]["details"] = self.details
31
+ return result
32
+
33
+
34
+ class ExecutionFailure(Exception):
35
+ """Exception carrying a normalized execution error."""
36
+
37
+ def __init__(self, error: ExecutionError) -> None:
38
+ super().__init__(error.message)
39
+ self.error = error
40
+
41
+
42
+ def error_for_status(status_code: int) -> ExecutionError:
43
+ """Map an HTTP status code to a normalized error."""
44
+
45
+ if status_code == 400:
46
+ return ExecutionError("bad_request", "The upstream API rejected the request.", status_code)
47
+ if status_code == 401:
48
+ return ExecutionError(
49
+ "authentication_failed",
50
+ "The upstream API rejected the provided authentication.",
51
+ status_code,
52
+ )
53
+ if status_code == 403:
54
+ return ExecutionError(
55
+ "authorization_failed",
56
+ "The upstream API denied access to this operation.",
57
+ status_code,
58
+ )
59
+ if status_code == 404:
60
+ return ExecutionError(
61
+ "not_found",
62
+ "The requested upstream resource was not found.",
63
+ status_code,
64
+ )
65
+ if status_code == 429:
66
+ return ExecutionError(
67
+ "rate_limited",
68
+ "The upstream API rate limit was exceeded.",
69
+ status_code,
70
+ retryable=True,
71
+ )
72
+ if status_code >= 500:
73
+ return ExecutionError(
74
+ "upstream_server_error",
75
+ "The upstream API returned a server error.",
76
+ status_code,
77
+ retryable=True,
78
+ )
79
+ return ExecutionError(
80
+ "upstream_http_error",
81
+ "The upstream API returned an unsuccessful response.",
82
+ status_code,
83
+ )
@@ -0,0 +1,31 @@
1
+ """Response and request size limits."""
2
+
3
+ from mcpforge.execution.errors import ExecutionError, ExecutionFailure
4
+
5
+
6
+ def enforce_response_limit(content: bytes, max_bytes: int) -> None:
7
+ """Reject response content exceeding the configured byte limit."""
8
+
9
+ if len(content) > max_bytes:
10
+ raise ExecutionFailure(
11
+ ExecutionError(
12
+ category="response_too_large",
13
+ message="The upstream response exceeded the configured payload limit.",
14
+ retryable=False,
15
+ details={"max_bytes": max_bytes},
16
+ )
17
+ )
18
+
19
+
20
+ def enforce_request_limit(content: bytes, max_bytes: int) -> None:
21
+ """Reject request bodies exceeding the configured byte limit."""
22
+
23
+ if len(content) > max_bytes:
24
+ raise ExecutionFailure(
25
+ ExecutionError(
26
+ category="request_too_large",
27
+ message="The request body exceeded the configured payload limit.",
28
+ retryable=False,
29
+ details={"max_bytes": max_bytes},
30
+ )
31
+ )
@@ -0,0 +1,87 @@
1
+ """Build HTTP requests from normalized endpoint arguments."""
2
+
3
+ import json
4
+ from dataclasses import dataclass
5
+ from typing import Any
6
+ from urllib.parse import quote
7
+
8
+ from mcpforge.auth.models import ResolvedAuth
9
+ from mcpforge.domain.enums import ParameterLocation
10
+ from mcpforge.domain.models import Endpoint
11
+ from mcpforge.execution.limits import enforce_request_limit
12
+
13
+
14
+ @dataclass(frozen=True, slots=True)
15
+ class BuiltRequest:
16
+ """Transport-independent HTTP request data."""
17
+
18
+ method: str
19
+ url: str
20
+ params: dict[str, Any]
21
+ headers: dict[str, str]
22
+ cookies: dict[str, Any]
23
+ json_body: Any
24
+ content: bytes | None
25
+ auth: tuple[str, str] | None
26
+
27
+
28
+ def build_request(
29
+ endpoint: Endpoint,
30
+ base_url: str,
31
+ arguments: dict[str, Any],
32
+ auth: ResolvedAuth | None = None,
33
+ *,
34
+ max_request_bytes: int = 10_000_000,
35
+ ) -> BuiltRequest:
36
+ """Map tool arguments into path, query, header, cookie, and body values."""
37
+
38
+ auth = auth or ResolvedAuth()
39
+ path = endpoint.path
40
+ params: dict[str, Any] = {}
41
+ headers: dict[str, str] = {}
42
+ cookies: dict[str, Any] = {}
43
+
44
+ for parameter in endpoint.parameters:
45
+ if parameter.name not in arguments:
46
+ if parameter.required:
47
+ raise ValueError(f"missing required parameter: {parameter.name}")
48
+ continue
49
+
50
+ value = arguments[parameter.name]
51
+ if parameter.location is ParameterLocation.PATH:
52
+ path = path.replace(
53
+ "{" + parameter.name + "}",
54
+ quote(str(value), safe=""),
55
+ )
56
+ elif parameter.location is ParameterLocation.QUERY:
57
+ params[parameter.name] = value
58
+ elif parameter.location is ParameterLocation.HEADER:
59
+ headers[parameter.name] = str(value)
60
+ elif parameter.location is ParameterLocation.COOKIE:
61
+ cookies[parameter.name] = value
62
+
63
+ body = arguments.get("body")
64
+ content: bytes | None = None
65
+ if body is not None:
66
+ content = json.dumps(body, separators=(",", ":")).encode("utf-8")
67
+ enforce_request_limit(content, max_request_bytes)
68
+ headers.setdefault("Content-Type", "application/json")
69
+
70
+ headers.update(auth.headers)
71
+ params.update(auth.query)
72
+ basic_auth = (
73
+ (auth.username, auth.password)
74
+ if auth.username is not None and auth.password is not None
75
+ else None
76
+ )
77
+
78
+ return BuiltRequest(
79
+ method=endpoint.method.value,
80
+ url=f"{base_url.rstrip('/')}/{path.lstrip('/')}",
81
+ params=params,
82
+ headers=headers,
83
+ cookies=cookies,
84
+ json_body=body,
85
+ content=content,
86
+ auth=basic_auth,
87
+ )
@@ -0,0 +1,64 @@
1
+ """HTTP response parsing and normalization."""
2
+
3
+ import json
4
+ from typing import Any
5
+
6
+ import httpx
7
+
8
+ from mcpforge.execution.errors import (
9
+ ExecutionError,
10
+ ExecutionFailure,
11
+ error_for_status,
12
+ )
13
+ from mcpforge.execution.limits import enforce_response_limit
14
+
15
+
16
+ def parse_response(
17
+ response: httpx.Response,
18
+ *,
19
+ max_response_bytes: int,
20
+ ) -> dict[str, Any]:
21
+ """Parse a successful response into a stable result object."""
22
+
23
+ content = response.content
24
+ enforce_response_limit(content, max_response_bytes)
25
+
26
+ if response.status_code >= 400:
27
+ error = error_for_status(response.status_code)
28
+ details: dict[str, Any] = {}
29
+ if content:
30
+ try:
31
+ payload = json.loads(content)
32
+ if isinstance(payload, dict):
33
+ details = payload
34
+ except json.JSONDecodeError:
35
+ details = {"body_available": True}
36
+ raise ExecutionFailure(
37
+ ExecutionError(
38
+ category=error.category,
39
+ message=error.message,
40
+ status_code=error.status_code,
41
+ retryable=error.retryable,
42
+ details=details or None,
43
+ )
44
+ )
45
+
46
+ if not content:
47
+ success_payload: Any = None
48
+ else:
49
+ try:
50
+ success_payload = response.json()
51
+ except (json.JSONDecodeError, ValueError) as exc:
52
+ raise ExecutionFailure(
53
+ ExecutionError(
54
+ "invalid_json",
55
+ "The upstream response was not valid JSON.",
56
+ status_code=response.status_code,
57
+ )
58
+ ) from exc
59
+
60
+ return {
61
+ "ok": True,
62
+ "status_code": response.status_code,
63
+ "data": success_payload,
64
+ }
@@ -0,0 +1,69 @@
1
+ """Retry policy and transient failure classification."""
2
+
3
+ import asyncio
4
+ from collections.abc import Awaitable, Callable
5
+ from typing import TypeVar
6
+
7
+ import httpx
8
+
9
+ from mcpforge.config.models import RetryConfig
10
+ from mcpforge.execution.errors import ExecutionError, ExecutionFailure
11
+
12
+ T = TypeVar("T")
13
+
14
+
15
+ def is_retryable_status(status_code: int) -> bool:
16
+ """Return whether an HTTP status is transient."""
17
+
18
+ return status_code == 429 or status_code >= 500
19
+
20
+
21
+ def retry_delay(config: RetryConfig, attempt: int) -> float:
22
+ """Calculate exponential backoff delay."""
23
+
24
+ backoff_seconds = float(str(config.backoff_seconds))
25
+ multiplier = float(2 ** max(0, attempt - 1))
26
+ return backoff_seconds * multiplier
27
+
28
+
29
+ async def run_with_retries(
30
+ operation: Callable[[], Awaitable[T]],
31
+ config: RetryConfig,
32
+ ) -> T:
33
+ """Run an async operation with bounded retries."""
34
+
35
+ last_error: ExecutionFailure | None = None
36
+
37
+ for attempt in range(1, config.max_attempts + 1):
38
+ try:
39
+ return await operation()
40
+ except httpx.TimeoutException as exc:
41
+ last_error = ExecutionFailure(
42
+ ExecutionError(
43
+ "timeout",
44
+ "The upstream request timed out.",
45
+ retryable=True,
46
+ )
47
+ )
48
+ if attempt == config.max_attempts:
49
+ raise last_error from exc
50
+ except httpx.NetworkError as exc:
51
+ last_error = ExecutionFailure(
52
+ ExecutionError(
53
+ "network_error",
54
+ "The upstream network request failed.",
55
+ retryable=True,
56
+ )
57
+ )
58
+ if attempt == config.max_attempts:
59
+ raise last_error from exc
60
+ except ExecutionFailure as exc:
61
+ last_error = exc
62
+ if not exc.error.retryable or attempt == config.max_attempts:
63
+ raise
64
+
65
+ await asyncio.sleep(retry_delay(config, attempt))
66
+
67
+ if last_error is not None:
68
+ raise last_error
69
+ raise RuntimeError("retry loop completed without a result")
@@ -0,0 +1,7 @@
1
+ """Endpoint filtering and operation safety."""
2
+
3
+ from mcpforge.filtering.evaluator import filter_document
4
+ from mcpforge.filtering.policies import SafetyPolicy
5
+ from mcpforge.filtering.selectors import matches_selectors
6
+
7
+ __all__ = ["SafetyPolicy", "filter_document", "matches_selectors"]