Merge remote-tracking branch 'upstream/main' into 013-structured-server-state

# Conflicts:
#	cmd/mcpproxy/upstream_cmd.go
#	internal/health/calculator.go
#	oas/docs.go

Author: technicalpickles

.github/workflows/prerelease.yml

@@ -202,7 +202,7 @@ jobs:
           fi
 
           echo "Building version: ${VERSION}"
-          LDFLAGS="-s -w -X mcpproxy-go/cmd/mcpproxy.version=${VERSION} -X main.version=${VERSION}"
+          LDFLAGS="-s -w -X mcpproxy-go/cmd/mcpproxy.version=${VERSION} -X main.version=${VERSION} -X mcpproxy-go/internal/httpapi.buildVersion=${VERSION}"
 
           # Determine clean binary name
           if [ "${{ matrix.goos }}" = "windows" ]; then

.github/workflows/release.yml

@@ -103,7 +103,8 @@ jobs:
           Requirements:
           - Maximum 400 words
           - Use markdown format
-          - Start with a brief 1-2 sentence summary of this release
+          - DO NOT include a title or header like 'MCPProxy vX.X.X Release Notes' - GitHub already shows the version
+          - Start directly with a brief 1-2 sentence summary of this release
           - Group changes into sections (use only sections that have content):
             - **New Features** - New functionality (feat: commits)
             - **Bug Fixes** - Fixed issues (fix: commits)
