yamcps 0.1.0__py3-none-any.whl

yamcps/__init__.py

@@ -0,0 +1,16 @@
+"""Yet Another Model Context Protocole Server public connector and credential contracts."""
+
+from yamcps.connectors import Connector, SecretConsumer, SecretRequirements, SkillProvider
+from yamcps.secrets import BasicAuth, ConnectorSecrets, SecretError, SecretSpec, TokenAuth
+
+__all__ = [
+    "Connector",
+    "SecretConsumer",
+    "SecretRequirements",
+    "SecretSpec",
+    "SkillProvider",
+    "ConnectorSecrets",
+    "SecretError",
+    "TokenAuth",
+    "BasicAuth",
+]

yamcps/__main__.py

@@ -0,0 +1,3 @@
+from yamcps.cli import main
+
+main()

yamcps/cli.py

@@ -0,0 +1,82 @@
+"""yamcps command line; stdout is reserved for stdio MCP traffic."""
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+
+from yamcps.connectors import ConnectorError, discover, load
+from yamcps.onboarding import configure_secrets, default_vault, initialize_vault, requirements
+from yamcps.secrets import SecretError, SecretSpec
+from yamcps.server import create_server
+from yamcps.vault import Vault
+
+
+def _vault_options(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--vault", type=Path)
+    parser.add_argument("--key-file", type=Path)
+
+
+def _select_vault(args: argparse.Namespace) -> Vault:
+    if bool(args.vault) != bool(args.key_file):
+        raise SecretError("--vault and --key-file must be supplied together")
+    return Vault(args.vault, args.key_file) if args.vault else default_vault()
+
+
+def _manage_secrets(args: argparse.Namespace) -> None:
+    vault = _select_vault(args)
+    if args.action == "init":
+        initialize_vault(vault)
+    elif args.action == "list":
+        for name in vault.names():
+            print(name)
+    elif args.action == "delete":
+        vault.delete(args.connector, args.name)
+    else:
+        specs = [SecretSpec(args.name)] if args.name else requirements(load([args.connector])[0])
+        configure_secrets(args.connector, specs, vault)
+
+
+def main() -> None:
+    """Parse CLI commands and start the server or manage an encrypted vault."""
+    parser = argparse.ArgumentParser(prog="yamcps")
+    commands = parser.add_subparsers(dest="command", required=True)
+    connectors = commands.add_parser("connectors").add_subparsers(dest="action", required=True)
+    connectors.add_parser("list")
+    secrets = commands.add_parser("secrets").add_subparsers(dest="action", required=True)
+    for action in ("init", "set", "delete", "list"):
+        subcommand = secrets.add_parser(action)
+        _vault_options(subcommand)
+        if action in ("set", "delete"):
+            subcommand.add_argument("--connector", required=True)
+            subcommand.add_argument("--name", required=action == "delete")
+    serve = commands.add_parser("serve")
+    serve.add_argument(
+        "--connector",
+        action="append",
+        help="Load only this connector (repeatable); defaults to all installed plugins",
+    )
+    serve.add_argument("--transport", choices=["stdio", "http"], default="stdio")
+    serve.add_argument("--port", type=int, default=8000)
+    _vault_options(serve)
+    args = parser.parse_args()
+    logging.basicConfig(level=logging.INFO)
+    try:
+        if args.command == "connectors":
+            for name, entry in sorted(discover().items()):
+                print(f"{name}\t{entry.value}")
+            return
+        if args.command == "secrets":
+            _manage_secrets(args)
+            return
+        if not 1 <= args.port <= 65535:
+            parser.error("--port must be between 1 and 65535")
+        server = create_server(
+            args.connector, vault=_select_vault(args), interactive=sys.stdin.isatty()
+        )
+        if args.transport == "stdio":
+            server.run(transport="stdio")
+        else:
+            server.run(transport="streamable-http", host="127.0.0.1", port=args.port)
+    except (ConnectorError, SecretError) as exc:
+        parser.exit(2, f"yamcps: {exc}\n")

yamcps/connectors.py

@@ -0,0 +1,99 @@
+"""Discover installed plugins without importing unselected connectors."""
+
+import inspect
+import re
+from collections.abc import Iterable
+from importlib.metadata import EntryPoint, entry_points
+from pathlib import Path
+from typing import Protocol
+
+from mcp.server import MCPServer
+
+from yamcps.secrets import ConnectorSecrets, SecretSpec
+
+
+class Connector(Protocol):
+    id: str
+
+    def register(self, server: MCPServer) -> None: ...
+
+
+class SecretConsumer(Protocol):
+    """Optional connector capability for receiving scoped API credentials."""
+
+    def configure(self, secrets: ConnectorSecrets) -> None:
+        """Validate and retain credentials before registering MCP handlers.
+
+        Args:
+            secrets: Credential view scoped to this connector.
+        """
+        ...
+
+
+class SecretRequirements(Protocol):
+    """Optional declaration used by interactive secret configuration."""
+
+    def required_secrets(self) -> Iterable[SecretSpec]:
+        """Describe the credentials required by this connector.
+
+        Returns:
+            Required fields in the order they should be prompted.
+        """
+        ...
+
+
+class SkillProvider(Protocol):
+    def skill_roots(self) -> Iterable[Path]: ...
+
+
+class ConnectorError(ValueError):
+    """A plugin cannot safely be loaded."""
+
+
+def discover() -> dict[str, EntryPoint]:
+    plugins: dict[str, EntryPoint] = {}
+    for entry in entry_points(group="yamcps.connectors"):
+        if entry.name in plugins:
+            raise ConnectorError(f"Duplicate connector entry point: {entry.name}")
+        plugins[entry.name] = entry
+    return plugins
+
+
+def load(names: list[str] | None = None) -> list[Connector]:
+    """Load selected connectors, or every installed connector when omitted.
+
+    Args:
+        names: Explicit selection; None selects all entry points in name order.
+
+    Returns:
+        Validated connector instances.
+
+    Raises:
+        ConnectorError: Discovery/loading fails or automatic selection is empty.
+    """
+    available = discover()
+    if names is None:
+        names = sorted(available)
+        if not names:
+            raise ConnectorError("No connectors installed; install an yamcps plugin first")
+    selected: list[Connector] = []
+    seen: set[str] = set()
+    for name in names:
+        try:
+            entry = available[name]
+            connector = entry.load()()
+            identifier = connector.id
+            if not isinstance(identifier, str) or not re.fullmatch(r"[a-z][a-z0-9-]*", identifier):
+                raise ValueError("id must be a lowercase kebab-case identifier")
+            if identifier != name:
+                raise ValueError(f"id {identifier!r} must match entry point {name!r}")
+            if identifier in seen:
+                raise ValueError(f"duplicate connector id: {identifier}")
+            register = getattr(connector, "register", None)
+            if not callable(register) or inspect.iscoroutinefunction(register):
+                raise ValueError("register must be a synchronous callable")
+            seen.add(identifier)
+            selected.append(connector)
+        except Exception as exc:
+            raise ConnectorError(f"Connector {name!r}: {exc}") from exc
+    return selected

yamcps/onboarding.py

@@ -0,0 +1,182 @@
+"""Discover required credentials and collect missing values before MCP starts."""
+
+import getpass
+import inspect
+import sys
+import warnings
+from collections.abc import Sequence
+from pathlib import Path
+
+from yamcps.connectors import Connector, ConnectorError
+from yamcps.secrets import ConnectorSecrets, SecretError, SecretSpec, _identifier
+from yamcps.vault import Vault
+
+
+def default_vault() -> Vault:
+    """Locate the default local vault and separate master key.
+
+    Returns:
+        A vault below ~/.local/share/yamcps with a key below ~/.config/yamcps/keys.
+    """
+    home = Path.home()
+    return Vault(
+        home / ".local/share/yamcps/secrets.yamcps-vault",
+        home / ".config/yamcps/keys/master.yamcps-key",
+    )
+
+
+def requirements(connector: Connector) -> list[SecretSpec]:
+    """Read a connector's optional credential declaration.
+
+    Args:
+        connector: Loaded connector whose declaration is inspected once.
+
+    Returns:
+        Ordered, unique required secret descriptions.
+
+    Raises:
+        ConnectorError: The declaration is invalid or cannot be read.
+    """
+    try:
+        declare = getattr(connector, "required_secrets", None)
+        if declare is None:
+            return []
+        if not callable(declare) or inspect.iscoroutinefunction(declare):
+            raise TypeError
+        specs = list(declare())
+        seen: set[str] = set()
+        for spec in specs:
+            if not isinstance(spec, SecretSpec) or spec.name in seen:
+                raise TypeError
+            seen.add(spec.name)
+        return specs
+    except Exception:
+        raise ConnectorError(
+            f"Connector {connector.id!r}: invalid required_secrets declaration"
+        ) from None
+
+
+def initialize_vault(vault: Vault) -> None:
+    """Create private parent directories and initialize a new vault.
+
+    Args:
+        vault: Vault whose existing files must never be overwritten.
+    """
+    try:
+        vault.path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+        vault.key_file.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    except OSError:
+        raise SecretError("Cannot create vault or key directory") from None
+    vault.initialize()
+
+
+def _read_values(vault: Vault) -> dict[str, str]:
+    if vault.path.exists() or vault.key_file.exists():
+        return vault.values()
+    return {}
+
+
+def _require_terminal() -> None:
+    if not sys.stdin.isatty():
+        raise SecretError(
+            "Interactive secret configuration requires a terminal; "
+            "run 'yamcps secrets set --connector <name>' in a terminal first"
+        )
+
+
+def _prompt(connector: str, spec: SecretSpec, *, existing: bool = False) -> str:
+    label = f"{connector}/{spec.name}"
+    if spec.description:
+        print(f"{label}: {spec.description}", file=sys.stderr)
+    suffix = " (empty: keep existing)" if existing else ""
+    with warnings.catch_warnings():
+        warnings.simplefilter("error", getpass.GetPassWarning)
+        while True:
+            try:
+                value = getpass.getpass(f"{label}{suffix}: ", stream=sys.stderr)
+            except (getpass.GetPassWarning, EOFError, KeyboardInterrupt):
+                raise SecretError(
+                    "Secret configuration cancelled or hidden input unavailable"
+                ) from None
+            if value or existing:
+                return value
+            print("A nonempty value is required.", file=sys.stderr)
+
+
+def _persist(vault: Vault, updates: dict[str, str]) -> dict[str, str]:
+    if updates:
+        if not vault.path.exists() and not vault.key_file.exists():
+            initialize_vault(vault)
+        vault.update(updates)
+    return _read_values(vault)
+
+
+def prepare_secrets(
+    connectors: Sequence[Connector], vault: Vault, *, interactive: bool
+) -> dict[str, str]:
+    """Collect only missing declared credentials before connector configuration.
+
+    Args:
+        connectors: Selected connector instances; no other plugins are loaded.
+        vault: Credential store, initialized only when values need to be saved.
+        interactive: Whether terminal prompting is allowed.
+
+    Returns:
+        Decrypted credentials to inject into connector configuration.
+
+    Raises:
+        SecretError: Credentials are missing without a terminal, or vault access fails.
+    """
+    declared = [(connector.id, requirements(connector)) for connector in connectors]
+    values = _read_values(vault)
+    missing = [
+        (identifier, spec)
+        for identifier, specs in declared
+        for spec in specs
+        if ConnectorSecrets(identifier, values).get(spec.name) is None
+    ]
+    if not missing:
+        return values
+    if not interactive or not sys.stdin.isatty():
+        commands = "; ".join(
+            f"yamcps secrets set --connector {identifier}"
+            for identifier in dict.fromkeys(item[0] for item in missing)
+        )
+        raise SecretError(f"Missing required secrets; configure them in a terminal: {commands}")
+    _require_terminal()
+    updates = {
+        _variable(identifier, spec.name): _prompt(identifier, spec) for identifier, spec in missing
+    }
+    return _persist(vault, updates)
+
+
+def _variable(connector: str, name: str) -> str:
+    return f"YAMCPS_{_identifier(connector)}_{_identifier(name)}"
+
+
+def configure_secrets(connector: str, specs: Sequence[SecretSpec], vault: Vault) -> None:
+    """Run the explicit configuration wizard for one connector.
+
+    Args:
+        connector: Connector identifier.
+        specs: Required fields, or one explicitly selected secret.
+        vault: Credential store to update after all prompts succeed.
+
+    Raises:
+        SecretError: No fields are declared or hidden terminal input is unavailable.
+    """
+    if not specs:
+        raise SecretError(
+            f"Connector {connector!r} declares no required secrets; "
+            "use --name to configure a specific secret"
+        )
+    _require_terminal()
+    values = _read_values(vault)
+    updates = {}
+    for spec in specs:
+        value = _prompt(
+            connector, spec, existing=ConnectorSecrets(connector, values).get(spec.name) is not None
+        )
+        if value:
+            updates[_variable(connector, spec.name)] = value
+    _persist(vault, updates)

yamcps/registry.py

@@ -0,0 +1,37 @@
+"""Reject duplicate registrations instead of the SDK's default replacement."""
+
+from collections.abc import Callable
+from typing import Any
+
+from mcp.server import MCPServer
+from mcp.server.mcpserver.prompts import Prompt
+from mcp.server.mcpserver.resources import Resource
+
+
+class StrictServer(MCPServer):
+    def __init__(self, **kwargs: Any) -> None:
+        self._yamcps_names: dict[str, set[str]] = {
+            "tool": set(),
+            "prompt": set(),
+            "resource": set(),
+        }
+        super().__init__(**kwargs)
+
+    def _claim(self, kind: str, name: str) -> None:
+        if name in self._yamcps_names[kind]:
+            raise ValueError(f"Duplicate {kind}: {name}")
+        self._yamcps_names[kind].add(name)
+
+    def add_tool(
+        self, fn: Callable[..., Any], name: str | None = None, *args: Any, **kwargs: Any
+    ) -> None:
+        self._claim("tool", name or fn.__name__)
+        super().add_tool(fn, name, *args, **kwargs)
+
+    def add_prompt(self, prompt: Prompt) -> None:
+        self._claim("prompt", prompt.name)
+        super().add_prompt(prompt)
+
+    def add_resource(self, resource: Resource) -> None:
+        self._claim("resource", str(resource.uri))
+        super().add_resource(resource)

yamcps/secrets.py

@@ -0,0 +1,167 @@
+"""Connector-scoped credentials for outbound API authentication."""
+
+import base64
+import os
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from pydantic import SecretStr
+
+
+class SecretError(ValueError):
+    """A required secret is missing or invalid; messages never include values."""
+
+
+def _identifier(value: str) -> str:
+    if not re.fullmatch(r"[a-z][a-z0-9]*(?:-[a-z0-9]+)*", value):
+        raise SecretError("Expected a lowercase kebab-case identifier")
+    return value.upper().replace("-", "_")
+
+
+@dataclass(frozen=True)
+class TokenAuth:
+    """An API token with a configurable Authorization scheme."""
+
+    token: SecretStr
+    scheme: str = "Bearer"
+
+    def authorization_header(self) -> SecretStr:
+        """Build a masked Authorization header.
+
+        Returns:
+            A secret header; explicitly call get_secret_value() to send it.
+
+        Raises:
+            SecretError: The token or authentication scheme is invalid.
+        """
+        token = self.token.get_secret_value()
+        if not re.fullmatch(r"[A-Za-z][A-Za-z0-9-]*", self.scheme):
+            raise SecretError("Invalid token authentication scheme")
+        if not token or any(not 33 <= ord(character) <= 126 for character in token):
+            raise SecretError("Invalid API token")
+        return SecretStr(f"{self.scheme} {token}")
+
+
+@dataclass(frozen=True)
+class BasicAuth:
+    """Username and password for HTTP Basic authentication."""
+
+    username: SecretStr
+    password: SecretStr
+
+    def authorization_header(self) -> SecretStr:
+        """Build a masked, UTF-8 Basic Authorization header.
+
+        Returns:
+            A secret header; explicitly call get_secret_value() to send it.
+
+        Raises:
+            SecretError: The username is empty or contains a colon.
+        """
+        username = self.username.get_secret_value()
+        if not username or ":" in username:
+            raise SecretError("Invalid Basic authentication username")
+        credentials = f"{username}:{self.password.get_secret_value()}".encode("utf-8")
+        encoded = base64.b64encode(credentials).decode("ascii")
+        return SecretStr(f"Basic {encoded}")
+
+
+class ConnectorSecrets:
+    """Read only the credentials named for one connector."""
+
+    def __init__(self, connector_id: str, values: Mapping[str, str] | None = None) -> None:
+        """Create a connector-scoped view over a credential source.
+
+        Args:
+            connector_id: Plugin identifier used to derive the environment prefix.
+            values: Credential source; defaults to the process environment.
+        """
+        self._prefix = f"YAMCPS_{_identifier(connector_id)}_"
+        self._values = os.environ if values is None else values
+
+    def redact(self, message: str) -> str:
+        """Mask this connector's raw secrets in a diagnostic.
+
+        Args:
+            message: Diagnostic text supplied by a connector.
+
+        Returns:
+            Text with known nonempty credential values replaced.
+        """
+        values = sorted(
+            {
+                value
+                for name, value in self._values.items()
+                if name.startswith(self._prefix) and value
+            },
+            key=len,
+            reverse=True,
+        )
+        for value in values:
+            message = message.replace(value, "[REDACTED]")
+        return message
+
+    def get(self, name: str) -> SecretStr | None:
+        """Read an optional secret without exposing its raw value.
+
+        Args:
+            name: Lowercase kebab-case secret name, such as api-token.
+
+        Returns:
+            A masked secret, or None when the variable is unset or empty.
+        """
+        value = self._values.get(self._prefix + _identifier(name))
+        return SecretStr(value) if value else None
+
+    def require(self, name: str) -> SecretStr:
+        """Read a required secret.
+
+        Args:
+            name: Lowercase kebab-case secret name.
+
+        Returns:
+            A masked secret.
+
+        Raises:
+            SecretError: The secret is missing or empty.
+        """
+        value = self.get(name)
+        if value is None:
+            raise SecretError(f"Missing secret: {self._prefix}{_identifier(name)}")
+        return value
+
+    def token_auth(self, name: str = "token", *, scheme: str = "Bearer") -> TokenAuth:
+        """Read and validate a token for an outbound API.
+
+        Args:
+            name: Secret name holding the token.
+            scheme: API authentication scheme, usually Bearer or Token.
+
+        Returns:
+            Masked token credentials.
+        """
+        auth = TokenAuth(self.require(name), scheme)
+        auth.authorization_header()
+        return auth
+
+    def basic_auth(self) -> BasicAuth:
+        """Read and validate username/password secrets.
+
+        Returns:
+            Masked HTTP Basic credentials.
+        """
+        auth = BasicAuth(self.require("username"), self.require("password"))
+        auth.authorization_header()
+        return auth
+
+
+@dataclass(frozen=True)
+class SecretSpec:
+    """Describe one required credential without including any value."""
+
+    name: str
+    description: str = ""
+
+    def __post_init__(self) -> None:
+        _identifier(self.name)

yamcps/server.py

@@ -0,0 +1,72 @@
+"""Compose selected connectors before starting either transport."""
+
+import inspect
+from collections.abc import Mapping
+
+from mcp.server import MCPServer
+
+from yamcps.connectors import ConnectorError, load
+from yamcps.onboarding import prepare_secrets
+from yamcps.registry import StrictServer
+from yamcps.secrets import ConnectorSecrets, SecretError
+from yamcps.skills import SkillCatalog
+from yamcps.vault import Vault
+
+
+def create_server(
+    names: list[str] | None = None,
+    *,
+    secret_values: Mapping[str, str] | None = None,
+    vault: Vault | None = None,
+    interactive: bool = False,
+) -> MCPServer:
+    """Compose a server with optional connector-scoped secrets.
+
+    Args:
+        names: Selected connector identifiers; None loads all installed plugins.
+        secret_values: Explicit values; None uses environment when no vault is given.
+        vault: Optional store to resolve declared secret requirements from.
+        interactive: Allow hidden prompts for missing vault credentials.
+
+    Returns:
+        A configured MCP server, ready to run.
+
+    Raises:
+        ConnectorError: Connector configuration or registration fails.
+    """
+    if vault is not None and secret_values is not None:
+        raise SecretError("Supply either vault or secret_values, not both")
+    catalog = SkillCatalog()
+    connectors = load(names)
+    if vault is not None:
+        secret_values = prepare_secrets(connectors, vault, interactive=interactive)
+    for connector in connectors:
+        configure = getattr(connector, "configure", None)
+        if configure is not None:
+            try:
+                if not callable(configure) or inspect.iscoroutinefunction(configure):
+                    raise TypeError("configure must be synchronous")
+                configure(ConnectorSecrets(connector.id, secret_values))
+            except SecretError as exc:
+                message = ConnectorSecrets(connector.id, secret_values).redact(str(exc))
+                raise ConnectorError(
+                    f"Connector {connector.id!r} configuration: {message}"
+                ) from None
+            except Exception:
+                raise ConnectorError(f"Connector {connector.id!r} configuration failed") from None
+        try:
+            roots = getattr(connector, "skill_roots", None)
+            if roots is not None:
+                catalog.add_roots(connector.id, roots())
+        except Exception as exc:
+            message = ConnectorSecrets(connector.id, secret_values).redact(str(exc))
+            raise ConnectorError(f"Connector {connector.id!r} skills: {message}") from None
+    server = StrictServer(name="yamcps", version="0.1.0", extensions=[catalog])
+    for connector in connectors:
+        try:
+            connector.register(server)
+        except Exception as exc:
+            message = ConnectorSecrets(connector.id, secret_values).redact(str(exc))
+            raise ConnectorError(f"Connector {connector.id!r} registration: {message}") from None
+    catalog.register_resources(server)
+    return server

yamcps/skills.py

@@ -0,0 +1,110 @@
+"""Immutable startup skill catalog and SDK extension compatibility adapter.
+
+The published mcp 2.3 SDK has Extension but not mcp.server.skills.
+Keep this adapter separate so the native implementation can replace it later.
+"""
+
+import hashlib
+import mimetypes
+import re
+from collections.abc import Iterable, Sequence
+from pathlib import Path
+from typing import Any
+from urllib.parse import quote
+
+import yaml
+from mcp.server import MCPServer
+from mcp.server.context import ServerRequestContext
+from mcp.server.extension import Extension, MethodBinding
+from mcp.server.mcpserver.resources import BinaryResource, TextResource
+from mcp.shared.exceptions import MCPError
+from mcp.types import INVALID_PARAMS, RequestParams
+
+
+class GetSkillParams(RequestParams):
+    uri: str
+
+
+class SkillCatalog(Extension):
+    identifier = "io.modelcontextprotocol/skills"
+
+    def __init__(self) -> None:
+        self.skills: dict[str, dict[str, Any]] = {}
+        self.files: dict[str, bytes] = {}
+
+    def add_roots(self, connector_id: str, roots: Iterable[Path]) -> None:
+        """Each root is one skill directory, named like its frontmatter name."""
+        for root in roots:
+            root = Path(root)
+            if root.is_symlink():
+                raise ValueError(f"Skill {root}: symbolic links are not supported")
+            root = root.resolve(strict=True)
+            paths = sorted(root.rglob("*"))
+            if any(path.is_symlink() for path in paths):
+                raise ValueError(f"Skill {root}: symbolic links are not supported")
+            contents = {
+                path.relative_to(root).as_posix(): path.read_bytes()
+                for path in paths
+                if path.is_file() and path.resolve().is_relative_to(root)
+            }
+            raw = contents.get("SKILL.md", b"").decode("utf-8")
+            match = re.match(r"\A---\r?\n(.*?)\r?\n---(?:\r?\n|\Z)", raw, re.DOTALL)
+            if not match:
+                raise ValueError(f"Skill {root}: missing YAML frontmatter")
+            metadata = yaml.safe_load(match.group(1))
+            if not isinstance(metadata, dict):
+                raise ValueError(f"Skill {root}: frontmatter must be a mapping")
+            name = metadata.get("name")
+            description = metadata.get("description")
+            if (
+                not isinstance(name, str)
+                or len(name) > 64
+                or not re.fullmatch(r"[a-z0-9]+(?:-[a-z0-9]+)*", name)
+                or not name.startswith(f"{connector_id}-")
+                or root.name != name
+            ):
+                raise ValueError(
+                    f"Skill {root}: name must match directory and start with {connector_id}-"
+                )
+            if not isinstance(description, str) or not description.strip():
+                raise ValueError(f"Skill {root}: description is required")
+            base = f"skill://{name}/"
+            uri = base + "SKILL.md"
+            if uri in self.skills:
+                raise ValueError(f"Duplicate skill: {name}")
+            resources = []
+            for relative, data in contents.items():
+                file_uri = base + quote(relative, safe="/")
+                self.files[file_uri] = data
+                resources.append(
+                    {
+                        "uri": file_uri,
+                        "size": len(data),
+                        "digest": "sha256:" + hashlib.sha256(data).hexdigest(),
+                    }
+                )
+            self.skills[uri] = {"uri": uri, "frontmatter": metadata, "resources": resources}
+
+    async def list_skills(self, ctx: ServerRequestContext[Any, Any], params: RequestParams) -> Any:
+        return {"skills": list(self.skills.values())}
+
+    async def get_skill(self, ctx: ServerRequestContext[Any, Any], params: GetSkillParams) -> Any:
+        if params.uri not in self.skills:
+            raise MCPError(code=INVALID_PARAMS, message=f"Unknown skill: {params.uri}")
+        return {"skill": self.skills[params.uri]}
+
+    def methods(self) -> Sequence[MethodBinding]:
+        return [
+            MethodBinding("skills/list", RequestParams, self.list_skills),
+            MethodBinding("skills/get", GetSkillParams, self.get_skill),
+        ]
+
+    def register_resources(self, server: MCPServer) -> None:
+        for uri, data in self.files.items():
+            mime = mimetypes.guess_type(uri)[0] or "application/octet-stream"
+            try:
+                text = data.decode("utf-8")
+            except UnicodeDecodeError:
+                server.add_resource(BinaryResource(uri=uri, data=data, mime_type=mime))
+            else:
+                server.add_resource(TextResource(uri=uri, text=text, mime_type=mime))

yamcps/vault.py

@@ -0,0 +1,184 @@
+"""Authenticated local credential storage with a separately supplied random key."""
+
+import json
+import os
+import stat
+import tempfile
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+from yamcps.secrets import SecretError, _identifier
+
+_HEADER = b"HMCPVAULT\x01"
+
+
+def _write_new(path: Path, data: bytes) -> None:
+    descriptor = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    with os.fdopen(descriptor, "wb") as stream:
+        stream.write(data)
+        stream.flush()
+        os.fsync(stream.fileno())
+
+
+class Vault:
+    """AES-256-GCM vault; no keyring, password derivation or plaintext export."""
+
+    def __init__(self, path: Path, key_file: Path) -> None:
+        """Locate a vault and its separate master key.
+
+        Args:
+            path: Encrypted vault file.
+            key_file: File containing exactly 32 random key bytes.
+
+        Raises:
+            SecretError: The vault and key point to the same file.
+        """
+        self.path = path.resolve()
+        self.key_file = key_file.resolve()
+        if self.path == self.key_file:
+            raise SecretError("Vault and key must be separate files")
+
+    def initialize(self) -> None:
+        """Create a new key and empty vault without overwriting existing files.
+
+        Raises:
+            SecretError: Files already exist or cannot be created.
+        """
+        if self.path.exists() or self.key_file.exists():
+            raise SecretError("Vault initialization requires two new file paths")
+        key = AESGCM.generate_key(bit_length=256)
+        created_key = False
+        try:
+            _write_new(self.key_file, key)
+            created_key = True
+            _write_new(self.path, self._encrypt({}, key))
+        except OSError:
+            if created_key:
+                self.key_file.unlink(missing_ok=True)
+            raise SecretError(
+                "Cannot initialize vault; check directories and permissions"
+            ) from None
+
+    def _key(self) -> bytes:
+        try:
+            with self.key_file.open("rb") as stream:
+                if os.name == "posix" and stat.S_IMODE(os.fstat(stream.fileno()).st_mode) & 0o077:
+                    raise SecretError("Master key permissions must restrict access to its owner")
+                key = stream.read(33)
+        except OSError:
+            raise SecretError("Cannot read master key") from None
+        if len(key) != 32:
+            raise SecretError("Master key must contain exactly 32 bytes")
+        return key
+
+    @staticmethod
+    def _encrypt(values: dict[str, str], key: bytes) -> bytes:
+        nonce = os.urandom(12)
+        plaintext = json.dumps(values, ensure_ascii=False).encode("utf-8")
+        return _HEADER + nonce + AESGCM(key).encrypt(nonce, plaintext, _HEADER)
+
+    def values(self) -> dict[str, str]:
+        """Decrypt credentials for server startup.
+
+        Returns:
+            Raw credentials for internal injection; never log this mapping.
+
+        Raises:
+            SecretError: The key, file, authentication tag or format is invalid.
+        """
+        key = self._key()
+        try:
+            data = self.path.read_bytes()
+        except OSError:
+            raise SecretError("Cannot read vault") from None
+        if not data.startswith(_HEADER) or len(data) < len(_HEADER) + 12 + 16:
+            raise SecretError("Invalid or unsupported vault format")
+        offset = len(_HEADER)
+        try:
+            plaintext = AESGCM(key).decrypt(
+                data[offset : offset + 12], data[offset + 12 :], _HEADER
+            )
+            values = json.loads(plaintext)
+        except (InvalidTag, ValueError, UnicodeDecodeError):
+            raise SecretError("Vault authentication failed or content is invalid") from None
+        if not isinstance(values, dict) or any(
+            not isinstance(name, str) or not isinstance(value, str)
+            for name, value in values.items()
+        ):
+            raise SecretError("Invalid vault credential format")
+        return values
+
+    @contextmanager
+    def _edit(self) -> Iterator[dict[str, str]]:
+        lock = self.path.with_name(self.path.name + ".lock")
+        try:
+            descriptor = os.open(lock, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+        except OSError:
+            raise SecretError("Vault is locked or not writable") from None
+        os.close(descriptor)
+        temporary: str | None = None
+        try:
+            values = self.values()
+            yield values
+            data = self._encrypt(values, self._key())
+            descriptor, temporary = tempfile.mkstemp(prefix=".yamcps-vault-", dir=self.path.parent)
+            with os.fdopen(descriptor, "wb") as stream:
+                stream.write(data)
+                stream.flush()
+                os.fsync(stream.fileno())
+            os.replace(temporary, self.path)
+        except OSError:
+            raise SecretError("Cannot update vault") from None
+        finally:
+            if temporary is not None:
+                Path(temporary).unlink(missing_ok=True)
+            lock.unlink(missing_ok=True)
+
+    def set(self, connector: str, name: str, value: str) -> None:
+        """Add or replace one credential.
+
+        Args:
+            connector: Connector identifier.
+            name: Secret identifier.
+            value: Nonempty raw secret obtained through hidden input.
+        """
+        variable = f"YAMCPS_{_identifier(connector)}_{_identifier(name)}"
+        if not value:
+            raise SecretError("Secret cannot be empty")
+        with self._edit() as values:
+            values[variable] = value
+
+    def update(self, values: dict[str, str]) -> None:
+        """Atomically persist a batch collected by the interactive wizard.
+
+        Args:
+            values: Nonempty credentials keyed by normalized YAMCPS variable names.
+
+        Raises:
+            SecretError: A credential name or value is invalid.
+        """
+        if any(not name.startswith("YAMCPS_") or not value for name, value in values.items()):
+            raise SecretError("Invalid credential batch")
+        with self._edit() as stored:
+            stored.update(values)
+
+    def delete(self, connector: str, name: str) -> None:
+        """Delete one credential, failing if it does not exist.
+
+        Args:
+            connector: Connector identifier.
+            name: Secret identifier.
+        """
+        variable = f"YAMCPS_{_identifier(connector)}_{_identifier(name)}"
+        with self._edit() as values:
+            if variable not in values:
+                raise SecretError("Secret does not exist")
+            del values[variable]
+
+    def names(self) -> list[str]:
+        """Return sorted credential names without their values."""
+        return sorted(self.values())

yamcps-0.1.0.dist-info/METADATA

@@ -0,0 +1,67 @@
+Metadata-Version: 2.5
+Name: yamcps
+Version: 0.1.0
+Summary: Yet Another Model Context Protocole Server: a plugin-based MCP server with skills
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: cryptography<51,>=46
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: pyyaml<7,>=6
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: hatchling; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# yamcps — Yet Another Model Context Protocole Server
+
+**yamcps** est un serveur MCP Python extensible qui expose les fonctionnalités de
+connecteurs à des assistants compatibles avec le Model Context Protocol.
+Python 3.12 ou supérieur est requis.
+
+## Fonctionnalités
+
+- Connecteurs indépendants distribuables sur PyPI sous le nom `yamcps-<nom>`.
+- Chargement de tous les plugins installés par défaut, ou sélection avec `--connector`.
+- Outils, ressources et prompts MCP fournis par les connecteurs.
+- Plugins `yamcps-sonarr` et `yamcps-radarr` : bibliothèques de séries/films, calendriers,
+  téléchargements, recherche et ajout.
+- Plugin `yamcps-prowlarr` : indexeurs, recherche de releases et diagnostics en lecture seule.
+- Skills `SKILL.md` et fichiers associés consultables via MCP.
+- Coffre local chiffré et configuration interactive des secrets requis par les connecteurs.
+- Transports stdio et Streamable HTTP local.
+- Plugins `yamcps-demo` et `yamcps-demo-secrets` pour tester les outils et la configuration des secrets.
+
+## Démarrage depuis le dépôt
+
+```sh
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e . -e plugins/yamcps-demo
+yamcps connectors list
+yamcps serve --connector demo
+```
+
+Pour charger tous les plugins installés : `yamcps serve`. Pour en sélectionner plusieurs :
+`yamcps serve --connector demo --connector demo-secrets`.
+
+Pour HTTP : `yamcps serve --connector demo --transport http --port 8000`.
+Le serveur écoute sur `http://127.0.0.1:8000/mcp`.
+
+## Documentation
+
+- [Manuel utilisateur](docs/user-manual.md) : installation, clients et utilisation.
+- [Architecture](docs/design.md) : contrats des connecteurs et gestion des skills.
+- [Contribution](contributing.md) : conventions, tests et contrôles qualité.
+- [Consignes pour les agents](AGENTS.md) : règles de travail dans le dépôt.
+
+Le nom PyPI `yamcps` est réservé pour ce projet. Seule la distribution de base
+est publiée par le [workflow de release](.github/workflows/workflow.yaml).
+Les plugins restent installables depuis le dépôt. Voir le guide de contribution
+pour configurer Trusted Publishing et publier une version.

yamcps-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+yamcps/__init__.py,sha256=45XIfAPIIlxWQDiyqtFK7t7Lc6w8Qb-E1fimCIFKQ6U,471
+yamcps/__main__.py,sha256=s_hB8Oj6ncX8xKsjFR7xpOpGD6FTZZ46pZZGEsGFhEg,36
+yamcps/cli.py,sha256=ipT0t_bC6-FK2E3RH3MXMmWHnqfRJk8GItB9zB7CnA8,3300
+yamcps/connectors.py,sha256=6OSaWjnAz_E-a5umbzPWAvC9_4MgBKzFfd2hrVZkwc8,3218
+yamcps/onboarding.py,sha256=MOMG5ej9Mzjj88AIp-v-6KZp8sptGPOxd3x-IFk4TMI,6249
+yamcps/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+yamcps/registry.py,sha256=EWZSdvK65EMGzSzsEx0AcJFeIhkMiJYMXJsZTTZbIvA,1237
+yamcps/secrets.py,sha256=x-pTiNuHHI0p3veQSdm8uI55Unig2W-ybgauctkAbzI,5234
+yamcps/server.py,sha256=VlfHABG2g4rCtznEo7uNFusI8euoVTwyvKuMi6NkAF8,3039
+yamcps/skills.py,sha256=n2UjYRystE82Mrm5mzEe07LmwLVgUi-1NRsbV-nf5A0,4701
+yamcps/vault.py,sha256=_avZvYqnWufsPVtYL9NZq_E5bVI-fDhkvGqpdLeqbV4,6906
+yamcps-0.1.0.dist-info/METADATA,sha256=h0rp9Rt5I4O-jG8ZwDvFl8t3YTcc4b8TsSZeDzvhjEs,2838
+yamcps-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+yamcps-0.1.0.dist-info/entry_points.txt,sha256=uTGiNtODerocojQyp80Zzl5RojGrwGUxqUy8p5-twKA,43
+yamcps-0.1.0.dist-info/licenses/LICENSE,sha256=lYIxZwOPglSE9QmzRMjPVmsKnxiU3Dra0YYOGRfBa64,1063
+yamcps-0.1.0.dist-info/RECORD,,

yamcps-0.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

yamcps-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+yamcps = yamcps.cli:main

yamcps-0.1.0.dist-info/licenses/LICENSE

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