api-to-tools 0.1.0__tar.gz

api_to_tools-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.eggs/
+.env
+.DS_Store
+.ruff_cache/
+.pytest_cache/
+node_modules/

api_to_tools-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SonAIengine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

api_to_tools-0.1.0/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.4
+Name: api-to-tools
+Version: 0.1.0
+Summary: Universal library that converts any API (OpenAPI, WSDL/SOAP, GraphQL, gRPC, AsyncAPI) into LLM-callable tool definitions
+Project-URL: Homepage, https://github.com/SonAIengine/api-to-tools
+Project-URL: Repository, https://github.com/SonAIengine/api-to-tools
+Author: SonAIengine
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,function-calling,graphql,grpc,llm,mcp,openapi,soap,swagger,tools,wsdl
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: graphql-core>=3.2
+Requires-Dist: grpcio-tools>=1.60
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.0
+Requires-Dist: openapi-spec-validator>=0.7
+Requires-Dist: prance>=23.6
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: xmltodict>=0.13
+Requires-Dist: zeep>=4.2
+Provides-Extra: asyncapi
+Requires-Dist: asyncapi-parser>=0.1; extra == 'asyncapi'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'

api_to_tools-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "api-to-tools"
+version = "0.1.0"
+description = "Universal library that converts any API (OpenAPI, WSDL/SOAP, GraphQL, gRPC, AsyncAPI) into LLM-callable tool definitions"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "SonAIengine" }]
+keywords = ["api", "openapi", "swagger", "wsdl", "soap", "graphql", "grpc", "mcp", "llm", "tools", "function-calling"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "httpx>=0.27",
+    "pyyaml>=6.0",
+    "prance>=23.6",       # OpenAPI parser
+    "openapi-spec-validator>=0.7",
+    "zeep>=4.2",          # WSDL/SOAP
+    "graphql-core>=3.2",  # GraphQL
+    "grpcio-tools>=1.60", # gRPC / protobuf
+    "mcp>=1.0",           # MCP SDK
+    "xmltodict>=0.13",    # XML <-> dict
+]
+
+[project.optional-dependencies]
+asyncapi = ["asyncapi-parser>=0.1"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "ruff>=0.4"]
+
+[project.scripts]
+api-to-tools = "api_to_tools.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/SonAIengine/api-to-tools"
+Repository = "https://github.com/SonAIengine/api-to-tools"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/api_to_tools"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120

api_to_tools-0.1.0/src/api_to_tools/__init__.py

@@ -0,0 +1,23 @@
+"""Universal API-to-LLM-tools converter."""
+
+from api_to_tools.types import Tool, ToolParameter, DetectionResult, SpecType, Protocol
+from api_to_tools.core import discover, to_tools, execute
+from api_to_tools.adapters.formats import to_function_calling, to_anthropic_tools
+from api_to_tools.utils import group_by_tag, group_by_method, summarize, search_tools
+
+__all__ = [
+    "discover",
+    "to_tools",
+    "execute",
+    "to_function_calling",
+    "to_anthropic_tools",
+    "group_by_tag",
+    "group_by_method",
+    "summarize",
+    "search_tools",
+    "Tool",
+    "ToolParameter",
+    "DetectionResult",
+    "SpecType",
+    "Protocol",
+]

api_to_tools-0.1.0/src/api_to_tools/adapters/__init__.py

@@ -0,0 +1,6 @@
+"""Output adapters."""
+
+from api_to_tools.adapters.mcp_adapter import create_mcp_server
+from api_to_tools.adapters.formats import to_function_calling, to_anthropic_tools
+
+__all__ = ["create_mcp_server", "to_function_calling", "to_anthropic_tools"]

api_to_tools-0.1.0/src/api_to_tools/adapters/formats.py

