Skip to content

v1.6.0 — agentic supremacy #15

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Codestz merged 6 commits into from
May 3, 2026
Merged

v1.6.0 — agentic supremacy #15

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
51c50d6
release: v1.6.0 — agentic supremacy
Codestz May 3, 2026
374a3b6
chore: bump Go to 1.26.2 to clear stdlib vulnerabilities
Codestz May 3, 2026
305c2b9
fix: result cache must invalidate when underlying file changes
Codestz May 3, 2026
7a0d64e
fix: remove result cache — correctness over speed
Codestz May 3, 2026
db13a77
fix: dashboard banner fires only on real tool calls
Codestz May 3, 2026
ec90b7c
fix: dashboard URL is on-demand, never auto-printed
Codestz May 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 27 additions & 56 deletions .claude/MCPX.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,66 +1,37 @@
# mcpx — MCP Server CLI Proxy
# mcpx

mcpx wraps MCP servers into CLI tools. Call them via Bash instead of loading schemas into context.
Call MCP tools through `mcpx <server> <tool> --flags`. Don't load native MCP — use the CLI commands below.

## Quick Reference
## Servers

```bash
mcpx list # List configured servers
mcpx list <server> -v # List all tools with flags
mcpx <server> --help # Show server tools
mcpx <server> <tool> --help # Show tool flags
mcpx <server> <tool> --flags # Call a tool
mcpx <server> <tool> --stdin # Read args from stdin JSON
mcpx <server> <tool> --json # Output raw JSON
mcpx daemon status # Show running daemons
```
- **serena** *(daemon)*

## Configured Servers
## Compose

- **serena** — `serena` (daemon)
| Need | How |
|---|---|
| Standard call | `mcpx <server> <tool> --flag value` |
| Large arg from file | `--body @/path/to/file` |
| Read body from stdin | `--body @-` or `--body -` |
| Pass full args as JSON | `printf '{...}' \| mcpx <server> <tool> --stdin` |
| Mix stdin + flags | `--stdin --flag value` (flags win) |
| Extract one JSON field | `--pick path.to.field` |
| Raw JSON output | `--json` |
| Per-call timeout | `--timeout 60s` (Go duration) |
| Show resolved command | `--dry-run` |
| Args skeleton | `mcpx <server> <tool> --example` |
| Type-check args | `mcpx <server> <tool> --validate-args ...` |

## Usage Pattern
## Discover

1. Discover: `mcpx <server> --help` to see available tools
2. Inspect: `mcpx <server> <tool> --help` to see flags
3. Call: `mcpx <server> <tool> --flag value`
4. For long args: `printf '{"key":"value"}' | mcpx <server> <tool> --stdin`
| Need | How |
|---|---|
| Find the right tool by intent | `mcpx find "<query>"` |
| One-line list of a server's tools | `mcpx <server> --help` |
| Full schema for one tool | `mcpx <server> <tool> --help` |
| Run many tool calls in parallel | `mcpx batch < calls.jsonl` |

## Large Content: @file syntax
## Exit codes

Any string flag accepts `@/path` to read from a file or `@-`/`-` to read from stdin:
```bash
mcpx <server> <tool> --body @/tmp/code.go # Read file into --body
mcpx <server> <tool> --body @- # Read stdin into --body
mcpx <server> <tool> --body - # Same (backward compat)
```

## Output Extraction: --pick

Extract a JSON field from the result without jq:
```bash
mcpx <server> <tool> --pick field.path # Dot-separated path
mcpx <server> <tool> --pick items.0.name # Array index access
```

## Timeout Override: --timeout

Override the default call timeout for a single invocation:
```bash
mcpx <server> <tool> --timeout 60s # Go duration format
```

## Stdin Merge

`--stdin` can be combined with CLI flags. Flags win on conflict:
```bash
echo '{"body":"content"}' | mcpx <server> <tool> --stdin --name_path Foo
```

## Tips for AI Agents

- Use `--body @/tmp/file` for large content to avoid shell escaping
- Use `--pick field` instead of piping through jq for single fields
- Combine `--stdin` with flags for mixed large+small arguments
- Use `--timeout 120s` for long-running operations
`0` ok · `1` tool error · `2` config · `3` connection · `4` timeout · `5` policy denied · `6` tool not found.
@SERENA.md
130 changes: 68 additions & 62 deletions .claude/SERENA.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,64 +1,70 @@
# serena (21 tools)

Usage: `mcpx serena <tool> --flags`

**list_dir** — Lists files and directories in the given directory (optionally with recursion).
--max_answer_chars <int>, --recursive <bool> *, --relative_path <string> *, --skip_ignored_files <bool>

