# 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/.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/.wiki/` | shared wiki clone (Gitea repo `projects-wiki`, content in root) |
| `~/.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/.wiki/`.**
  If it exists with a non-matching `origin`, stop and ask — the user
  may have an unrelated wiki there.
- **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/.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.