@@ -0,0 +1,54 @@
+"""Format converters for LLM tool calling."""
+
+from __future__ import annotations
+
+from api_to_tools.types import Tool
+
+
+def to_function_calling(tools: list[Tool]) -> list[dict]:
+    """Convert to OpenAI function calling format."""
+    return [
+        {
+            "type": "function",
+            "function": {
+                "name": tool.name,
+                "description": tool.description,
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        p.name: {
+                            "type": p.type,
+                            **({"description": p.description} if p.description else {}),
+                            **({"enum": p.enum} if p.enum else {}),
+                        }
+                        for p in tool.parameters
+                    },
+                    "required": [p.name for p in tool.parameters if p.required],
+                },
+            },
+        }
+        for tool in tools
+    ]
+
+
+def to_anthropic_tools(tools: list[Tool]) -> list[dict]:
+    """Convert to Anthropic tool_use format."""
+    return [
+        {
+            "name": tool.name,
+            "description": tool.description,
+            "input_schema": {
+                "type": "object",
+                "properties": {
+                    p.name: {
+                        "type": p.type,
+                        **({"description": p.description} if p.description else {}),
+                        **({"enum": p.enum} if p.enum else {}),
+                    }
+                    for p in tool.parameters
+                },
+                "required": [p.name for p in tool.parameters if p.required],
+            },
+        }
+        for tool in tools
+    ]

api_to_tools-0.1.0/src/api_to_tools/adapters/mcp_adapter.py

@@ -0,0 +1,44 @@
+"""MCP Server adapter."""
+
+from __future__ import annotations
+
+import json
+
+from mcp.server.fastmcp import FastMCP
+
+from api_to_tools.types import Tool
+from api_to_tools.executors import get_executor
+
+
+def create_mcp_server(tools: list[Tool], name: str = "api-to-tools") -> FastMCP:
+    """Create an MCP server from a list of tools."""
+    mcp = FastMCP(name)
+
+    for tool in tools:
+        # Capture tool in closure
+        _register_tool(mcp, tool)
+
+    return mcp
+
+
+def _register_tool(mcp: FastMCP, tool: Tool):
+    """Register a single tool on the MCP server."""
+
+    # Build parameter annotations for FastMCP
+    param_descriptions = {p.name: p.description or "" for p in tool.parameters}
+    description = tool.description
+    if param_descriptions:
+        param_lines = [f"  - {k}: {v}" for k, v in param_descriptions.items() if v]
+        if param_lines:
+            description += "\n\nParameters:\n" + "\n".join(param_lines)
+
+    @mcp.tool(name=tool.name, description=description)
+    def _handler(**kwargs) -> str:
+        try:
+            executor = get_executor(tool.protocol)
+            result = executor(tool, kwargs)
+            if isinstance(result.data, str):
+                return result.data
+            return json.dumps(result.data, ensure_ascii=False, indent=2, default=str)
+        except Exception as e:
+            return f"Error: {e}"

api_to_tools-0.1.0/src/api_to_tools/cli.py

