@e4779/skills 0.0.0-stage → 0.1.1
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/chrome-devtools/README.md +76 -0
- package/chrome-devtools/SKILL.md +277 -0
- package/chrome-devtools/references/recipes.md +379 -0
- package/chrome-devtools/references/setup.md +138 -0
- package/drawio/SKILL.md +395 -0
- package/gh-cli/SKILL.md +83 -0
- package/grill/SKILL.md +72 -0
- package/layout-check/README.md +32 -0
- package/layout-check/SKILL.md +416 -0
- package/layout-check/scripts/layoutProbe.mjs +539 -0
- package/mcpls/SKILL.md +261 -0
- package/mcpls/references/configuration.md +131 -0
- package/mcpls/references/install.md +13 -0
- package/mcporter/SKILL.md +90 -0
- package/mindmap/SKILL.md +46 -0
- package/mindmap/references/drawio-recipe.md +60 -0
- package/mindmap/references/mindmap-design.md +63 -0
- package/opensource-contribution/SKILL.md +119 -0
- package/package.json +33 -5
- package/shell-taste/.shellcheckrc +16 -0
- package/shell-taste/SKILL.md +95 -0
- package/shell-taste/references/handbook/dialects.md +168 -0
- package/shell-taste/references/handbook/dom/01-output-logging.md +245 -0
- package/shell-taste/references/handbook/dom/02-errors-exit.md +48 -0
- package/shell-taste/references/handbook/dom/03-installation-setup.md +179 -0
- package/shell-taste/references/handbook/dom/04-network.md +384 -0
- package/shell-taste/references/handbook/dom/05-files-paths.md +74 -0
- package/shell-taste/references/handbook/dom/06-checks-validation.md +127 -0
- package/shell-taste/references/handbook/dom/07-system-administration.md +103 -0
- package/shell-taste/references/handbook/dom/08-privilege-users.md +58 -0
- package/shell-taste/references/handbook/dom/09-text-data.md +62 -0
- package/shell-taste/references/handbook/dom/10-terminal-ux.md +60 -0
- package/shell-taste/references/handbook/dom/11-process-control.md +28 -0
- package/shell-taste/references/handbook/dom/12-uncategorized.md +161 -0
- package/shell-taste/references/handbook/dom/13-containers.md +13 -0
- package/shell-taste/references/handbook/dom/14-agents-ai-tooling.md +13 -0
- package/shell-taste/references/handbook/family-index.md +230 -0
- package/shell-taste/references/handbook/index.md +41 -0
- package/skill-author/SKILL.md +86 -0
- package/sobesednik/SKILL.md +98 -0
- package/sobesednik/card-template.md +23 -0
- package/sobesednik/personas/advocate.md +27 -0
- package/sobesednik/personas/analyst.md +29 -0
- package/sobesednik/personas/chat.md +42 -0
- package/sobesednik/personas/ifs.md +32 -0
- package/sobesednik/personas/journal/README.md +6 -0
- package/sobesednik/personas/nasreddin.md +29 -0
- package/sobesednik/personas/premortem.md +29 -0
- package/sobesednik/personas/rogers.md +27 -0
- package/sobesednik/personas/socratic.md +29 -0
- package/sobesednik/personas/stoic.md +27 -0
- package/sobesednik/references/persona-design.md +41 -0
- package/zai-mcp/README.md +63 -0
- package/zai-mcp/SKILL.md +160 -0
- package/zai-mcp/references/recipes.md +273 -0
- package/zai-mcp/references/tools.md +266 -0
- package/README.md +0 -3
package/mcpls/SKILL.md
ADDED
|
@@ -0,0 +1,261 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: mcpls
|
|
3
|
+
description: >
|
|
4
|
+
Semantic code navigation via LSP through the mcpls MCP→LSP bridge:
|
|
5
|
+
definitions, references, hover types, workspace symbols, compiler
|
|
6
|
+
diagnostics, call hierarchy, completions, workspace-wide rename —
|
|
7
|
+
compiler-accurate, not text-level guesses. Use instead of grep/rg when
|
|
8
|
+
you need WHERE a symbol is defined, WHAT type it is, WHO calls or uses a
|
|
9
|
+
function, or WHAT diagnostics exist, in Rust, TypeScript, Python, Go,
|
|
10
|
+
C/C++, Zig projects. Don't use for plain text search (use rg) or
|
|
11
|
+
structural pattern replace (use ast-grep). Call from sh blocks via
|
|
12
|
+
`mcporter call mcpls.<tool>` or the `~/bin/mcpls-*` wrappers (primary,
|
|
13
|
+
vanilla pi contour — MCP is not configured inside pi); legacy fabric
|
|
14
|
+
fallback: `mcp.mcpls.*` inside fabric_exec.
|
|
15
|
+
RU: где определена функция, найди определение, кто вызывает, кто
|
|
16
|
+
использует, найди референсы, тип символа, диагностика, безопасный rename,
|
|
17
|
+
пустой результат rust-analyzer. Errors: path outside workspace,
|
|
18
|
+
LSP server not available.
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
# mcpls (MCP→LSP bridge)
|
|
22
|
+
|
|
23
|
+
Compiler-accurate code understanding via the Language Server Protocol — type
|
|
24
|
+
inference, cross-references, semantic navigation, diagnostics.
|
|
25
|
+
Two call contours: shell (primary) and Fabric (legacy fallback). On this
|
|
26
|
+
machine pi runs the vanilla contour — bare prose + sh blocks, zero model
|
|
27
|
+
tools — so MCP is not configured inside pi: mcpls is reached from shell.
|
|
28
|
+
|
|
29
|
+
## When to use
|
|
30
|
+
|
|
31
|
+
| Use mcpls | Use instead |
|
|
32
|
+
|---|---|
|
|
33
|
+
| Find WHERE a symbol is defined | Text occurrences of a string → `rg` |
|
|
34
|
+
| List all symbols/functions in a file | Regex pattern search → `rg` |
|
|
35
|
+
| Find all references to a symbol | Count matches across files → `rg` |
|
|
36
|
+
| Get type info (hover) | Comments or string literals → `rg` |
|
|
37
|
+
| Get compiler diagnostics | Simple text search → `rg` |
|
|
38
|
+
| Rename a symbol workspace-wide | Structural pattern replace → `ast-grep` |
|
|
39
|
+
| Trace call hierarchy (who calls what) | — |
|
|
40
|
+
|
|
41
|
+
**Don't** use mcpls for plain text search or AST-pattern rewrites — `rg` is
|
|
42
|
+
faster for text, `ast-grep` for structural replace.
|
|
43
|
+
|
|
44
|
+
## Prerequisites
|
|
45
|
+
|
|
46
|
+
At least one language server **on PATH**; mcpls picks which from project
|
|
47
|
+
markers (Cargo.toml, package.json, pyproject.toml, go.mod, ...):
|
|
48
|
+
|
|
49
|
+
| Language | Server | Install |
|
|
50
|
+
|---|---|---|
|
|
51
|
+
| Rust | rust-analyzer | `rustup component add rust-analyzer` |
|
|
52
|
+
| TS/JS | typescript-language-server + typescript | `npm i -g typescript-language-server typescript` |
|
|
53
|
+
| Python | pyright | `npm i -g pyright` |
|
|
54
|
+
| Go | gopls | `go install golang.org/x/tools/gopls@latest` |
|
|
55
|
+
| C/C++ | clangd | system package manager |
|
|
56
|
+
| Zig | zls | `zig build -Doptimize=ReleaseSafe` from zls source |
|
|
57
|
+
|
|
58
|
+
TS/JS cross-file resolution (definitions/references beyond one file) requires
|
|
59
|
+
`tsconfig.json` at the project root (`jsconfig.json` for plain JS).
|
|
60
|
+
|
|
61
|
+
## Installation
|
|
62
|
+
|
|
63
|
+
From crates.io (requires rustc >= 1.99):
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
cargo install mcpls --locked
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
HTTP transport (needed for the `~/bin/mcpls-ensure` fallback):
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
cargo install mcpls --locked --features transport-http
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Pre-built binaries: [GitHub Releases](https://github.com/bug-ops/mcpls/releases) —
|
|
76
|
+
verify the `.sha256` sidecar; commands in [references/install.md](references/install.md).
|
|
77
|
+
|
|
78
|
+
Verify: `mcpls --version`.
|
|
79
|
+
|
|
80
|
+
## Configuration
|
|
81
|
+
|
|
82
|
+
Resolution order, trust model, and all fields:
|
|
83
|
+
[references/configuration.md](references/configuration.md).
|
|
84
|
+
|
|
85
|
+
Key rule: a project-local `mcpls.toml` is ignored unless trusted; enabling
|
|
86
|
+
`--trust-project-config` on an untrusted checkout is arbitrary code execution
|
|
87
|
+
(it can set the `command`/`args` of spawned servers).
|
|
88
|
+
|
|
89
|
+
## How to call — two contours
|
|
90
|
+
|
|
91
|
+
### Shell (primary): `mcporter call` from sh blocks
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
mcporter call mcpls.get_hover file_path=src/lib.rs line=42 character=8
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
- The mcporter daemon pools the stdio server via `lifecycle: keep-alive`:
|
|
98
|
+
spawn on first call, idle retire after 10 min.
|
|
99
|
+
- **Cold start:** the first call after spawn/idle may return empty results
|
|
100
|
+
while the project loads — **retry once**; later calls are warm.
|
|
101
|
+
- Keep-alive needs a local patch (openclaw/mcporter#499); on `retirement is unverified` use the fallbacks below.
|
|
102
|
+
|
|
103
|
+
Fallbacks if the pooled path is unavailable:
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
# One-shot stdio session (spawn + retry handled internally)
|
|
107
|
+
~/bin/mcpls-call get_references file_path=src/handler.rs line=30 character=12
|
|
108
|
+
|
|
109
|
+
# Or start the HTTP daemon explicitly, then call via its baseUrl
|
|
110
|
+
~/bin/mcpls-ensure && mcporter call mcpls.get_diagnostics file_path=src/lib.rs
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### Fabric (legacy fallback): `mcp.mcpls.*` inside `fabric_exec`
|
|
114
|
+
|
|
115
|
+
Only on the legacy fabric contour (in-guest MCP tool calls), while it still
|
|
116
|
+
exists. Register once per session (cwd = project root), then call tools:
|
|
117
|
+
|
|
118
|
+
```ts
|
|
119
|
+
await mcp.$register({
|
|
120
|
+
name: "mcpls",
|
|
121
|
+
command: "mcpls",
|
|
122
|
+
cwd: process.cwd(),
|
|
123
|
+
});
|
|
124
|
+
await mcp.mcpls.get_server_logs({}); // smoke test
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
## Core workflow
|
|
128
|
+
|
|
129
|
+
Three rules:
|
|
130
|
+
|
|
131
|
+
1. **Launch with cwd = project root** — `mcporter call` and the wrappers
|
|
132
|
+
inherit the sh block's cwd; run them from the project root so mcpls
|
|
133
|
+
auto-detects workspace markers. (Fabric: pass `cwd` to `mcp.$register`.)
|
|
134
|
+
2. **File paths must be relative** to project root. Absolute paths cause
|
|
135
|
+
`"path outside workspace"`; if a relative path still fails, check
|
|
136
|
+
`[workspace] roots` in `mcpls.toml` — the file must sit under a root.
|
|
137
|
+
3. **Positions are 1-based** — line 1, character 1 = first character. Line
|
|
138
|
+
numbers from reads work as-is (mcpls translates to 0-based LSP internally).
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
mcporter call mcpls.get_hover file_path=src/main.rs line=10 character=5
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
- `rename_symbol` returns workspace text edits — it does **not** apply them.
|
|
145
|
+
- `get_diagnostics` reflects disk state — save the file first.
|
|
146
|
+
- TS/JS cross-file navigation needs `tsconfig.json` (`jsconfig.json` for JS).
|
|
147
|
+
|
|
148
|
+
## Top tools
|
|
149
|
+
|
|
150
|
+
Shell syntax shown; fabric legacy: `await mcp.mcpls.<tool>({...})`.
|
|
151
|
+
|
|
152
|
+
### Code Intelligence
|
|
153
|
+
|
|
154
|
+
```bash
|
|
155
|
+
# What type/signature is at this position?
|
|
156
|
+
mcporter call mcpls.get_hover file_path=src/lib.rs line=42 character=8
|
|
157
|
+
# Jump to definition
|
|
158
|
+
mcporter call mcpls.get_definition file_path=src/main.rs line=15 character=20
|
|
159
|
+
# Find all references across the workspace
|
|
160
|
+
mcporter call mcpls.get_references file_path=src/handler.rs line=30 character=12
|
|
161
|
+
# Structured outline of a file (functions, types, imports)
|
|
162
|
+
mcporter call mcpls.get_document_symbols file_path=src/lib.rs
|
|
163
|
+
# Search for a symbol by name across the workspace
|
|
164
|
+
mcporter call mcpls.workspace_symbol_search query=process_request
|
|
165
|
+
# Context-aware completions at a position
|
|
166
|
+
mcporter call mcpls.get_completions file_path=src/app.ts line=50 character=4
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
### Diagnostics & Refactoring
|
|
170
|
+
|
|
171
|
+
```bash
|
|
172
|
+
# Real compiler errors and warnings (file MUST be saved to disk first)
|
|
173
|
+
mcporter call mcpls.get_diagnostics file_path=src/lib.rs
|
|
174
|
+
# Quick fixes available at a position (after seeing diagnostics)
|
|
175
|
+
mcporter call mcpls.get_code_actions file_path=src/lib.rs line=42 character=8
|
|
176
|
+
# Workspace-wide rename (prefer over manual find-and-replace).
|
|
177
|
+
# Returns text edits — does NOT apply them.
|
|
178
|
+
mcporter call mcpls.rename_symbol file_path=src/lib.rs line=20 character=5 new_name=new_function_name
|
|
179
|
+
# Auto-format document
|
|
180
|
+
mcporter call mcpls.format_document file_path=src/lib.rs
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
### Call Hierarchy
|
|
184
|
+
|
|
185
|
+
```bash
|
|
186
|
+
# Step 1: get call hierarchy items at a position
|
|
187
|
+
mcporter call mcpls.prepare_call_hierarchy file_path=src/lib.rs line=25 character=1
|
|
188
|
+
# Then: get_incoming_calls — who calls it? get_outgoing_calls — what does it call?
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
### Server Monitoring
|
|
192
|
+
|
|
193
|
+
```bash
|
|
194
|
+
# Debug "no results" issues
|
|
195
|
+
mcporter call mcpls.get_server_logs
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
## Rust: rust-analyzer indexing delay (empty results after cold start)
|
|
199
|
+
|
|
200
|
+
**rust-analyzer needs 10-30 seconds to index after cold start.** During
|
|
201
|
+
indexing, `get_hover`, `get_definition`, and `get_references` return empty
|
|
202
|
+
results `[]` for Rust files (mcpls doesn't block on indexing —
|
|
203
|
+
bug-ops/mcpls#196).
|
|
204
|
+
|
|
205
|
+
**`get_document_symbols` works immediately** (file-level, no indexing needed).
|
|
206
|
+
**TypeScript/JavaScript works immediately** — tsserver needs no background
|
|
207
|
+
indexing.
|
|
208
|
+
|
|
209
|
+
### Workaround for Rust
|
|
210
|
+
|
|
211
|
+
1. Warmup call first — `get_document_symbols` or `get_hover` on a known
|
|
212
|
+
symbol — to trigger the language server to start.
|
|
213
|
+
2. Wait 20-30 seconds.
|
|
214
|
+
3. Retry the actual `get_definition` / `get_references` call.
|
|
215
|
+
4. If still empty, check `get_server_logs` for `rust-analyzer` indexing status.
|
|
216
|
+
|
|
217
|
+
Subsequent calls are fast — indexing is one-time per mcpls session.
|
|
218
|
+
|
|
219
|
+
## Diagnostic-driven editing workflow
|
|
220
|
+
|
|
221
|
+
After editing a file:
|
|
222
|
+
|
|
223
|
+
1. **Save the file to disk** — diagnostics reflect disk state, not memory.
|
|
224
|
+
2. Call `get_diagnostics` on the changed file.
|
|
225
|
+
3. For each error, call `get_code_actions` for available fixes.
|
|
226
|
+
4. Apply fixes or edit manually.
|
|
227
|
+
5. Repeat until `get_diagnostics` returns `[]`.
|
|
228
|
+
|
|
229
|
+
## Anti-patterns
|
|
230
|
+
|
|
231
|
+
- ❌ Using `rename_symbol` without first checking `get_references` → may miss
|
|
232
|
+
usages in macro expansions or generated code.
|
|
233
|
+
- ❌ Guessing types/signatures when `get_hover` is available → use the compiler.
|
|
234
|
+
|
|
235
|
+
## Troubleshooting
|
|
236
|
+
|
|
237
|
+
| Symptom | Fix |
|
|
238
|
+
|---|---|
|
|
239
|
+
| Empty `[]` on the first call after spawn/idle (any language) | Project still loading. Retry once; calls are warm afterwards. |
|
|
240
|
+
| `"path outside workspace"` | Use a relative path from project root; verify `[workspace] roots` in `mcpls.toml` covers the file. |
|
|
241
|
+
| `"LSP server not available for file type"` | No server configured for that extension. Install one (see Prerequisites). |
|
|
242
|
+
| Empty `[]` from Rust `get_definition` / `get_references` | rust-analyzer still indexing. Wait 20-30s, retry. Check `get_server_logs`. |
|
|
243
|
+
| `get_diagnostics` returns stale errors | Save the file to disk first. Diagnostics reflect disk state. |
|
|
244
|
+
| `"server is still initializing"` | Large project loading. Wait and retry; raise `timeout_seconds` in config. |
|
|
245
|
+
| `"Position out of bounds"` | Verify the line exists. Positions are 1-based — not 0-based LSP. |
|
|
246
|
+
| Rust: symbols/diagnostics fine, hover/definition/references empty | `workspace.roots` has only umbrella directories — none is a cargo root, so rust-analyzer treats files as detached. Add the project root (dir with `Cargo.toml`) to `roots` and restart. TS tolerates umbrellas (tsserver finds nested tsconfig); Rust does not. |
|
|
247
|
+
| Slow first response, fast subsequent | Normal cold start / indexing. Pre-warm with a dummy `get_document_symbols`. |
|
|
248
|
+
| rename/references cover one file only; definition from a usage lands on the import line | Cold project graph: answers are valid but **local-only** and look correct. Warm the project (any call + a few seconds; a `get_references` before `rename_symbol`), then retry. A large project sharing the pooled session delays warming of others. |
|
|
249
|
+
| Applying rename/format edits by hand | Result positions are 1-based (mcpls normalizes). Use `~/bin/mcpls-apply` — accepts `{changes}`, a bare changes array, or `{edits}`. |
|
|
250
|
+
| `rename_symbol` misses some references | Symbol is in macro expansion or generated code. Verify with `get_references` first. |
|
|
251
|
+
| mcporter: `"retirement is unverified"` | Keep-alive patch (openclaw/mcporter#499) missing. Use the `~/bin/mcpls-call` wrapper. |
|
|
252
|
+
| Call hierarchy / code actions return an error or `isError` on TS | typescript-language-server does not support them. Check `get_tool_support` before relying on a capability for a given language. |
|
|
253
|
+
| Completions return `[]` | Cursor position must be inside the document (line beyond end → empty). |
|
|
254
|
+
|
|
255
|
+
## When you need more
|
|
256
|
+
|
|
257
|
+
- mcpls book (full docs) → https://bug-ops.github.io/mcpls/
|
|
258
|
+
- README / architecture → https://github.com/bug-ops/mcpls
|
|
259
|
+
- Troubleshooting guide → https://bug-ops.github.io/mcpls/guide/troubleshooting.html
|
|
260
|
+
- `get_tool_support` — which tools the active server supports (check before
|
|
261
|
+
relying on call hierarchy or rename for a given language).
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
# mcpls.toml — configuration reference
|
|
2
|
+
|
|
3
|
+
Compact field tables for `mcpls.toml`. This is a schema reference, not a tutorial —
|
|
4
|
+
for worked examples per language, see
|
|
5
|
+
[Configuration Reference](https://bug-ops.github.io/mcpls/reference/config.html)
|
|
6
|
+
and [Complete Examples](https://bug-ops.github.io/mcpls/reference/config.html#complete-examples).
|
|
7
|
+
|
|
8
|
+
## `[mcp]` fields
|
|
9
|
+
|
|
10
|
+
Overrides the text mcpls reports about itself over MCP; every field is optional and
|
|
11
|
+
independent, defaulting to mcpls's built-in text when omitted. `serverInfo.name`,
|
|
12
|
+
`version`, and `website_url` are not configurable here.
|
|
13
|
+
|
|
14
|
+
| Field | Type | Default | Max size | Notes |
|
|
15
|
+
|---|---|---|---|---|
|
|
16
|
+
| `title` | string | `"MCPLS - MCP to LSP Bridge"` | 128 bytes | Overrides `serverInfo.title`. |
|
|
17
|
+
| `description` | string | crate's `Cargo.toml` description | 1024 bytes | Overrides `serverInfo.description`. |
|
|
18
|
+
| `instructions` | string | built-in capability blurb | 4096 bytes | **Replaces** `ServerInfo.instructions` entirely — does not append to the built-in text. Read it at connection time instead of assuming the built-in blurb; see the note below. |
|
|
19
|
+
| `tool_prefix` | string | unprefixed tool names | 32 bytes | Prefixes every tool name with `{tool_prefix}_`, so a client running multiple mcpls bridges can tell their tools apart. Charset `[A-Za-z0-9_-]`, must start/end with a letter or digit. |
|
|
20
|
+
|
|
21
|
+
Limits are UTF-8 bytes, not characters, and apply to the raw configured string,
|
|
22
|
+
including surrounding whitespace — a whitespace-only value is rejected as empty
|
|
23
|
+
rather than checked against the byte cap.
|
|
24
|
+
|
|
25
|
+
## `[workspace]` fields
|
|
26
|
+
|
|
27
|
+
| Field | Type | Default | Notes |
|
|
28
|
+
|---|---|---|---|
|
|
29
|
+
| `roots` | array of strings | `[]` | Workspace root directories. Empty array auto-detects from the current directory. |
|
|
30
|
+
| `position_encodings` | array of strings | `["utf-8", "utf-16"]` | Preferred LSP position encodings (`utf-8`, `utf-16`, `utf-32`), offered to each spawned server during the `initialize` handshake in the listed order. A preference, not a restriction — per the LSP spec, UTF-16 is a mandatory fallback a server may still choose even if omitted here. |
|
|
31
|
+
| `language_extensions` | array of `{extensions, language_id}` | `[]` within an explicit `[workspace]` table; 30 built-in mappings only when `[workspace]` is absent entirely | Custom or overriding file-extension → language-ID mappings. Adding a `[workspace]` table for any other field (e.g. just `roots`) silently drops the 30 built-ins unless you list `language_extensions` yourself — list every language you need, not just the new one. |
|
|
32
|
+
| `heuristics_max_depth` | integer | `10` | Recursion depth for `heuristics.project_markers` search (see below). Maximum `64`; larger values are rejected at startup. |
|
|
33
|
+
| `max_concurrent_server_starts` | integer | `8` | Upper bound on LSP servers starting at the same time; the rest start as earlier ones settle. Rejects `0`. |
|
|
34
|
+
|
|
35
|
+
## `[[lsp_servers]]` fields
|
|
36
|
+
|
|
37
|
+
Each entry defines one language server; a language may have multiple entries (see
|
|
38
|
+
`handles` below).
|
|
39
|
+
|
|
40
|
+
| Field | Type | Required | Default | Notes |
|
|
41
|
+
|---|---|---|---|---|
|
|
42
|
+
| `language_id` | string | yes | — | e.g. `rust`, `python`, `typescript`. |
|
|
43
|
+
| `command` | string | yes | — | Executable name (resolved via `PATH`) or absolute path. |
|
|
44
|
+
| `args` | array of strings | no | `[]` | e.g. `["--stdio"]` for servers that need it. |
|
|
45
|
+
| `file_patterns` | array of glob strings | no | `[]` | e.g. `["**/*.rs"]`. Determines which files route to this server. |
|
|
46
|
+
| `name` | string | no | the `language_id` | Explicit routing identity. Required when two servers share one `language_id`, so each has a distinct identity. |
|
|
47
|
+
| `handles` | array of routing values | no | unset = catch-all | Restricts a server to specific tools; see [Tool routing](#tool-routing-handles) below. |
|
|
48
|
+
| `timeout_seconds` | integer | no | `30` | Timeout for the `initialize` handshake only. Must be 1 to 900; rejected at load time otherwise. |
|
|
49
|
+
| `request_timeout_seconds` | integer | no | `30` | Timeout per individual LSP request after initialization (hover, definition, etc.), independent of `timeout_seconds`. Must be 1 to 900; rejected at load time otherwise. Worst case per tool call: `4 * request_timeout_seconds + 3.5s` (retry budget on `-32802` responses). The completions timeout is `min(request_timeout_seconds, 10s)` — a value below 10 lowers the completions cap too; values above 10 are capped at 10. |
|
|
50
|
+
| `initialization_options` | table | no | `{}` | Server-specific options passed in the LSP `initialize` request, e.g. `cargo.features = "all"` for rust-analyzer. For `typescript-language-server`, mcpls adds `tsserver.path` (the bundled tsserver) unless you set it or set other options without it. |
|
|
51
|
+
| `settings` | table | no | unset | Per-server settings pushed in `workspace/didChangeConfiguration` after `initialized` and served on `workspace/configuration`. Top-level dotted keys expand into nested tables (`"python.analysis.typeCheckingMode" = "strict"`); keys inside a value are left as written (gopls `"ui.semanticTokens"`). Must not be empty and must not contain TOML datetimes. Use the server's own section names (`rust-analyzer.*`, `python.*`, `gopls`, ...): other keys are silently ignored by the server. Setting it also advertises `workspace.configuration`, and servers that pull configuration after each push (rust-analyzer, jdtls) then replace what `initialization_options` set, so do not combine both unless `settings` repeats those options (mcpls warns). |
|
|
52
|
+
| `env` | table | no | `{}` | See [Environment passthrough](#environment-passthrough-env) below. |
|
|
53
|
+
| `heuristics.project_markers` | array of strings | no | unset | Marker files/directories that make this server applicable. mcpls searches for them recursively through the workspace tree up to `heuristics_max_depth` levels, skipping `node_modules`, `target`, and `.git`, e.g. `["pyproject.toml"]`. |
|
|
54
|
+
|
|
55
|
+
## Tool routing (`handles`)
|
|
56
|
+
|
|
57
|
+
`handles` values are routing identifiers, not MCP tool names — most match directly,
|
|
58
|
+
a few map many-to-one:
|
|
59
|
+
|
|
60
|
+
| `handles` value | MCP tool(s) it governs |
|
|
61
|
+
|---|---|
|
|
62
|
+
| `hover` | `get_hover` |
|
|
63
|
+
| `definition` | `get_definition` |
|
|
64
|
+
| `type_definition` | `go_to_type_definition` |
|
|
65
|
+
| `declaration` | `go_to_declaration` |
|
|
66
|
+
| `implementation` | `go_to_implementation` |
|
|
67
|
+
| `references` | `get_references` |
|
|
68
|
+
| `diagnostics` | `get_diagnostics` (pull) **and** `get_cached_diagnostics` (same route serves both) |
|
|
69
|
+
| `rename` | `rename_symbol`, `prepare_rename` |
|
|
70
|
+
| `completions` | `get_completions` |
|
|
71
|
+
| `signature_help` | `get_signature_help` |
|
|
72
|
+
| `document_symbols` | `get_document_symbols` |
|
|
73
|
+
| `workspace_symbols` | `workspace_symbol_search` (see the special case below) |
|
|
74
|
+
| `format_document` | `format_document` |
|
|
75
|
+
| `format_range` | `format_range` |
|
|
76
|
+
| `selection_range` | `get_selection_ranges` |
|
|
77
|
+
| `folding_range` | `get_folding_ranges` |
|
|
78
|
+
| `code_actions` | `get_code_actions` |
|
|
79
|
+
| `call_hierarchy` | `prepare_call_hierarchy`, `get_incoming_calls`, `get_outgoing_calls`, sharing one route: an incoming/outgoing-calls lookup only makes sense against the server that produced the originating call-hierarchy item |
|
|
80
|
+
| `inlay_hints` | `get_inlay_hints` |
|
|
81
|
+
| `type_hierarchy` | `prepare_type_hierarchy`, `get_supertypes`, `get_subtypes`, sharing one route like call hierarchy |
|
|
82
|
+
| `document_highlights` | `get_document_highlights` |
|
|
83
|
+
|
|
84
|
+
Rules:
|
|
85
|
+
|
|
86
|
+
- Each language may have one, and only one, server without `handles` set; that
|
|
87
|
+
unrestricted server catches every tool the other servers for the language don't
|
|
88
|
+
explicitly claim.
|
|
89
|
+
- A tool may be claimed by only one server per language.
|
|
90
|
+
- If the server routed to a tool fails to spawn, that tool falls back to the
|
|
91
|
+
language's catch-all (if running); otherwise the call fails naming "no server
|
|
92
|
+
available" rather than silently reaching a server that explicitly declined it via
|
|
93
|
+
`handles`.
|
|
94
|
+
- `workspace_symbol_search` is the one tool with no document to route on. It
|
|
95
|
+
resolves, across *all* configured servers, to the first explicit
|
|
96
|
+
`workspace_symbols` claimant, else the first catch-all — there is no per-language
|
|
97
|
+
fallback since the tool has no language. With neither, the call fails by name.
|
|
98
|
+
|
|
99
|
+
## Ambiguous configs fail at startup, not silently
|
|
100
|
+
|
|
101
|
+
A startup check looks for any pair of servers configured for the same language that
|
|
102
|
+
would both be active in the same workspace at once (per `heuristics.project_markers`).
|
|
103
|
+
If that pair also collides on routing — same `name`, both lacking `handles`, or both
|
|
104
|
+
claiming an identical tool — mcpls refuses to start rather than pick one arbitrarily,
|
|
105
|
+
and the error names the conflicting `[[lsp_servers]]` entries. Two servers whose
|
|
106
|
+
`heuristics.project_markers` are mutually exclusive never overlap in one workspace, so
|
|
107
|
+
that combination is not flagged and starts fine.
|
|
108
|
+
|
|
109
|
+
## Environment passthrough (`env`)
|
|
110
|
+
|
|
111
|
+
Spawned LSP server processes do **not** inherit mcpls's full environment — this is a
|
|
112
|
+
deliberate security boundary, not an oversight. Each child's environment is cleared,
|
|
113
|
+
then a minimal allowlist is passed through from mcpls's own process (`PATH`, `HOME`,
|
|
114
|
+
`USERPROFILE`, `TMPDIR`/`TEMP`/`TMP` on every platform, plus Windows loader
|
|
115
|
+
essentials), and only then is the server's `[lsp_servers.env]` table applied on top,
|
|
116
|
+
so entries there can override the passthrough.
|
|
117
|
+
|
|
118
|
+
Use `env` to restore anything a server needs beyond that allowlist: proxy settings,
|
|
119
|
+
`VIRTUAL_ENV`/`PYTHONPATH`, or toolchain variables a `build.rs` reads (`DATABASE_URL`,
|
|
120
|
+
`LIBCLANG_PATH`, `SSH_AUTH_SOCK`, …). Values here are written literally into
|
|
121
|
+
`mcpls.toml`, a file that's often committed to VCS — don't put real secrets in it;
|
|
122
|
+
and forwarding `SSH_AUTH_SOCK` hands the ssh-agent socket to the spawned LSP
|
|
123
|
+
process, so only do so for servers you trust.
|
|
124
|
+
|
|
125
|
+
**`PATH` caution:** an `env.PATH` entry overwrites the passthrough value rather than
|
|
126
|
+
extending it, and the two platforms then behave differently. On Unix, a bare
|
|
127
|
+
`command` with no directory component is now resolved against your override, so it
|
|
128
|
+
stops working unless you kept the original directory in it; on Windows the loader
|
|
129
|
+
still consults the parent process's `PATH` as a fallback after your override, so the
|
|
130
|
+
same mistake is less likely to break anything. If you just need to add one directory,
|
|
131
|
+
give `command` an absolute path instead of touching `PATH` at all.
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# Install — pre-built binaries
|
|
2
|
+
|
|
3
|
+
Download from [GitHub Releases](https://github.com/bug-ops/mcpls/releases),
|
|
4
|
+
verify the `.sha256` sidecar, extract, and move `mcpls` onto `PATH`:
|
|
5
|
+
|
|
6
|
+
```bash
|
|
7
|
+
curl -LO https://github.com/bug-ops/mcpls/releases/latest/download/mcpls-<target>.tar.gz
|
|
8
|
+
curl -LO https://github.com/bug-ops/mcpls/releases/latest/download/mcpls-<target>.tar.gz.sha256
|
|
9
|
+
shasum -a 256 -c mcpls-<target>.tar.gz.sha256
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
`<target>` — per-platform archive name; see the releases page. Verify with
|
|
13
|
+
`mcpls --version`.
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: mcporter
|
|
3
|
+
description: >
|
|
4
|
+
MCP servers under fabric: config, discovery, and the mcporter CLI.
|
|
5
|
+
Fabric's MCP runtime is mcporter-based — servers live in
|
|
6
|
+
~/.mcporter/mcporter.json and are called as mcp.<server>.<tool>() natives
|
|
7
|
+
inside fabric_exec. Use the CLI only for debugging, ad-hoc servers, and
|
|
8
|
+
config surgery. Overview skill — per-server details live in their own skills.
|
|
9
|
+
RU: MCP-сервер не отвечает, неизвестный тул, конфиг mcporter, добавить сервер.
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
# mcporter (fabric's MCP runtime)
|
|
13
|
+
|
|
14
|
+
Under fabric you rarely invoke the `mcporter` CLI directly: fabric embeds the
|
|
15
|
+
mcporter runtime, discovers every server in `~/.mcporter/mcporter.json`, and
|
|
16
|
+
binds each tool as a **native** inside `fabric_exec`:
|
|
17
|
+
|
|
18
|
+
```ts
|
|
19
|
+
await mcp.zai_search.web_search_prime({ search_query: "..." }); // zai-search → zai_search
|
|
20
|
+
await tools.call({ ref: "mcp.$servers" }); // what's registered? (tool counts, staleness)
|
|
21
|
+
await tools.call({ ref: "mcp.$reload" }); // re-read config after editing it
|
|
22
|
+
await tools.call({ ref: "mcp.$call", // explicit server+tool (computed names)
|
|
23
|
+
args: { server: "zai-zread", tool: "read_file", args: { repo_name: "9fans/go", file_path: "README.md" } } });
|
|
24
|
+
await mcp.$register({ name: "mcpls", command: "mcpls", cwd: process.cwd() }); // ephemeral ad-hoc server
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Rules of thumb:
|
|
28
|
+
|
|
29
|
+
- **Calling a tool** → native `mcp.<server>.<tool>(args)`; hyphens become
|
|
30
|
+
underscores. Batch independent calls with `Promise.all`.
|
|
31
|
+
- **"What servers/tools exist?"** → `tools.list({ provider: "mcp" })` or
|
|
32
|
+
`tools.search({ query: "..." })`; one schema → `tools.describe({ ref })`.
|
|
33
|
+
- **Config changed** → `tools.call({ ref: "mcp.$reload" })`.
|
|
34
|
+
- **One-off server for this session** → `mcp.$register({ name, command, cwd })`.
|
|
35
|
+
- **CLI in a shell** → debugging, daemon management, config import — see below.
|
|
36
|
+
|
|
37
|
+
## When to use the CLI
|
|
38
|
+
|
|
39
|
+
- Debug a server outside fabric (`mcporter list <server> --status`)
|
|
40
|
+
- Manage the keep-alive **daemon** (fabric doesn't use it; standalone CLI calls do)
|
|
41
|
+
- Import servers from other clients (`mcporter config import cursor --copy`)
|
|
42
|
+
- Run an ad-hoc server from a shell script
|
|
43
|
+
|
|
44
|
+
**Don't** use the CLI for calls fabric can make natively — the CLI adds process
|
|
45
|
+
spawn, shell quoting, and stringly-typed output for zero benefit.
|
|
46
|
+
|
|
47
|
+
## CLI reference
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
mcporter call <server>.<tool> key=value ...
|
|
51
|
+
mcporter call '<server>.<tool>(key: "value", num: 1)' # function-call syntax
|
|
52
|
+
mcporter call <server>.<tool> --args '{"key":"value"}' # JSON payload
|
|
53
|
+
mcporter list # configured servers
|
|
54
|
+
mcporter list <server> --brief # tool names (exact!)
|
|
55
|
+
mcporter list <server> --schema # full signatures
|
|
56
|
+
mcporter list <server> --status # connectivity check
|
|
57
|
+
mcporter daemon status|start|stop|restart # keep-alive daemon (CLI-only)
|
|
58
|
+
mcporter config list|add|remove|get # config surgery
|
|
59
|
+
mcporter config import cursor --copy # steal servers from other clients
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Flags on `call`: `--timeout <ms>`, `--output json|text|markdown|raw`,
|
|
63
|
+
`--save-images <dir>`, `--raw-strings`, `--no-coerce`, `--tail-log`.
|
|
64
|
+
|
|
65
|
+
Ad-hoc without config:
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
mcporter call --stdio "npx -y @modelcontextprotocol/server-filesystem" --tool read_file path=/tmp/data.txt
|
|
69
|
+
mcporter call https://api.example.com/mcp.fetch url=https://example.com
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
(Inside fabric, prefer `mcp.$register` for the same effect — no quoting.)
|
|
73
|
+
|
|
74
|
+
## Config
|
|
75
|
+
|
|
76
|
+
`~/.mcporter/mcporter.json` → `{ "mcpServers": { <name>: { command+args | baseUrl+headers, env } } }`.
|
|
77
|
+
Priority: `./config/mcporter.json` (project) > `~/.mcporter/mcporter.json`.
|
|
78
|
+
After editing: `tools.call({ ref: "mcp.$reload" })` (fabric) or
|
|
79
|
+
`mcporter daemon restart` (CLI daemon).
|
|
80
|
+
|
|
81
|
+
Auth lives per-server: `env` (e.g. `GITHUB_PERSONAL_ACCESS_TOKEN`,
|
|
82
|
+
`Z_AI_API_KEY`) or `headers.Authorization` for HTTP servers.
|
|
83
|
+
|
|
84
|
+
## Per-server skills
|
|
85
|
+
|
|
86
|
+
| skill | servers | purpose |
|
|
87
|
+
|---|---|---|
|
|
88
|
+
| [chrome-devtools](../chrome-devtools/SKILL.md) | `chrome-devtools`, `chrome-devtools-proxy` | Drive a real Chrome tab (scrape, test, debug) |
|
|
89
|
+
| [zai-mcp](../zai-mcp/SKILL.md) | `zai-search`, `zai-reader`, `zai-zread`, `zai-vision` | Web search, page-to-markdown, repo knowledge, image/video analysis |
|
|
90
|
+
| [mcpls](../mcpls/SKILL.md) | `mcpls` (ad-hoc stdio) | Semantic code navigation via LSP |
|
package/mindmap/SKILL.md
ADDED
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: mindmap
|
|
3
|
+
description: >-
|
|
4
|
+
Create, grow, or fix drawio mindmaps (.drawio): from an idea, a text
|
|
5
|
+
outline, or notes — central node, one color per branch, curved organic
|
|
6
|
+
edges in native mindmap styles. Use when the user asks for a mindmap /
|
|
7
|
+
майндмапу / карту идей / concept map / brainstorm map, asks to beautify,
|
|
8
|
+
re-layout, or QA an existing mindmap canvas, or to turn text into a visual
|
|
9
|
+
map. Covers programmatic XML generation and drawio MCP round-trips. Not
|
|
10
|
+
for other diagram types (drawio skill) and not for Socratic interview
|
|
11
|
+
sessions (grill skill — it grows its canvas with these same references).
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
# Mindmap — drawio mindmaps end to end
|
|
15
|
+
|
|
16
|
+
Build or edit a mindmap canvas. The .drawio file is the artifact; a text
|
|
17
|
+
outline is a by-product on request.
|
|
18
|
+
|
|
19
|
+
Theory (Buzan's laws adapted to drawio):
|
|
20
|
+
[references/mindmap-design.md](references/mindmap-design.md).
|
|
21
|
+
Generation mechanics, MCP calls, QA loop:
|
|
22
|
+
[references/drawio-recipe.md](references/drawio-recipe.md).
|
|
23
|
+
|
|
24
|
+
## Workflow
|
|
25
|
+
|
|
26
|
+
1. **Canvas**: reuse the file the user names, or create
|
|
27
|
+
`<project>/docs/<topic>.drawio`. If draw.io Desktop has it open, ask the
|
|
28
|
+
user to SAVE before each of your write rounds — unsaved app edits clobber
|
|
29
|
+
MCP writes and vice versa.
|
|
30
|
+
2. **Skeleton**: one central ellipse node in native mindmap styles
|
|
31
|
+
(recipe, "Generation"). Never assemble styles from memory — clone from a
|
|
32
|
+
file the app saved.
|
|
33
|
+
3. **Content**: if starting from text, split it into atoms first — 1-3
|
|
34
|
+
keywords per node, one idea per node, <=9 first-level branches, depth <=4
|
|
35
|
+
(design reference, hard rules). Splitting "X and Y" into two nodes is the
|
|
36
|
+
thinking.
|
|
37
|
+
4. **Layout**: one fillColor per first-level subtree; curved thick-to-thin
|
|
38
|
+
edges; related branches adjacent. Radial "sun" for exploration,
|
|
39
|
+
right-flowing tree when reading order matters.
|
|
40
|
+
5. **QA loop**: recipe, "QA loop" — validate, render, vision-check, fix,
|
|
41
|
+
re-render. On this machine there is no drawio CLI: validate with
|
|
42
|
+
ElementTree and round-trip through the drawio MCP
|
|
43
|
+
(`tools.search("drawio")` finds it — tools.list caps at 100 and hides it),
|
|
44
|
+
then judge via screenshot + vision if a browser path exists.
|
|
45
|
+
6. **Hand-off**: offer the extracted indented outline; commit the canvas if
|
|
46
|
+
it lives in a repo.
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# Drawio programmatic recipe — quick reference
|
|
2
|
+
|
|
3
|
+
This file is self-contained for the skill.
|
|
4
|
+
|
|
5
|
+
## The pitfall
|
|
6
|
+
|
|
7
|
+
Geometry cells must be `<mxGeometry ... as="geometry"/>`. Using
|
|
8
|
+
`as="mxGeometry"` is well-formed XML that validates fine, but drawio does
|
|
9
|
+
not bind it: nodes lose geometry, render as label slivers at (0,0), and CLI
|
|
10
|
+
export yields a ~40x27 px crop. Check exported PNG IHDR dimensions when in
|
|
11
|
+
doubt.
|
|
12
|
+
|
|
13
|
+
## Generation
|
|
14
|
+
|
|
15
|
+
1. Clone styles verbatim from a file the app saved (native template). For
|
|
16
|
+
mindmaps the load-bearing attributes: swimlane containerType=tree;
|
|
17
|
+
nodes treeFolding=1;treeMoving=1;newEdgeStyle={...}; edges
|
|
18
|
+
edgeStyle=entityRelationEdgeStyle;curved=1, no arrows.
|
|
19
|
+
2. Escape attribute values: " for quotes inside newEdgeStyle,
|
|
20
|
+
& < > for the rest.
|
|
21
|
+
3. Validate with ElementTree, then export before shipping.
|
|
22
|
+
4. When debugging render failures, mutate a known-good file instead of
|
|
23
|
+
assembling from scratch.
|
|
24
|
+
|
|
25
|
+
## drawio MCP (via mcporter: mcp.drawio.*)
|
|
26
|
+
|
|
27
|
+
Discover refs with `tools.search("drawio")` — `tools.list` pages at 100 and
|
|
28
|
+
servers sorted past the cap look missing (a whole session once "lost" drawio
|
|
29
|
+
this way).
|
|
30
|
+
|
|
31
|
+
- list_pages {path} -> ids/names/sizes.
|
|
32
|
+
- get_page {path, page: "<page NAME>"} -> page mxGraphModel text. page is
|
|
33
|
+
the NAME string, not an index.
|
|
34
|
+
- set_page {path, page, content} -> surgical page write; drawio
|
|
35
|
+
re-serializes itself, envelope stays intact.
|
|
36
|
+
- Pool/Lane/Note: Pool = swimlane with childLayout=stackLayout; a shape
|
|
37
|
+
dropped in a lane gets parent=<lane id> — board state is the parent map.
|
|
38
|
+
|
|
39
|
+
## CLI
|
|
40
|
+
|
|
41
|
+
- Export: drawio -x -f png -e -b 10 -s 2 -o out.png in.drawio
|
|
42
|
+
- Mermaid -> drawio and --layout (ELK: radialTree/horizontalTree/organic):
|
|
43
|
+
need desktop build >= 31.x (29.7.9 lacks both — check --help).
|
|
44
|
+
- Version: PowerShell (Get-Item 'C:\Program Files\draw.io\draw.io.exe').VersionInfo.ProductVersion
|
|
45
|
+
- Update: download release installer, verify SHA256 against
|
|
46
|
+
Files-SHA256-Hashes.txt (match exact filename — arm64 lines share the
|
|
47
|
+
substring), taskkill draw.io.exe, install /S.
|
|
48
|
+
|
|
49
|
+
## QA loop
|
|
50
|
+
|
|
51
|
+
Export at -s 2 -> multimodal critique of the PNG (overlaps, truncation,
|
|
52
|
+
edges through nodes, balance) -> fix coordinates -> re-export. Judge by IHDR
|
|
53
|
+
dimensions + vision, never byte size.
|
|
54
|
+
|
|
55
|
+
No drawio CLI on this machine (native Linux; the `drawio -x` and
|
|
56
|
+
PowerShell-version notes above are Windows/WSL history). There: validate the
|
|
57
|
+
XML with ElementTree, round-trip through the drawio MCP (set_page then
|
|
58
|
+
get_page — drawio re-serializes and stays the authority), and screenshot +
|
|
59
|
+
vision-check if a browser path exists. `pi.bash` raises on nonzero exit —
|
|
60
|
+
pass `settle=True` for probing commands (a failed glob is not a crash).
|