vitya
6c96682c60
Wraps the local projects-meta-mcp stdio server with the validated split-pair pattern (setup-X / using-X), 4th application after context7 / wiki / tasks. setup-projects-meta — 8-phase install: clones server repo to ~/.local/projects-meta-mcp, builds, writes ~/.config/projects-mcp/auth.toml, clones shared wiki to ~/projects/projects-wiki/ (canon path; legacy ~/projects/.wiki is detected and migrated — old path caused the wiki-path-mismatch bug, fixed upstream in 621a69f), registers mcpServers.projects-meta in ~/.claude.json. Confirmation gates between discovery and writes. using-projects-meta — runtime policy: read tools (tasks_aggregate, knowledge_search, meta_status, ...) and mutation tools with mandatory two-step preview→confirm. Carries the local-first rule inline: for the current project read .tasks/ / .wiki/ from disk; MCP cache is for *other* projects only. Wiki concept page concepts/projects-meta-skills.md documents the design, the path-canon fix, and the round-trip task lifecycle across machines. Closes [projects-meta-skills] in claude-skills (created from DESKTOP-NSEF0UK via projects-meta-mcp). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
99 lines
4.5 KiB
Markdown
99 lines
4.5 KiB
Markdown
# setup-projects-meta
|
|
|
|
One-time skill that brings up the local `projects-meta-mcp` stdio server on a
|
|
new (or freshly broken) machine. Clones the server repo, builds it, writes
|
|
`~/.config/projects-mcp/auth.toml` with the user's Gitea token, clones the
|
|
shared wiki to `~/projects/projects-wiki/.wiki`, and registers `mcpServers.projects-meta`
|
|
in `~/.claude.json`.
|
|
|
|
The runtime policy for *using* the resulting tools lives in
|
|
[`using-projects-meta`](../using-projects-meta/) — `setup-projects-meta` is the
|
|
only place that touches user-level config or installs the server.
|
|
|
|
`projects-meta-mcp` reference (full):
|
|
`mcp__projects-meta__knowledge_get slug=packages/projects-meta-mcp`
|
|
|
|
## When it triggers
|
|
|
|
- User says: "install projects-meta", "set up projects-meta", "configure projects-meta",
|
|
"настрой projects-meta", "установи projects-meta", "projects-meta не работает",
|
|
"projects-meta isn't working".
|
|
- [`using-projects-meta`](../using-projects-meta/) detects missing
|
|
`mcp__projects-meta__*` tools and delegates here via its Prerequisites
|
|
section.
|
|
- A new machine in the multi-machine fleet — install once per machine.
|
|
|
|
## What it installs
|
|
|
|
| Path | Role |
|
|
|---|---|
|
|
| `~/.local/projects-meta-mcp/` | server repo (cloned from Gitea) |
|
|
| `~/.local/projects-meta-mcp/dist/server.js` | built stdio entry point |
|
|
| `~/.config/projects-mcp/auth.toml` | Gitea credentials (token-bearing) |
|
|
| `~/.cache/projects-mcp/tasks.json` | aggregated tasks cache |
|
|
| `~/projects/projects-wiki/` | shared wiki clone root (Gitea repo `projects-wiki`) |
|
|
| `~/projects/projects-wiki/.wiki/` | wiki content root (read by MCP server) |
|
|
| `~/.claude.json` (`mcpServers.projects-meta`) | MCP registration |
|
|
|
|
## Hard rules
|
|
|
|
- **Never auto-mutate.** Phase 1 (discovery) and Phase 2 (plan) always pause
|
|
for explicit confirmation. A trigger phrase grants permission to inspect,
|
|
not to clone or write secrets.
|
|
- **Never echo the Gitea token in chat.** Edit / Write tool calls inevitably
|
|
contain it (that's how it lands in `auth.toml`); chat output must not.
|
|
- **Never clone over an unrelated `~/projects/projects-wiki/` (or legacy `~/projects/.wiki`).**
|
|
If either path exists with a non-matching `origin`, stop and ask — the user
|
|
may have an unrelated wiki there.
|
|
- **Don't use the legacy `~/projects/.wiki` path.** It's deprecated — the MCP
|
|
server's `loadWiki` reads from `~/projects/projects-wiki/.wiki/<type>/...`,
|
|
while writes to `~/projects/.wiki/.wiki/...` would be invisible. Phase 4
|
|
detects a legacy clone and migrates to the canon path.
|
|
- **Always `chmod 600` `auth.toml` on Linux / macOS.** Token leak otherwise.
|
|
|
|
## Procedure (high-level)
|
|
|
|
1. **Phase 0** — environment sanity (Node ≥ 18, git, npm, network to Gitea).
|
|
2. **Phase 1** — discovery (token / repo / wiki clone / MCP registration / cache).
|
|
3. **Phase 2** — plan + confirm. Wait for explicit "ok"/"go"/"поехали".
|
|
4. **Phase 3** — backup (`~/.claude.json`, existing `auth.toml`).
|
|
5. **Phase 4** — clone / pull repo + `npm install && npm run build`; clone
|
|
shared wiki if absent.
|
|
6. **Phase 5** — write `~/.config/projects-mcp/auth.toml` with `gitea_token`.
|
|
7. **Phase 6** — register `mcpServers.projects-meta` in `~/.claude.json` with
|
|
absolute path to `dist/server.js`.
|
|
8. **Phase 7** — smoke test (`mcp__projects-meta__meta_status`) + `node dist/sync.js`
|
|
to populate the cache.
|
|
9. **Phase 8** — restart guidance + final report.
|
|
|
|
Full procedure with shell snippets and templates lives in [`SKILL.md`](SKILL.md).
|
|
|
|
## Rollback
|
|
|
|
1. Stop. Don't fix forward.
|
|
2. `cp <file>.bak-<ts> <file>` for `~/.claude.json` and `~/.config/projects-mcp/auth.toml`.
|
|
3. Optional: `rm -rf ~/.local/projects-meta-mcp` and `rm -rf ~/.cache/projects-mcp`.
|
|
Keep `~/projects/projects-wiki/` — it's a useful clone regardless of MCP state.
|
|
4. Restart Claude Code.
|
|
5. Confirm `mcp__projects-meta__*` tools are gone (or back to the prior version).
|
|
|
|
## Install
|
|
|
|
From the repo root:
|
|
|
|
```bash
|
|
bash scripts/install.sh setup-projects-meta
|
|
```
|
|
|
|
Works on Windows under git-bash, Linux, macOS.
|
|
|
|
## See also
|
|
|
|
- [`using-projects-meta`](../using-projects-meta/) — runtime policy for
|
|
cross-project task aggregation and shared-wiki query / ingest.
|
|
- [`setup-context7`](../setup-context7/) — companion pattern for the context7
|
|
MCP plugin (similar 8-phase shape).
|
|
- [`setup-wiki`](../setup-wiki/), [`setup-tasks`](../setup-tasks/) —
|
|
per-project setup skills (in-repo `.wiki/` and `.tasks/`); orthogonal to
|
|
this skill, which sets up the cross-project layer.
|