@@ -0,0 +1,131 @@
+"""CLI entry point."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from api_to_tools.core import discover
+from api_to_tools.adapters.formats import to_function_calling, to_anthropic_tools
+from api_to_tools.utils import summarize, search_tools
+
+
+def cmd_serve(args):
+    from api_to_tools.adapters.mcp_adapter import create_mcp_server
+
+    print(f"Discovering API at {args.url}...", file=sys.stderr)
+    tools = discover(args.url)
+    print(f"Found {len(tools)} tools. Starting MCP server '{args.name}'...", file=sys.stderr)
+    for t in tools:
+        print(f"  - {t.name}", file=sys.stderr)
+
+    mcp = create_mcp_server(tools, name=args.name)
+    mcp.run(transport="stdio")
+
+
+def cmd_list(args):
+    tools = discover(args.url)
+
+    if args.tag:
+        tools = [t for t in tools if any(args.tag.lower() in tag.lower() for tag in t.tags)]
+    if args.method:
+        tools = [t for t in tools if t.method.upper() == args.method.upper()]
+    if args.search:
+        tools = search_tools(tools, args.search)
+
+    for t in tools:
+        params = ", ".join(f"{p.name}{'!' if p.required else '?'}:{p.type}" for p in t.parameters)
+        print(f"[{t.method:<8}] {t.name}")
+        if t.description:
+            print(f"           {t.description[:80]}")
+        if params:
+            print(f"           ({params})")
+
+    print(f"\nTotal: {len(tools)} tools", file=sys.stderr)
+
+
+def cmd_info(args):
+    print(f"Discovering API at {args.url}...", file=sys.stderr)
+    tools = discover(args.url)
+    summary = summarize(tools)
+
+    print(f"Total tools: {summary['total']}\n")
+
+    print("By Protocol:")
+    for k, v in summary["by_protocol"].items():
+        print(f"  {k}: {v}")
+
+    print("\nBy Method:")
+    for k, v in summary["by_method"].items():
+        print(f"  {k}: {v}")
+
+    print("\nBy Tag:")
+    tags = list(summary["by_tag"].items())
+    for k, v in tags[:20]:
+        print(f"  {k}: {v}")
+    if len(tags) > 20:
+        print(f"  ... and {len(tags) - 20} more tags")
+
+
+def cmd_export(args):
+    tools = discover(args.url)
+
+    if args.tag:
+        tools = [t for t in tools if any(args.tag.lower() in tag.lower() for tag in t.tags)]
+    if args.search:
+        tools = search_tools(tools, args.search)
+
+    if args.format == "openai":
+        output = to_function_calling(tools)
+    elif args.format == "anthropic":
+        output = to_anthropic_tools(tools)
+    else:
+        from dataclasses import asdict
+        output = [asdict(t) for t in tools]
+
+    print(json.dumps(output, indent=2, ensure_ascii=False))
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="api-to-tools",
+        description="Convert any API into LLM-callable tools",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    # serve
+    p_serve = sub.add_parser("serve", help="Start MCP server (stdio)")
+    p_serve.add_argument("url", help="API spec URL or website URL")
+    p_serve.add_argument("--name", default="api-to-tools", help="MCP server name")
+
+    # list
+    p_list = sub.add_parser("list", help="List discovered tools")
+    p_list.add_argument("url")
+    p_list.add_argument("--tag", help="Filter by tag")
+    p_list.add_argument("--method", help="Filter by HTTP method")
+    p_list.add_argument("--search", help="Search by name/description")
+
+    # info
+    p_info = sub.add_parser("info", help="Show API summary")
+    p_info.add_argument("url")
+
+    # export
+    p_export = sub.add_parser("export", help="Export tool definitions")
+    p_export.add_argument("url")
+    p_export.add_argument("--format", choices=["openai", "anthropic", "json"], default="json")
+    p_export.add_argument("--tag", help="Filter by tag")
+    p_export.add_argument("--search", help="Search filter")
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    cmd_map = {"serve": cmd_serve, "list": cmd_list, "info": cmd_info, "export": cmd_export}
+    cmd_map[args.command](args)
+
+
+if __name__ == "__main__":
+    main()

api_to_tools-0.1.0/src/api_to_tools/core.py

@@ -0,0 +1,65 @@
+"""Core functions."""
+
+from __future__ import annotations
+
+from api_to_tools.types import Tool, DetectionResult, ExecutionResult
+from api_to_tools.detector import detect
+from api_to_tools.parsers import get_parser
+from api_to_tools.executors import get_executor
+
+
+def discover(url: str, **kwargs) -> list[Tool]:
+    """Discover and parse API spec from a URL into tools.
+
+    >>> tools = discover("https://date.nager.at/openapi/v3.json")
+    >>> tools = discover("https://petstore.swagger.io")  # auto-detects
+    """
+    # Separate detect options from filter options
+    detect_kwargs = {k: kwargs[k] for k in ("timeout", "probe_paths") if k in kwargs}
+    detection = detect(url, **detect_kwargs)
+    return to_tools(detection, **kwargs)
+
+
+def to_tools(detection: DetectionResult, **kwargs) -> list[Tool]:
+    """Parse a detected spec into tools."""
+    parser = get_parser(detection.type)
+    # WSDL/GraphQL need the URL, not raw content (libraries fetch themselves)
+    if detection.type in ("wsdl", "graphql"):
+        input_data = detection.spec_url
+    else:
+        input_data = detection.raw_content or detection.spec_url
+    tools = parser(input_data, source_url=detection.spec_url)
+
+    # Apply base URL override
+    base_url = kwargs.get("base_url")
+    if base_url:
+        import re
+        for t in tools:
+            t.endpoint = re.sub(r"^https?://[^/]+", base_url, t.endpoint)
+
+    # Filters
+    tags = kwargs.get("tags")
+    if tags:
+        tools = [t for t in tools if any(tag in t.tags for tag in tags)]
+
+    methods = kwargs.get("methods")
+    if methods:
+        upper = [m.upper() for m in methods]
+        tools = [t for t in tools if t.method.upper() in upper]
+
+    path_filter = kwargs.get("path_filter")
+    if path_filter:
+        import re
+        tools = [t for t in tools if re.search(path_filter, t.endpoint)]
+
+    return tools
+
+
+def execute(tool: Tool, args: dict) -> ExecutionResult:
+    """Execute a tool with given arguments.
+
+    >>> tools = discover("https://date.nager.at/openapi/v3.json")
+    >>> result = execute(tools[0], {"countryCode": "KR"})
+    """
+    executor = get_executor(tool.protocol)
+    return executor(tool, args)

api_to_tools-0.1.0/src/api_to_tools/detector/__init__.py

@@ -0,0 +1,181 @@
+"""Auto-detect API spec type from a URL."""
+
+from __future__ import annotations
+
+import re
+from urllib.parse import urljoin, urlparse
+
+import httpx
+
+from api_to_tools.types import DetectionResult, SpecType
+
+WELL_KNOWN_PATHS: dict[SpecType, list[str]] = {
+    "openapi": [
+        "/openapi.json", "/openapi.yaml", "/openapi/v3.json",
+        "/swagger.json", "/swagger.yaml",
+        "/api-docs", "/v2/api-docs", "/v3/api-docs",
+        "/.well-known/openapi",
+        "/docs/openapi.json", "/docs/swagger.json",
+        "/swagger/v1/swagger.json", "/swagger/v2/swagger.json",
+        "/api/swagger.json", "/api/openapi.json",
+        "/spec.json", "/api/spec.json",
+        "/api-docs.json", "/api/api-docs",
+    ],
+    "wsdl": ["?wsdl", "?WSDL", "/ws?wsdl", "/services?wsdl"],
+    "graphql": ["/graphql", "/.well-known/graphql"],
+    "grpc": [],
+    "asyncapi": ["/asyncapi.json", "/asyncapi.yaml"],
+    "jsonrpc": ["/rpc", "/jsonrpc"],
+}
+
+GRAPHQL_PROBE_QUERY = '{"query":"{ __schema { types { name } } }"}'
+
+
+def _detect_from_content(content: str, content_type: str = "") -> SpecType | None:
+    """Detect spec type from response content."""
+    # JSON
+    if "json" in content_type or content.lstrip().startswith("{"):
+        try:
+            import json
+            data = json.loads(content)
+            if "openapi" in data or "swagger" in data:
+                return "openapi"
+            if "asyncapi" in data:
+                return "asyncapi"
+            if isinstance(data.get("data"), dict) and "__schema" in data["data"]:
+                return "graphql"
+        except (json.JSONDecodeError, TypeError):
+            pass
+
+    # XML
+    if "xml" in content_type or content.lstrip().startswith("<"):
+        if "<definitions" in content or "<wsdl:definitions" in content:
+            return "wsdl"
+
+    # YAML
+    if "openapi:" in content or "swagger:" in content:
+        return "openapi"
+    if "asyncapi:" in content:
+        return "asyncapi"
+
+    return None
+
+
+def _extract_spec_url_from_html(html: str, base_url: str, client: httpx.Client, timeout: float) -> str | None:
+    """Extract spec URL from Swagger UI / Redoc HTML."""
+    # Swagger UI: url: "..."
+    m = re.search(r'url:\s*["\']([^"\']+)["\']', html)
+    if m:
+        return urljoin(base_url, m.group(1))
+
+    # Redoc: spec-url="..."
+    m = re.search(r'spec-url=["\']([^"\']+)["\']', html)
+    if m:
+        return urljoin(base_url, m.group(1))
+
+    # Link tag
+    m = re.search(r'<link[^>]+rel=["\']api-definition["\'][^>]+href=["\']([^"\']+)["\']', html)
+    if m:
+        return urljoin(base_url, m.group(1))
+
+    # Swagger UI initializer JS
+    for script_match in re.finditer(r'<script[^>]+src=["\']([^"\']*(?:initializer|config)[^"\']*)["\']', html, re.I):
+        try:
+            js_url = urljoin(base_url, script_match.group(1))
+            js_res = client.get(js_url, timeout=timeout)
+            if js_res.is_success:
+                js = js_res.text
+                # url: "https://..." pattern
+                url_m = re.search(r'url:\s*["\'](https?://[^"\']+|/[^"\'/][^"\']*)["\']', js)
+                if url_m:
+                    return urljoin(base_url, url_m.group(1))
+                # Variable assignment pattern
+                var_m = re.search(
+                    r'(?:const|let|var)\s+\w*(?:url|definition|spec|swagger|openapi)\w*\s*=\s*["\'](https?://[^"\']+\.json[^"\']*)["\']',
+                    js, re.I,
+                )
+                if var_m:
+                    return urljoin(base_url, var_m.group(1))
+        except httpx.HTTPError:
+            continue
+
+    return None
+
+
+def _probe(url: str, client: httpx.Client, timeout: float) -> DetectionResult | None:
+    """Probe a URL for an API spec."""
+    try:
+        res = client.get(url, timeout=timeout, follow_redirects=True,
+                         headers={"Accept": "application/json, application/xml, text/yaml, */*"})
+        if not res.is_success:
+            return None
+
+        ct = res.headers.get("content-type", "")
+        content = res.text
+        spec_type = _detect_from_content(content, ct)
+
+        if spec_type:
+            return DetectionResult(type=spec_type, spec_url=url, raw_content=content, content_type=ct)
+
+        # HTML -> extract spec URL
+        if "html" in ct:
+            spec_url = _extract_spec_url_from_html(content, url, client, timeout)
+            if spec_url:
+                return _probe(spec_url, client, timeout)
+
+        return None
+    except (httpx.HTTPError, httpx.InvalidURL):
+        return None
+
+
+def _probe_graphql(base_url: str, client: httpx.Client, timeout: float) -> DetectionResult | None:
+    """Try GraphQL introspection."""
+    urls = [base_url] + [urljoin(base_url + "/", p.lstrip("/")) for p in WELL_KNOWN_PATHS["graphql"]]
+    seen = set()
+    for url in urls:
+        if url in seen:
+            continue
+        seen.add(url)
+        try:
+            res = client.post(url, content=GRAPHQL_PROBE_QUERY,
+                              headers={"Content-Type": "application/json"}, timeout=timeout)
+            if res.is_success and "__schema" in res.text:
+                return DetectionResult(type="graphql", spec_url=url)
+        except (httpx.HTTPError, httpx.InvalidURL):
+            continue
+    return None
+
+
+def detect(url: str, *, timeout: float = 10.0, probe_paths: bool = True) -> DetectionResult:
+    """Discover API spec from a URL.
+
+    Tries direct detection, then probes well-known paths.
+    """
+    with httpx.Client() as client:
+        # GraphQL endpoint heuristic
+        if "graphql" in url or url.endswith("/gql"):
+            result = _probe_graphql(url.rstrip("/"), client, timeout)
+            if result:
+                return result
+
+        # Direct probe
+        result = _probe(url, client, timeout)
+        if result:
+            return result
+
+        # Well-known paths
+        if probe_paths:
+            base = url.rstrip("/")
+            for paths in WELL_KNOWN_PATHS.values():
+                for path in paths:
+                    probe_url = f"{base}{path}" if path.startswith("?") else urljoin(base + "/", path.lstrip("/"))
+                    result = _probe(probe_url, client, timeout)
+                    if result:
+                        return result
+
+            # GraphQL (POST-based)
+            result = _probe_graphql(base, client, timeout)
+            if result:
+                return result
+
+    raise ValueError(f"Could not detect API spec at {url}. Try providing the direct spec URL.")

api_to_tools-0.1.0/src/api_to_tools/executors/__init__.py

@@ -0,0 +1,21 @@
+"""API executors."""
+
+from __future__ import annotations
+
+from api_to_tools.types import Protocol
+from api_to_tools.executors.rest import execute_rest
+from api_to_tools.executors.soap import execute_soap
+from api_to_tools.executors.graphql import execute_graphql
+
+EXECUTORS = {
+    "rest": execute_rest,
+    "soap": execute_soap,
+    "graphql": execute_graphql,
+}
+
+
+def get_executor(protocol: Protocol):
+    executor = EXECUTORS.get(protocol)
+    if not executor:
+        raise NotImplementedError(f"Executor for '{protocol}' is not yet implemented")
+    return executor