From c9c56ba293bb62955f2b88bb3273d33b16216873 Mon Sep 17 00:00:00 2001 From: "D. Dessy" Date: Tue, 9 Jun 2026 10:21:20 +0200 Subject: [PATCH] Add Vellem agent guidance and demo-prep make targets. Document Vellem as session memory alongside Splunk MCP, add make demo-prep and make verify for presales checks, and clarify token storage in docs. Co-authored-by: Cursor --- AGENTS.md | 4 +++- Makefile | 17 ++++++++++++++++- docs/INSTALLATION.md | 2 +- docs/PRESALES.md | 4 ++-- docs/QUICK_START.md | 5 +++-- 5 files changed, 25 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 395adff..edc4772 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,6 +7,7 @@ Repo-specific guidance for AI agents and contributors working in `splunk-mcp`. - **Purpose**: local PoC that runs **Splunk Enterprise** in Docker and exposes **Splunk MCP Server** on `https://localhost:8089/services/mcp`. - **Client bridge**: **Claude Desktop**, **Cursor**, and **Goose** use **`npx mcp-remote`** to `https://localhost:8089/services/mcp` (token minted at `make update-*-config` after **`splunk-init`** completes; stored only in client config, not the repo). See `make update-mcp-clients` or `make update-mcp-client MCP_CLIENT=…`. **SE / presales**: **`docs/PRESALES.md`**. - **Sample app**: **`SA-S4R`** (UI label **Splunk4Rookies**) — bind-mounted Eventgen traffic, lookups, dashboard assets. See **`docs/SA-S4R-APP.md`** and **`docs/What Does the Business Want to See.md`** (workshop dashboard spec). +- **Session memory (Vellem)**: when the **vellem** MCP server is enabled in Cursor, start with **`search_notes_semantic`** on folder **`splunk-mcp`** (boot, verify, troubleshooting) before deep doc reads. Use **`list_expiring_contexts`** to avoid stale notes. After demos or non-obvious fixes, capture outcomes in Vellem (**`add_decision_note`** / **`append_to_daily`**) — not in git. Splunk MCP handles live data; Vellem holds repo-specific memory (no secrets). ## Golden rules (don’t break these) @@ -51,6 +52,7 @@ Splunk REST bootstrap (see **`docs/SETUP_SPLUNK_SCRIPT.md`** for detail): | -------- | ----------------- | | Stack healthy? | `make status` — **`splunk-init`** line + **Splunk is ready ✓**; exits non-zero if init failed or Splunk down | | MCP client path OK? | `make verify-mcp-remote` (all clients) or `make verify-mcp-remote MCP_VERIFY_CLIENT=cursor` | +| Pre-demo / both checks? | `make demo-prep` (status + verify + warm-stack reminder) or `make verify` (status then verify only) | | Init failed? | `docker logs splunk-init` (see **`docs/TROUBLESHOOTING.md`**) | | Eventgen modinput? | `curl -k -u admin: "https://localhost:8089/servicesNS/nobody/SA-Eventgen/data/inputs/modinput_eventgen/default?output_mode=json"` | @@ -73,7 +75,7 @@ Splunk REST bootstrap (see **`docs/SETUP_SPLUNK_SCRIPT.md`** for detail): ## Change discipline - Prefer small commits; keep **`make up`**, **`make status`**, **`make verify-mcp-remote`** working. -- When changing **`Makefile`**, **`compose.yml`**, or **`scripts/setup-splunk.sh`**, update **`docs/CONFIGURATION.md`**, **`docs/OVERVIEW.md`**, and/or **`docs/TROUBLESHOOTING.md`** as needed. +- When changing **`Makefile`**, **`compose.yml`**, or **`scripts/setup-splunk.sh`**, update **`docs/CONFIGURATION.md`**, **`docs/OVERVIEW.md`**, and/or **`docs/TROUBLESHOOTING.md`** as needed; refresh or expire Vellem **`splunk-mcp`** folder notes when behavior changes. - Lint before push: **`pre-commit run --all-files`** (**shellcheck** on **`scripts/*.sh`**, **markdownlint-cli2** on Markdown). Requires **shellcheck** on PATH (`brew install shellcheck`) and **Node/npx**. Auto-fix Markdown: `npx --yes markdownlint-cli2 --fix`. - **License:** contributions are under **[LICENSE](LICENSE)** (MIT). diff --git a/Makefile b/Makefile index 78b28f9..afc95df 100644 --- a/Makefile +++ b/Makefile @@ -14,7 +14,7 @@ MCP_CLIENTS := cursor goose claude export ENV_FILE ENV_OUT ENV_EXAMPLE OP DC -.PHONY: help up down restart clean logs status \ +.PHONY: help up down restart clean logs status demo-prep verify \ update-mcp-clients update-mcp-client verify-mcp-remote \ update-claude-config update-cursor-config update-goose-config @@ -88,3 +88,18 @@ update-goose-config: ## Goose: npx mcp-remote + bearer token verify-mcp-remote: ## Verify client configs + Splunk MCP (MCP_VERIFY_CLIENT=all|…) @./scripts/mcp-client.sh verify "$(MCP_VERIFY_CLIENT)" + +demo-prep: ## Pre-demo check: status + MCP verify + warm-stack reminder + @echo "=== Splunk MCP demo prep ===" + @echo "Tip: warm the stack before a live meeting — cold 'make up' can take many minutes." + @echo "" + @$(MAKE) status + @echo "" + @$(MAKE) verify-mcp-remote + @echo "" + @echo "Demo prep complete. Restart Cursor/Claude if you refreshed MCP configs." + @echo "Splunk Web: https://localhost:8000 | MCP: https://localhost:8089/services/mcp" + +verify: ## Stack status then Splunk MCP client verify + @$(MAKE) status + @$(MAKE) verify-mcp-remote diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md index d0adc8a..db0c77a 100644 --- a/docs/INSTALLATION.md +++ b/docs/INSTALLATION.md @@ -142,7 +142,7 @@ Use **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** for Docker, ports, `op` auth, S ## Security (local PoC) -This setup targets **trusted localhost** use: self-signed TLS, dev-oriented MCP settings. Do not treat it as production-ready. See [SECURITY.md](SECURITY.md). Do not commit **`.env`**, **`.secrets/`**, or client files containing live tokens. +This setup targets **trusted localhost** use: self-signed TLS, dev-oriented MCP settings. Do not treat it as production-ready. See [SECURITY.md](SECURITY.md). Do not commit **`.env`**, **`tpl.env`**, or client files containing live MCP bearer tokens. (Legacy **`.secrets/`** is gitignored and only used when **`ALLOW_LEGACY_SECRETS=1`** — tokens are not written there.) ## Next steps diff --git a/docs/PRESALES.md b/docs/PRESALES.md index cebfb54..3cc3b7b 100644 --- a/docs/PRESALES.md +++ b/docs/PRESALES.md @@ -14,9 +14,9 @@ This repo is a **local proof-of-concept**: **Splunk Enterprise** in Docker, **Sp - **Path B (no 1Password):** `cp .env.example .env`, fill `SPLUNK_PASSWORD`, `SPLUNKBASE_USER`, `SPLUNKBASE_PASS`, `SPLUNK_MCP_PASSWORD`, `SPLUNK_IMAGE`, `TZ`. Never commit `.env`. 3. **Network:** The host must reach **splunkbase.splunk.com** (HTTPS) and your container registry (e.g. Docker Hub). VPN/firewall/proxy often blocks corporate demos—test ahead. 4. **Start:** `make up` from the repo root. First cold start is often **several minutes** (image pull, Splunk, Splunkbase app downloads, **`splunk-init`**). For a live meeting, warm the stack **before** the call or the day before. -5. **Wait for green:** `make status` until it prints **Splunk is ready ✓**. +5. **Wait for green:** `make status` until it prints **Splunk is ready ✓** (or run **`make demo-prep`** — status + MCP verify + warm-stack reminder). 6. **Cursor (recommended):** **`make up`** already wrote **`.cursor/mcp.json`**; restart Cursor or reload MCP servers. Confirm Splunk/MCP tools in the tool list and run a **read-only** tool (e.g. a small search). -7. **Sanity check from the shell:** `make verify-mcp-remote` (checks all client configs + Splunk MCP `tools/list`). +7. **Sanity check from the shell:** `make verify-mcp-remote` or **`make demo-prep`** (checks all client configs + Splunk MCP `tools/list`). 8. **Claude / Goose (if used):** **`make up`** runs **`update-mcp-clients`**; **quit Claude fully (Cmd+Q)** and reopen, and restart Goose. If anything fails, go straight to [TROUBLESHOOTING.md](TROUBLESHOOTING.md) (Splunkbase auth, ports, token timeout, MCP 401). diff --git a/docs/QUICK_START.md b/docs/QUICK_START.md index 200229d..2c65eff 100644 --- a/docs/QUICK_START.md +++ b/docs/QUICK_START.md @@ -33,8 +33,9 @@ With **`tpl.env`** and no **`.env`**, **`make up`** injects secrets via **`op ru ## 3. Verify ```bash -make status -make verify-mcp-remote +make demo-prep # status + MCP verify + presales reminder +# or: +make verify # status then verify-mcp-remote only ``` - Splunk Web: `https://localhost:8000` (admin + password from your secret source).