specstream-mcp-stdio 1.1.0__py3-none-any.whl

specstream_mcp_stdio/__init__.py

@@ -0,0 +1,5 @@
+"""SPECSTREAM MCP stdio proxy. Bearer from environment only."""
+
+from specstream_mcp_stdio.proxy import authorization_from_env, main
+
+__all__ = ["authorization_from_env", "main"]

specstream_mcp_stdio/__main__.py

@@ -0,0 +1,4 @@
+from specstream_mcp_stdio.proxy import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

specstream_mcp_stdio/proxy.py

@@ -0,0 +1,259 @@
+"""Stdio to Streamable HTTP proxy. Authorization is copied from env only.
+
+Both MCP eras pass through. A request that carries its protocol version in
+`params._meta` (2026-07-28 and later) is forwarded statelessly with the version, method
+and name mirrored into headers. A client that starts with `initialize` gets the session
+revision the server negotiates, and its session id is kept for later requests.
+"""
+
+from __future__ import annotations
+
+import base64
+import ipaddress
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+from collections.abc import Mapping
+from typing import Any, TextIO
+from urllib.parse import urlsplit
+
+DEFAULT_MCP_URL = "https://api.specstream.ai/mcp"
+PROTOCOL_VERSION = "2025-11-25"
+VERSION_KEY = "io.modelcontextprotocol/protocolVersion"
+NAMED_METHODS = {"tools/call": "name", "prompts/get": "name", "resources/read": "uri"}
+MISSING_KEY = "SPECSTREAM_API_KEY is required. MCP does not elicit keys."
+
+
+def authorization_from_env(env: Mapping[str, str]) -> str:
+    for name in ("SPECSTREAM_API_KEY", "SPECSTREAM_AUTHORIZATION", "AUTHORIZATION"):
+        value = (env.get(name) or "").strip()
+        if value:
+            if any(not 32 <= ord(char) < 127 for char in value):
+                raise ValueError("The configured authorization header contains invalid characters")
+            return value if value.lower().startswith("bearer ") else f"Bearer {value}"
+    raise KeyError("SPECSTREAM_API_KEY")
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(
+        self, req: Any, fp: Any, code: int, msg: str, headers: Any, newurl: str
+    ) -> None:
+        return None
+
+
+def _mcp_url(env: Mapping[str, str]) -> str:
+    value = (env.get("SPECSTREAM_MCP_URL") or DEFAULT_MCP_URL).strip() or DEFAULT_MCP_URL
+    try:
+        parsed = urlsplit(value)
+        host = parsed.hostname
+        port = parsed.port
+        try:
+            loopback = host is not None and ipaddress.ip_address(host).is_loopback
+        except ValueError:
+            loopback = host == "localhost"
+        if (
+            not host
+            or parsed.scheme not in {"http", "https"}
+            or parsed.scheme == "http"
+            and not loopback
+            or parsed.username is not None
+            or parsed.password is not None
+            or parsed.query
+            or parsed.fragment
+            or port == 0
+            or any(ord(char) <= 32 or ord(char) == 127 for char in value)
+        ):
+            raise ValueError
+    except ValueError:
+        raise ValueError(
+            "SPECSTREAM_MCP_URL must use HTTPS (or loopback HTTP), "
+            "without credentials, query or fragment"
+        ) from None
+    return value
+
+
+def _header_value(value: str) -> str:
+    """Mcp-Name as the revision sends it: plain visible ASCII, or the Base64 sentinel form."""
+    plain = (
+        value == value.strip()
+        and all(32 <= ord(char) < 127 for char in value)
+        and not (value.startswith("=?base64?") and value.endswith("?="))
+    )
+    if plain:
+        return value
+    return "=?base64?" + base64.b64encode(value.encode("utf-8")).decode("ascii") + "?="
+
+
+def _stateless_version(message: Mapping[str, Any]) -> str | None:
+    params = message.get("params")
+    meta = params.get("_meta") if isinstance(params, Mapping) else None
+    version = meta.get(VERSION_KEY) if isinstance(meta, Mapping) else None
+    return version if isinstance(version, str) and version else None
+
+
+def _json_from_sse(text: str, request_id: Any) -> dict[str, Any]:
+    for event in text.replace("\r\n", "\n").split("\n\n"):
+        blob = "\n".join(
+            line[5:].lstrip() for line in event.splitlines() if line.startswith("data:")
+        )
+        if not blob:
+            continue
+        payload = json.loads(blob)
+        if isinstance(payload, dict) and "id" in payload and payload["id"] == request_id:
+            return payload
+    raise ValueError("mcp returned no response for the request")
+
+
+def _post_json(
+    url: str,
+    message: dict[str, Any],
+    *,
+    authorization: str,
+    session_id: str | None,
+    session_version: str = PROTOCOL_VERSION,
+) -> tuple[int, dict[str, str], dict[str, Any] | None]:
+    payload = json.dumps(message, separators=(",", ":")).encode("utf-8")
+    request = urllib.request.Request(url, data=payload, method="POST")
+    request.add_header("Authorization", authorization)
+    request.add_header("Accept", "application/json, text/event-stream")
+    request.add_header("Content-Type", "application/json")
+    stateless = _stateless_version(message)
+    if stateless:
+        method = str(message.get("method", ""))
+        request.add_header("MCP-Protocol-Version", stateless)
+        request.add_header("Mcp-Method", method)
+        params = message.get("params")
+        field = NAMED_METHODS.get(method)
+        name = params.get(field) if field and isinstance(params, Mapping) else None
+        if isinstance(name, str):
+            request.add_header("Mcp-Name", _header_value(name))
+    else:
+        request.add_header("MCP-Protocol-Version", session_version)
+        if session_id:
+            request.add_header("MCP-Session-Id", session_id)
+    try:
+        opener = urllib.request.build_opener(urllib.request.ProxyHandler({}), _NoRedirect())
+        with opener.open(request, timeout=60) as response:
+            status = int(response.status)
+            headers = {key.lower(): value for key, value in response.headers.items()}
+            raw = response.read().decode("utf-8")
+    except urllib.error.HTTPError as exc:
+        status = int(exc.code)
+        header_items = exc.headers.items() if exc.headers else []
+        headers = {key.lower(): value for key, value in header_items}
+        raw = exc.read().decode("utf-8") if exc.fp is not None else ""
+    if not 200 <= status < 300:
+        # The 2026-07-28 revision answers version, header and method problems with a JSON-RPC
+        # error on a 4xx; the client needs it to pick another version or fall back.
+        error = _error_body(raw, message.get("id"))
+        if error is None:
+            raise ValueError(f"mcp http {status}")
+        return status, headers, error
+    if status == 202:
+        if "id" in message:
+            raise ValueError("mcp returned no response for the request")
+        return status, headers, None
+    if not raw:
+        raise ValueError("mcp returned an empty response")
+    content_type = headers.get("content-type", "")
+    if "text/event-stream" in content_type:
+        loaded = _json_from_sse(raw, message.get("id"))
+    else:
+        loaded = json.loads(raw)
+    if (
+        not isinstance(loaded, dict)
+        or loaded.get("jsonrpc") != "2.0"
+        or "id" not in loaded
+        or loaded["id"] != message.get("id")
+        or not ({"result", "error"} & loaded.keys())
+    ):
+        raise ValueError("mcp returned an invalid response")
+    return status, headers, loaded
+
+
+def _error_body(raw: str, request_id: Any) -> dict[str, Any] | None:
+    try:
+        loaded = json.loads(raw) if raw else None
+    except json.JSONDecodeError:
+        return None
+    if (
+        isinstance(loaded, dict)
+        and loaded.get("jsonrpc") == "2.0"
+        and "id" in loaded
+        and loaded["id"] == request_id
+        and isinstance(loaded.get("error"), dict)
+    ):
+        return loaded
+    return None
+
+
+def main(
+    argv: list[str] | None = None,
+    env: Mapping[str, str] | None = None,
+    stdin: TextIO | None = None,
+    stdout: TextIO | None = None,
+    stderr: TextIO | None = None,
+) -> int:
+    del argv
+    environ = env if env is not None else os.environ
+    in_stream = stdin if stdin is not None else sys.stdin
+    out_stream = stdout if stdout is not None else sys.stdout
+    err_stream = stderr if stderr is not None else sys.stderr
+    try:
+        authorization = authorization_from_env(environ)
+        url = _mcp_url(environ)
+    except KeyError:
+        print(MISSING_KEY, file=err_stream)
+        return 2
+    except ValueError as exc:
+        print(str(exc), file=err_stream)
+        return 2
+    session_id: str | None = None
+    session_version = PROTOCOL_VERSION
+    for line in in_stream:
+        text = line.strip()
+        if not text:
+            continue
+        try:
+            message = json.loads(text)
+        except json.JSONDecodeError:
+            print("invalid jsonrpc line", file=err_stream)
+            return 1
+        if not isinstance(message, dict):
+            print("invalid jsonrpc line", file=err_stream)
+            return 1
+        if message.get("method") == "notifications/cancelled" and "id" not in message:
+            # Each request is a blocking POST here, so there is nothing to cancel upstream.
+            continue
+        try:
+            status, headers, body = _post_json(
+                url,
+                message,
+                authorization=authorization,
+                session_id=session_id,
+                session_version=session_version,
+            )
+        except (ValueError, OSError) as exc:
+            print(f"mcp transport failed: {exc}", file=err_stream)
+            return 1
+        header_session = headers.get("mcp-session-id")
+        if header_session and not _stateless_version(message):
+            session_id = header_session
+        if message.get("method") == "initialize" and isinstance(body, dict):
+            negotiated = (body.get("result") or {}).get("protocolVersion")
+            if isinstance(negotiated, str) and negotiated:
+                session_version = negotiated
+        if body is None:
+            if status >= 400:
+                print(f"mcp http {status}", file=err_stream)
+                return 1
+            continue
+        out_stream.write(json.dumps(body, separators=(",", ":")) + "\n")
+        out_stream.flush()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

