@evantahler/mcpx 0.15.8 → 0.15.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude/skills/mcpx.md +115 -75
- package/package.json +1 -1
package/.claude/skills/mcpx.md
CHANGED
|
@@ -29,12 +29,15 @@ mcpx exec <server> <tool> '<json args>'
|
|
|
29
29
|
mcpx exec <server> <tool> -f params.json
|
|
30
30
|
```
|
|
31
31
|
|
|
32
|
+
Output is JSON when piped. Use `--json` to force JSON output in any context — prefer this when you need to parse results programmatically.
|
|
33
|
+
|
|
32
34
|
## Rules
|
|
33
35
|
|
|
34
36
|
- Always search before executing — don't assume tool names exist
|
|
35
37
|
- Always inspect the schema before executing — validate you have the right arguments
|
|
36
38
|
- Use `mcpx search -k` for exact name matching
|
|
37
39
|
- Pipe results through `jq` when you need to extract specific fields
|
|
40
|
+
- Use `--json` when parsing output programmatically (automatic when piped, but explicit is safer)
|
|
38
41
|
- Use `-v` for verbose debugging (HTTP details + JSON-RPC protocol messages) if an exec fails unexpectedly
|
|
39
42
|
- Use `-l debug` to see all server log messages, or `-l error` for errors only
|
|
40
43
|
|
|
@@ -58,16 +61,22 @@ mcpx exec github search_repositories '{"query":"mcp"}' \
|
|
|
58
61
|
# Read args from stdin
|
|
59
62
|
echo '{"path":"./README.md"}' | mcpx exec filesystem read_file
|
|
60
63
|
|
|
61
|
-
# Pipe from a file
|
|
62
|
-
cat params.json | mcpx exec server tool
|
|
63
|
-
|
|
64
64
|
# Read args from a file with --file flag
|
|
65
65
|
mcpx exec filesystem read_file -f params.json
|
|
66
66
|
```
|
|
67
67
|
|
|
68
|
-
##
|
|
68
|
+
## Troubleshooting
|
|
69
|
+
|
|
70
|
+
- **"Not authenticated" / 401 error** → Run `mcpx auth <server>` to start the OAuth flow
|
|
71
|
+
- **Exec timeout** → Use `-v` to see where it stalls; set `MCP_TIMEOUT=<seconds>` to increase the timeout (default: 1800)
|
|
72
|
+
- **Search returns no results** → Try `mcpx search -k "*keyword*"` for glob matching, or `mcpx index` to rebuild the search index
|
|
73
|
+
- **Missing or stale tools** → Run `mcpx index` to rebuild; any command that connects to a server also auto-updates the index
|
|
74
|
+
- **Server won't connect** → Run `mcpx ping <server>` to check connectivity; use `-v` for protocol-level details
|
|
75
|
+
- **Auth token expired** → Run `mcpx auth <server> -r` to force a token refresh
|
|
76
|
+
|
|
77
|
+
## Long-running tools (Tasks)
|
|
69
78
|
|
|
70
|
-
Some tools support async execution via MCP Tasks. mcpx auto-detects this
|
|
79
|
+
Some tools support async execution via MCP Tasks. mcpx auto-detects this.
|
|
71
80
|
|
|
72
81
|
```bash
|
|
73
82
|
# Default: waits for the task to complete, showing progress
|
|
@@ -76,90 +85,121 @@ mcpx exec my-server long_running_tool '{"input": "data"}'
|
|
|
76
85
|
# Return immediately with a task handle (for scripting/polling)
|
|
77
86
|
mcpx exec my-server long_running_tool '{"input": "data"}' --no-wait
|
|
78
87
|
|
|
79
|
-
# Check task status
|
|
88
|
+
# Check task status / retrieve result / cancel
|
|
80
89
|
mcpx task get my-server <taskId>
|
|
81
|
-
|
|
82
|
-
# Retrieve the result once complete
|
|
83
90
|
mcpx task result my-server <taskId>
|
|
84
|
-
|
|
85
|
-
# List all tasks on a server
|
|
86
|
-
mcpx task list my-server
|
|
87
|
-
|
|
88
|
-
# Cancel a running task
|
|
89
91
|
mcpx task cancel my-server <taskId>
|
|
92
|
+
mcpx task list my-server
|
|
90
93
|
```
|
|
91
94
|
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
## 5. Elicitation (Server-Requested Input)
|
|
95
|
-
|
|
96
|
-
Some servers request user input mid-operation (e.g., confirmations, auth flows). mcpx handles this automatically:
|
|
97
|
-
|
|
98
|
-
```bash
|
|
99
|
-
# Interactive — prompts appear in the terminal
|
|
100
|
-
mcpx exec my-server deploy_tool '{"target": "staging"}'
|
|
101
|
-
# Server requests input: Confirm deployment
|
|
102
|
-
# *Confirm [y/n]: y
|
|
103
|
-
|
|
104
|
-
# Non-interactive — decline all elicitation (for scripts/CI)
|
|
105
|
-
mcpx exec my-server deploy_tool '{"target": "staging"}' --no-interactive
|
|
95
|
+
## Elicitation (Server-Requested Input)
|
|
106
96
|
|
|
107
|
-
|
|
108
|
-
echo '{"action":"accept","content":{"confirm":true}}' | \
|
|
109
|
-
mcpx exec my-server deploy_tool '{"target": "staging"}' --json
|
|
110
|
-
```
|
|
97
|
+
Some servers request user input mid-operation. mcpx handles this automatically in interactive mode. Use `-N` / `--no-interactive` to decline all elicitation (for scripts/CI), or `--json` to handle elicitation programmatically via stdin/stdout.
|
|
111
98
|
|
|
112
99
|
## Authentication
|
|
113
100
|
|
|
114
|
-
Some HTTP servers require OAuth. If you see an "Not authenticated" error:
|
|
115
|
-
|
|
116
101
|
```bash
|
|
117
|
-
mcpx auth <server>
|
|
118
|
-
mcpx auth <server> -s
|
|
119
|
-
mcpx auth <server> -r
|
|
120
|
-
mcpx
|
|
102
|
+
mcpx auth <server> # authenticate via browser
|
|
103
|
+
mcpx auth <server> -s # check token status and TTL
|
|
104
|
+
mcpx auth <server> -r # force token refresh
|
|
105
|
+
mcpx auth <server> --no-index # authenticate without rebuilding search index
|
|
106
|
+
mcpx deauth <server> # remove stored auth
|
|
121
107
|
```
|
|
122
108
|
|
|
123
109
|
## Available commands
|
|
124
110
|
|
|
125
111
|
| Command | Purpose |
|
|
126
112
|
| -------------------------------------- | --------------------------------- |
|
|
127
|
-
| `mcpx`
|
|
128
|
-
| `mcpx servers`
|
|
129
|
-
| `mcpx -d`
|
|
130
|
-
| `mcpx info <server>`
|
|
131
|
-
| `mcpx info <server> <tool>`
|
|
132
|
-
| `mcpx exec <server>`
|
|
133
|
-
| `mcpx exec <server> <tool> '<json>'`
|
|
134
|
-
| `mcpx exec <server> <tool> -f file`
|
|
135
|
-
| `mcpx search "<query>"`
|
|
136
|
-
| `mcpx search -k "<pattern>"`
|
|
137
|
-
| `mcpx search -q "<query>"`
|
|
138
|
-
| `mcpx search -n <number> "<query>"`
|
|
139
|
-
| `mcpx index`
|
|
140
|
-
| `mcpx index -i`
|
|
141
|
-
| `mcpx auth <server>`
|
|
142
|
-
| `mcpx auth <server> -s`
|
|
113
|
+
| `mcpx` | List all servers and tools |
|
|
114
|
+
| `mcpx servers` | List servers (name, type, detail) |
|
|
115
|
+
| `mcpx -d` | List with descriptions |
|
|
116
|
+
| `mcpx info <server>` | Server overview (version, capabilities, tools) |
|
|
117
|
+
| `mcpx info <server> <tool>` | Show tool schema |
|
|
118
|
+
| `mcpx exec <server>` | List tools for a server |
|
|
119
|
+
| `mcpx exec <server> <tool> '<json>'` | Execute a tool |
|
|
120
|
+
| `mcpx exec <server> <tool> -f file` | Execute with args from file |
|
|
121
|
+
| `mcpx search "<query>"` | Search tools (keyword + semantic) |
|
|
122
|
+
| `mcpx search -k "<pattern>"` | Keyword/glob search only |
|
|
123
|
+
| `mcpx search -q "<query>"` | Semantic search only |
|
|
124
|
+
| `mcpx search -n <number> "<query>"` | Limit number of results (default: 10) |
|
|
125
|
+
| `mcpx index` | Build/rebuild search index |
|
|
126
|
+
| `mcpx index -i` | Show index status |
|
|
127
|
+
| `mcpx auth <server>` | Authenticate with OAuth |
|
|
128
|
+
| `mcpx auth <server> -s` | Check token status and TTL |
|
|
143
129
|
| `mcpx auth <server> -r` | Force token refresh |
|
|
144
|
-
| `mcpx
|
|
145
|
-
| `mcpx
|
|
146
|
-
| `mcpx ping
|
|
147
|
-
| `mcpx
|
|
148
|
-
| `mcpx add <name> --
|
|
149
|
-
| `mcpx add <name> --url <url
|
|
150
|
-
| `mcpx remove <name>`
|
|
151
|
-
| `mcpx skill install --claude`
|
|
152
|
-
| `mcpx skill install --cursor`
|
|
153
|
-
| `mcpx resource`
|
|
154
|
-
| `mcpx resource <server>`
|
|
155
|
-
| `mcpx resource <server> <uri>`
|
|
156
|
-
| `mcpx prompt`
|
|
157
|
-
| `mcpx prompt <server>`
|
|
158
|
-
| `mcpx prompt <server> <name> '<json>'` | Get a specific prompt
|
|
159
|
-
| `mcpx
|
|
160
|
-
| `mcpx
|
|
161
|
-
| `mcpx
|
|
162
|
-
| `mcpx task
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
130
|
+
| `mcpx auth <server> --no-index` | Authenticate without rebuilding index |
|
|
131
|
+
| `mcpx deauth <server>` | Remove stored authentication |
|
|
132
|
+
| `mcpx ping` | Check connectivity to all servers |
|
|
133
|
+
| `mcpx ping <server> [server2...]` | Check specific server(s) |
|
|
134
|
+
| `mcpx add <name> --command <cmd>` | Add a stdio MCP server |
|
|
135
|
+
| `mcpx add <name> --url <url>` | Add an HTTP MCP server |
|
|
136
|
+
| `mcpx remove <name>` | Remove an MCP server |
|
|
137
|
+
| `mcpx skill install --claude` | Install mcpx skill for Claude |
|
|
138
|
+
| `mcpx skill install --cursor` | Install mcpx rule for Cursor |
|
|
139
|
+
| `mcpx resource` | List all resources across servers |
|
|
140
|
+
| `mcpx resource <server>` | List resources for a server |
|
|
141
|
+
| `mcpx resource <server> <uri>` | Read a specific resource |
|
|
142
|
+
| `mcpx prompt` | List all prompts across servers |
|
|
143
|
+
| `mcpx prompt <server>` | List prompts for a server |
|
|
144
|
+
| `mcpx prompt <server> <name> '<json>'` | Get a specific prompt |
|
|
145
|
+
| `mcpx task list <server>` | List tasks on a server |
|
|
146
|
+
| `mcpx task get <server> <taskId>` | Get task status |
|
|
147
|
+
| `mcpx task result <server> <taskId>` | Retrieve completed task result |
|
|
148
|
+
| `mcpx task cancel <server> <taskId>` | Cancel a running task |
|
|
149
|
+
|
|
150
|
+
## Global flags
|
|
151
|
+
|
|
152
|
+
| Flag | Purpose |
|
|
153
|
+
| ------------------------- | -------------------------------------------------------- |
|
|
154
|
+
| `-j, --json` | Force JSON output (default when piped) |
|
|
155
|
+
| `-v, --verbose` | Show HTTP details and JSON-RPC protocol messages |
|
|
156
|
+
| `-d, --with-descriptions` | Include tool descriptions in list output |
|
|
157
|
+
| `-c, --config <path>` | Specify config file location |
|
|
158
|
+
| `-N, --no-interactive` | Decline server elicitation requests (for scripted usage) |
|
|
159
|
+
| `-S, --show-secrets` | Show full auth tokens in verbose output (unmasked) |
|
|
160
|
+
| `-l, --log-level <level>` | Minimum server log level to display (default: `warning`) |
|
|
161
|
+
|
|
162
|
+
## `add` options
|
|
163
|
+
|
|
164
|
+
| Flag | Purpose |
|
|
165
|
+
| -------------------------- | -------------------------------------- |
|
|
166
|
+
| `--command <cmd>` | Command to run (stdio server) |
|
|
167
|
+
| `--args <a1,a2,...>` | Comma-separated arguments |
|
|
168
|
+
| `--env <KEY=VAL,...>` | Comma-separated environment variables |
|
|
169
|
+
| `--cwd <dir>` | Working directory for the command |
|
|
170
|
+
| `--url <url>` | Server URL (HTTP server) |
|
|
171
|
+
| `--header <Key:Value>` | HTTP header (repeatable) |
|
|
172
|
+
| `--transport <type>` | Transport: `sse` or `streamable-http` |
|
|
173
|
+
| `--allowed-tools <t1,t2>` | Comma-separated allowed tool patterns |
|
|
174
|
+
| `--disabled-tools <t1,t2>` | Comma-separated disabled tool patterns |
|
|
175
|
+
| `-f, --force` | Overwrite if server already exists |
|
|
176
|
+
| `--no-auth` | Skip automatic OAuth after adding |
|
|
177
|
+
| `--no-index` | Skip rebuilding the search index |
|
|
178
|
+
|
|
179
|
+
## `remove` options
|
|
180
|
+
|
|
181
|
+
| Flag | Purpose |
|
|
182
|
+
| ------------- | ------------------------------------------------ |
|
|
183
|
+
| `--keep-auth` | Don't remove stored auth credentials |
|
|
184
|
+
| `--dry-run` | Show what would be removed without changing files |
|
|
185
|
+
|
|
186
|
+
## `skill install` options
|
|
187
|
+
|
|
188
|
+
| Flag | Purpose |
|
|
189
|
+
| ----------- | ------------------------------------------ |
|
|
190
|
+
| `--claude` | Install skill for Claude Code |
|
|
191
|
+
| `--cursor` | Install rule for Cursor |
|
|
192
|
+
| `--global` | Install to global location (`~/`) |
|
|
193
|
+
| `--project` | Install to project location (default) |
|
|
194
|
+
| `-f, --force` | Overwrite if file already exists |
|
|
195
|
+
|
|
196
|
+
## Environment variables
|
|
197
|
+
|
|
198
|
+
| Variable | Purpose | Default |
|
|
199
|
+
| ----------------- | --------------------------- | ---------- |
|
|
200
|
+
| `MCP_CONFIG_PATH` | Config directory path | `~/.mcpx/` |
|
|
201
|
+
| `MCP_TIMEOUT` | Request timeout (seconds) | `1800` |
|
|
202
|
+
| `MCP_CONCURRENCY` | Parallel server connections | `5` |
|
|
203
|
+
| `MCP_MAX_RETRIES` | Retry attempts | `3` |
|
|
204
|
+
| `MCP_STRICT_ENV` | Error on missing `${VAR}` | `true` |
|
|
205
|
+
| `MCP_DEBUG` | Enable debug output | `false` |
|