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,26 @@
1
+ """Endpoint filtering service."""
2
+
3
+ from mcpforge.config.models import EndpointFilterConfig, SecurityConfig
4
+ from mcpforge.domain.models import ApiDocument
5
+ from mcpforge.filtering.policies import SafetyPolicy
6
+ from mcpforge.filtering.selectors import matches_selectors
7
+
8
+
9
+ def filter_document(
10
+ document: ApiDocument,
11
+ filters: EndpointFilterConfig | None = None,
12
+ security: SecurityConfig | None = None,
13
+ ) -> ApiDocument:
14
+ """Return a new document containing only permitted endpoints."""
15
+
16
+ selector_config = filters or EndpointFilterConfig()
17
+ safety = SafetyPolicy.from_config(
18
+ security or SecurityConfig(),
19
+ include_deprecated=selector_config.include_deprecated,
20
+ )
21
+ endpoints = [
22
+ endpoint
23
+ for endpoint in document.endpoints
24
+ if matches_selectors(endpoint, selector_config) and safety.allows(endpoint)
25
+ ]
26
+ return document.model_copy(update={"endpoints": endpoints})
@@ -0,0 +1,44 @@
1
+ """Endpoint safety policies."""
2
+
3
+ from dataclasses import dataclass
4
+
5
+ from mcpforge.config.models import SecurityConfig
6
+ from mcpforge.domain.enums import HttpMethod, OperationSafety
7
+ from mcpforge.domain.models import Endpoint
8
+
9
+
10
+ @dataclass(frozen=True, slots=True)
11
+ class SafetyPolicy:
12
+ """Controls which operation classes may be exposed."""
13
+
14
+ allow_write_operations: bool = False
15
+ allow_delete_operations: bool = False
16
+ include_deprecated: bool = False
17
+
18
+ @classmethod
19
+ def from_config(
20
+ cls, config: SecurityConfig, include_deprecated: bool = False
21
+ ) -> "SafetyPolicy":
22
+ return cls(
23
+ allow_write_operations=config.allow_write_operations,
24
+ allow_delete_operations=config.allow_delete_operations,
25
+ include_deprecated=include_deprecated,
26
+ )
27
+
28
+ def allows(self, endpoint: Endpoint) -> bool:
29
+ if endpoint.deprecated and not self.include_deprecated:
30
+ return False
31
+ safety = endpoint.safety or self.classify(endpoint.method)
32
+ if safety is OperationSafety.DELETE:
33
+ return self.allow_delete_operations
34
+ if safety is OperationSafety.WRITE:
35
+ return self.allow_write_operations
36
+ return True
37
+
38
+ @staticmethod
39
+ def classify(method: HttpMethod) -> OperationSafety:
40
+ if method is HttpMethod.DELETE:
41
+ return OperationSafety.DELETE
42
+ if method in {HttpMethod.POST, HttpMethod.PUT, HttpMethod.PATCH}:
43
+ return OperationSafety.WRITE
44
+ return OperationSafety.READ
@@ -0,0 +1,31 @@
1
+ """Path, method, and tag endpoint selectors."""
2
+
3
+ from fnmatch import fnmatch
4
+
5
+ from mcpforge.config.models import EndpointFilterConfig
6
+ from mcpforge.domain.models import Endpoint
7
+
8
+
9
+ def _matches_path(path: str, patterns: list[str]) -> bool:
10
+ return any(fnmatch(path, pattern) or pattern in path for pattern in patterns)
11
+
12
+
13
+ def matches_selectors(endpoint: Endpoint, config: EndpointFilterConfig) -> bool:
14
+ """Apply deterministic selector precedence.
15
+
16
+ Exclusions always win. If an include selector category is configured,
17
+ the endpoint must match that category.
18
+ """
19
+
20
+ if _matches_path(endpoint.path, config.exclude_paths):
21
+ return False
22
+ if set(endpoint.tags) & set(config.exclude_tags):
23
+ return False
24
+
25
+ if config.include_paths and not _matches_path(endpoint.path, config.include_paths):
26
+ return False
27
+ if config.include_tags and not set(endpoint.tags) & set(config.include_tags):
28
+ return False
29
+ if config.methods and endpoint.method not in config.methods:
30
+ return False
31
+ return not (endpoint.deprecated and not config.include_deprecated)
@@ -0,0 +1,19 @@
1
+ """MCP tool generation."""
2
+
3
+ from mcpforge.generation.collisions import unique_names
4
+ from mcpforge.generation.descriptions import endpoint_description
5
+ from mcpforge.generation.input_schema import build_input_schema, schema_to_json
6
+ from mcpforge.generation.models import ToolDefinition, ToolParameter
7
+ from mcpforge.generation.naming import default_tool_name
8
+ from mcpforge.generation.service import generate_tools
9
+
10
+ __all__ = [
11
+ "ToolDefinition",
12
+ "ToolParameter",
13
+ "build_input_schema",
14
+ "default_tool_name",
15
+ "endpoint_description",
16
+ "generate_tools",
17
+ "schema_to_json",
18
+ "unique_names",
19
+ ]
@@ -0,0 +1,24 @@
1
+ """Deterministic generated-name collision handling."""
2
+
3
+ from collections.abc import Iterable
4
+
5
+ from mcpforge.domain.models import Endpoint
6
+ from mcpforge.generation.naming import default_tool_name
7
+
8
+
9
+ def unique_names(endpoints: Iterable[Endpoint]) -> dict[int, str]:
10
+ """Assign stable unique names using operation order and numeric suffixes."""
11
+
12
+ used: set[str] = set()
13
+ result: dict[int, str] = {}
14
+
15
+ for index, endpoint in enumerate(endpoints):
16
+ base = default_tool_name(endpoint)
17
+ name = base
18
+ suffix = 2
19
+ while name in used:
20
+ name = f"{base}_{suffix}"
21
+ suffix += 1
22
+ used.add(name)
23
+ result[index] = name
24
+ return result
@@ -0,0 +1,15 @@
1
+ """Generated tool descriptions."""
2
+
3
+
4
+ def endpoint_description(
5
+ summary: str | None,
6
+ description: str | None,
7
+ method: str,
8
+ path: str,
9
+ ) -> str:
10
+ """Build a concise deterministic description."""
11
+
12
+ text = summary or description
13
+ if text:
14
+ return text.strip()
15
+ return f"Execute {method.upper()} {path}."
@@ -0,0 +1,53 @@
1
+ """AI-facing JSON Schema generation."""
2
+
3
+ from typing import Any
4
+
5
+ from mcpforge.domain.models import Endpoint, JsonSchema
6
+
7
+
8
+ def schema_to_json(schema: JsonSchema) -> dict[str, Any]:
9
+ """Serialize a normalized schema into JSON Schema form."""
10
+
11
+ result: dict[str, Any] = {}
12
+ for key, value in schema.model_dump(by_alias=True, exclude_none=True).items():
13
+ if key == "properties":
14
+ result[key] = {
15
+ name: schema_to_json(JsonSchema.model_validate(child))
16
+ for name, child in value.items()
17
+ }
18
+ elif key == "items" and value is not None:
19
+ result[key] = schema_to_json(JsonSchema.model_validate(value))
20
+ else:
21
+ result[key] = value
22
+ return result
23
+
24
+
25
+ def build_input_schema(endpoint: Endpoint) -> dict[str, Any]:
26
+ """Combine location parameters and body into one strict object schema."""
27
+
28
+ properties: dict[str, Any] = {}
29
+ required: list[str] = []
30
+
31
+ for parameter in endpoint.parameters:
32
+ properties[parameter.name] = schema_to_json(parameter.schema)
33
+ if parameter.description:
34
+ properties[parameter.name]["description"] = parameter.description
35
+ if parameter.required:
36
+ required.append(parameter.name)
37
+
38
+ if endpoint.request_body is not None:
39
+ body_schema = schema_to_json(endpoint.request_body.schema)
40
+ properties["body"] = body_schema
41
+ if endpoint.request_body.description:
42
+ properties["body"]["description"] = endpoint.request_body.description
43
+ if endpoint.request_body.required:
44
+ required.append("body")
45
+
46
+ result: dict[str, Any] = {
47
+ "type": "object",
48
+ "properties": properties,
49
+ "additionalProperties": False,
50
+ }
51
+ if required:
52
+ result["required"] = required
53
+ return result
@@ -0,0 +1,32 @@
1
+ """Generated MCP tool contracts."""
2
+
3
+ from typing import Any
4
+
5
+ from pydantic import BaseModel, ConfigDict, Field
6
+
7
+
8
+ class ToolParameter(BaseModel):
9
+ """AI-facing tool parameter metadata."""
10
+
11
+ model_config = ConfigDict(extra="forbid")
12
+
13
+ name: str
14
+ location: str
15
+ required: bool = False
16
+ schema: dict[str, Any] = Field(default_factory=dict) # type: ignore[assignment]
17
+ description: str | None = None
18
+
19
+
20
+ class ToolDefinition(BaseModel):
21
+ """Transport-independent generated tool definition."""
22
+
23
+ model_config = ConfigDict(extra="forbid", frozen=True)
24
+
25
+ name: str
26
+ description: str
27
+ endpoint_path: str
28
+ method: str
29
+ input_schema: dict[str, Any] = Field(default_factory=dict)
30
+ parameters: tuple[ToolParameter, ...] = ()
31
+ operation_id: str | None = None
32
+ deprecated: bool = False
@@ -0,0 +1,54 @@
1
+ """Deterministic MCP tool naming."""
2
+
3
+ import re
4
+
5
+ from mcpforge.domain.models import Endpoint
6
+
7
+ _STOP_WORDS = {"a", "an", "the", "by", "with", "for"}
8
+
9
+
10
+ def _words(value: str) -> list[str]:
11
+ value = re.sub(r"\{([^}]+)\}", r" \1 ", value)
12
+ value = re.sub(r"([a-z0-9])([A-Z])", r"\1 \2", value)
13
+ return [word.lower() for word in re.split(r"[^A-Za-z0-9]+", value) if word]
14
+
15
+
16
+ def _singular(value: str) -> str:
17
+ if value.endswith("ies"):
18
+ return value[:-3] + "y"
19
+ if value.endswith("ses"):
20
+ return value[:-2]
21
+ if value.endswith("s") and not value.endswith("ss"):
22
+ return value[:-1]
23
+ return value
24
+
25
+
26
+ def default_tool_name(endpoint: Endpoint) -> str:
27
+ """Create a stable snake_case name from operationId or path."""
28
+
29
+ if endpoint.operation_id:
30
+ words = _words(endpoint.operation_id)
31
+ return "_".join(words)
32
+
33
+ segments = [segment for segment in endpoint.path.split("/") if segment]
34
+ resources = [
35
+ _singular(segment)
36
+ for segment in segments
37
+ if not (segment.startswith("{") and segment.endswith("}"))
38
+ ]
39
+ method = endpoint.method.value.lower()
40
+
41
+ if method == "get" and segments and segments[-1].startswith("{"):
42
+ verb = "get"
43
+ elif method == "post":
44
+ verb = "create"
45
+ elif method in {"put", "patch"}:
46
+ verb = "update"
47
+ elif method == "delete":
48
+ verb = "delete"
49
+ elif method == "get":
50
+ verb = "list"
51
+ else:
52
+ verb = method
53
+
54
+ return "_".join([verb, *resources]) or method
@@ -0,0 +1,64 @@
1
+ """Endpoint-to-tool generation."""
2
+
3
+ from collections.abc import Mapping
4
+ from typing import Any
5
+
6
+ from mcpforge.domain.models import ApiDocument
7
+ from mcpforge.generation.collisions import unique_names
8
+ from mcpforge.generation.descriptions import endpoint_description
9
+ from mcpforge.generation.input_schema import build_input_schema
10
+ from mcpforge.generation.models import ToolDefinition, ToolParameter
11
+
12
+
13
+ def generate_tools(
14
+ document: ApiDocument,
15
+ overrides: Mapping[str, Mapping[str, Any]] | None = None,
16
+ ) -> tuple[ToolDefinition, ...]:
17
+ """Generate immutable tool definitions from a normalized document."""
18
+
19
+ overrides = overrides or {}
20
+ names = unique_names(document.endpoints)
21
+ tools: list[ToolDefinition] = []
22
+
23
+ for index, endpoint in enumerate(document.endpoints):
24
+ override = overrides.get(endpoint.operation_id or endpoint.path, {})
25
+ name = str(override.get("name", names[index]))
26
+ description = str(
27
+ override.get(
28
+ "description",
29
+ endpoint_description(
30
+ endpoint.summary,
31
+ endpoint.description,
32
+ endpoint.method.value,
33
+ endpoint.path,
34
+ ),
35
+ )
36
+ )
37
+ parameters = tuple(
38
+ ToolParameter(
39
+ name=parameter.name,
40
+ location=parameter.location.value,
41
+ required=parameter.required,
42
+ schema=parameter.schema.model_dump(
43
+ mode="json",
44
+ by_alias=True,
45
+ exclude_none=True,
46
+ ),
47
+ description=parameter.description,
48
+ )
49
+ for parameter in endpoint.parameters
50
+ )
51
+
52
+ tools.append(
53
+ ToolDefinition(
54
+ name=name,
55
+ description=description,
56
+ endpoint_path=endpoint.path,
57
+ method=endpoint.method.value,
58
+ input_schema=build_input_schema(endpoint),
59
+ parameters=parameters,
60
+ operation_id=endpoint.operation_id,
61
+ deprecated=endpoint.deprecated,
62
+ )
63
+ )
64
+ return tuple(tools)
@@ -0,0 +1,26 @@
1
+ """Multi-source API ingestion and normalization."""
2
+
3
+ from mcpforge.ingestion.errors import (
4
+ IngestionError,
5
+ ReferenceResolutionError,
6
+ SourceLoadError,
7
+ SpecificationError,
8
+ UnsupportedFormatError,
9
+ )
10
+ from mcpforge.ingestion.service import detect_format, ingest, ingest_path, parser_for
11
+ from mcpforge.ingestion.source import LoadedDocument, Source, SourceKind
12
+
13
+ __all__ = [
14
+ "IngestionError",
15
+ "LoadedDocument",
16
+ "ReferenceResolutionError",
17
+ "Source",
18
+ "SourceKind",
19
+ "SourceLoadError",
20
+ "SpecificationError",
21
+ "UnsupportedFormatError",
22
+ "detect_format",
23
+ "ingest",
24
+ "ingest_path",
25
+ "parser_for",
26
+ ]
@@ -0,0 +1,23 @@
1
+ """Errors raised by the API ingestion pipeline."""
2
+
3
+ from mcpforge.domain.errors import MCPForgeError
4
+
5
+
6
+ class IngestionError(MCPForgeError):
7
+ """Base error for source loading, parsing, and normalization failures."""
8
+
9
+
10
+ class SourceLoadError(IngestionError):
11
+ """Raised when an API specification cannot be loaded safely."""
12
+
13
+
14
+ class UnsupportedFormatError(IngestionError):
15
+ """Raised when a source format cannot be detected or is unsupported."""
16
+
17
+
18
+ class SpecificationError(IngestionError):
19
+ """Raised when a specification is malformed or semantically invalid."""
20
+
21
+
22
+ class ReferenceResolutionError(SpecificationError):
23
+ """Raised when a local JSON Pointer cannot be resolved safely."""
@@ -0,0 +1,7 @@
1
+ """Specification source loaders."""
2
+
3
+ from mcpforge.ingestion.loaders.file import load_file
4
+ from mcpforge.ingestion.loaders.remote import load_remote
5
+ from mcpforge.ingestion.source import LoadedDocument, Source
6
+
7
+ __all__ = ["LoadedDocument", "Source", "load_file", "load_remote"]
@@ -0,0 +1,48 @@
1
+ """Safe local specification loading."""
2
+
3
+ import json
4
+ from pathlib import Path
5
+ from typing import Any
6
+
7
+ import yaml
8
+
9
+ from mcpforge.ingestion.errors import SourceLoadError
10
+ from mcpforge.ingestion.source import LoadedDocument, Source
11
+
12
+
13
+ def _parse_document(text: str, suffix: str) -> dict[str, Any]:
14
+ try:
15
+ value: Any = json.loads(text) if suffix.lower() == ".json" else yaml.safe_load(text)
16
+ except (json.JSONDecodeError, yaml.YAMLError) as exc:
17
+ raise SourceLoadError("local specification contains invalid JSON or YAML") from exc
18
+
19
+ if not isinstance(value, dict):
20
+ raise SourceLoadError("specification root must be a mapping")
21
+ return value
22
+
23
+
24
+ def load_file(source: Source) -> LoadedDocument:
25
+ """Read and parse a local JSON or YAML specification."""
26
+
27
+ if source.kind.value != "file":
28
+ raise SourceLoadError("load_file requires a local file source")
29
+
30
+ path = Path(source.location)
31
+ if not path.is_file():
32
+ raise SourceLoadError(f"specification file does not exist: {path}")
33
+
34
+ try:
35
+ size = path.stat().st_size
36
+ except OSError as exc:
37
+ raise SourceLoadError(f"cannot inspect specification file: {path}") from exc
38
+
39
+ if size > source.max_bytes:
40
+ raise SourceLoadError(f"specification file exceeds the {source.max_bytes}-byte limit")
41
+
42
+ try:
43
+ text = path.read_text(encoding="utf-8")
44
+ except (OSError, UnicodeDecodeError) as exc:
45
+ raise SourceLoadError(f"cannot read specification file: {path}") from exc
46
+
47
+ document = _parse_document(text, path.suffix)
48
+ return LoadedDocument(document=document, source=source)
@@ -0,0 +1,83 @@
1
+ """Safe remote specification loading without coupling ingestion to HTTPX."""
2
+
3
+ import json
4
+ from typing import Any
5
+ from urllib.error import HTTPError, URLError
6
+ from urllib.parse import urlparse
7
+ from urllib.request import Request, urlopen
8
+
9
+ import yaml
10
+
11
+ from mcpforge.ingestion.errors import SourceLoadError
12
+ from mcpforge.ingestion.source import LoadedDocument, Source
13
+
14
+
15
+ def _parse_document(text: str, content_type: str | None, url: str) -> dict[str, Any]:
16
+ try:
17
+ suffix = urlparse(url).path.lower()
18
+ if "json" in (content_type or "").lower() or suffix.endswith(".json"):
19
+ value: Any = json.loads(text)
20
+ else:
21
+ value = yaml.safe_load(text)
22
+ except (json.JSONDecodeError, yaml.YAMLError) as exc:
23
+ raise SourceLoadError("remote specification contains invalid JSON or YAML") from exc
24
+
25
+ if not isinstance(value, dict):
26
+ raise SourceLoadError("remote specification root must be a mapping")
27
+ return value
28
+
29
+
30
+ def load_remote(source: Source) -> LoadedDocument:
31
+ """Fetch and parse a remote JSON or YAML specification with a byte limit."""
32
+
33
+ if source.kind.value != "url":
34
+ raise SourceLoadError("load_remote requires an HTTP or HTTPS source")
35
+
36
+ parsed = urlparse(source.location)
37
+ if parsed.scheme not in {"http", "https"} or not parsed.netloc:
38
+ raise SourceLoadError("remote source must use a valid HTTP or HTTPS URL")
39
+
40
+ request = Request(
41
+ source.location,
42
+ headers={
43
+ "Accept": "application/json, application/yaml, text/yaml, */*",
44
+ "User-Agent": "MCPForge/0.1",
45
+ },
46
+ method="GET",
47
+ )
48
+
49
+ try:
50
+ with urlopen(request, timeout=source.timeout_seconds) as response:
51
+ content_type = response.headers.get("Content-Type")
52
+ declared_length = response.headers.get("Content-Length")
53
+ if declared_length and int(declared_length) > source.max_bytes:
54
+ raise SourceLoadError(
55
+ f"remote specification exceeds the {source.max_bytes}-byte limit"
56
+ )
57
+
58
+ chunks: list[bytes] = []
59
+ total = 0
60
+ while True:
61
+ chunk = response.read(min(64 * 1024, source.max_bytes - total + 1))
62
+ if not chunk:
63
+ break
64
+ total += len(chunk)
65
+ if total > source.max_bytes:
66
+ raise SourceLoadError(
67
+ f"remote specification exceeds the {source.max_bytes}-byte limit"
68
+ )
69
+ chunks.append(chunk)
70
+ except SourceLoadError:
71
+ raise
72
+ except HTTPError as exc:
73
+ raise SourceLoadError(f"remote specification returned HTTP {exc.code}") from exc
74
+ except (URLError, TimeoutError, OSError) as exc:
75
+ raise SourceLoadError(f"cannot fetch remote specification: {source.location}") from exc
76
+
77
+ try:
78
+ text = b"".join(chunks).decode("utf-8")
79
+ except UnicodeDecodeError as exc:
80
+ raise SourceLoadError("remote specification is not valid UTF-8") from exc
81
+
82
+ document = _parse_document(text, content_type, source.location)
83
+ return LoadedDocument(document=document, source=source, media_type=content_type)
@@ -0,0 +1,23 @@
1
+ """Conversion helpers for normalized domain models."""
2
+
3
+ from mcpforge.ingestion.normalization.operation import (
4
+ endpoint_from_operation,
5
+ operation_safety,
6
+ )
7
+ from mcpforge.ingestion.normalization.parameters import (
8
+ normalize_parameter,
9
+ normalize_request_body,
10
+ normalize_response,
11
+ )
12
+ from mcpforge.ingestion.normalization.references import ReferenceResolver
13
+ from mcpforge.ingestion.normalization.schemas import normalize_schema
14
+
15
+ __all__ = [
16
+ "ReferenceResolver",
17
+ "endpoint_from_operation",
18
+ "normalize_parameter",
19
+ "normalize_request_body",
20
+ "normalize_response",
21
+ "normalize_schema",
22
+ "operation_safety",
23
+ ]
@@ -0,0 +1,83 @@
1
+ """Normalization of complete API operations."""
2
+
3
+ from collections.abc import Mapping, Sequence
4
+ from typing import Any
5
+
6
+ from mcpforge.domain.enums import HttpMethod, OperationSafety
7
+ from mcpforge.domain.models import Endpoint, Parameter, RequestBody
8
+ from mcpforge.ingestion.errors import SpecificationError
9
+ from mcpforge.ingestion.normalization.parameters import (
10
+ normalize_parameter,
11
+ normalize_request_body,
12
+ normalize_response,
13
+ )
14
+ from mcpforge.ingestion.normalization.references import ReferenceResolver
15
+
16
+
17
+ def operation_safety(method: HttpMethod) -> OperationSafety:
18
+ """Classify an HTTP method for later safety policy evaluation."""
19
+
20
+ if method is HttpMethod.DELETE:
21
+ return OperationSafety.DELETE
22
+ if method in {HttpMethod.POST, HttpMethod.PUT, HttpMethod.PATCH}:
23
+ return OperationSafety.WRITE
24
+ return OperationSafety.READ
25
+
26
+
27
+ def _method(value: str) -> HttpMethod:
28
+ try:
29
+ return HttpMethod(value.upper())
30
+ except ValueError as exc:
31
+ raise SpecificationError(f"unsupported HTTP method: {value}") from exc
32
+
33
+
34
+ def endpoint_from_operation(
35
+ path: str,
36
+ method: str,
37
+ raw: Mapping[str, Any],
38
+ resolver: ReferenceResolver,
39
+ path_parameters: Sequence[Mapping[str, Any]] = (),
40
+ swagger: bool = False,
41
+ ) -> Endpoint:
42
+ """Build a normalized endpoint from one raw operation."""
43
+
44
+ http_method = _method(method)
45
+ parameters: list[Parameter] = []
46
+ body: RequestBody | None = None
47
+
48
+ merged_parameters = [*path_parameters, *raw.get("parameters", [])]
49
+ for parameter in merged_parameters:
50
+ resolved = resolver.resolve(parameter)
51
+ if not isinstance(resolved, Mapping):
52
+ raise SpecificationError("parameter reference must resolve to a mapping")
53
+ if resolved.get("in") == "body":
54
+ body = normalize_request_body(resolved, resolver)
55
+ else:
56
+ parameters.append(normalize_parameter(resolved, resolver))
57
+
58
+ if not swagger and isinstance(raw.get("requestBody"), Mapping):
59
+ body = normalize_request_body(raw["requestBody"], resolver)
60
+
61
+ raw_responses = raw.get("responses", {})
62
+ if not isinstance(raw_responses, Mapping):
63
+ raise SpecificationError(f"responses for {method} {path} must be a mapping")
64
+
65
+ responses = [
66
+ normalize_response(status, response, resolver, swagger=swagger)
67
+ for status, response in raw_responses.items()
68
+ if isinstance(response, Mapping)
69
+ ]
70
+
71
+ return Endpoint(
72
+ operation_id=raw.get("operationId"),
73
+ path=path,
74
+ method=http_method,
75
+ summary=raw.get("summary"),
76
+ description=raw.get("description"),
77
+ tags=[str(tag) for tag in raw.get("tags", [])],
78
+ parameters=parameters,
79
+ request_body=body,
80
+ responses=responses,
81
+ deprecated=bool(raw.get("deprecated", False)),
82
+ safety=operation_safety(http_method),
83
+ )