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,71 @@
1
+ """Project scaffolding helpers."""
2
+
3
+ from pathlib import Path
4
+
5
+ DEFAULT_CONFIG = """name: mcpforge-project
6
+ source:
7
+ location: ./openapi.yaml
8
+ format: openapi
9
+ auth:
10
+ type: none
11
+ filters:
12
+ include_deprecated: false
13
+ security:
14
+ allow_write_operations: false
15
+ allow_delete_operations: false
16
+ allowed_hosts: []
17
+ block_private_networks: true
18
+ max_response_bytes: 5000000
19
+ http:
20
+ timeout_seconds: 30
21
+ verify_tls: true
22
+ retry:
23
+ max_attempts: 3
24
+ backoff_seconds: 0.5
25
+ """
26
+
27
+ DEFAULT_ENV = """# MCPForge runtime secrets
28
+ # MCPFORGE_API_TOKEN=
29
+ """
30
+
31
+ DEFAULT_OPENAPI = """openapi: 3.0.3
32
+ info:
33
+ title: Example API
34
+ version: "1.0.0"
35
+ servers:
36
+ - url: https://api.example.com
37
+ paths:
38
+ /health:
39
+ get:
40
+ operationId: health_check
41
+ summary: Check API health
42
+ responses:
43
+ "200":
44
+ description: Healthy
45
+ """
46
+
47
+
48
+ def scaffold_project(
49
+ directory: Path,
50
+ *,
51
+ force: bool = False,
52
+ with_example: bool = True,
53
+ ) -> tuple[Path, ...]:
54
+ """Create a starter MCPForge project."""
55
+
56
+ directory.mkdir(parents=True, exist_ok=True)
57
+ files: dict[Path, str] = {
58
+ directory / "mcpforge.yaml": DEFAULT_CONFIG,
59
+ directory / ".env.example": DEFAULT_ENV,
60
+ }
61
+ if with_example:
62
+ files[directory / "openapi.yaml"] = DEFAULT_OPENAPI
63
+
64
+ created: list[Path] = []
65
+ for path, content in files.items():
66
+ if path.exists() and not force:
67
+ raise FileExistsError(f"file already exists: {path}")
68
+ path.parent.mkdir(parents=True, exist_ok=True)
69
+ path.write_text(content, encoding="utf-8")
70
+ created.append(path)
71
+ return tuple(created)
@@ -0,0 +1,37 @@
1
+ """Configuration loading and runtime secret resolution."""
2
+
3
+ from mcpforge.config.loader import DEFAULT_CONFIG_FILENAME, load_config
4
+ from mcpforge.config.models import (
5
+ ApiKeyAuthConfig,
6
+ ApiSourceConfig,
7
+ BasicAuthConfig,
8
+ BearerAuthConfig,
9
+ EndpointFilterConfig,
10
+ EnvReference,
11
+ HttpConfig,
12
+ NoAuthConfig,
13
+ ProjectConfig,
14
+ RetryConfig,
15
+ SecurityConfig,
16
+ StaticHeadersAuthConfig,
17
+ )
18
+ from mcpforge.config.secrets import resolve_env, validate_secret_references
19
+
20
+ __all__ = [
21
+ "ApiKeyAuthConfig",
22
+ "ApiSourceConfig",
23
+ "BasicAuthConfig",
24
+ "BearerAuthConfig",
25
+ "DEFAULT_CONFIG_FILENAME",
26
+ "EndpointFilterConfig",
27
+ "EnvReference",
28
+ "HttpConfig",
29
+ "NoAuthConfig",
30
+ "ProjectConfig",
31
+ "RetryConfig",
32
+ "SecurityConfig",
33
+ "StaticHeadersAuthConfig",
34
+ "load_config",
35
+ "resolve_env",
36
+ "validate_secret_references",
37
+ ]
@@ -0,0 +1,44 @@
1
+ """YAML and JSON configuration loader."""
2
+
3
+ import json
4
+ from pathlib import Path
5
+ from typing import Any
6
+
7
+ import yaml
8
+ from pydantic import ValidationError
9
+
10
+ from mcpforge.config.models import ProjectConfig
11
+ from mcpforge.domain.errors import ConfigurationError
12
+
13
+ DEFAULT_CONFIG_FILENAME = "mcpforge.yaml"
14
+
15
+
16
+ def _read_document(path: Path) -> dict[str, Any]:
17
+ try:
18
+ text = path.read_text(encoding="utf-8")
19
+ except OSError as exc:
20
+ raise ConfigurationError(f"cannot read configuration {path}: {exc}") from exc
21
+
22
+ try:
23
+ document: Any = json.loads(text) if path.suffix.lower() == ".json" else yaml.safe_load(text)
24
+ except (json.JSONDecodeError, yaml.YAMLError) as exc:
25
+ raise ConfigurationError(f"invalid configuration syntax in {path}") from exc
26
+
27
+ if not isinstance(document, dict):
28
+ raise ConfigurationError(f"configuration root in {path} must be a mapping")
29
+ return document
30
+
31
+
32
+ def load_config(path: str | Path = DEFAULT_CONFIG_FILENAME) -> ProjectConfig:
33
+ """Load and validate a YAML or JSON project configuration."""
34
+
35
+ config_path = Path(path)
36
+ if not config_path.is_file():
37
+ raise ConfigurationError(f"configuration file does not exist: {config_path}")
38
+
39
+ try:
40
+ return ProjectConfig.model_validate(_read_document(config_path))
41
+ except ValidationError as exc:
42
+ raise ConfigurationError(
43
+ f"configuration validation failed for {config_path}: {exc}"
44
+ ) from exc
@@ -0,0 +1,25 @@
1
+ """Safe recursive configuration merging."""
2
+
3
+ from collections.abc import Mapping
4
+ from copy import deepcopy
5
+ from typing import Any
6
+
7
+
8
+ def merge_mappings(
9
+ base: Mapping[str, Any],
10
+ override: Mapping[str, Any],
11
+ ) -> dict[str, Any]:
12
+ """Deep-merge mappings without mutating either input.
13
+
14
+ Nested mappings merge recursively. Lists and scalar values are replaced
15
+ by the overriding value.
16
+ """
17
+
18
+ result: dict[str, Any] = deepcopy(dict(base))
19
+ for key, value in override.items():
20
+ current = result.get(key)
21
+ if isinstance(current, Mapping) and isinstance(value, Mapping):
22
+ result[key] = merge_mappings(current, value)
23
+ else:
24
+ result[key] = deepcopy(value)
25
+ return result
@@ -0,0 +1,182 @@
1
+ """Strict user-facing MCPForge project configuration models."""
2
+
3
+ from typing import Annotated, Literal, Self
4
+
5
+ from pydantic import AnyHttpUrl, BaseModel, ConfigDict, Field, model_validator
6
+
7
+ from mcpforge.config.secrets import validate_secret_references
8
+ from mcpforge.domain.enums import AuthType, HttpMethod
9
+
10
+
11
+ class EnvReference(BaseModel):
12
+ """Reference to a value resolved from an environment variable."""
13
+
14
+ model_config = ConfigDict(extra="forbid")
15
+
16
+ env: Annotated[
17
+ str,
18
+ Field(
19
+ min_length=1,
20
+ pattern=r"^[A-Za-z_][A-Za-z0-9_]*$",
21
+ ),
22
+ ]
23
+ required: bool = True
24
+ default: str | None = None
25
+
26
+ @model_validator(mode="after")
27
+ def validate_default(self) -> Self:
28
+ if self.required and self.default is not None:
29
+ raise ValueError("required environment references cannot define defaults")
30
+ return self
31
+
32
+
33
+ class ApiSourceConfig(BaseModel):
34
+ """API specification source configuration."""
35
+
36
+ model_config = ConfigDict(extra="forbid")
37
+
38
+ location: Annotated[str, Field(min_length=1)]
39
+ format: Literal["openapi", "swagger", "manual"] | None = None
40
+ base_url: AnyHttpUrl | None = None
41
+ timeout_seconds: Annotated[float, Field(gt=0, le=300)] = 30.0
42
+
43
+
44
+ class NoAuthConfig(BaseModel):
45
+ """Explicitly unauthenticated API configuration."""
46
+
47
+ model_config = ConfigDict(extra="forbid")
48
+
49
+ type: Literal[AuthType.NONE] = AuthType.NONE
50
+
51
+
52
+ class BearerAuthConfig(BaseModel):
53
+ """Bearer-token authentication configuration."""
54
+
55
+ model_config = ConfigDict(extra="forbid")
56
+
57
+ type: Literal[AuthType.BEARER] = AuthType.BEARER
58
+ token: EnvReference
59
+
60
+
61
+ class ApiKeyAuthConfig(BaseModel):
62
+ """API-key authentication configuration."""
63
+
64
+ model_config = ConfigDict(extra="forbid")
65
+
66
+ type: Literal[AuthType.API_KEY] = AuthType.API_KEY
67
+ name: Annotated[str, Field(min_length=1)]
68
+ location: Literal["header", "query"] = "header"
69
+ value: EnvReference
70
+
71
+
72
+ class BasicAuthConfig(BaseModel):
73
+ """HTTP Basic authentication configuration."""
74
+
75
+ model_config = ConfigDict(extra="forbid")
76
+
77
+ type: Literal[AuthType.BASIC] = AuthType.BASIC
78
+ username: EnvReference
79
+ password: EnvReference
80
+
81
+
82
+ class StaticHeadersAuthConfig(BaseModel):
83
+ """Environment-backed static header configuration."""
84
+
85
+ model_config = ConfigDict(extra="forbid")
86
+
87
+ type: Literal[AuthType.STATIC_HEADERS] = AuthType.STATIC_HEADERS
88
+ headers: dict[
89
+ Annotated[str, Field(min_length=1)],
90
+ EnvReference,
91
+ ] = Field(min_length=1)
92
+
93
+
94
+ AuthConfig = (
95
+ NoAuthConfig | BearerAuthConfig | ApiKeyAuthConfig | BasicAuthConfig | StaticHeadersAuthConfig
96
+ )
97
+
98
+
99
+ class EndpointFilterConfig(BaseModel):
100
+ """Endpoint inclusion and exclusion rules."""
101
+
102
+ model_config = ConfigDict(extra="forbid")
103
+
104
+ include_paths: list[str] = Field(default_factory=list)
105
+ exclude_paths: list[str] = Field(default_factory=list)
106
+ include_tags: list[str] = Field(default_factory=list)
107
+ exclude_tags: list[str] = Field(default_factory=list)
108
+ methods: set[HttpMethod] | None = None
109
+ include_deprecated: bool = False
110
+
111
+
112
+ class SecurityConfig(BaseModel):
113
+ """Operation and network security controls."""
114
+
115
+ model_config = ConfigDict(extra="forbid")
116
+
117
+ allow_write_operations: bool = False
118
+ allow_delete_operations: bool = False
119
+ allowed_hosts: set[str] = Field(default_factory=set)
120
+ block_private_networks: bool = True
121
+ max_response_bytes: Annotated[int, Field(gt=0, le=100_000_000)] = 5_000_000
122
+
123
+
124
+ class RetryConfig(BaseModel):
125
+ """Transient request retry policy."""
126
+
127
+ model_config = ConfigDict(extra="forbid")
128
+
129
+ max_attempts: Annotated[int, Field(ge=1, le=10)] = 3
130
+ backoff_seconds: Annotated[float, Field(ge=0, le=60)] = 0.5
131
+
132
+
133
+ class HttpConfig(BaseModel):
134
+ """HTTP client and retry settings."""
135
+
136
+ model_config = ConfigDict(extra="forbid")
137
+
138
+ timeout_seconds: Annotated[float, Field(gt=0, le=300)] = 30.0
139
+ retry: RetryConfig = Field(default_factory=RetryConfig)
140
+ verify_tls: bool = True
141
+
142
+
143
+ class ProjectConfig(BaseModel):
144
+ """Top-level ``mcpforge.yaml`` project configuration."""
145
+
146
+ model_config = ConfigDict(extra="forbid")
147
+
148
+ name: Annotated[
149
+ str,
150
+ Field(
151
+ min_length=1,
152
+ pattern=r"^[A-Za-z0-9][A-Za-z0-9_-]*$",
153
+ ),
154
+ ] = "mcpforge-project"
155
+ source: ApiSourceConfig
156
+ auth: AuthConfig = Field(default_factory=NoAuthConfig)
157
+ filters: EndpointFilterConfig = Field(default_factory=EndpointFilterConfig)
158
+ security: SecurityConfig = Field(default_factory=SecurityConfig)
159
+ http: HttpConfig = Field(default_factory=HttpConfig)
160
+
161
+ @model_validator(mode="after")
162
+ def validate_configuration(self) -> Self:
163
+ validate_secret_references(self.model_dump(mode="python"))
164
+
165
+ if self.source.base_url is not None and self.security.allowed_hosts:
166
+ source_host = self.source.base_url.host
167
+ if source_host is None:
168
+ raise ValueError("source base URL must include a host")
169
+ allowed_hosts = {
170
+ host.strip().rstrip(".").lower() for host in self.security.allowed_hosts
171
+ }
172
+ if source_host.lower().rstrip(".") not in allowed_hosts:
173
+ raise ValueError(
174
+ f"source host {source_host!r} is not present in security.allowed_hosts"
175
+ )
176
+
177
+ return self
178
+
179
+ def safe_dump(self) -> dict[str, object]:
180
+ """Serialize configuration without resolving secret values."""
181
+
182
+ return self.model_dump(mode="json")
@@ -0,0 +1,94 @@
1
+ """Environment-backed secret handling without configuration-model imports."""
2
+
3
+ import os
4
+ from collections.abc import Mapping, Sequence
5
+ from typing import Any, Protocol, runtime_checkable
6
+
7
+ from mcpforge.domain.errors import ConfigurationError
8
+
9
+
10
+ @runtime_checkable
11
+ class EnvironmentReference(Protocol):
12
+ """Structural contract for an environment-backed configuration value."""
13
+
14
+ env: str
15
+ required: bool
16
+ default: str | None
17
+
18
+
19
+ def _is_environment_reference(value: Any) -> bool:
20
+ """Return whether a value has the EnvReference runtime shape."""
21
+
22
+ if isinstance(value, Mapping):
23
+ keys = set(value)
24
+ return isinstance(value.get("env"), str) and keys <= {"env", "required", "default"}
25
+
26
+ return (
27
+ isinstance(value, EnvironmentReference)
28
+ and isinstance(value.env, str)
29
+ and isinstance(value.required, bool)
30
+ and (value.default is None or isinstance(value.default, str))
31
+ )
32
+
33
+
34
+ def resolve_env(reference: EnvironmentReference) -> str:
35
+ """Resolve a required or optional environment variable."""
36
+
37
+ if not _is_environment_reference(reference):
38
+ raise ConfigurationError("secret values must be environment-variable references")
39
+
40
+ environment_name = reference.env
41
+ value = os.getenv(environment_name)
42
+
43
+ if value is None:
44
+ if reference.default is not None:
45
+ return reference.default
46
+ if reference.required:
47
+ raise ConfigurationError(
48
+ f"required environment variable {environment_name!r} is not set"
49
+ )
50
+ return ""
51
+
52
+ if not value:
53
+ raise ConfigurationError(f"environment variable {environment_name!r} is empty")
54
+
55
+ return value
56
+
57
+
58
+ def _is_secret_key(key: object) -> bool:
59
+ normalized = str(key).strip().lower().replace("-", "_")
60
+ return normalized in {
61
+ "token",
62
+ "password",
63
+ "secret",
64
+ "api_key",
65
+ "access_token",
66
+ "refresh_token",
67
+ "client_secret",
68
+ "authorization",
69
+ }
70
+
71
+
72
+ def validate_secret_references(value: Any, path: str = "config") -> None:
73
+ """Reject literal values in secret-bearing configuration fields.
74
+
75
+ This function intentionally depends only on structural typing and standard
76
+ library protocols, so ``config.models`` can import it without a cycle.
77
+ """
78
+
79
+ if _is_environment_reference(value):
80
+ return
81
+
82
+ if isinstance(value, Mapping):
83
+ for key, child in value.items():
84
+ child_path = f"{path}.{key}"
85
+
86
+ if _is_secret_key(key) and not _is_environment_reference(child):
87
+ raise ConfigurationError(f"{child_path} must be an environment variable reference")
88
+
89
+ validate_secret_references(child, child_path)
90
+ return
91
+
92
+ if isinstance(value, Sequence) and not isinstance(value, str | bytes | bytearray):
93
+ for index, child in enumerate(value):
94
+ validate_secret_references(child, f"{path}[{index}]")
@@ -0,0 +1,37 @@
1
+ """Framework-independent normalized API domain contracts."""
2
+
3
+ from mcpforge.domain.enums import (
4
+ AuthType,
5
+ HttpMethod,
6
+ OperationSafety,
7
+ ParameterLocation,
8
+ )
9
+ from mcpforge.domain.errors import DomainValidationError, MCPForgeError
10
+ from mcpforge.domain.models import (
11
+ ApiDocument,
12
+ Endpoint,
13
+ JsonSchema,
14
+ Parameter,
15
+ RequestBody,
16
+ ResponseDefinition,
17
+ )
18
+ from mcpforge.domain.parameters import ParameterCollection
19
+ from mcpforge.domain.schemas import JsonObject, JsonValue
20
+
21
+ __all__ = [
22
+ "ApiDocument",
23
+ "AuthType",
24
+ "DomainValidationError",
25
+ "Endpoint",
26
+ "HttpMethod",
27
+ "JsonObject",
28
+ "JsonSchema",
29
+ "JsonValue",
30
+ "MCPForgeError",
31
+ "OperationSafety",
32
+ "Parameter",
33
+ "ParameterCollection",
34
+ "ParameterLocation",
35
+ "RequestBody",
36
+ "ResponseDefinition",
37
+ ]
@@ -0,0 +1,42 @@
1
+ """Domain enumerations."""
2
+
3
+ from enum import StrEnum
4
+
5
+
6
+ class HttpMethod(StrEnum):
7
+ """Supported HTTP methods."""
8
+
9
+ GET = "GET"
10
+ POST = "POST"
11
+ PUT = "PUT"
12
+ PATCH = "PATCH"
13
+ DELETE = "DELETE"
14
+ HEAD = "HEAD"
15
+ OPTIONS = "OPTIONS"
16
+
17
+
18
+ class ParameterLocation(StrEnum):
19
+ """Locations in which endpoint parameters can be transmitted."""
20
+
21
+ PATH = "path"
22
+ QUERY = "query"
23
+ HEADER = "header"
24
+ COOKIE = "cookie"
25
+
26
+
27
+ class OperationSafety(StrEnum):
28
+ """High-level operation safety classification."""
29
+
30
+ READ = "read"
31
+ WRITE = "write"
32
+ DELETE = "delete"
33
+
34
+
35
+ class AuthType(StrEnum):
36
+ """Supported authentication mechanisms."""
37
+
38
+ NONE = "none"
39
+ BEARER = "bearer"
40
+ API_KEY = "api_key"
41
+ BASIC = "basic"
42
+ STATIC_HEADERS = "static_headers"
@@ -0,0 +1,13 @@
1
+ """Domain-level exceptions."""
2
+
3
+
4
+ class MCPForgeError(Exception):
5
+ """Base exception for expected MCPForge failures."""
6
+
7
+
8
+ class DomainValidationError(MCPForgeError):
9
+ """Raised when a normalized domain object violates an invariant."""
10
+
11
+
12
+ class ConfigurationError(MCPForgeError):
13
+ """Raised when project configuration cannot be loaded or validated."""
@@ -0,0 +1,142 @@
1
+ """Normalized parser-independent REST API models."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Annotated, Self
6
+
7
+ from pydantic import BaseModel, ConfigDict, Field, model_validator
8
+
9
+ from mcpforge.domain.enums import HttpMethod, OperationSafety, ParameterLocation
10
+
11
+
12
+ class JsonSchema(BaseModel):
13
+ """Conservative JSON Schema representation used by the internal model."""
14
+
15
+ model_config = ConfigDict(extra="allow", populate_by_name=True)
16
+
17
+ type: str | None = None
18
+ title: str | None = None
19
+ description: str | None = None
20
+ format: str | None = None
21
+ enum: list[object] | None = None
22
+ default: object | None = None
23
+ required: list[str] = Field(default_factory=list)
24
+ properties: dict[str, JsonSchema] = Field(default_factory=dict)
25
+ items: JsonSchema | None = None
26
+ additional_properties: bool | JsonSchema | None = Field(
27
+ default=None,
28
+ alias="additionalProperties",
29
+ )
30
+
31
+ @model_validator(mode="after")
32
+ def validate_shape(self) -> Self:
33
+ if self.type == "object" and self.items is not None:
34
+ raise ValueError("object schemas cannot define items")
35
+ if self.type == "array" and self.properties:
36
+ raise ValueError("array schemas cannot define properties")
37
+ unknown = set(self.required) - set(self.properties)
38
+ if unknown:
39
+ names = ", ".join(sorted(unknown))
40
+ raise ValueError(f"required fields are not defined: {names}")
41
+ return self
42
+
43
+
44
+ class Parameter(BaseModel):
45
+ """A path, query, header, or cookie parameter."""
46
+
47
+ model_config = ConfigDict(extra="forbid")
48
+
49
+ name: Annotated[str, Field(min_length=1, pattern=r"^[A-Za-z0-9._-]+$")]
50
+ location: ParameterLocation
51
+ required: bool = False
52
+ description: str | None = None
53
+ schema: JsonSchema = Field(default_factory=JsonSchema) # type: ignore[assignment]
54
+ deprecated: bool = False
55
+ example: object | None = None
56
+
57
+ @model_validator(mode="after")
58
+ def validate_path_requirement(self) -> Self:
59
+ if self.location is ParameterLocation.PATH and not self.required:
60
+ raise ValueError("path parameters must be required")
61
+ return self
62
+
63
+
64
+ class RequestBody(BaseModel):
65
+ """Normalized request body definition."""
66
+
67
+ model_config = ConfigDict(extra="forbid")
68
+
69
+ required: bool = False
70
+ content_type: str = "application/json"
71
+ schema: JsonSchema = Field(default_factory=JsonSchema) # type: ignore[assignment]
72
+ description: str | None = None
73
+
74
+
75
+ class ResponseDefinition(BaseModel):
76
+ """One possible normalized endpoint response."""
77
+
78
+ model_config = ConfigDict(extra="forbid")
79
+
80
+ status_code: Annotated[int, Field(ge=100, le=599)]
81
+ description: str | None = None
82
+ content_type: str | None = None
83
+ schema: JsonSchema | None = None # type: ignore[assignment]
84
+
85
+
86
+ class Endpoint(BaseModel):
87
+ """A complete normalized REST endpoint."""
88
+
89
+ model_config = ConfigDict(extra="forbid")
90
+
91
+ operation_id: str | None = None
92
+ path: Annotated[str, Field(min_length=1, pattern=r"^/")]
93
+ method: HttpMethod
94
+ summary: str | None = None
95
+ description: str | None = None
96
+ tags: list[str] = Field(default_factory=list)
97
+ parameters: list[Parameter] = Field(default_factory=list)
98
+ request_body: RequestBody | None = None
99
+ responses: list[ResponseDefinition] = Field(default_factory=list)
100
+ deprecated: bool = False
101
+ safety: OperationSafety | None = None
102
+
103
+ @model_validator(mode="after")
104
+ def validate_endpoint(self) -> Self:
105
+ path_names = {
106
+ segment[1:-1]
107
+ for segment in self.path.split("/")
108
+ if segment.startswith("{") and segment.endswith("}")
109
+ }
110
+ defined_names = {
111
+ parameter.name
112
+ for parameter in self.parameters
113
+ if parameter.location is ParameterLocation.PATH
114
+ }
115
+ missing = path_names - defined_names
116
+ if missing:
117
+ raise ValueError(f"path parameters are not defined: {', '.join(sorted(missing))}")
118
+
119
+ seen: set[str] = set()
120
+ duplicates: set[str] = set()
121
+ for parameter in self.parameters:
122
+ if parameter.name in seen:
123
+ duplicates.add(parameter.name)
124
+ seen.add(parameter.name)
125
+ if duplicates:
126
+ raise ValueError(f"duplicate parameter names: {', '.join(sorted(duplicates))}")
127
+ return self
128
+
129
+
130
+ class ApiDocument(BaseModel):
131
+ """The stable parser output consumed by future pipeline stages."""
132
+
133
+ model_config = ConfigDict(extra="forbid")
134
+
135
+ title: str = "Untitled API"
136
+ version: str = "0.0.0"
137
+ base_url: str | None = None
138
+ description: str | None = None
139
+ endpoints: list[Endpoint] = Field(default_factory=list)
140
+ source_format: str | None = None
141
+ source_name: str | None = None
142
+ extensions: dict[str, object] = Field(default_factory=dict)