Feat/mcp improvments to docs

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "sc4s-plugin",
       "source": "./",
       "description": "Create, configure, troubleshoot, and safely manage SC4S.",
-      "version": "0.1.0",
+      "version": "3.47.0",
       "author": {
         "name": "Karol Wrona"
       }

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "sc4s-plugin",
-  "version": "0.1.0",
+  "version": "3.47.0",
   "description": "Create, configure, troubleshoot, and safely manage SC4S.",
   "author": {
     "name": "Karol Wrona"

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "sc4s-plugin",
-  "version": "0.1.0",
+  "version": "3.47.0",
   "description": "Create, configure, troubleshoot, and safely manage SC4S.",
   "author": {
     "name": "Karol Wrona"

.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "sc4s-plugin",
   "displayName": "SC4S Plugin",
-  "version": "0.1.0",
+  "version": "3.47.0",
   "description": "Create, configure, troubleshoot, and safely manage SC4S.",
   "author": {
     "name": "Karol Wrona"

docs/mcp_server/index.md

@@ -1,5 +1,10 @@
 # SC4S MCP Server
 
+!!! warning "Beta feature"
+    The SC4S MCP server and AI agent plugin are beta features. They are
+    currently supported only with SC4S `3.47.0`, and their interfaces may
+    change between releases.
+
 The **SC4S MCP Server** is a [Model Context Protocol](https://modelcontextprotocol.io) server
 that exposes Splunk Connect for Syslog (SC4S) knowledge and a safe management
 API to any MCP-compatible AI assistant or agent (for example: Cursor,
@@ -52,17 +57,20 @@ communicates with:
     that API, decides what configuration is accepted, validates syntax,
     and restarts `syslog-ng` inside the SC4S container when needed.
 
-Concretely, the MCP server only does two kinds of I/O:
+Concretely, the MCP server performs these kinds of I/O:
 
 * **Reads** a small, read-only set of files that are baked into its own
   container image at build time: the documentation under `docs/`, the
-  parser library under `package/lite/etc/addons/`, and the parser-creator
+  parser library under `package/shared/addons/`, and the parser-creator
   knowledge base. These are static; the MCP server does not reach into
   your host filesystem.
 * **Makes HTTP(S) requests** to `SC4S_API_URL`, the REST API running
   inside the SC4S container. Every "management" tool is a thin wrapper
-  over a single HTTP call. There is no shell, no `exec`, and no process
-  spawning.
+  over a single HTTP call.
+* **Runs the bundled configuration generator** when `sc4s_build_config`
+  is called. This tool starts `configuration-tool.sh` with `bash` inside
+  the MCP container. The script generates an `env_file` preview; it does
+  not execute commands on the host or modify the running SC4S instance.
 
 Additional the shipped image:
 
@@ -80,6 +88,33 @@ Additional the shipped image:
   [Installation](installation.md#prepare-your-sc4s-instance) applies
   to the SC4S container, not to the MCP server container.
 
+## Beta status and support
+
+The SC4S MCP server is currently available as a beta feature. Use the MCP
+server version that matches the SC4S version it manages; this beta release
+supports SC4S `3.47.0` only. Compatibility with earlier or later SC4S versions
+is not guaranteed.
+
+Known limitations:
+
+* Management tools require the SC4S management API to be enabled. Applying an
+  `env_file` can restart SC4S, while parser and metadata changes can reload it.
+* Tool schemas, prompts, and plugin workflows may change during the beta.
+
+Beta support is provided by the SC4S community on a best-effort basis. Report
+bugs through the
+[SC4S GitHub issue tracker](https://github.com/splunk/splunk-connect-for-syslog/issues)
+or ask for help in the SC4S community channel in Splunk Community Slack. Never
+include authentication tokens, `env_file` secrets, customer data, or other
+sensitive information in an issue or Slack message.
+
+Before upgrading, record the currently deployed MCP image tag or digest and
+keep the existing container configuration. Upgrade SC4S and its MCP server to
+matching versions. If verification
+fails, recreate the MCP container with the previously recorded image. See
+[Upgrading](installation.md#upgrading) for the full
+procedure.
+
 ## Next steps
 
 * **[Installation](installation.md)**, build the image, run it with

docs/mcp_server/installation.md

@@ -199,7 +199,7 @@ For example, `https://browser.example.com` and
 unlisted or malformed `Origin` is rejected with HTTP 403. Wildcard syntax is
 not supported; list each host or origin explicitly.
 
-The image ships a healthcheck that verifies the SSE endpoint is up. Check
+The image ships a healthcheck that verifies the `/health` endpoint. Check
 the container status with:
 
 ```bash
@@ -313,6 +313,15 @@ process and communicates via standard input/output. Provide:
 * an `args` array that starts the MCP server,
 * optional environment variables (`SC4S_API_URL`, `MCP_TRANSPORT=stdio`).
 
+### Codex MCP client configuration
+
+```bash
+codex mcp add sc4s --url http://<MCP_HOST>:8000/mcp
+```
+
+Replace <MCP_HOST> with the hostname or IP address that the MCP client can use
+to reach the MCP server.
+
 ## Verify the installation
 
 1. Confirm the container is running: `docker ps` or `podman ps`.
@@ -326,8 +335,10 @@ process and communicates via standard input/output. Provide:
 
 ## Upgrading
 
-To upgrade the MCP server, pull a newer image and recreate the container with
-the same configuration options. No data migration is required.
+The MCP server version must match the SC4S version it manages. Before upgrading,
+record the image tag or digest used by the running MCP container and keep its
+current configuration. Pull the replacement image before stopping the existing
+container. No data migration is required.
 
 Docker:
 

docs/mcp_server/resources_and_prompts.md

@@ -95,5 +95,5 @@ adding support for a new vendor might look like this:
 
 Throughout this flow the MCP server itself only reads files from its own
 container and makes HTTP calls to `SC4S_API_URL`. See
-[Security model](index.md#security-model-no-host-command-execution) for
-details.
+[Security model](index.md#security-model) for
+details.

docs/mcp_server/tools.md

@@ -30,7 +30,7 @@ outbound calls and cannot modify anything.
 | Tool | Description |
 |---|---|
 | `list_vendors()` | Lists all vendors supported by SC4S, based on the subdirectories of `docs/sources/vendor/`. |
-| `list_all_parsers()` | Lists all `.conf` parser files from `package/lite/etc/addons/`. |
+| `list_all_parsers()` | Lists all `.conf` parser files from `package/shared/addons/`. |
 | `list_vendor_parsers(vendor)` | Lists parser files whose contents reference a vendor name (case-insensitive whole-word match). |
 | `get_parser(parser_name)` | Returns the content of a parser file. Accepts either the file name (`foo.conf`) or the stem (`foo`). Returns `{ "found": bool, "path": ..., "content": ... }`. |
 | `search_docs(query)` | Regex search across every markdown file under `docs/`. Returns `path:line: snippet` entries. |

mkdocs.yml

@@ -83,12 +83,13 @@ nav:
       - Pluggable modules: "pluggable_modules.md"
   - Enterprise: enterprise.md
   - Edge Processor: "edge_processor.md"
-  - MCP Server:
-      - Overview: "mcp_server/index.md"
-      - Installation: "mcp_server/installation.md"
-      - Tools: "mcp_server/tools.md"
-      - Resources and Prompts: "mcp_server/resources_and_prompts.md"
-  - AI Agent Plugin: "sc4s-plugin.md"
+  - AI Features (experimental):
+      - MCP Server:
+          - Overview: "mcp_server/index.md"
+          - Installation: "mcp_server/installation.md"
+          - Tools: "mcp_server/tools.md"
+          - Resources and Prompts: "mcp_server/resources_and_prompts.md"
+      - AI Agent Plugin: "sc4s-plugin.md"
   - Troubleshooting:
       - SC4S Startup and Validation: "troubleshooting/troubleshoot_SC4S_server.md"
       - SC4S Logging and Troubleshooting Resources: "troubleshooting/troubleshoot_resources.md"

skills/sc4s-guided-configuration/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  display_name: "Configure SC4S"
+  display_name: "SC4S Guided Configuration"
   short_description: "Guide SC4S env_file setup and performance tuning"
   default_prompt: "Use $sc4s-guided-configuration to guide me through creating and optionally applying an SC4S env_file."