hidden-moves-mcp 0.1.0__tar.gz

hidden_moves_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ella Inng
+
+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.

hidden_moves_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: hidden-moves-mcp
+Version: 0.1.0
+Summary: Expose selected Python capabilities through the Model Context Protocol.
+Keywords: mcp,tools,capabilities,python
+Author: Ella Inng
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: hidden-moves>=0.1,<0.2
+Requires-Dist: mcp>=2.3.0,<3
+Maintainer: Outside Labs
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/outside-labs/hidden_moves
+Project-URL: Source, https://github.com/outside-labs/hidden_moves
+Project-URL: Issues, https://github.com/outside-labs/hidden_moves/issues
+Project-URL: Documentation, https://github.com/outside-labs/hidden_moves/blob/main/packages/hidden-moves-mcp/README.md
+Description-Content-Type: text/markdown
+
+# Hidden Moves MCP adapter
+
+An optional adapter around explicitly selected capability catalogs. The MCP SDK
+dependency belongs to this distribution; the core registry remains independent.
+
+```sh
+python -m pip install hidden-moves-mcp==0.1.0
+hidden-moves-mcp --help
+```
+
+The experimental 0.1.x adapter depends on `hidden-moves>=0.1,<0.2` and Python
+3.11 or newer. Published GitHub releases use `v0.1.0-mcp` for this package in the
+shared repository. `.github/workflows/release.yaml` builds only its distribution,
+checks installed-wheel transports, and publishes in environment `pypi-mcp`.
+
+## Local installation
+
+From the repository root:
+
+```sh
+uv venv /tmp/hidden-moves-mcp-env
+uv pip install --python /tmp/hidden-moves-mcp-env/bin/python \
+  . ./examples/text-plugin ./packages/hidden-moves-mcp
+/tmp/hidden-moves-mcp-env/bin/python -m unittest discover \
+  -s packages/hidden-moves-mcp/tests -v
+```
+
+The adapter uses the official Python SDK, `mcp>=2.3.0,<3`. The local proof was
+verified with SDK 2.3.0 and protocol `2026-07-28`; legacy clients can negotiate
+the SDK's supported `2025-11-25` handshake. See the official
+[protocol-version documentation](https://py.sdk.modelcontextprotocol.io/protocol-versions/).
+
+## Configure a local stdio host
+
+A host starts the installed executable and owns the subprocess:
+
+```json
+{
+  "command": "/tmp/hidden-moves-mcp-env/bin/hidden-moves-mcp",
+  "args": [
+    "--plugin", "example-text",
+    "--move", "example.text.repeat"
+  ]
+}
+```
+
+The `--move` option is required and repeatable. Only those names are listed and
+callable. Providers must be explicitly enabled with `--plugin`; installing one
+does not activate it. The executable begins with an empty registry and supplies
+no target binding. Configure a Python host for target-bound providers. It waits for protocol input on
+stdin and exits when its host closes the connection. Output on stdout is the
+protocol stream; application logging belongs on stderr.
+
+This is an executable local proof, without a public service or configured account.
+The temporary environment is suitable for testing; install into a durable location
+before configuring a host for regular use.
+
+## Python setup and binding
+
+```python
+import asyncio
+
+from hidden_moves import Moves
+from hidden_moves.adapters import CapabilityCatalog
+from hidden_moves_example_text import repeat_text
+from hidden_moves_mcp import MCPAdapter, serve_stdio
+
+moves = Moves()
+moves.learn(repeat_text, name="repeat", namespace="example.text")
+catalog = CapabilityCatalog(moves, ["example.text.repeat"])
+server = MCPAdapter(catalog).server()
+
+if __name__ == "__main__":
+    asyncio.run(serve_stdio(server))
+```
+
+Applications can configure clients or targets before building the catalog. The
+adapter consumes those bound callables and does not infer credentials or context.
+The stdio adapter defaults to invoking synchronous functions in the request
+handler and awaiting awaitable results there. `MCPAdapter` also accepts explicit
+`offload_sync=True` and a finite `call_timeout` for hosts that need them. Client
+resource setup and shutdown belong to the application.
+
+## Local Streamable HTTP
+
+```python
+from hidden_moves_mcp import create_http_app, serve_http
+
+async def authorize(request):
+    # Check the application's local request grant without consuming the body.
+    return await local_access_policy(request.headers)
+
+app = create_http_app(catalog, authorize=authorize)
+asyncio.run(serve_http(app, port=8000))
+```
+
+The application supplies an async authorizer that returns exactly `True` for each
+allowed request. Missing grants, rejected grants and authorizer exceptions return
+401 before protocol dispatch. It chooses credentials, request identity and the
+selected catalog; no installed provider or account is activated implicitly.
+
+`serve_http` binds only `127.0.0.1`. The
+[SDK's ASGI app](https://py.sdk.modelcontextprotocol.io/run/asgi/) handles
+Streamable HTTP, initialization, protocol negotiation and lifespan cleanup at
+`/mcp`, with its default localhost Host/Origin protection. Responses are JSON and
+HTTP is stateless. The same adapter supplies schemas, annotations and
+`structuredContent: {"result": value}` over HTTP and stdio. Unselected names remain
+protocol errors. Mounting the returned app inside another application requires
+the host to run its lifespan, as described in the SDK guide.
+
+Defaults are a 10-second call deadline, 30-second request deadline, 16 concurrent
+requests and a 1 MiB request body. Limits must be finite; excess concurrency returns
+503, an expired request returns 504, and the SDK rejects oversized bodies with 413.
+Timed-out tools return sanitized tool errors. Access logging is disabled by the
+local serving helper, and forwarded identity headers are not trusted.
+
+HTTP offloads synchronous capabilities by default so blocking I/O does not stop
+other requests. Async capabilities execute on the event loop. Configure the
+underlying clients with their own finite I/O timeouts: cancellation cannot stop a
+running Python worker thread, and a timed-out write may still complete. Inspect
+its outcome before submitting another write. Thread-affine resources need an
+application-owned execution strategy; `offload_sync=False` is available for fast
+event-loop-safe callables, whose deadlines depend on cooperative yielding. The
+host owns resource cleanup and concurrency safety.
+
+`examples/mcp_http.py` serves only `example.text.repeat` using an explicitly
+configured `HIDDEN_MOVES_LOCAL_HTTP_TOKEN` of 32–512 printable ASCII characters.
+It demonstrates a local request grant; hosted OAuth, delegated GitHub credentials
+and per-user catalog isolation require their separate authentication work.
+
+Installed-wheel tests run real loopback initialize/list/call clients in modern
+and legacy modes, compare Python/HTTP DTOs, check authorization and request limits,
+exercise cancellation and worker offloading, then shut down the SDK lifespan and
+listener. The existing real stdio subprocess checks still run in the same suite.
+
+## Export contract
+
+MCP names retain qualified capability names when they satisfy the protocol's ASCII
+name rules. Explicit `tool_names={qualified_name: alias}` mappings handle other
+names; invalid or colliding aliases fail before server creation. Exported schemas
+are independent copies of neutral definitions.
+
+All successful results use `structuredContent: {"result": value}` with the matching
+object output schema and an equivalent JSON text block. This includes object,
+scalar, list, and null results. The catalog validates and serializes the underlying
+value before wrapping it. Ordinary Python results remain unchanged outside this
+adapter.
+
+Behavioral hints map explicitly to MCP annotations, with unknown hints omitted.
+They do not authorize calls. The host/application chooses exposure and approval
+policy. Invalid arguments and invalid results are tool errors. Capability failures
+are tool errors reporting the exception type, without exposing arbitrary exception
+contents. Unknown/unexposed tool names are protocol errors. Cancellation propagates.
+
+The [low-level SDK server](https://py.sdk.modelcontextprotocol.io/advanced/low-level-server/)
+handles protocol discovery, legacy negotiation, wire types, and connection lifetime;
+the adapter owns its list/call handlers and uses the catalog for validation.

hidden_moves_mcp-0.1.0/README.md

@@ -0,0 +1,157 @@
+# Hidden Moves MCP adapter
+
+An optional adapter around explicitly selected capability catalogs. The MCP SDK
+dependency belongs to this distribution; the core registry remains independent.
+
+```sh
+python -m pip install hidden-moves-mcp==0.1.0
+hidden-moves-mcp --help
+```
+
+The experimental 0.1.x adapter depends on `hidden-moves>=0.1,<0.2` and Python
+3.11 or newer. Published GitHub releases use `v0.1.0-mcp` for this package in the
+shared repository. `.github/workflows/release.yaml` builds only its distribution,
+checks installed-wheel transports, and publishes in environment `pypi-mcp`.
+
+## Local installation
+
+From the repository root:
+
+```sh
+uv venv /tmp/hidden-moves-mcp-env
+uv pip install --python /tmp/hidden-moves-mcp-env/bin/python \
+  . ./examples/text-plugin ./packages/hidden-moves-mcp
+/tmp/hidden-moves-mcp-env/bin/python -m unittest discover \
+  -s packages/hidden-moves-mcp/tests -v
+```
+
+The adapter uses the official Python SDK, `mcp>=2.3.0,<3`. The local proof was
+verified with SDK 2.3.0 and protocol `2026-07-28`; legacy clients can negotiate
+the SDK's supported `2025-11-25` handshake. See the official
+[protocol-version documentation](https://py.sdk.modelcontextprotocol.io/protocol-versions/).
+
+## Configure a local stdio host
+
+A host starts the installed executable and owns the subprocess:
+
+```json
+{
+  "command": "/tmp/hidden-moves-mcp-env/bin/hidden-moves-mcp",
+  "args": [
+    "--plugin", "example-text",
+    "--move", "example.text.repeat"
+  ]
+}
+```
+
+The `--move` option is required and repeatable. Only those names are listed and
+callable. Providers must be explicitly enabled with `--plugin`; installing one
+does not activate it. The executable begins with an empty registry and supplies
+no target binding. Configure a Python host for target-bound providers. It waits for protocol input on
+stdin and exits when its host closes the connection. Output on stdout is the
+protocol stream; application logging belongs on stderr.
+
+This is an executable local proof, without a public service or configured account.
+The temporary environment is suitable for testing; install into a durable location
+before configuring a host for regular use.
+
+## Python setup and binding
+
+```python
+import asyncio
+
+from hidden_moves import Moves
+from hidden_moves.adapters import CapabilityCatalog
+from hidden_moves_example_text import repeat_text
+from hidden_moves_mcp import MCPAdapter, serve_stdio
+
+moves = Moves()
+moves.learn(repeat_text, name="repeat", namespace="example.text")
+catalog = CapabilityCatalog(moves, ["example.text.repeat"])
+server = MCPAdapter(catalog).server()
+
+if __name__ == "__main__":
+    asyncio.run(serve_stdio(server))
+```
+
+Applications can configure clients or targets before building the catalog. The
+adapter consumes those bound callables and does not infer credentials or context.
+The stdio adapter defaults to invoking synchronous functions in the request
+handler and awaiting awaitable results there. `MCPAdapter` also accepts explicit
+`offload_sync=True` and a finite `call_timeout` for hosts that need them. Client
+resource setup and shutdown belong to the application.
+
+## Local Streamable HTTP
+
+```python
+from hidden_moves_mcp import create_http_app, serve_http
+
+async def authorize(request):
+    # Check the application's local request grant without consuming the body.
+    return await local_access_policy(request.headers)
+
+app = create_http_app(catalog, authorize=authorize)
+asyncio.run(serve_http(app, port=8000))
+```
+
+The application supplies an async authorizer that returns exactly `True` for each
+allowed request. Missing grants, rejected grants and authorizer exceptions return
+401 before protocol dispatch. It chooses credentials, request identity and the
+selected catalog; no installed provider or account is activated implicitly.
+
+`serve_http` binds only `127.0.0.1`. The
+[SDK's ASGI app](https://py.sdk.modelcontextprotocol.io/run/asgi/) handles
+Streamable HTTP, initialization, protocol negotiation and lifespan cleanup at
+`/mcp`, with its default localhost Host/Origin protection. Responses are JSON and
+HTTP is stateless. The same adapter supplies schemas, annotations and
+`structuredContent: {"result": value}` over HTTP and stdio. Unselected names remain
+protocol errors. Mounting the returned app inside another application requires
+the host to run its lifespan, as described in the SDK guide.
+
+Defaults are a 10-second call deadline, 30-second request deadline, 16 concurrent
+requests and a 1 MiB request body. Limits must be finite; excess concurrency returns
+503, an expired request returns 504, and the SDK rejects oversized bodies with 413.
+Timed-out tools return sanitized tool errors. Access logging is disabled by the
+local serving helper, and forwarded identity headers are not trusted.
+
+HTTP offloads synchronous capabilities by default so blocking I/O does not stop
+other requests. Async capabilities execute on the event loop. Configure the
+underlying clients with their own finite I/O timeouts: cancellation cannot stop a
+running Python worker thread, and a timed-out write may still complete. Inspect
+its outcome before submitting another write. Thread-affine resources need an
+application-owned execution strategy; `offload_sync=False` is available for fast
+event-loop-safe callables, whose deadlines depend on cooperative yielding. The
+host owns resource cleanup and concurrency safety.
+
+`examples/mcp_http.py` serves only `example.text.repeat` using an explicitly
+configured `HIDDEN_MOVES_LOCAL_HTTP_TOKEN` of 32–512 printable ASCII characters.
+It demonstrates a local request grant; hosted OAuth, delegated GitHub credentials
+and per-user catalog isolation require their separate authentication work.
+
+Installed-wheel tests run real loopback initialize/list/call clients in modern
+and legacy modes, compare Python/HTTP DTOs, check authorization and request limits,
+exercise cancellation and worker offloading, then shut down the SDK lifespan and
+listener. The existing real stdio subprocess checks still run in the same suite.
+
+## Export contract
+
+MCP names retain qualified capability names when they satisfy the protocol's ASCII
+name rules. Explicit `tool_names={qualified_name: alias}` mappings handle other
+names; invalid or colliding aliases fail before server creation. Exported schemas
+are independent copies of neutral definitions.
+
+All successful results use `structuredContent: {"result": value}` with the matching
+object output schema and an equivalent JSON text block. This includes object,
+scalar, list, and null results. The catalog validates and serializes the underlying
+value before wrapping it. Ordinary Python results remain unchanged outside this
+adapter.
+
+Behavioral hints map explicitly to MCP annotations, with unknown hints omitted.
+They do not authorize calls. The host/application chooses exposure and approval
+policy. Invalid arguments and invalid results are tool errors. Capability failures
+are tool errors reporting the exception type, without exposing arbitrary exception
+contents. Unknown/unexposed tool names are protocol errors. Cancellation propagates.
+
+The [low-level SDK server](https://py.sdk.modelcontextprotocol.io/advanced/low-level-server/)
+handles protocol discovery, legacy negotiation, wire types, and connection lifetime;
+the adapter owns its list/call handlers and uses the catalog for validation.

hidden_moves_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "hidden-moves-mcp"
+version = "0.1.0"
+description = "Expose selected Python capabilities through the Model Context Protocol."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "mcp",
+    "tools",
+    "capabilities",
+    "python",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "hidden-moves>=0.1,<0.2",
+    "mcp>=2.3.0,<3",
+]
+
+[[project.authors]]
+name = "Ella Inng"
+
+[[project.maintainers]]
+name = "Outside Labs"
+
+[project.scripts]
+hidden-moves-mcp = "hidden_moves_mcp.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/outside-labs/hidden_moves"
+Source = "https://github.com/outside-labs/hidden_moves"
+Issues = "https://github.com/outside-labs/hidden_moves/issues"
+Documentation = "https://github.com/outside-labs/hidden_moves/blob/main/packages/hidden-moves-mcp/README.md"
+
+[build-system]
+requires = ["uv_build>=0.12.1,<0.13.0"]
+build-backend = "uv_build"

hidden_moves_mcp-0.1.0/pyproject.toml.orig

@@ -0,0 +1,36 @@
+[project]
+name = "hidden-moves-mcp"
+version = "0.1.0"
+description = "Expose selected Python capabilities through the Model Context Protocol."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Ella Inng" }]
+maintainers = [{ name = "Outside Labs" }]
+keywords = ["mcp", "tools", "capabilities", "python"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "hidden-moves>=0.1,<0.2",
+    "mcp>=2.3.0,<3",
+]
+
+[project.scripts]
+hidden-moves-mcp = "hidden_moves_mcp.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/outside-labs/hidden_moves"
+Source = "https://github.com/outside-labs/hidden_moves"
+Issues = "https://github.com/outside-labs/hidden_moves/issues"
+Documentation = "https://github.com/outside-labs/hidden_moves/blob/main/packages/hidden-moves-mcp/README.md"
+
+[build-system]
+requires = ["uv_build>=0.12.1,<0.13.0"]
+build-backend = "uv_build"

hidden_moves_mcp-0.1.0/src/hidden_moves_mcp/__init__.py

@@ -0,0 +1,6 @@
+"""An optional MCP consumer of the neutral capability catalog."""
+
+from .http import create_http_app, serve_http
+from .server import MCPAdapter, serve_stdio
+
+__all__ = ["MCPAdapter", "create_http_app", "serve_http", "serve_stdio"]

hidden_moves_mcp-0.1.0/src/hidden_moves_mcp/__main__.py

@@ -0,0 +1,6 @@
+"""Support python -m hidden_moves_mcp without starting a server on import."""
+
+from .cli import main
+
+if __name__ == "__main__":
+	main()

hidden_moves_mcp-0.1.0/src/hidden_moves_mcp/cli.py

@@ -0,0 +1,31 @@
+"""Explicit provider activation and capability selection for a local stdio host."""
+
+import argparse
+import asyncio
+
+from hidden_moves import MoveError, Moves, Registry, discover_providers, load_provider
+from hidden_moves.adapters import CapabilityCatalog
+
+from .server import MCPAdapter, serve_stdio
+
+
+def main() -> None:
+	parser = argparse.ArgumentParser(description="Serve explicitly selected Hidden Moves capabilities over MCP stdio.")
+	parser.add_argument("--move", dest="moves", action="append", required=True, help="Qualified capability to expose; repeat for multiple names.")
+	parser.add_argument("--plugin", action="append", default=[], help="Installed provider to explicitly activate.")
+	parser.add_argument("--name", default="hidden-moves", help="Server identity.")
+	arguments = parser.parse_args()
+	registry = Registry()
+	try:
+		if arguments.plugin:
+			entries = discover_providers()
+			for name in arguments.plugin:
+				matches = [entry for entry in entries if entry.name == name]
+				if len(matches) != 1:
+					parser.error(f"Provider {name!r} must be installed and unambiguous.")
+				load_provider(matches[0], registry)
+		catalog = CapabilityCatalog(Moves(registry=registry), arguments.moves)
+		server = MCPAdapter(catalog).server(arguments.name)
+	except (MoveError, ValueError) as error:
+		parser.error(str(error))
+	asyncio.run(serve_stdio(server))

hidden_moves_mcp-0.1.0/src/hidden_moves_mcp/http.py

@@ -0,0 +1,166 @@
+"""A bounded local HTTP host; the SDK owns all MCP protocol handling."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Mapping
+from math import isfinite
+
+import anyio
+import uvicorn
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+from hidden_moves.adapters import CapabilityCatalog
+
+from .server import MCPAdapter
+
+RequestAuthorizer = Callable[[Request], Awaitable[bool]]
+
+
+class _RequestGuard:
+    def __init__(
+        self,
+        app: ASGIApp,
+        *,
+        authorize: RequestAuthorizer,
+        timeout: float,
+        concurrency: int,
+    ) -> None:
+        self.app = app
+        self.authorize = authorize
+        self.timeout = timeout
+        self.capacity = anyio.CapacityLimiter(concurrency)
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+        try:
+            self.capacity.acquire_nowait()
+        except anyio.WouldBlock:
+            await JSONResponse({"error": "request capacity exceeded"}, status_code=503)(
+                scope, receive, send
+            )
+            return
+        started = False
+        completed = False
+
+        async def tracked_send(message: Message) -> None:
+            nonlocal started, completed
+            if message["type"] == "http.response.start":
+                started = True
+            elif message["type"] == "http.response.body":
+                completed = not message.get("more_body", False)
+            await send(message)
+
+        try:
+            with anyio.fail_after(self.timeout):
+                try:
+                    permitted = await self.authorize(Request(scope, receive))
+                except Exception:
+                    # Upstream identity failures may contain credentials.
+                    permitted = False
+                if permitted is not True:
+                    await JSONResponse(
+                        {"error": "request authorization required"}, status_code=401
+                    )(scope, receive, tracked_send)
+                    return
+                await self.app(scope, receive, tracked_send)
+        except TimeoutError:
+            if not started:
+                await JSONResponse(
+                    {"error": "request deadline exceeded"}, status_code=504
+                )(scope, receive, send)
+            elif not completed:
+                await send(
+                    {"type": "http.response.body", "body": b"", "more_body": False}
+                )
+        finally:
+            self.capacity.release()
+
+
+def create_http_app(
+    catalog: CapabilityCatalog,
+    *,
+    authorize: RequestAuthorizer,
+    name: str = "hidden-moves",
+    version: str = "0.1.0",
+    tool_names: Mapping[str, str] | None = None,
+    call_timeout: float = 10,
+    request_timeout: float = 30,
+    max_concurrency: int = 16,
+    max_request_body_size: int = 1024 * 1024,
+    offload_sync: bool = True,
+) -> Starlette:
+    """Create a stateless, JSON-response app for explicitly authorized local use.
+
+    The async authorizer must return exactly True for each allowed request. Its
+    identity/credential policy and capability resource lifetimes belong to the
+    application. Construction opens no listener and resolves no credentials.
+    """
+    if not callable(authorize):
+        raise ValueError("An explicit asynchronous request authorizer is required.")
+    if (
+        isinstance(request_timeout, bool)
+        or not isinstance(request_timeout, (int, float))
+        or not isfinite(request_timeout)
+        or not 0 < request_timeout <= 120
+    ):
+        raise ValueError(
+            "request_timeout must be finite and between 0 and 120 seconds."
+        )
+    if (
+        isinstance(max_concurrency, bool)
+        or not isinstance(max_concurrency, int)
+        or not 1 <= max_concurrency <= 64
+    ):
+        raise ValueError("max_concurrency must be between 1 and 64.")
+    if (
+        isinstance(max_request_body_size, bool)
+        or not isinstance(max_request_body_size, int)
+        or not 1 <= max_request_body_size <= 4 * 1024 * 1024
+    ):
+        raise ValueError("max_request_body_size must be between 1 byte and 4 MiB.")
+    adapter = MCPAdapter(
+        catalog,
+        tool_names=tool_names,
+        offload_sync=offload_sync,
+        call_timeout=call_timeout,
+    )
+    if call_timeout is None or call_timeout > request_timeout:
+        raise ValueError("call_timeout must not exceed request_timeout.")
+    app = adapter.server(name, version=version).streamable_http_app(
+        host="127.0.0.1",
+        stateless_http=True,
+        json_response=True,
+        max_request_body_size=max_request_body_size,
+        session_idle_timeout=request_timeout,
+        max_sessions=max_concurrency,
+    )
+    app.add_middleware(
+        _RequestGuard,
+        authorize=authorize,
+        timeout=request_timeout,
+        concurrency=max_concurrency,
+    )
+    return app
+
+
+async def serve_http(app: Starlette, *, port: int = 8000) -> None:
+    """Serve the local app on IPv4 loopback until shutdown, including its lifespan."""
+    if isinstance(port, bool) or not isinstance(port, int) or not 1 <= port <= 65535:
+        raise ValueError("port must be between 1 and 65535.")
+    config = uvicorn.Config(
+        app,
+        host="127.0.0.1",
+        port=port,
+        access_log=False,
+        log_level="warning",
+        proxy_headers=False,
+        lifespan="on",
+        timeout_keep_alive=5,
+        timeout_graceful_shutdown=5,
+    )
+    await uvicorn.Server(config).serve()

hidden_moves_mcp-0.1.0/src/hidden_moves_mcp/server.py

@@ -0,0 +1,150 @@
+"""MCP tools consume the neutral catalog without changing its definitions."""
+
+from __future__ import annotations
+
+import inspect
+import json
+import re
+from collections.abc import Mapping
+from contextlib import nullcontext
+from math import isfinite
+
+import anyio
+from mcp import MCPError
+from mcp.server import Server, ServerRequestContext
+from mcp.server.stdio import stdio_server
+from mcp.types import (
+	INVALID_PARAMS,
+	CallToolRequestParams,
+	CallToolResult,
+	ListToolsResult,
+	PaginatedRequestParams,
+	TextContent,
+	Tool,
+	ToolAnnotations,
+)
+
+from hidden_moves.adapters import (
+	CapabilityArgumentError,
+	CapabilityCatalog,
+	CapabilityResultError,
+)
+
+_TOOL_NAME = re.compile(r"[A-Za-z0-9_.-]{1,128}\Z")
+_HINT_NAMES = {
+	"read_only": "read_only_hint",
+	"destructive": "destructive_hint",
+	"idempotent": "idempotent_hint",
+	"external": "open_world_hint",
+}
+
+
+class MCPAdapter:
+	"""Export and dispatch exactly the catalog's selected capabilities."""
+
+	def __init__(
+		self,
+		catalog: CapabilityCatalog,
+		*,
+		tool_names: Mapping[str, str] | None = None,
+		offload_sync: bool = False,
+		call_timeout: float | None = None,
+	) -> None:
+		if not isinstance(offload_sync, bool):
+			raise ValueError("offload_sync must be a boolean.")
+		if call_timeout is not None and (
+			isinstance(call_timeout, bool) or not isinstance(call_timeout, (int, float))
+			or not isfinite(call_timeout) or not 0 < call_timeout <= 120
+		):
+			raise ValueError("call_timeout must be finite and between 0 and 120 seconds.")
+		self._offload_sync = offload_sync
+		self._call_timeout = call_timeout
+		self.catalog = catalog
+		aliases = dict(tool_names or {})
+		selected = {definition.name for definition in catalog.definitions()}
+		if set(aliases) - selected:
+			raise ValueError("Tool aliases must reference selected capabilities.")
+		self._names = {}
+		for definition in catalog.definitions():
+			name = aliases.get(definition.name, definition.name)
+			if not isinstance(name, str) or not _TOOL_NAME.fullmatch(name):
+				raise ValueError("MCP tool names require 1-128 ASCII letters, digits, underscores, hyphens, or dots; supply an alias.")
+			if name in self._names:
+				raise ValueError(f"MCP tool name collision: {name!r}.")
+			self._names[name] = definition.name
+
+	def tools(self) -> list[Tool]:
+		tools = []
+		for name, qualified_name in self._names.items():
+			definition = self.catalog.describe(qualified_name)
+			data = definition.to_dict()
+			hints = {
+				_HINT_NAMES[key]: value for key, value in definition.annotations.to_dict().items()
+				if value is not None
+			}
+			tools.append(Tool(
+				name=name,
+				description=definition.description,
+				input_schema=data["input_schema"],
+				output_schema={
+					"type": "object",
+					"properties": {"result": data["output_schema"] or {}},
+					"required": ["result"],
+					"additionalProperties": False,
+				},
+				annotations=ToolAnnotations(**hints) if hints else None,
+			))
+		return tools
+
+	async def _list_tools(
+		self,
+		_context: ServerRequestContext,
+		params: PaginatedRequestParams | None,
+	) -> ListToolsResult:
+		if params is not None and params.cursor:
+			raise MCPError(code=INVALID_PARAMS, message="This catalog has no pagination cursors.")
+		return ListToolsResult(tools=self.tools())
+
+	async def _call_tool(
+		self,
+		_context: ServerRequestContext,
+		params: CallToolRequestParams,
+	) -> CallToolResult:
+		try:
+			qualified_name = self._names[params.name]
+		except KeyError as error:
+			raise MCPError(code=INVALID_PARAMS, message="Unknown or unexposed tool.") from error
+		try:
+			budget = anyio.fail_after(self._call_timeout) if self._call_timeout is not None else nullcontext()
+			with budget:
+				arguments = params.arguments if params.arguments is not None else {}
+				if self._offload_sync and not self.catalog.describe(qualified_name).is_async:
+					result = await anyio.to_thread.run_sync(
+						lambda: self.catalog.invoke(qualified_name, arguments), abandon_on_cancel=True,
+					)
+				else:
+					result = self.catalog.invoke(qualified_name, arguments)
+				if inspect.isawaitable(result):
+					result = await result
+				value = self.catalog.serialize_result(qualified_name, result)
+		except (CapabilityArgumentError, CapabilityResultError) as error:
+			return CallToolResult(is_error=True, content=[TextContent(type="text", text=str(error))])
+		except Exception as error:
+			# Capability errors may contain private client state; report the failure type.
+			return CallToolResult(is_error=True, content=[TextContent(
+				type="text", text=f"Capability {params.name!r} failed ({type(error).__name__}).",
+			)])
+		structured = {"result": value}
+		return CallToolResult(
+			content=[TextContent(type="text", text=json.dumps(structured, ensure_ascii=False, allow_nan=False))],
+			structured_content=structured,
+		)
+
+	def server(self, name: str = "hidden-moves", *, version: str = "0.1.0") -> Server:
+		return Server(name, version=version, on_list_tools=self._list_tools, on_call_tool=self._call_tool)
+
+
+async def serve_stdio(server: Server) -> None:
+	"""Serve until the host closes stdin; the SDK owns the protocol connection."""
+	async with stdio_server() as (read_stream, write_stream):
+		await server.run(read_stream, write_stream, server.create_initialization_options())