**find_file** — Finds non-gitignored files matching the given file mask within the given relative path.
--file_mask <string> *, --relative_path <string> *

**search_for_pattern** — Offers a flexible search for arbitrary patterns in the codebase, including the
--context_lines_after <int>, --context_lines_before <int>, --max_answer_chars <int>, --paths_exclude_glob <string>, --paths_include_glob <string>, --relative_path <string>, --restrict_search_to_code_files <bool>, --substring_pattern <string> *

**get_symbols_overview** — Use this tool to get a high-level understanding of the code symbols in a file.
--depth <int>, --max_answer_chars <int>, --relative_path <string> *

**find_symbol** — Retrieves information on all symbols/code entities (classes, methods, etc.) based on the given name path pattern.
--depth <int>, --exclude_kinds <json[]>, --include_body <bool>, --include_info <bool>, --include_kinds <json[]>, --max_answer_chars <int>, --name_path_pattern <string> *, --relative_path <string>, --substring_matching <bool>

**find_referencing_symbols** — Finds references to the symbol at the given `name_path`.
--exclude_kinds <json[]>, --include_kinds <json[]>, --max_answer_chars <int>, --name_path <string> *, --relative_path <string> *

**replace_symbol_body** — Replaces the body of the symbol with the given `name_path`.
--body <string> *, --name_path <string> *, --relative_path <string> *

