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.
- mcpforge/__init__.py +8 -0
- mcpforge/__main__.py +6 -0
- mcpforge/auth/__init__.py +28 -0
- mcpforge/auth/models.py +25 -0
- mcpforge/auth/providers.py +72 -0
- mcpforge/auth/redaction.py +47 -0
- mcpforge/auth/resolver.py +42 -0
- mcpforge/cli/__init__.py +1 -0
- mcpforge/cli/app.py +45 -0
- mcpforge/cli/commands/__init__.py +13 -0
- mcpforge/cli/commands/import_spec.py +41 -0
- mcpforge/cli/commands/init.py +42 -0
- mcpforge/cli/commands/inspect.py +56 -0
- mcpforge/cli/commands/run.py +44 -0
- mcpforge/cli/commands/serve.py +31 -0
- mcpforge/cli/commands/test.py +60 -0
- mcpforge/cli/commands/validate.py +41 -0
- mcpforge/cli/context.py +14 -0
- mcpforge/cli/output.py +31 -0
- mcpforge/cli/scaffold.py +71 -0
- mcpforge/config/__init__.py +37 -0
- mcpforge/config/loader.py +44 -0
- mcpforge/config/merger.py +25 -0
- mcpforge/config/models.py +182 -0
- mcpforge/config/secrets.py +94 -0
- mcpforge/domain/__init__.py +37 -0
- mcpforge/domain/enums.py +42 -0
- mcpforge/domain/errors.py +13 -0
- mcpforge/domain/models.py +142 -0
- mcpforge/domain/parameters.py +33 -0
- mcpforge/domain/schemas.py +6 -0
- mcpforge/execution/__init__.py +36 -0
- mcpforge/execution/client.py +55 -0
- mcpforge/execution/engine.py +199 -0
- mcpforge/execution/errors.py +83 -0
- mcpforge/execution/limits.py +31 -0
- mcpforge/execution/request_builder.py +87 -0
- mcpforge/execution/response.py +64 -0
- mcpforge/execution/retry.py +69 -0
- mcpforge/filtering/__init__.py +7 -0
- mcpforge/filtering/evaluator.py +26 -0
- mcpforge/filtering/policies.py +44 -0
- mcpforge/filtering/selectors.py +31 -0
- mcpforge/generation/__init__.py +19 -0
- mcpforge/generation/collisions.py +24 -0
- mcpforge/generation/descriptions.py +15 -0
- mcpforge/generation/input_schema.py +53 -0
- mcpforge/generation/models.py +32 -0
- mcpforge/generation/naming.py +54 -0
- mcpforge/generation/service.py +64 -0
- mcpforge/ingestion/__init__.py +26 -0
- mcpforge/ingestion/errors.py +23 -0
- mcpforge/ingestion/loaders/__init__.py +7 -0
- mcpforge/ingestion/loaders/file.py +48 -0
- mcpforge/ingestion/loaders/remote.py +83 -0
- mcpforge/ingestion/normalization/__init__.py +23 -0
- mcpforge/ingestion/normalization/operation.py +83 -0
- mcpforge/ingestion/normalization/parameters.py +119 -0
- mcpforge/ingestion/normalization/references.py +57 -0
- mcpforge/ingestion/normalization/schemas.py +76 -0
- mcpforge/ingestion/parsers/__init__.py +8 -0
- mcpforge/ingestion/parsers/base.py +14 -0
- mcpforge/ingestion/parsers/manual.py +82 -0
- mcpforge/ingestion/parsers/openapi.py +87 -0
- mcpforge/ingestion/parsers/swagger.py +95 -0
- mcpforge/ingestion/service.py +84 -0
- mcpforge/ingestion/source.py +50 -0
- mcpforge/mcp/__init__.py +39 -0
- mcpforge/mcp/adapter.py +88 -0
- mcpforge/mcp/errors.py +25 -0
- mcpforge/mcp/server.py +46 -0
- mcpforge/mcp/tools.py +110 -0
- mcpforge/mcp/transports.py +51 -0
- mcpforge/observability/__init__.py +23 -0
- mcpforge/observability/diagnostics.py +45 -0
- mcpforge/observability/events.py +58 -0
- mcpforge/observability/logging.py +45 -0
- mcpforge/runtime/__init__.py +15 -0
- mcpforge/runtime/application.py +82 -0
- mcpforge/runtime/dependencies.py +77 -0
- mcpforge/runtime/lifecycle.py +50 -0
- mcpforge/security/__init__.py +40 -0
- mcpforge/security/hosts.py +32 -0
- mcpforge/security/redaction.py +60 -0
- mcpforge/security/safety.py +39 -0
- mcpforge/security/ssrf.py +77 -0
- mcpforge/security/validation.py +36 -0
- openapi_mcpforge-0.1.0.dist-info/METADATA +1566 -0
- openapi_mcpforge-0.1.0.dist-info/RECORD +92 -0
- openapi_mcpforge-0.1.0.dist-info/WHEEL +4 -0
- openapi_mcpforge-0.1.0.dist-info/entry_points.txt +2 -0
- openapi_mcpforge-0.1.0.dist-info/licenses/LICENSE +21 -0
mcpforge/cli/scaffold.py
ADDED
|
@@ -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
|
+
]
|
mcpforge/domain/enums.py
ADDED
|
@@ -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)
|