@@ -368,7 +369,7 @@ jobs:
           CGO_LDFLAGS: "-mmacosx-version-min=12.0"
         run: |
           VERSION=${GITHUB_REF#refs/tags/}
-          LDFLAGS="-s -w -X mcpproxy-go/cmd/mcpproxy.version=${VERSION} -X main.version=${VERSION}"
+          LDFLAGS="-s -w -X mcpproxy-go/cmd/mcpproxy.version=${VERSION} -X main.version=${VERSION} -X mcpproxy-go/internal/httpapi.buildVersion=${VERSION}"
 
           # Determine clean binary name
           if [ "${{ matrix.goos }}" = "windows" ]; then
@@ -987,66 +988,69 @@ jobs:
 
             ---
 
-            ## mcpproxy ${{ github.ref_name }}
+            ## Download Installers
 
-            Smart MCP Proxy - Intelligent tool discovery and proxying for Model Context Protocol servers.
+            | Platform | Download | Notes |
+            |----------|----------|-------|
+            | **macOS (Apple Silicon)** | [**Download DMG**](https://github.com/${{ github.repository }}/releases/download/${{ github.ref_name }}/mcpproxy-${{ env.CLEAN_VERSION }}-darwin-arm64-installer.dmg) | Signed & Notarized - Recommended for M1/M2/M3/M4 |
+            | **macOS (Intel)** | [**Download DMG**](https://github.com/${{ github.repository }}/releases/download/${{ github.ref_name }}/mcpproxy-${{ env.CLEAN_VERSION }}-darwin-amd64-installer.dmg) | Signed & Notarized |
+            | **Windows (64-bit)** | [**Download Setup**](https://github.com/${{ github.repository }}/releases/download/${{ github.ref_name }}/mcpproxy-setup-${{ github.ref_name }}-amd64.exe) | Setup wizard |
+            | **Windows (ARM64)** | [**Download Setup**](https://github.com/${{ github.repository }}/releases/download/${{ github.ref_name }}/mcpproxy-setup-${{ github.ref_name }}-arm64.exe) | For ARM Windows devices |
+            | **Linux (AMD64)** | [**Download tar.gz**](https://github.com/${{ github.repository }}/releases/download/${{ github.ref_name }}/mcpproxy-${{ env.CLEAN_VERSION }}-linux-amd64.tar.gz) | Binary package |
+            | **Linux (ARM64)** | [**Download tar.gz**](https://github.com/${{ github.repository }}/releases/download/${{ github.ref_name }}/mcpproxy-${{ env.CLEAN_VERSION }}-linux-arm64.tar.gz) | For ARM Linux |
 
-            ### Download Links
+            **Homebrew (macOS/Linux):**
+            ```bash
+            brew install smart-mcp-proxy/mcpproxy/mcpproxy
+            ```
 
-            **Latest Version (auto-updates):**
-            - [Linux AMD64](https://github.com/${{ github.repository }}/releases/latest/download/mcpproxy-latest-linux-amd64.tar.gz) 
-            - [Linux ARM64](https://github.com/${{ github.repository }}/releases/latest/download/mcpproxy-latest-linux-arm64.tar.gz)
-            - [Windows AMD64](https://github.com/${{ github.repository }}/releases/latest/download/mcpproxy-latest-windows-amd64.zip)
-            - [Windows ARM64](https://github.com/${{ github.repository }}/releases/latest/download/mcpproxy-latest-windows-arm64.zip)
-            - [macOS AMD64](https://github.com/${{ github.repository }}/releases/latest/download/mcpproxy-latest-darwin-amd64.tar.gz)
-            - [macOS ARM64](https://github.com/${{ github.repository }}/releases/latest/download/mcpproxy-latest-darwin-arm64.tar.gz)
+            <details>
+            <summary>Other download options (auto-update URLs, archives)</summary>
 
-            **Windows Installer:**
-            - [Setup (AMD64)](https://github.com/${{ github.repository }}/releases/download/${{ github.ref_name }}/mcpproxy-setup-${{ github.ref_name }}-amd64.exe)
-            - [Setup (ARM64)](https://github.com/${{ github.repository }}/releases/download/${{ github.ref_name }}/mcpproxy-setup-${{ github.ref_name }}-arm64.exe)
+            **Auto-update URLs** (always points to latest):
+            - [Linux AMD64](https://github.com/${{ github.repository }}/releases/latest/download/mcpproxy-latest-linux-amd64.tar.gz) | [Linux ARM64](https://github.com/${{ github.repository }}/releases/latest/download/mcpproxy-latest-linux-arm64.tar.gz)
+            - [Windows AMD64](https://github.com/${{ github.repository }}/releases/latest/download/mcpproxy-latest-windows-amd64.zip) | [Windows ARM64](https://github.com/${{ github.repository }}/releases/latest/download/mcpproxy-latest-windows-arm64.zip)
+            - [macOS AMD64](https://github.com/${{ github.repository }}/releases/latest/download/mcpproxy-latest-darwin-amd64.tar.gz) | [macOS ARM64](https://github.com/${{ github.repository }}/releases/latest/download/mcpproxy-latest-darwin-arm64.tar.gz)
 
-            **macOS Installer:**
-            - [Signed DMG (Apple Silicon)](https://github.com/${{ github.repository }}/releases/download/${{ github.ref_name }}/mcpproxy-${{ env.CLEAN_VERSION }}-darwin-arm64-installer.dmg)
-            - [Signed DMG (Intel)](https://github.com/${{ github.repository }}/releases/download/${{ github.ref_name }}/mcpproxy-${{ env.CLEAN_VERSION }}-darwin-amd64-installer.dmg)
+            **Binary archives (this version):**
+            - [macOS AMD64](https://github.com/${{ github.repository }}/releases/download/${{ github.ref_name }}/mcpproxy-${{ env.CLEAN_VERSION }}-darwin-amd64.tar.gz) | [macOS ARM64](https://github.com/${{ github.repository }}/releases/download/${{ github.ref_name }}/mcpproxy-${{ env.CLEAN_VERSION }}-darwin-arm64.tar.gz)
+            - [Windows AMD64](https://github.com/${{ github.repository }}/releases/download/${{ github.ref_name }}/mcpproxy-${{ env.CLEAN_VERSION }}-windows-amd64.zip) | [Windows ARM64](https://github.com/${{ github.repository }}/releases/download/${{ github.ref_name }}/mcpproxy-${{ env.CLEAN_VERSION }}-windows-arm64.zip)
 
-            **This Version (${{ github.ref_name }}):**
-            - [Linux AMD64](https://github.com/${{ github.repository }}/releases/download/${{ github.ref_name }}/mcpproxy-${{ env.CLEAN_VERSION }}-linux-amd64.tar.gz)
-            - [Linux ARM64](https://github.com/${{ github.repository }}/releases/download/${{ github.ref_name }}/mcpproxy-${{ env.CLEAN_VERSION }}-linux-arm64.tar.gz)
-            - [Windows AMD64](https://github.com/${{ github.repository }}/releases/download/${{ github.ref_name }}/mcpproxy-${{ env.CLEAN_VERSION }}-windows-amd64.zip)
-            - [Windows ARM64](https://github.com/${{ github.repository }}/releases/download/${{ github.ref_name }}/mcpproxy-${{ env.CLEAN_VERSION }}-windows-arm64.zip)
-            - [macOS AMD64](https://github.com/${{ github.repository }}/releases/download/${{ github.ref_name }}/mcpproxy-${{ env.CLEAN_VERSION }}-darwin-amd64.tar.gz)
-            - [macOS ARM64](https://github.com/${{ github.repository }}/releases/download/${{ github.ref_name }}/mcpproxy-${{ env.CLEAN_VERSION }}-darwin-arm64.tar.gz)
+            </details>
 
-            ### Installation
+            ---
+
+            <details>
+            <summary>Installation Instructions</summary>
 
-            **Windows:**
-            1. Download the installer for your architecture (AMD64 or ARM64)
+            ### Windows
+            1. Download the installer for your architecture
             2. Run `mcpproxy-setup-*.exe`
             3. Follow the installation wizard (requires Administrator privileges)
-            4. MCPProxy will be added to Start Menu and system PATH
-            5. Launch "MCPProxy" from Start Menu to start the tray app
-            6. The app will appear in your system tray
+            4. Launch "MCPProxy" from Start Menu
 
-            **macOS:**
-            1. Download the signed installer DMG for your Mac (Apple Silicon or Intel)
+            ### macOS
+            1. Download the signed DMG for your Mac
             2. Double-click the DMG to mount it
             3. Double-click the PKG installer inside
             4. Follow the installation wizard
-            5. CLI tool `mcpproxy` will be available in Terminal
-            6. Launch mcpproxy.app from Applications folder
-            7. The app will appear in your system tray
+            5. Launch mcpproxy.app from Applications folder
 
-            **Manual Installation (All Platforms):**
-            1. Download the appropriate archive for your platform using the links above
-            2. Extract the archive: `tar -xzf mcpproxy-*.tar.gz` (Linux/macOS) or unzip (Windows)
-            3. Make it executable: `chmod +x mcpproxy` (Linux/macOS)
-            4. Run `./mcpproxy` to start
+            ### Linux / Manual Installation
+            1. Download the appropriate archive
+            2. Extract: `tar -xzf mcpproxy-*.tar.gz`
+            3. Make executable: `chmod +x mcpproxy`
+            4. Run: `./mcpproxy serve`
 
-            ### Platform Support
+            </details>
 
+            <details>
+            <summary>Platform Support & Usage</summary>
+
+            ### Platform Support
             - **macOS**: Full system tray support with menu and icons
-            - **Windows**: Full system tray support with menu and icons  
-            - **Linux**: Headless mode only (no system tray due to compatibility)
+            - **Windows**: Full system tray support with menu and icons
+            - **Linux**: Headless mode only (CLI)
 
             ### Usage
 
@@ -1055,10 +1059,13 @@ jobs:
             - Manages server via system tray menu
 
             **CLI:**
-            - Start core server: `mcpproxy serve`
-            - Custom port: `mcpproxy serve --listen 127.0.0.1:8081`
-            - Set API key: `export MCPPROXY_API_KEY=your-secret-key`
-            - Start tray separately: `mcpproxy-tray` (if core already running)
+            ```bash
+            mcpproxy serve                           # Start server
+            mcpproxy serve --listen 127.0.0.1:8081  # Custom port
+            export MCPPROXY_API_KEY=your-secret-key  # Set API key
+            ```
+
+            </details>
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
@@ -1137,7 +1144,7 @@ jobs:
           mkdir -p Formula
 
           # Create formula file
-          printf 'class Mcpproxy < Formula\n  desc "Smart MCP Proxy - Intelligent tool discovery and proxying for Model Context Protocol servers"\n  homepage "https://github.com/smart-mcp-proxy/mcpproxy-go"\n  url "https://github.com/smart-mcp-proxy/mcpproxy-go/archive/refs/tags/v%s.tar.gz"\n  sha256 "%s"\n  license "MIT"\n  head "https://github.com/smart-mcp-proxy/mcpproxy-go.git"\n\n  depends_on "go" => :build\n\n  def install\n    system "go", "build", "-ldflags", "-s -w -X mcpproxy-go/cmd/mcpproxy.version=v%s -X main.version=v%s", "-o", "mcpproxy", "./cmd/mcpproxy"\n    bin.install "mcpproxy"\n  end\n\n  test do\n    assert_match version.to_s, shell_output("#{bin}/mcpproxy --version")\n  end\nend\n' "${VERSION}" "${SOURCE_SHA}" "${VERSION}" "${VERSION}" > Formula/mcpproxy.rb
+          printf 'class Mcpproxy < Formula\n  desc "Smart MCP Proxy - Intelligent tool discovery and proxying for Model Context Protocol servers"\n  homepage "https://github.com/smart-mcp-proxy/mcpproxy-go"\n  url "https://github.com/smart-mcp-proxy/mcpproxy-go/archive/refs/tags/v%s.tar.gz"\n  sha256 "%s"\n  license "MIT"\n  head "https://github.com/smart-mcp-proxy/mcpproxy-go.git"\n\n  depends_on "go" => :build\n\n  def install\n    system "go", "build", "-ldflags", "-s -w -X mcpproxy-go/cmd/mcpproxy.version=v%s -X main.version=v%s -X mcpproxy-go/internal/httpapi.buildVersion=v%s", "-o", "mcpproxy", "./cmd/mcpproxy"\n    bin.install "mcpproxy"\n  end\n\n  test do\n    assert_match version.to_s, shell_output("#{bin}/mcpproxy --version")\n  end\nend\n' "${VERSION}" "${SOURCE_SHA}" "${VERSION}" "${VERSION}" "${VERSION}" > Formula/mcpproxy.rb
 
                     echo "Formula created successfully"
           cat Formula/mcpproxy.rb

CLAUDE.md

@@ -61,6 +61,31 @@ mcpproxy doctor                     # Run health checks
 
 See [docs/cli-management-commands.md](docs/cli-management-commands.md) for complete reference.
 
+### Activity Log CLI
+```bash
+mcpproxy activity list              # List recent activity
+mcpproxy activity list --type tool_call --status error  # Filter by type/status
+mcpproxy activity watch             # Real-time activity stream
+mcpproxy activity show <id>         # View activity details
+mcpproxy activity summary           # Show 24h statistics
+mcpproxy activity export --output audit.jsonl  # Export for compliance
+```
+
+See [docs/cli/activity-commands.md](docs/cli/activity-commands.md) for complete reference.
+
+### CLI Output Formatting
+```bash
+mcpproxy upstream list -o json      # JSON output for scripting
+mcpproxy upstream list -o yaml      # YAML output
+mcpproxy upstream list --json       # Shorthand for -o json
+mcpproxy --help-json                # Machine-readable help for AI agents
+```
+
+**Formats**: `table` (default), `json`, `yaml`
+**Environment**: `MCPPROXY_OUTPUT=json` sets default format
+
+See [docs/cli-output-formatting.md](docs/cli-output-formatting.md) for complete reference.
+
 ## Architecture Overview
 
 ### Core Components
@@ -69,6 +94,7 @@ See [docs/cli-management-commands.md](docs/cli-management-commands.md) for compl
 |-----------|---------|
 | `cmd/mcpproxy/` | CLI entry point, Cobra commands |
 | `cmd/mcpproxy-tray/` | System tray application with state machine |
+| `internal/cli/output/` | CLI output formatters (table, JSON, YAML) |
 | `internal/runtime/` | Lifecycle, event bus, background services |
 | `internal/server/` | HTTP server, MCP proxy |
 | `internal/httpapi/` | REST API endpoints (`/api/v1`) |
@@ -137,13 +163,26 @@ See [docs/configuration.md](docs/configuration.md) for complete reference.
 ## MCP Protocol
 
 ### Built-in Tools
-- **`retrieve_tools`** - BM25 keyword search across all upstream tools
-- **`call_tool`** - Proxy tool calls to upstream servers
+- **`retrieve_tools`** - BM25 keyword search across all upstream tools, returns annotations and recommended tool variant
+- **`call_tool_read`** - Proxy read-only tool calls to upstream servers (Spec 018)
+- **`call_tool_write`** - Proxy write tool calls to upstream servers (Spec 018)
+- **`call_tool_destructive`** - Proxy destructive tool calls to upstream servers (Spec 018)
 - **`code_execution`** - Execute JavaScript to orchestrate multiple tools (disabled by default)
 - **`upstream_servers`** - CRUD operations for server management
 
 **Tool Format**: `<serverName>:<toolName>` (e.g., `github:create_issue`)
 
+**Intent Declaration (Spec 018)**: Tool variants enable granular IDE permission control. The `intent` parameter provides two-key security:
+```json
+{
+  "intent": {
+    "operation_type": "read",
+    "data_sensitivity": "public",
+    "reason": "User requested list of repositories"
+  }
+}
+```
+
 ### HTTP API Endpoints
 
 **Base Path**: `/api/v1`
@@ -155,6 +194,9 @@ See [docs/configuration.md](docs/configuration.md) for complete reference.
 | `POST /api/v1/servers/{name}/enable` | Enable/disable server |
 | `POST /api/v1/servers/{name}/quarantine` | Quarantine/unquarantine server |
 | `GET /api/v1/tools` | Search tools across servers |
+| `GET /api/v1/activity` | List activity records with filtering |
+| `GET /api/v1/activity/{id}` | Get activity record details |
+| `GET /api/v1/activity/export` | Export activity records (JSON/CSV) |
 | `GET /events` | SSE stream for live updates |
 
 **Authentication**: Use `X-API-Key` header or `?apikey=` query parameter.
@@ -333,6 +375,16 @@ See `docs/prerelease-builds.md` for download instructions.
 ## Active Technologies
 - Go 1.24 (toolchain go1.24.10) (001-update-version-display)
 - In-memory only for version cache (no persistence per clarification) (001-update-version-display)
+- Go 1.24 (toolchain go1.24.10) + Cobra CLI framework, encoding/json, gopkg.in/yaml.v3 (014-cli-output-formatting)
+- N/A (CLI output only) (014-cli-output-formatting)
+- Go 1.24 (toolchain go1.24.10) + BBolt (storage), Chi router (HTTP), Zap (logging), existing event bus (016-activity-log-backend)
+- BBolt database (existing `~/.mcpproxy/config.db`) (016-activity-log-backend)
+- Go 1.24 (toolchain go1.24.10) + Cobra CLI framework, encoding/json, internal/cli/output (spec 014), internal/cliclien (017-activity-cli-commands)
+- N/A (CLI layer only - uses REST API from spec 016) (017-activity-cli-commands)
+- Go 1.24 (toolchain go1.24.10) + Cobra CLI, Chi router, BBolt (storage), Zap (logging), mark3labs/mcp-go (MCP protocol) (018-intent-declaration)
+- BBolt database (`~/.mcpproxy/config.db`) - ActivityRecord extended with intent metadata (018-intent-declaration)
+- TypeScript 5.9, Vue 3.5, Go 1.24 (backend already exists) + Vue 3, Vue Router 4, Pinia 2, Tailwind CSS 3, DaisyUI 4, Vite 5 (019-activity-webui)
+- N/A (frontend consumes REST API from backend) (019-activity-webui)
 
 ## Recent Changes
 - 001-update-version-display: Added Go 1.24 (toolchain go1.24.10)

Makefile

@@ -46,11 +46,17 @@ swagger-verify: swagger
 	fi
 	@echo "✅ OpenAPI artifacts are up to date."
 
+# Version detection for builds
+VERSION ?= $(shell git describe --tags --abbrev=0 2>/dev/null || echo "v0.1.0-dev")
+COMMIT ?= $(shell git rev-parse --short HEAD 2>/dev/null || echo "unknown")
+BUILD_DATE ?= $(shell date -u +%Y-%m-%dT%H:%M:%SZ)
+LDFLAGS := -X main.version=$(VERSION) -X main.commit=$(COMMIT) -X main.date=$(BUILD_DATE) -X mcpproxy-go/internal/httpapi.buildVersion=$(VERSION) -s -w
+
 # Build complete project
 build: swagger frontend-build
-	@echo "🔨 Building Go binary with embedded frontend..."
-	go build -o mcpproxy ./cmd/mcpproxy
-	go build -o mcpproxy-tray ./cmd/mcpproxy-tray
+	@echo "🔨 Building Go binary with embedded frontend (version: $(VERSION))..."
+	go build -ldflags "$(LDFLAGS)" -o mcpproxy ./cmd/mcpproxy
+	go build -ldflags "$(LDFLAGS)" -o mcpproxy-tray ./cmd/mcpproxy-tray
 	@echo "✅ Build completed! Run: ./mcpproxy serve"
 	@echo "🌐 Web UI: http://localhost:8080/ui/"
 	@echo "📚 API Docs: http://localhost:8080/swagger/"
@@ -74,8 +80,8 @@ frontend-dev:
 
 # Build backend with dev flag (for development with frontend hot reload)
 backend-dev:
-	@echo "🔨 Building backend in development mode..."
-	go build -tags dev -o mcpproxy-dev ./cmd/mcpproxy
+	@echo "🔨 Building backend in development mode (version: $(VERSION))..."
+	go build -tags dev -ldflags "$(LDFLAGS)" -o mcpproxy-dev ./cmd/mcpproxy
 	@echo "✅ Development backend ready!"
 	@echo "🚀 Run: ./mcpproxy-dev serve"
 	@echo "🌐 In dev mode, make sure frontend dev server is running on port 3000"