feat(gateway): meta-gateway invoke (search → schema → invoke)

.github/ISSUE_TEMPLATE/config.yml

@@ -1,8 +1,17 @@
-blank_issues_enabled: false
+blank_issues_enabled: true
 contact_links:
   - name: Questions & Help
     url: https://github.com/mcpmux/mcp-mux/discussions/categories/q-a
     about: Ask questions and get help in GitHub Discussions
   - name: Feature Ideas
     url: https://github.com/mcpmux/mcp-mux/discussions/categories/ideas
     about: Share and discuss feature ideas
+  - name: Contribute a Server Definition (PR)
+    url: https://github.com/mcpmux/mcp-servers/blob/main/CONTRIBUTING.md
+    about: Server definitions live in the mcp-servers repo and land via PR — read the guide
+  - name: Request a Server
+    url: https://github.com/mcpmux/mcp-servers/issues/new?template=request-server.yml
+    about: Ask the community to add an MCP server to the registry
+  - name: Report a Server Definition Bug
+    url: https://github.com/mcpmux/mcp-servers/issues/new?template=bug-report.yml
+    about: Found a broken or incorrect server in the registry? Report it here

AGENTS.md

@@ -0,0 +1,131 @@
+# AGENTS.md
+
+Guidance for coding agents working inside the `mcp-mux` repo — the McpMux desktop app and local gateway. Complements [`README.md`](README.md) and [`CONTRIBUTING.md`](CONTRIBUTING.md); when anything here conflicts with an explicit user instruction in the current session, the user wins.
+
+## Project Overview
+
+McpMux is a Tauri 2 desktop app (Rust + React 19) with a local Axum HTTP gateway on `localhost:45818`. It lets users configure MCP servers once and connect every AI client (Cursor, Claude Desktop, VS Code, Windsurf) through a single endpoint, with credentials encrypted in the OS keychain instead of plain-text JSON files.
+
+A more detailed map of the workspace lives in [`CLAUDE.md`](CLAUDE.md) at the repo root — read it for the crate layout, frontend architecture, and cross-project context. This file captures the minimum an agent needs to make safe, useful changes here.
+
+## Workspace Layout
+
+```
+mcp-mux/
+├── apps/desktop/          # Tauri shell — React frontend (src/) + Rust Tauri commands (src-tauri/)
+├── crates/
+│   ├── mcpmux-core/       # Domain entities, repository traits, service layer, EventBus
+│   ├── mcpmux-gateway/    # Axum gateway — routing, OAuth refresh, FeatureSet filtering
+│   ├── mcpmux-storage/    # SQLite + AES-256-GCM field encryption + OS keychain
+│   └── mcpmux-mcp/        # MCP protocol client wrapper (rmcp SDK)
+├── packages/ui/           # Shared UI components (`@mcpmux/ui`)
+├── schemas/               # JSON Schemas surfaced in the Monaco editor
+└── tests/                 # Rust integration, TS unit (vitest), desktop E2E (WDIO), web E2E (playwright)
+```
+
+## Build & Dev Commands
+
+Run everything from `mcp-mux/`:
+
+| Command | What it does |
+|---------|--------------|
+| `pnpm setup` | First-time dev environment setup (PowerShell on Windows). |
+| `pnpm dev` | Tauri desktop dev mode (Rust + React hot-reload). |
+| `pnpm dev:web` | Web UI only via Vite — no Rust, no Tauri shell. |
+| `pnpm build` | Production Tauri build for the current platform. |
+| `pnpm validate` | Full correctness gate — runs the items below in sequence. |
+| `pnpm lint` | ESLint (recursive) + `cargo clippy --workspace -- -D warnings`. |
+| `pnpm lint:fix` | Auto-fix lint issues. |
+| `pnpm format` | `prettier --write .` + `cargo fmt --all`. |
+| `pnpm format:check` | Formatting check (no writes). |
+| `pnpm typecheck` | Recursive TypeScript typecheck. |
+
+**Before claiming a change is done**, run `pnpm validate` (or the relevant subset) — it mirrors what CI enforces.
+
+## Testing
+
+| Command | Scope |
+|---------|-------|
+| `pnpm test` | Rust + TypeScript, everything. |
+| `pnpm test:rust` | `cargo nextest run --workspace`. |
+| `pnpm test:rust:unit` | `cargo nextest run --workspace --lib`. |
+| `pnpm test:rust:int` | `cargo nextest run -p tests` — integration crate in `tests/rust`. |
+| `pnpm test:rust:doc` | `cargo test --workspace --doc`. |
+| `pnpm test:ts` | Vitest run (`tests/ts/vitest.config.ts`). |
+| `pnpm test:ts:watch` | Vitest watch. |
+| `pnpm test:e2e` | Desktop E2E via WebDriver IO — requires `MCPMUX_REGISTRY_URL`. |
+| `pnpm test:e2e:file -- tests/e2e/specs/foo.ts` | One WDIO spec file. |
+| `pnpm test:e2e:grep -- "test name"` | WDIO tests matching a name. |
+| `pnpm test:e2e:web` | Playwright on the web UI. |
+| `pnpm test:coverage` | `cargo llvm-cov` + Vitest coverage. |
+
+Prefer narrow commands over `pnpm test` while iterating — the full suite is slow.
+
+## Code Style
+
+- **Rust:** 100-char max width, 4-space indent. Clippy runs with `avoid-breaking-exported-api = false`; all warnings are denied in CI.
+- **TypeScript / JSX:** Prettier — single quotes, 2-space indent, 100-char width, trailing commas (es5), Tailwind CSS plugin for class ordering.
+- **Path aliases:** `@/` → `apps/desktop/src/`; `@mcpmux/ui` → `packages/ui`.
+- **No emojis in code or commits** unless the user explicitly asks for them.
+- **Comments:** only when the *why* is non-obvious. Identifiers should explain the *what*.
+
+## Commit & PR Guidelines
+
+- Commits must be **signed off** (DCO): `git commit -s -m "..."`. CI rejects unsigned commits.
+- Prefer conventional-style subjects — releases use release-please for semantic versioning.
+- PRs follow [`.github/pull_request_template.md`](.github/pull_request_template.md): describe the change, how you tested, and check the `pnpm test` / `pnpm lint` / `pnpm typecheck` boxes.
+- Don't bypass hooks (`--no-verify`) or DCO signing unless explicitly told to.
+
+## Platform Gotchas
+
+### Child-process flags
+
+Anything that spawns a child process (stdio MCP servers, installers, etc.) **must** go through `mcpmux_gateway::pool::transport::configure_child_process_platform()`. That helper applies:
+
+- **Windows:** `CREATE_NO_WINDOW` (`0x08000000`) — release builds use `windows_subsystem = "windows"`, so without this the OS briefly flashes a console window when a child starts.
+- **Unix:** `process_group(0)` — stops SIGINT/SIGTSTP from the parent terminal from tearing down the child.
+
+`tokio::process::Command` already exposes `creation_flags()` (Windows) and `process_group()` (Unix). **Do not** import `std::os::*::process::CommandExt` — those traits are unused with Tokio's `Command` and trigger clippy.
+
+### Cross-platform CI
+
+- The pre-commit hook runs `cargo clippy --workspace -- -D warnings` on your dev machine.
+- `#[cfg(unix)]` only compiles on Unix; `#[cfg(windows)]` only on Windows. CI is Linux, so Windows-gated code is **not** linted in CI, and Unix-gated code is not linted on a Windows dev box.
+- When you touch platform-conditional code, check the *other* platform compiles before pushing — CI won't catch a Windows-only clippy regression.
+
+### Secret handling
+
+- Never log tokens, API keys, headers with auth material, or raw OAuth responses. Use the existing sanitised-log helpers in `mcpmux-gateway`.
+- Credentials encrypt at rest via AES-256-GCM in SQLite plus DPAPI (Windows) / OS keychain (macOS, Linux). Don't add new code paths that persist secrets any other way.
+- Secrets should be wiped from memory after use via `zeroize`.
+- The gateway binds to `127.0.0.1`. Don't bind to `0.0.0.0` or expose it on the network.
+
+## Frontend Notes
+
+- Entry point: `apps/desktop/src/main.tsx` → `App.tsx`.
+- Global state: a single Zustand store at `src/stores/appStore.ts`.
+- Key hooks: `useServerManager` (server CRUD), `useSpaces` (workspace switching), `useDomainEvents` (Rust-side EventBus listener), `useDataSync`.
+- UI: React 19, Tailwind CSS, Lucide icons, Monaco Editor for JSON config surfaces.
+- Open external URLs through `openExternal` in `apps/desktop/src/lib/contribute.ts` — it routes through the Tauri opener plugin so links open in the user's default browser, not the webview.
+- For UI changes, launch `pnpm dev` and exercise the feature in the running app before reporting done — typecheck and tests verify correctness, not UX regressions.
+
+## Rust Architecture Cues
+
+- Cross-layer communication goes through the `EventBus` in `mcpmux-core`. Prefer emitting a domain event over reaching across module boundaries directly.
+- Storage is behind repository traits — don't call SQLx or SQLite APIs directly from gateway or app code; add or use a repo method.
+- Services are wired up via the `ApplicationServices` builders in `mcpmux-core`. New services should follow the same DI pattern.
+
+## MCP Specification
+
+The full MCP spec is vendored at `../modelcontextprotocol/docs/specification/`. Default to the latest stable version (`2025-11-25`) and **read the relevant section before** implementing or modifying protocol behaviour (transports, lifecycle, capability negotiation, OAuth flows, tools / resources / prompts). For features targeting a specific protocol version, use that version's folder.
+
+## Server Definitions
+
+Server catalog entries live in the separate [`mcp-servers`](https://github.com/mcpmux/mcp-servers) repo — **not here**. If a task involves adding, editing, or fixing a server definition, switch to that repo and follow its `AGENTS.md`.
+
+## Things Not To Do
+
+- Don't add backwards-compatibility shims, deprecated aliases, or `// removed` placeholder comments when removing code — delete it cleanly.
+- Don't introduce new fallbacks or input validation for states that are already framework-guaranteed. Trust internal invariants; validate only at the boundary (user input, external APIs).
+- Don't edit generated files: `CHANGELOG.md`, release-please manifests, `bundle/*.json` in sibling repos, `packages/ui/dist`.
+- Don't commit screenshots, videos, or large binaries to the repo — link out instead.

Cargo.toml

@@ -58,7 +58,7 @@ os_pipe = "1"
 
 # MCP Protocol
 # NOTE: Never use local path dependency - E:\one-mcp\rust-sdk is for source lookup only
-rmcp = { version = "0.17.0", features = [
+rmcp = { version = "1.5", features = [
     "client",
     "server",
     "transport-io",

README.md

@@ -77,7 +77,7 @@ Lightweight and cross-platform — built in Rust with Tauri 2, McpMux uses minim
 }
 ```
 
-**3.** Done. Every tool from every server is available in every client, right now.
+**3.** Done. Connected clients see a small fixed meta-tool surface (~12 `mcpmux_*` tools). Backend tools are discovered via **`mcpmux_search_tools`** → **`mcpmux_get_tool_schema`** → **`mcpmux_invoke_tool`**, keeping context windows lean. Optionally surface individual hot-path tools into `tools/list` per FeatureSet.
 
 McpMux routes calls to the right server, refreshes OAuth tokens automatically, and keeps credentials encrypted in your OS keychain — you never think about it again.
 
@@ -109,10 +109,37 @@ Create isolated Spaces — each with their own servers, credentials, and permiss
 
 ### Control What Each Client Can Do
 
-Not every AI client should have the same power. Create Feature Sets — permission bundles that control exactly which tools, prompts, and resources a client can access. Build a "Read Only" set for cautious workflows, a "React Development" set with just GitHub and Filesystem, or a "Full Stack Dev" set with everything. Assign them per-client so each tool only goes where you want it.
+Not every AI client should have the same power. Create Feature Sets — permission bundles that control exactly which tools a client can **invoke** (search + invoke ACL). In the editor, the **checkbox** includes a tool in that ACL; the **Surface** button (optional, per row) promotes an included tool into the client's `tools/list` for one-hop hot paths. Build a "Read Only" set for cautious workflows, a "React Development" set with just GitHub and Filesystem, or a "Full Stack Dev" set with everything. Assign them per-client so each tool only goes where you want it.
 
 ![Feature Sets — granular per-server tool selection](docs/screenshots/featureset-detail.png)
 
+### Self-Management Meta Tools (mcpmux_*)
+
+Connected AI clients see a fixed ~12-tool meta surface instead of every backend tool definition. FeatureSets define what is **invokable**; optional **surfaced** tools (0–N per set) can be promoted into `tools/list` for one-hop hot paths. Workspace bindings pin stable per-folder toolsets; session enable/disable gates server activity without bloating context.
+
+McpMux exposes a built-in `mcpmux_*` tool namespace for search → schema → invoke workflows:
+
+1. Call **`mcpmux_list_servers`** — server-level manifest with per-server status: `enabled_via_binding`, `enabled_via_session`, `disabled_via_session`, or `inactive`.
+2. Call **`mcpmux_enable_server`** or **`mcpmux_disable_server`** — toggle servers on or off for the session or workspace.
+3. Call **`mcpmux_search_tools`** — find invokable tools by query (respects FeatureSet ACL).
+4. Call **`mcpmux_get_tool_schema`** — load parameter schemas before invoking.
+5. Call **`mcpmux_invoke_tool`** — invoke any permitted backend tool through one entry point.
+
+| Tool | Type | Purpose |
+| ---- | ---- | ------- |
+| `mcpmux_list_all_tools` | read | Full tool roster in the resolved Space (diagnostic) |
+| `mcpmux_list_feature_sets` | read | FeatureSets available in the resolved Space |
+| `mcpmux_list_servers` | read | Server-level manifest with status |
+| `mcpmux_search_tools` | read | Search invokable tools with optional schema detail |
+| `mcpmux_get_tool_schema` | read | Load input schemas before invoke |
+| `mcpmux_invoke_tool` | read | Invoke a backend tool by server_id + tool name |
+| `mcpmux_enable_server` | write | Enable a server (session or workspace scope) |
+| `mcpmux_disable_server` | write | Disable a server (session or workspace scope) |
+| `mcpmux_create_feature_set` | write | Create a custom FeatureSet (optional `surfaced_tools[]`) |
+| `mcpmux_bind_current_workspace` | write | Bind the session's workspace root to FeatureSets |
+
+In the desktop app: **Settings → Self-management tools** toggles the whole namespace and optional approval for session-scope overrides. **Workspaces → live folder inspector → Active session overrides** shows per-session enabled/disabled servers and lets you clear overrides with one click.
+
 ### See and Manage Every Connected Client
 
 Cursor, VS Code, Windsurf, Claude Code — see every AI client connected to your gateway in real time. Click any client to manage its workspace, grant or revoke feature sets, and see exactly which tools it can access. New clients authenticate via OAuth with a one-click approval flow.