diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index e2c9959d22..69137e69f7 100644 --- a/.claude-plugin/marketplace.json +++ b/.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" } diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index c44702c006..51a9bea192 100644 --- a/.claude-plugin/plugin.json +++ b/.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" diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index b6ade14b47..de4e903b24 100644 --- a/.codex-plugin/plugin.json +++ b/.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" diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 3fd3ff8317..0f9a03e5f2 100644 --- a/.cursor-plugin/plugin.json +++ b/.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" diff --git a/docs/mcp_server/index.md b/docs/mcp_server/index.md index 339d277b5f..270e05cc9c 100644 --- a/docs/mcp_server/index.md +++ b/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 diff --git a/docs/mcp_server/installation.md b/docs/mcp_server/installation.md index 93e51fe9c6..6b5617a224 100644 --- a/docs/mcp_server/installation.md +++ b/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://:8000/mcp +``` + +Replace 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: diff --git a/docs/mcp_server/resources_and_prompts.md b/docs/mcp_server/resources_and_prompts.md index 038b5fd054..6d374da217 100644 --- a/docs/mcp_server/resources_and_prompts.md +++ b/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. \ No newline at end of file +[Security model](index.md#security-model) for +details. diff --git a/docs/mcp_server/tools.md b/docs/mcp_server/tools.md index 9e5d18b00a..7317ea3f4d 100644 --- a/docs/mcp_server/tools.md +++ b/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. | diff --git a/mkdocs.yml b/mkdocs.yml index 1f6fd353e9..3da25f71be 100644 --- a/mkdocs.yml +++ b/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" diff --git a/skills/sc4s-guided-configuration/agents/openai.yaml b/skills/sc4s-guided-configuration/agents/openai.yaml index c7be9dc0b5..6d7c26258f 100644 --- a/skills/sc4s-guided-configuration/agents/openai.yaml +++ b/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."