@e4779/skills 0.0.0-stage → 0.1.0

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.
Files changed (57) hide show
  1. package/chrome-devtools/README.md +76 -0
  2. package/chrome-devtools/SKILL.md +277 -0
  3. package/chrome-devtools/references/recipes.md +379 -0
  4. package/chrome-devtools/references/setup.md +138 -0
  5. package/drawio/SKILL.md +395 -0
  6. package/gh-cli/SKILL.md +83 -0
  7. package/grill/SKILL.md +72 -0
  8. package/layout-check/README.md +32 -0
  9. package/layout-check/SKILL.md +416 -0
  10. package/layout-check/scripts/layoutProbe.mjs +539 -0
  11. package/mcpls/SKILL.md +261 -0
  12. package/mcpls/references/configuration.md +131 -0
  13. package/mcpls/references/install.md +13 -0
  14. package/mcporter/SKILL.md +90 -0
  15. package/mindmap/SKILL.md +46 -0
  16. package/mindmap/references/drawio-recipe.md +60 -0
  17. package/mindmap/references/mindmap-design.md +63 -0
  18. package/opensource-contribution/SKILL.md +119 -0
  19. package/package.json +29 -5
  20. package/shell-taste/.shellcheckrc +16 -0
  21. package/shell-taste/SKILL.md +95 -0
  22. package/shell-taste/references/handbook/dialects.md +168 -0
  23. package/shell-taste/references/handbook/dom/01-output-logging.md +245 -0
  24. package/shell-taste/references/handbook/dom/02-errors-exit.md +48 -0
  25. package/shell-taste/references/handbook/dom/03-installation-setup.md +179 -0
  26. package/shell-taste/references/handbook/dom/04-network.md +384 -0
  27. package/shell-taste/references/handbook/dom/05-files-paths.md +74 -0
  28. package/shell-taste/references/handbook/dom/06-checks-validation.md +127 -0
  29. package/shell-taste/references/handbook/dom/07-system-administration.md +103 -0
  30. package/shell-taste/references/handbook/dom/08-privilege-users.md +58 -0
  31. package/shell-taste/references/handbook/dom/09-text-data.md +62 -0
  32. package/shell-taste/references/handbook/dom/10-terminal-ux.md +60 -0
  33. package/shell-taste/references/handbook/dom/11-process-control.md +28 -0
  34. package/shell-taste/references/handbook/dom/12-uncategorized.md +161 -0
  35. package/shell-taste/references/handbook/dom/13-containers.md +13 -0
  36. package/shell-taste/references/handbook/dom/14-agents-ai-tooling.md +13 -0
  37. package/shell-taste/references/handbook/family-index.md +230 -0
  38. package/shell-taste/references/handbook/index.md +41 -0
  39. package/skill-author/SKILL.md +86 -0
  40. package/sobesednik/SKILL.md +98 -0
  41. package/sobesednik/card-template.md +23 -0
  42. package/sobesednik/personas/advocate.md +27 -0
  43. package/sobesednik/personas/analyst.md +29 -0
  44. package/sobesednik/personas/chat.md +42 -0
  45. package/sobesednik/personas/ifs.md +32 -0
  46. package/sobesednik/personas/journal/README.md +6 -0
  47. package/sobesednik/personas/nasreddin.md +29 -0
  48. package/sobesednik/personas/premortem.md +29 -0
  49. package/sobesednik/personas/rogers.md +27 -0
  50. package/sobesednik/personas/socratic.md +29 -0
  51. package/sobesednik/personas/stoic.md +27 -0
  52. package/sobesednik/references/persona-design.md +41 -0
  53. package/zai-mcp/README.md +63 -0
  54. package/zai-mcp/SKILL.md +160 -0
  55. package/zai-mcp/references/recipes.md +273 -0
  56. package/zai-mcp/references/tools.md +266 -0
  57. 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 |
@@ -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: &quot; for quotes inside newEdgeStyle,
20
+ &amp; &lt; &gt; 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).