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
|
@@ -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
|
+
)
|