fc-client-docker 0.9.0__tar.gz → 0.9.2__tar.gz

fc_client_docker-0.9.2/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.1
+Name: fc_client_docker
+Version: 0.9.2
+Summary: Dockerized wrapper for the FC client
+Home-page: https://github.com/NXP/fc
+Author: Larry Shen
+Author-email: larry.shen@nxp.com
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+
+What is FC?
+-----------
+
+FC (Framework Coordinator), is an open source coordinator service among different embeded frameworks.
+It's built using the same principles as `Mesos <http://mesos.apache.org/>`_, provides different frameworks (e.g., LAVA, Labgrid) with API's for
+resource management and scheduling across entire board farms.
+
+Background
+----------
+
+There are many different systems in embedded test community, see `this <https://elinux.org/Test_Systems>`_. They are good at different scenarios, e.g.
+
+* **Test automation:**
+
+  LAVA, Fuego, autotest, avocado, TI VATF, U-Boot test tool, CI-RT R4D, Baylibe Lab in a Box......
+
+* **Development automation:**
+
+  Labgrid......
+
+Let's take a look at why FC is useful by going back in time.
+
+.. image:: doc/images/era.svg
+
+* **Traditional deployment era:** Early on, as nearly all above systems require dedicated control of the board resources, organizations have to
+  afford multiple series of hardware to meet the requirements of different frameworks, which leads to resource waste when leverage different systems.
+* **FC deployment era:** As a solution, FC was introduced. It allows different frameworks could share same series of hardware, move resources between
+  systems seamlessly. Different systems will continue work without aware existence of other systems. So, FC could be treat as "scheduler's scheduler".
+  The initial idea comes from `Jan's proposal to move boards between LAVA and labgrid on ATS2019 <https://elinux.org/Automated_Testing_Summit_2019>`_,
+  we realized the FC based on that thought (Thanks community to inspire the idea).
+
+Compared to other resource management system, it has low invasion to frameworks. This means: unlike mesos which you should write your mesos scheduler
+for your framework & inject it into your framework code, FC won't change your framework code, it tries to adapt to your framework.
+But still, your framework need next two features:
+
+* Your framework needs to have a job queue which FC could monitor.
+* Your framework needs to have ways to let FC control resource's availability, temporary connect/disconnect from your framework.
+
+Supported frameworks
+--------------------
+
+FC is designed as a plugin system to support different frameworks, it currently supports:
+
+* **LAVA:** use it for test automation
+* **Labgrid:** use it for development automation
+
+But, it not limits to above two, you could write your own plugins to support other framework.
+
+For more detail, move your steps to `FC home page <https://fc.readthedocs.org/>`_.
+

fc_client_docker-0.9.2/fc_client_docker.egg-info/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.1
+Name: fc_client_docker
+Version: 0.9.2
+Summary: Dockerized wrapper for the FC client
+Home-page: https://github.com/NXP/fc
+Author: Larry Shen
+Author-email: larry.shen@nxp.com
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+
+What is FC?
+-----------
+
+FC (Framework Coordinator), is an open source coordinator service among different embeded frameworks.
+It's built using the same principles as `Mesos <http://mesos.apache.org/>`_, provides different frameworks (e.g., LAVA, Labgrid) with API's for
+resource management and scheduling across entire board farms.
+
+Background
+----------
+
+There are many different systems in embedded test community, see `this <https://elinux.org/Test_Systems>`_. They are good at different scenarios, e.g.
+
+* **Test automation:**
+
+  LAVA, Fuego, autotest, avocado, TI VATF, U-Boot test tool, CI-RT R4D, Baylibe Lab in a Box......
+
+* **Development automation:**
+
+  Labgrid......
+
+Let's take a look at why FC is useful by going back in time.
+
+.. image:: doc/images/era.svg
+
+* **Traditional deployment era:** Early on, as nearly all above systems require dedicated control of the board resources, organizations have to
+  afford multiple series of hardware to meet the requirements of different frameworks, which leads to resource waste when leverage different systems.
+* **FC deployment era:** As a solution, FC was introduced. It allows different frameworks could share same series of hardware, move resources between
+  systems seamlessly. Different systems will continue work without aware existence of other systems. So, FC could be treat as "scheduler's scheduler".
+  The initial idea comes from `Jan's proposal to move boards between LAVA and labgrid on ATS2019 <https://elinux.org/Automated_Testing_Summit_2019>`_,
+  we realized the FC based on that thought (Thanks community to inspire the idea).
+
+Compared to other resource management system, it has low invasion to frameworks. This means: unlike mesos which you should write your mesos scheduler
+for your framework & inject it into your framework code, FC won't change your framework code, it tries to adapt to your framework.
+But still, your framework need next two features:
+
+* Your framework needs to have a job queue which FC could monitor.
+* Your framework needs to have ways to let FC control resource's availability, temporary connect/disconnect from your framework.
+
+Supported frameworks
+--------------------
+
+FC is designed as a plugin system to support different frameworks, it currently supports:
+
+* **LAVA:** use it for test automation
+* **Labgrid:** use it for development automation
+
+But, it not limits to above two, you could write your own plugins to support other framework.
+
+For more detail, move your steps to `FC home page <https://fc.readthedocs.org/>`_.
+