specstream_mcp_stdio-1.1.0.dist-info/METADATA

@@ -0,0 +1,87 @@
+Metadata-Version: 2.5
+Name: specstream-mcp-stdio
+Version: 1.1.0
+Summary: Stdio proxy for the SpecStream MCP server, for Zed, Cline, and Continue. Finished lists with sources, priced before they run.
+Project-URL: Homepage, https://specstream.ai
+Project-URL: Documentation, https://specstream.ai/docs/mcp
+Project-URL: Repository, https://github.com/Specstreamai/specstream-tools
+Project-URL: Issues, https://github.com/Specstreamai/specstream-tools/issues
+Author-email: SpecStream <support@specstream.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,mcp,model-context-protocol,proxy,specstream,stdio,web-data
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# specstream-mcp-stdio
+
+A stdio proxy for the [SpecStream](https://specstream.ai) MCP server at `https://api.specstream.ai/mcp`. Use it with clients that only start local servers, such as Zed, Cline and Continue. Clients that connect to a remote URL do not need it.
+
+The proxy forwards to the same Streamable HTTP service that remote clients use, so your agent works on your account: the same balance, permissions and spending limits you have.
+
+## Install
+
+Python 3.12 or newer. The package has no dependencies.
+
+```sh
+pip install specstream-mcp-stdio
+```
+
+The command is `specstream-mcp-stdio`. In a GUI client, use its absolute path if the environment it was installed into is not on `PATH`.
+
+Create an API key under **Agents & API** in your SpecStream workspace. Set `SPECSTREAM_API_KEY` in the private environment of the client, outside prompts and shared configuration. `SPECSTREAM_MCP_URL` is an optional endpoint override.
+
+## Client configuration
+
+For clients that take an `mcpServers` entry:
+
+```json
+{
+  "mcpServers": {
+    "specstream": {
+      "command": "specstream-mcp-stdio",
+      "args": [],
+      "env": { "SPECSTREAM_MCP_URL": "https://api.specstream.ai/mcp" }
+    }
+  }
+}
+```
+
+Zed uses `context_servers` with the same fields. Continue takes a YAML file:
+
+```yaml
+name: SpecStream
+version: 1.0.0
+schema: v1
+mcpServers:
+  - name: specstream
+    type: stdio
+    command: specstream-mcp-stdio
+    args: []
+    env:
+      SPECSTREAM_MCP_URL: https://api.specstream.ai/mcp
+      SPECSTREAM_API_KEY: ${{ secrets.SPECSTREAM_API_KEY }}
+```
+
+## Use the tools
+
+Reconnect your client and list the tools. Start with `compile` to read a request, or `list_specs` and `list_projects` to find saved work.
+
+New paid work goes `quote_capacity_work`, then `authorize_capacity_work` with the quote ID and hash, the approved maximum in `confirm_max_cents` and a stable request key. Reading saved results does not start more paid work. See the [agent guide](https://specstream.ai/docs/mcp).
+
+## Connection problems
+
+The proxy needs the endpoint and a valid key. If it cannot connect, check the client's environment and the key's permissions. Keep TLS verification on.
+
+Protocol messages use stdin and stdout; diagnostics use stderr. The proxy keeps the negotiated HTTP session and does not follow redirects with credentials.
+
+Source and issues: [github.com/Specstreamai/specstream-tools](https://github.com/Specstreamai/specstream-tools). MIT license.

specstream_mcp_stdio-1.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+specstream_mcp_stdio/__init__.py,sha256=ewGvSNMoTL0JDIUc5U_0N166EFeBenDbMynpHNYRqrE,179
+specstream_mcp_stdio/__main__.py,sha256=fVAF8LCkKI3ly1ynnea5LhHYxTM9gUvK6AB5ECE-Iw0,101
+specstream_mcp_stdio/proxy.py,sha256=ByLJFWKWUr3SUS-YfeDlrhzWkurpfPT_Zd83wjWTH3c,9854
+specstream_mcp_stdio-1.1.0.dist-info/METADATA,sha256=eCrR7s0U618t_O9mtNMj8Yc934uEpnzoIP1qbEJXw0c,3572
+specstream_mcp_stdio-1.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+specstream_mcp_stdio-1.1.0.dist-info/entry_points.txt,sha256=Xuuibbea9KTKFUPWMX4W_5leFZfp9gpMZ0KoiCf7sEY,73
+specstream_mcp_stdio-1.1.0.dist-info/licenses/LICENSE,sha256=lvzGtfzsxc8Xe1_0sabdiWTcSDiSg3jqaFKV9x3F4oo,1071
+specstream_mcp_stdio-1.1.0.dist-info/RECORD,,

specstream_mcp_stdio-1.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

specstream_mcp_stdio-1.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+specstream-mcp-stdio = specstream_mcp_stdio.proxy:main

specstream_mcp_stdio-1.1.0.dist-info/licenses/LICENSE

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