**insert_after_symbol** — Inserts the given body/content after the end of the definition of the given symbol (via the symbol's location).
--body <string> *, --name_path <string> *, --relative_path <string> *

**insert_before_symbol** — Inserts the given content before the beginning of the definition of the given symbol (via the symbol's location).
--body <string> *, --name_path <string> *, --relative_path <string> *

**rename_symbol** — Renames the symbol with the given `name_path` to `new_name` throughout the entire codebase.
--name_path <string> *, --new_name <string> *, --relative_path <string> *

**write_memory** — Write information (utf-8-encoded) about this project that can be useful for future tasks to a memory in md format.
--content <string> *, --max_chars <int>, --memory_name <string> *

**read_memory** — Reads the contents of a memory.
--memory_name <string> *

**list_memories** — Lists available memories, optionally filtered by topic.
--topic <string>

**delete_memory** — Delete a memory, only call if instructed explicitly or permission was granted by the user.
--memory_name <string> *

**rename_memory** — Rename or move a memory, use "/" in the name to organize into topics.
--new_name <string> *, --old_name <string> *

**edit_memory** — Replaces content matching a regular expression in a memory.
--allow_multiple_occurrences <bool>, --memory_name <string> *, --mode <string> *, --needle <string> *, --repl <string> *

**activate_project** — Activates the project with the given name or path.
--project <string> *

**get_current_config** — Print the current configuration of the agent, including the active and available projects, tools, contexts, and modes.

**check_onboarding_performed** — Checks whether project onboarding was already performed.

**onboarding** — Call this tool if onboarding was not performed yet.

**initial_instructions** — Provides the 'Serena Instructions Manual', which contains essential information on how to use the Serena toolbox.
# serena

`mcpx serena <tool> --flags` — 21 tools. Use `--help` / `--example` / `--validate-args` per tool.

## Tool selector

| Tool | What it does | Required |
|---|---|---|
| `list_dir` | Lists files and directories in the given directory (optionally with recursion). | `--relative_path` `--recursive` |
| `find_file` | Finds non-gitignored files matching the given file mask within the given relative path. | `--file_mask` `--relative_path` |
| `search_for_pattern` | Offers a flexible search for arbitrary patterns in the codebase, including the | `--substring_pattern` |
| `get_symbols_overview` | Use this tool to get a high-level understanding of the code symbols in a file. | `--relative_path` |
| `find_symbol` | Retrieves information on all symbols/code entities (classes, methods, etc.) based on the given name path pattern. | `--name_path_pattern` |
| `find_referencing_symbols` | Finds references to the symbol at the given `name_path`. | `--name_path` `--relative_path` |
| `replace_symbol_body` | Replaces the body of the symbol with the given `name_path`. | `--name_path` `--relative_path` `--body` |
| `insert_after_symbol` | Inserts the given body/content after the end of the definition of the given symbol (via the symbol's location). | `--name_path` `--relative_path` `--body` |
| `insert_before_symbol` | Inserts the given content before the beginning of the definition of the given symbol (via the symbol's location). | `--name_path` `--relative_path` `--body` |
| `rename_symbol` | Renames the symbol with the given `name_path` to `new_name` throughout the entire codebase. | `--name_path` `--relative_path` `--new_name` |
| `write_memory` | Write information (utf-8-encoded) about this project that can be useful for future tasks to a memory in md format. | `--memory_name` `--content` |
| `read_memory` | Reads the contents of a memory. | `--memory_name` |
| `list_memories` | Lists available memories, optionally filtered by topic. | — |
| `delete_memory` | Delete a memory, only call if instructed explicitly or permission was granted by the user. | `--memory_name` |
| `rename_memory` | Rename or move a memory, use "/" in the name to organize into topics. | `--old_name` `--new_name` |
| `edit_memory` | Replaces content matching a regular expression in a memory. | `--memory_name` `--needle` `--repl` `--mode` |
| `activate_project` | Activates the project with the given name or path. | `--project` |
| `get_current_config` | Print the current configuration of the agent, including the active and available projects, tools, contexts, and modes. | — |
| `check_onboarding_performed` | Checks whether project onboarding was already performed. | — |
| `onboarding` | Call this tool if onboarding was not performed yet. | — |
| `initial_instructions` | Provides the 'Serena Instructions Manual', which contains essential information on how to use the Serena toolbox. | — |

## Edit-tool safety

For `replace_symbol_body`, body must start AFTER the declaration keyword — the keyword is preserved by the server. mcpx warns on duplicates and (for `.go`) re-parses the file post-edit.

| Language | ✓ correct | ✗ wrong |
|---|---|---|
| Go | `Foo struct{...}` / `Foo() error {...}` | `type Foo...` / `func Foo...` |
| Python | `foo():\n ...` | `def foo():` |
| TS / JS | `bar() { ... }` | `function bar()` / `class Bar` |
| Rust | `foo() { ... }` | `fn foo()` / `struct Foo` |

## Notes

- Symbol-aware lookups (`find_symbol`) are faster and more accurate than text search (`search_for_pattern`) for code symbols — prefer them.

## Compact reference

- `list_dir` --max_answer_chars <int> --recursive <bool>* --relative_path <string>* --skip_ignored_files <bool>
- `find_file` --file_mask <string>* --relative_path <string>*
- `search_for_pattern` --context_lines_after <int> --context_lines_before <int> --max_answer_chars <int> --paths_exclude_glob <string> --paths_include_glob <string> --relative_path <string> --restrict_search_to_code_files <bool> --substring_pattern <string>*
- `get_symbols_overview` --depth <int> --max_answer_chars <int> --relative_path <string>*
- `find_symbol` --depth <int> --exclude_kinds <json[]> --include_body <bool> --include_info <bool> --include_kinds <json[]> --max_answer_chars <int> --name_path_pattern <string>* --relative_path <string> --substring_matching <bool>
- `find_referencing_symbols` --exclude_kinds <json[]> --include_kinds <json[]> --max_answer_chars <int> --name_path <string>* --relative_path <string>*
- `replace_symbol_body` --body <string>* --name_path <string>* --relative_path <string>*
- `insert_after_symbol` --body <string>* --name_path <string>* --relative_path <string>*
- `insert_before_symbol` --body <string>* --name_path <string>* --relative_path <string>*
- `rename_symbol` --name_path <string>* --new_name <string>* --relative_path <string>*
- `write_memory` --content <string>* --max_chars <int> --memory_name <string>*
- `read_memory` --memory_name <string>*
- `list_memories` --topic <string>
- `delete_memory` --memory_name <string>*
- `rename_memory` --new_name <string>* --old_name <string>*
- `edit_memory` --allow_multiple_occurrences <bool> --memory_name <string>* --mode <string>* --needle <string>* --repl <string>*
- `activate_project` --project <string>*
- `get_current_config`
- `check_onboarding_performed`
- `onboarding`
- `initial_instructions`

`*` = required
3 changes: 2 additions & 1 deletion .mcpx/config.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,8 @@ servers:
args:
- start-mcp-server
- --context=claude-code
- --project-from-cwd
- --project
- "$(mcpx.project_root)"
transport: stdio
daemon: true
startup_timeout: 30s
64 changes: 64 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,70 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [1.6.0] - 2026-05-03

The "Agentic Supremacy" release. mcpx becomes a measurable, observable, and intelligent control plane: every call is recorded, every schema is cached, every server is one `mcpx find` away, and an always-on dashboard makes ROI visible.

### Added — Foundation

- **JSONL stats** (`internal/stats/`) — every tool call writes one line to `~/.mcpx/stats.jsonl`: timestamp, args, latency, cache hits, exit code, tokens saved vs native MCP loading. Async writer; never blocks the caller.
- **Schema cache** (`internal/schemacache/`) — `tools/list` (and prompts/resources) cached at `~/.mcpx/cache/schemas/<key>.json` with TTL. First call per server is slow; everything after is instant. Computes `native_baseline_tokens` once at populate time so the stats writer can quote real savings.
- **Result cache: deliberately not shipped.** Caching tool RESPONSES is a correctness footgun — recursive searches, multi-file reads, network-backed tools, and any non-filesystem state can all return stale data inside a TTL. mcpx is the trustworthy intermediary; we'd rather make the round-trip than risk acting on stale snapshots. If a future MCP server adopts `readOnlyHint: true` annotations widely, server-driven result caching becomes safe to add back.
- **Schema normalizer** — handles JSON Schema union types (`type: ["string","null"]`), `oneOf`/`anyOf`/`allOf`, `$ref`; unknown keywords preserved in `Ext`. Fixes #14 (Sentry MCP server initialization).

### Added — Agent superpowers

- **`mcpx find <query>`** — BM25-ranked tool search across every configured server. ~80 tokens for top candidates instead of 5–15K tokens for `mcpx list -v`.
- **`mcpx batch`** — NDJSON in/out, parallel by default, single client per server reused across the entire batch.
- **`mcpx <server> <tool> --example`** — JSON skeleton with placeholder values from the normalized schema.
- **`mcpx <server> <tool> --validate-args ...`** — type/required check without invoking the tool.
- **Default-compact help** — `mcpx <server> --help` is one line per tool with required flags surfaced. Add `--full` for descriptions.
- **Typo remediation** — Levenshtein-2 "did you mean…" suggestions on tool-not-found and unknown-flag errors.
- **Pre/post edit guards** — `replace_symbol_body` calls are warned when the body starts with a duplicate declaration keyword (Go, Python, TS, JS, Rust, Ruby, Java, Kotlin, Swift). For `.go` files the modified file is re-parsed and `file:line:col` is surfaced when the edit broke syntax.

### Added — Operator surfaces

- **`mcpx gain`** — premium terminal dashboard: hero metric (tokens saved), 7-day sparkline, top-tools bars, top-savers, server health, recent calls. Subcommands: `--by tool|server|day`, `--history N`, `--suggest`, `--watch`, `--all`, `--project`, `--since`, `--json`.
- **Always-on web dashboard** — auto-spawned on first call. Token-protected, 127.0.0.1-only, idle-shutdown after 1h, opt-out via `MCPX_UI=off` or `ui.enabled: false`. Single-page UI: project sidebar, time range tabs (1h/24h/7d/30d/all), token efficiency bar, top tools, server health, click-to-inspect drawer, SSE live tail, regex filter (`/`).
- **`mcpx ui status|stop|open|disable`** — dashboard daemon controls.
- **`mcpx doctor`** — config + command path + secret resolution + daemon liveness + initialize + tools/list checks. `--json` for machine-readable output.

### Changed

- **Structured exit codes** — `0` ok · `1` tool error · `2` config · `3` connection · `4` timeout · `5` policy denied · `6` tool not found.
- **`mcpx version`** warns loudly on `+dirty` builds (so leaked debug code from local builds doesn't silently propagate).
- **`mcpx configure`** rewritten — generates an agent-grounded `MCPX.md` (composition + discover + exit codes) and per-server `<SERVER>.md` files (tool-selector table + compact reference). The `--format compact` flag is now hidden; output is agent-optimized by default. Edit-tool safety guidance only emitted for servers that expose body-mutation tools.
- Client version bumped to `1.6.0` in the MCP handshake.

### New packages

- `internal/stats/` — JSONL writer (async, drop-on-overflow), reader, aggregator (top-K, p95, daily buckets, hit rates).
- `internal/schemacache/` — schema cache, result cache, idempotence detection.
- `internal/find/` — BM25 ranker (snake/camel splitting, name-coverage bonus, plural stem).
- `internal/render/` — terminal primitives (Box, Bar, Sparkline, FormatNumber/Duration/Percent, term width).
- `internal/ui/` — dashboard daemon (lazy supervisor, HTTP, SSE, embedded HTML/CSS/JS).

### Config additions

```yaml
gain:
enabled: true
tokenizer: estimate # bytes ÷ 4; honest approximation of Claude tokenization
retain_days: 30
stats_path: "" # default: ~/.mcpx/stats.jsonl

cache:
schema_ttl: 5m # only the schema cache is shipped — see notes above

ui:
enabled: true
port: 7878 # 0 = ephemeral
bind: 127.0.0.1
idle_timeout: 1h
```

Environment overrides: `MCPX_AGENT`, `MCPX_CACHE`, `MCPX_UI`, `MCPX_VERBOSE`.

## [1.5.0] - 2026-03-30

### Added
Expand Down
Loading
Loading