diff --git a/AGENTS.md b/AGENTS.md index 9b40506..332214c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,6 +17,7 @@ Guide for autonomous coding agents (e.g., OpenAI Codex) working in **streamnativ | `cmd/streamnative-mcp-server/` | `main.go` entry‑point for the CLI/server | **yes** | | `pkg/` | Core library packages (Kafka tools, Pulsar tools, cloud integration, feature gating) | yes | | `sdk/` | Thin Go client helpers (generated) | can be re‑generated | +| `charts/` | Helm charts (snmcp chart + values + README) | **yes** | | `docs/tools/` | One Markdown file per MCP tool – these are surfaced to the LLM at runtime | **yes** | | `.github/workflows/` | CI (lint, unit test, release) | only if changing CI | | `Makefile` | Local build helpers (`make build`, `make fix-license`, …) | safe | @@ -98,6 +99,7 @@ For HTTP/SSE mode add `sse --http-addr :9090 --http-path /mcp`. | **Add a new MCP tool** | 1) create package in `pkg/tools/...` 2) update `docs/tools/.md` 3) add to feature flag map 4) go‑vet + tests | | **Bug fix** | reproduce with unit test first → fix → ensure lint/test pass | | **Docs** | update both README **and** the per‑tool doc; regenerate table of contents | +| **Helm chart changes** | update `charts/snmcp/README.md`; keep repo install instructions current | | **Release prep** | bump version tag, update changelog, run `goreleaser release --snapshot` | --- @@ -136,4 +138,4 @@ This file follows the AGENTS.md spec described in the Codex system message (scop Happy hacking! 🚀 -@CLAUDE.md as reference. \ No newline at end of file +@CLAUDE.md as reference. diff --git a/README.md b/README.md index 690eff2..80169be 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,10 @@ StreamNative MCP Server releases the Docker Image to [streamnative/snmcp](https: docker pull streamnative/snmcp ``` +### Helm Chart (Kubernetes) + +See [charts/snmcp/README.md](charts/snmcp/README.md) for Helm installation via the StreamNative chart repository. + ### From Github Release Visit https://github.com/streamnative/streamnative-mcp-server/releases to get the latest binary of StreamNative MCP Server. @@ -97,10 +101,10 @@ bin/snmcp stdio --organization my-org --key-file /path/to/key-file.json --pulsar bin/snmcp stdio --use-external-kafka --kafka-bootstrap-servers localhost:9092 --kafka-auth-type SASL_SSL --kafka-auth-mechanism PLAIN --kafka-auth-user user --kafka-auth-pass pass --kafka-use-tls --kafka-schema-registry-url https://sr.local --kafka-schema-registry-auth-user user --kafka-schema-registry-auth-pass pass # Start MCP server with external Pulsar -snmcp stdio --use-external-pulsar --pulsar-web-service-url http://pulsar.example.com:8080 -bin/snmcp stdio --use-external-pulsar --pulsar-web-service-url http://pulsar.example.com:8080 --pulsar-token "xxx" +bin/snmcp stdio --use-external-pulsar --pulsar-web-service-url http://pulsar.example.com:8080 +bin/snmcp stdio --use-external-pulsar --pulsar-web-service-url http://pulsar.example.com:8080 --pulsar-token "xxx" -# Start MCP server with SSE by docker with StreamNative Cloud authentication +# Start MCP server with stdio by docker with StreamNative Cloud authentication docker run -i --rm -e SNMCP_ORGANIZATION=my-org -e SNMCP_KEY_FILE=/key.json -v /path/to/key-file.json:/key.json -p 9090:9090 streamnative/snmcp stdio ``` @@ -108,17 +112,17 @@ docker run -i --rm -e SNMCP_ORGANIZATION=my-org -e SNMCP_KEY_FILE=/key.json -v / ```bash # Start MCP server with SSE and StreamNative Cloud authentication -snmcp sse --http-addr :9090 --http-path /mcp --organization my-org --key-file /path/to/key-file.json +bin/snmcp sse --http-addr :9090 --http-path /mcp --organization my-org --key-file /path/to/key-file.json # Start MCP server with SSE and pre-configured StreamNative Cloud context # When --pulsar-instance and --pulsar-cluster are provided, context management tools are disabled -snmcp sse --http-addr :9090 --http-path /mcp --organization my-org --key-file /path/to/key-file.json --pulsar-instance my-instance --pulsar-cluster my-cluster +bin/snmcp sse --http-addr :9090 --http-path /mcp --organization my-org --key-file /path/to/key-file.json --pulsar-instance my-instance --pulsar-cluster my-cluster # Start MCP server with SSE and external Kafka -snmcp sse --http-addr :9090 --http-path /mcp --use-external-kafka --kafka-bootstrap-servers localhost:9092 +bin/snmcp sse --http-addr :9090 --http-path /mcp --use-external-kafka --kafka-bootstrap-servers localhost:9092 # Start MCP server with SSE and external Pulsar -snmcp sse --http-addr :9090 --http-path /mcp --use-external-pulsar --pulsar-web-service-url http://pulsar.example.com:8080 +bin/snmcp sse --http-addr :9090 --http-path /mcp --use-external-pulsar --pulsar-web-service-url http://pulsar.example.com:8080 # Start MCP server with SSE by docker with StreamNative Cloud authentication docker run -i --rm -e SNMCP_ORGANIZATION=my-org -e SNMCP_KEY_FILE=/key.json -v /path/to/key-file.json:/key.json -p 9090:9090 streamnative/snmcp sse @@ -130,7 +134,7 @@ When running the SSE server with external Pulsar, you can enable **multi-session ```bash # Start SSE server with multi-session Pulsar mode -snmcp sse --http-addr :9090 --http-path /mcp \ +bin/snmcp sse --http-addr :9090 --http-path /mcp \ --use-external-pulsar \ --pulsar-web-service-url http://pulsar.example.com:8080 \ --multi-session-pulsar \ @@ -163,10 +167,11 @@ snmcp sse --http-addr :9090 --http-path /mcp \ ``` Usage: - snmcp [command] + bin/snmcp [command] Available Commands: stdio Start stdio server + sse Start sse server help Help about any command Flags: @@ -175,7 +180,7 @@ Flags: --config-dir string If present, the config directory to use --enable-command-logging When enabled, the server will log all command requests and responses to the log file --features strings Features to enable, defaults to `all` - -h, --help help for snmcp + -h, --help help for bin/snmcp --issuer string The OAuth 2.0 issuer endpoint (default "https://auth.streamnative.cloud/") --kafka-auth-mechanism string The auth mechanism to use for Kafka --kafka-auth-pass string The auth password to use for Kafka @@ -213,7 +218,7 @@ Flags: --multi-session-pulsar Enable per-user Pulsar sessions based on Authorization header tokens (only for external Pulsar mode) --session-cache-size int Maximum number of cached Pulsar sessions when multi-session is enabled (default 100) --session-ttl-minutes int Session TTL in minutes before eviction when multi-session is enabled (default 30) - -v, --version version for snmcp + -v, --version version for bin/snmcp ``` ## Tool Configuration @@ -303,7 +308,7 @@ npm install -g @modelcontextprotocol/inspector ```bash # Inspect a stdio server -mcp-inspector stdio --command "snmcp stdio --organization my-org --key-file /path/to/key-file.json" +mcp-inspector stdio --command "bin/snmcp stdio --organization my-org --key-file /path/to/key-file.json" # Inspect an SSE server mcp-inspector sse --url "http://localhost:9090/mcp" @@ -453,4 +458,3 @@ This project uses [semver](https://semver.org/) semantics. Licensed under the Apache License Version 2.0: http://www.apache.org/licenses/LICENSE-2.0 - diff --git a/charts/snmcp/README.md b/charts/snmcp/README.md index 2078146..f69818b 100644 --- a/charts/snmcp/README.md +++ b/charts/snmcp/README.md @@ -10,6 +10,24 @@ This Helm chart deploys the StreamNative MCP Server on Kubernetes with **Multi-S ## Installation +Install from the StreamNative Helm repository: + +```bash +helm repo add streamnative https://charts.streamnative.io +helm repo update + +helm install snmcp streamnative/snmcp \ + --set pulsar.webServiceURL=http://pulsar.example.com:8080 +``` + +Optional: check available chart versions + +```bash +helm search repo streamnative/snmcp +``` + +Install from local chart (for development): + ```bash helm install snmcp ./charts/snmcp \ --set pulsar.webServiceURL=http://pulsar.example.com:8080 @@ -65,14 +83,14 @@ The container listens on port 9090. Use `service.port` or Ingress to expose a di ### Basic Installation ```bash -helm install snmcp ./charts/snmcp \ +helm install snmcp streamnative/snmcp \ --set pulsar.webServiceURL=http://pulsar:8080 ``` ### With Ingress ```bash -helm install snmcp ./charts/snmcp \ +helm install snmcp streamnative/snmcp \ --set pulsar.webServiceURL=http://pulsar:8080 \ --set ingress.enabled=true \ --set ingress.hosts[0].host=mcp.example.com \ @@ -83,7 +101,7 @@ helm install snmcp ./charts/snmcp \ ### Read-Only Mode with Limited Features ```bash -helm install snmcp ./charts/snmcp \ +helm install snmcp streamnative/snmcp \ --set pulsar.webServiceURL=http://pulsar:8080 \ --set server.readOnly=true \ --set server.features="{pulsar-admin,pulsar-client}" @@ -98,7 +116,7 @@ kubectl create secret generic pulsar-tls \ --from-file=tls.crt=./tls.crt \ --from-file=tls.key=./tls.key -helm install snmcp ./charts/snmcp \ +helm install snmcp streamnative/snmcp \ --set pulsar.webServiceURL=https://pulsar:8443 \ --set pulsar.tls.enabled=true \ --set pulsar.tls.secretName=pulsar-tls \