{fc_client_docker-0.9.0 → fc_client_docker-0.9.2}/fc_client_docker.egg-info/SOURCES.txt

@@ -60,6 +60,7 @@ fc_common/etcd.py
 fc_common/logger.py
 fc_common/version.py
 fc_guarder/guarder.py
+fc_mcp/README.md
 fc_mcp/__init__.py
 fc_mcp/mcp_base.py
 fc_mcp/mcp_server.py

fc_client_docker-0.9.2/fc_common/VERSION

@@ -0,0 +1 @@
+0.9.2

fc_client_docker-0.9.2/fc_mcp/README.md

@@ -0,0 +1,196 @@
+# FC MCP Server
+
+An [MCP](https://modelcontextprotocol.io/) server, built on
+[FastMCP](https://github.com/jlowin/fastmcp), that exposes FC
+operations as MCP tools. Under the hood every tool shells out to `fc-client`,
+so an AI agent can lock/unlock resources, query status, run console/ssh/power
+commands, and drive image deploy/flash workflows.
+
+## Architecture
+
+The server is plugin based. `mcp_server.py` creates the FastMCP instance, loads
+the internal plugin, then auto-discovers external plugins.
+
+```
+fc_mcp/
+  mcp_server.py                # entry point (fc-mcp), transport handling
+  mcp_base.py                  # MCPPlugin base class + shared helpers
+  mcp_plugins/
+    internal/fc_mcp.py         # core fc-client operations (always loaded)
+    external/
+      uuu_bcu_mcp.py           # UUU/BCU flashing tools (sample external plugin)
+      uboot_mcp.py             # U-Boot / predeploy config tools (sample)
+```
+
+Any `*_mcp.py` file placed under `mcp_plugins/external/` that exposes a
+`Plugin` class is discovered and loaded automatically at startup.
+
+## Installation
+
+From the repository root:
+
+```bash
+python setup.py install fc-mcp
+```
+
+
+This installs the `fc-mcp` console entry point. Requires Python >= 3.10 and
+`fastmcp >= 2.3` (needed for the Streamable HTTP transport).
+
+## Starting the server
+
+The server supports two transports. **stdio** is the default and is what a
+local client (for example `fc-agent`, which launches the server as a
+subprocess) uses. **Streamable HTTP** runs the server as a standalone HTTP
+service so remote / third-party MCP clients can connect.
+
+### stdio (default)
+
+```bash
+fc-mcp
+```
+
+The client is responsible for spawning the process and talking JSON-RPC over
+stdin/stdout.
+
+### Streamable HTTP
+
+```bash
+# Local only (default host 127.0.0.1, port 8000, path /mcp)
+fc-mcp --transport http
+
+# Expose to the network
+fc-mcp --transport http --host 0.0.0.0 --port 8000 --path /mcp
+```
+
+Clients then connect to `http://<host>:<port><path>`, e.g.
+`http://127.0.0.1:8000/mcp`.
+
+### Options
+
+Every flag has a matching environment variable, so the server can be configured
+in containers/services without CLI arguments. CLI flags take precedence.
+
+| Flag          | Environment variable | Default     | Description                                        |
+| ------------- | -------------------- | ----------- | -------------------------------------------------- |
+| `--transport` | `FC_MCP_TRANSPORT`   | `stdio`     | Transport mode: `stdio` or `http`.                 |
+| `--host`      | `FC_MCP_HOST`        | `127.0.0.1` | Bind host (HTTP transport only).                   |
+| `--port`      | `FC_MCP_PORT`        | `8000`      | Bind port (HTTP transport only).                   |
+| `--path`      | `FC_MCP_PATH`        | `/mcp`      | URL path the MCP endpoint is served on (HTTP only).|
+| _(none)_      | `FC_MCP_AUTH_TOKEN`  | _(unset)_   | Static Bearer token for HTTP transport (env only). |
+
+Example using environment variables:
+
+```bash
+export FC_MCP_TRANSPORT=http
+export FC_MCP_HOST=0.0.0.0
+export FC_MCP_PORT=9000
+fc-mcp
+# -> http://0.0.0.0:9000/mcp
+```
+
+## Authentication (HTTP transport)
+
+By default the HTTP endpoint is **unauthenticated** — anyone who can reach
+`http://<host>:<port><path>` can invoke every tool. When exposing the server on
+a network (`--host 0.0.0.0`), enable static Bearer-token auth by setting the
+`FC_MCP_AUTH_TOKEN` environment variable:
+
+```bash
+export FC_MCP_TRANSPORT=http
+export FC_MCP_HOST=0.0.0.0
+export FC_MCP_AUTH_TOKEN="$(openssl rand -hex 32)"
+fc-mcp
+```
+
+Behavior:
+
+- If `FC_MCP_AUTH_TOKEN` is unset or empty, the server runs without auth
+  (backward compatible).
+- If set, every request must include `Authorization: Bearer <token>`;
+  otherwise the server responds with `401 Unauthorized`.
+- The token is only enforced for HTTP transport. stdio transport ignores it.
+
+The token is intentionally read **only from an environment variable**, not from
+a CLI flag: command-line arguments are visible to other local users via `ps` /
+`/proc/<pid>/cmdline` (and leak into shell history), whereas
+`/proc/<pid>/environ` is readable only by the process owner and root.
+
+Client config with a Bearer token:
+
+```json
+{
+  "mcpServers": {
+    "fc": {
+      "url": "http://127.0.0.1:8000/mcp",
+      "headers": {
+        "Authorization": "Bearer <token>"
+      }
+    }
+  }
+}
+```
+
+## Connecting a third-party MCP client
+
+For HTTP transport, point the client at the server URL. A typical MCP client
+config entry looks like:
+
+```json
+{
+  "mcpServers": {
+    "fc": {
+      "url": "http://127.0.0.1:8000/mcp"
+    }
+  }
+}
+```
+
+For stdio transport, configure the client to launch the process instead:
+
+```json
+{
+  "mcpServers": {
+    "fc": {
+      "command": "fc-mcp"
+    }
+  }
+}
+```
+
+## Available tools
+
+Grouped by purpose (see the plugin sources for full signatures):
+
+- **Resource management** (`mcp_plugins/internal/fc_mcp.py`):
+  `lock`, `unlock`, `status`, `cluster_info`, `all_locks`,
+  `advanced_features`, `get_console_names`, `set_comment`.
+- **Command execution** (`mcp_plugins/internal/fc_mcp.py`):
+  `get_fc_command` (build a command string), `fc_command` (run or return
+  ssh/console/power/scp/rsync commands).
+- **Deploy / flash** (`mcp_plugins/external/uuu_bcu_mcp.py`):
+  `boot_mode_switch`, `flash_usb_boot_nexus`, `flash_usb_boot_uri`,
+  `flash_non_usb_boot_uri`.
+- **U-Boot / predeploy** (`mcp_plugins/external/uboot_mcp.py`):
+  `get_board_server_ip`, `get_uboot_config_uri`, `get_uboot_config_nexus`,
+  `list_available_boards`.
+
+## Extending with plugins
+
+Add a new `*_mcp.py` file under `mcp_plugins/external/` that defines a `Plugin`
+class subclassing `MCPPlugin` and implementing `register_tools()`:
+
+```python
+from fc_mcp.mcp_base import MCPPlugin
+
+
+class Plugin(MCPPlugin):
+    def register_tools(self):
+        @self.mcp.tool()
+        def my_tool(resource_id: str) -> dict:
+            """Describe what the tool does for the agent."""
+            ...
+            return {"success": True}
+```
+
+The file is picked up automatically the next time the server starts.

fc_client_docker-0.9.2/fc_mcp/mcp_server.py

@@ -0,0 +1,274 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# Copyright 2025-2026 NXP
+#
+# SPDX-License-Identifier: MIT
+
+"""
+FastMCP Server for FC Agent
+Provides tools to interact with fc clusters by calling fc-client.
+"""
+
+import argparse
+import importlib
+import logging
+import os
+import signal
+import sys
+import threading
+import time
+
+from fastmcp import FastMCP
+from fastmcp.server.auth.providers.jwt import StaticTokenVerifier
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+
+from fc_common.logger import Logger
+from fc_mcp.mcp_base import MCPPlugin
+from fc_mcp.mcp_plugins.internal.fc_mcp import Plugin
+
+LOGGER = logging.getLogger("fc_mcp")
+
+
+class IdleMonitor(Middleware):
+    """Track MCP request activity and shut the server down after being idle.
+
+    A FastMCP middleware refreshes the last-activity timestamp on every
+    incoming MCP message. A background daemon thread periodically checks the
+    elapsed idle time and, once it exceeds the configured timeout, records a
+    log entry and sends SIGTERM to the current process so uvicorn performs a
+    graceful shutdown.
+
+    This is only meaningful for the HTTP transport, where requests exist.
+    """
+
+    def __init__(self, timeout_seconds, check_interval=300):
+        self._timeout = timeout_seconds
+        # Poll at most every check_interval seconds, but never longer than the timeout itself.
+        self._check_interval = min(check_interval, timeout_seconds)
+        self._last_activity = time.monotonic()
+        self._lock = threading.Lock()
+
+    def _touch(self):
+        with self._lock:
+            self._last_activity = time.monotonic()
+
+    async def on_message(self, context: MiddlewareContext, call_next):
+        self._touch()
+        return await call_next(context)
+
+    def start(self):
+        """Launch the background idle-watchdog thread (daemon)."""
+        thread = threading.Thread(
+            target=self._watch, name="fc-mcp-idle-monitor", daemon=True
+        )
+        thread.start()
+
+    def _watch(self):
+        while True:
+            time.sleep(self._check_interval)
+            with self._lock:
+                idle = time.monotonic() - self._last_activity
+            if idle >= self._timeout:
+                LOGGER.info(
+                    "FC MCP HTTP server idle for %.0f seconds "
+                    "(timeout %d seconds), shutting down gracefully.",
+                    idle,
+                    self._timeout,
+                )
+                # Trigger uvicorn's graceful shutdown via its signal handler.
+                os.kill(os.getpid(), signal.SIGTERM)
+                return
+
+
+def load_external_plugins():
+    """Automatically discover and load all plugins from the external folder"""
+    external_dir = os.path.join(os.path.dirname(__file__), "mcp_plugins", "external")
+
+    if not os.path.exists(external_dir):
+        MCPPlugin.load_plugins(mcp)
+        return
+
+    # Find all *_mcp.py files
+    for filename in os.listdir(external_dir):
+        if filename.endswith("_mcp.py") and not filename.startswith("__"):
+            module_name = filename[:-3]
+            try:
+                full_module_name = f"fc_mcp.mcp_plugins.external.{module_name}"
+                module = importlib.import_module(full_module_name)
+
+                if hasattr(module, "Plugin"):
+                    plugin_class = getattr(module, "Plugin")
+                    plugin_class(mcp)
+                    print(f"Loaded external plugin: {module_name}")
+                else:
+                    print(f"Warning: No Plugin class found in {module_name}")
+
+            except Exception as exce:  # pylint: disable=broad-except
+                print(f"Failed to load plugin {module_name}: {exce}")
+
+
+# Initialize the FastMCP server
+mcp = FastMCP("FC MCP Server")
+
+# Load internal plugins
+Plugin(mcp)
+
+# Load external plugins
+load_external_plugins()
+
+
+def _default_port():
+    """Read FC_MCP_PORT from env, falling back to 8000 if unset or invalid."""
+    raw = os.environ.get("FC_MCP_PORT", "8000")
+    try:
+        return int(raw)
+    except (TypeError, ValueError):
+        print(
+            f"Warning: invalid FC_MCP_PORT '{raw}', falling back to 8000",
+            file=sys.stderr,
+        )
+        return 8000
+
+
+def _default_idle_timeout():
+    """Read FC_MCP_IDLE_TIMEOUT from env, falling back to 3600 seconds."""
+    raw = os.environ.get("FC_MCP_IDLE_TIMEOUT", "3600")
+    try:
+        return int(raw)
+    except (TypeError, ValueError):
+        print(
+            f"Warning: invalid FC_MCP_IDLE_TIMEOUT '{raw}', falling back to 3600",
+            file=sys.stderr,
+        )
+        return 3600
+
+
+def parse_args():
+    """Parse command line arguments for transport selection.
+
+    Environment variables provide the defaults so the server can be
+    configured in containerized/service deployments without CLI flags:
+      FC_MCP_TRANSPORT, FC_MCP_HOST, FC_MCP_PORT, FC_MCP_PATH, FC_MCP_IDLE_TIMEOUT
+    """
+    parser = argparse.ArgumentParser(
+        prog="fc-mcp",
+        description="FC MCP Server (supports stdio and streamable HTTP transports).",
+    )
+    parser.add_argument(
+        "--transport",
+        choices=["stdio", "http"],
+        default=os.environ.get("FC_MCP_TRANSPORT", "stdio"),
+        help="Transport mode: 'stdio' (default) or 'http' (streamable HTTP).",
+    )
+    parser.add_argument(
+        "--host",
+        default=os.environ.get("FC_MCP_HOST", "127.0.0.1"),
+        help="Host to bind when using HTTP transport (default: 127.0.0.1).",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=_default_port(),
+        help="Port to bind when using HTTP transport (default: 8000).",
+    )
+    parser.add_argument(
+        "--path",
+        default=os.environ.get("FC_MCP_PATH", "/mcp"),
+        help="URL path to serve MCP on when using HTTP transport (default: /mcp).",
+    )
+    parser.add_argument(
+        "--idle-timeout",
+        type=int,
+        default=_default_idle_timeout(),
+        help=(
+            "Idle timeout in seconds for HTTP transport. If no MCP request is "
+            "received within this window, the server shuts down gracefully. "
+            "Set to 0 to disable (default: 3600). Env: FC_MCP_IDLE_TIMEOUT."
+        ),
+    )
+    return parser.parse_args()
+
+
+def _configure_http_auth():
+    """Enable static Bearer-token auth for HTTP transport when configured.
+
+    The token is read from the FC_MCP_AUTH_TOKEN environment variable only.
+    Passing secrets via environment variables avoids exposing them through the
+    process command line (visible via ps / /proc/<pid>/cmdline to other users).
+
+    Behavior:
+      - If FC_MCP_AUTH_TOKEN is unset or empty, HTTP transport runs without
+        authentication (backward compatible).
+      - If set, clients must send 'Authorization: Bearer <token>' or requests
+        are rejected with HTTP 401.
+
+    The token is only enforced for HTTP transport; stdio transport ignores it.
+    """
+    token = os.environ.get("FC_MCP_AUTH_TOKEN", "").strip()
+    if not token:
+        print(
+            "FC MCP HTTP transport: no FC_MCP_AUTH_TOKEN set, "
+            "running WITHOUT authentication.",
+            file=sys.stderr,
+        )
+        return
+
+    mcp.auth = StaticTokenVerifier(
+        tokens={
+            token: {
+                "client_id": "fc-mcp",
+                "scopes": [],
+            }
+        }
+    )
+    print(
+        "FC MCP HTTP transport: Bearer token authentication ENABLED.",
+        file=sys.stderr,
+    )
+
+
+def main():
+    args = parse_args()
+
+    if args.transport == "http":
+        # Streamable HTTP transport for remote/third-party MCP clients.
+        # Clients connect to http://<host>:<port><path>, e.g. http://127.0.0.1:8000/mcp
+        Logger.init("fc_mcp", log_name="mcp_server.log")
+        _configure_http_auth()
+
+        idle_monitor = None
+        if args.idle_timeout > 0:
+            idle_monitor = IdleMonitor(args.idle_timeout)
+            mcp.add_middleware(idle_monitor)
+            LOGGER.info(
+                "FC MCP HTTP server starting on %s:%d%s " "(idle timeout %d seconds).",
+                args.host,
+                args.port,
+                args.path,
+                args.idle_timeout,
+            )
+            idle_monitor.start()
+        else:
+            LOGGER.info(
+                "FC MCP HTTP server starting on %s:%d%s (idle timeout disabled).",
+                args.host,
+                args.port,
+                args.path,
+            )
+
+        mcp.run(
+            transport="http",
+            host=args.host,
+            port=args.port,
+            path=args.path,
+            show_banner=False,
+        )
+        LOGGER.info("FC MCP HTTP server stopped.")
+    else:
+        # Default stdio transport (used by fc-agent subprocess launch).
+        mcp.run(show_banner=False)
+
+
+if __name__ == "__main__":
+    main()