commit 101317aa354d79f178664484300042fe5ae842e7
parent 97fa060969938793e1c5dce2a6f9bc848cdaf34d
Author: I Mean I'm Just Saying <imeanimjustsaying@kiwifarms.st>
Date: Mon, 28 Sep 2026 12:38:43 -0400
docs: the MCP examples register and run the server as `archilyzer mcp`
`claude mcp add archilyzer … -- pnpm -C "$PWD" archilyzer mcp` in AGENTS.md,
README.md (both blocks, and the run-it example) and mcp/README.md (Run it,
Add to Claude Code, the mcp.json form), in place of the long
`--filter yt-dlp-transcript-mcp exec tsx src/index.ts` form. mcp/README's
examples now register the server as `archilyzer` too, which the tracked
/ask and /sweep commands need. Env lines unchanged. Checked through the
worktree: `pnpm -C <repo> archilyzer mcp --local <dir>` answers initialize
as the first stdout line; pnpm's `$ …` line is on stderr. PUBLISH.md's
"(the form mcp/README.md uses)" is no longer true and goes.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Diffstat:
4 files changed, 39 insertions(+), 34 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
@@ -54,11 +54,14 @@ claude mcp add archilyzer \
--env TRANSCRIPT_SITE_URL=https://jeralyzer.pages.dev \
--env ARCHILYZER_EDITOR_URL=http://localhost:3001 \
--env WORKER_TOKEN=… \
- -- pnpm -C "$PWD" --filter yt-dlp-transcript-mcp exec tsx src/index.ts
+ -- pnpm -C "$PWD" archilyzer mcp
```
The two editor lines are optional: they let `fetch_clip` ask a local editor for clip
-media (`WORKER_TOKEN` is the editor's own, from `editor/.env`).
+media (`WORKER_TOKEN` is the editor's own, from `editor/.env`). `archilyzer mcp`
+(`common/bin/mcp.ts`) is `pnpm --filter yt-dlp-transcript-mcp exec tsx src/index.ts`
+behind the repo's CLI: the environment and any `--local`/`--remote`/`--hub` pass
+through, and stdout carries nothing but the protocol (pnpm's `$ …` line goes to stderr).
`TRANSCRIPT_HUB_URL` federates several sites; `TRANSCRIPT_LOCAL_DIR` reads a local
build off disk. The server never writes to an archive — `fetch_clip` asks the editor,
diff --git a/PUBLISH.md b/PUBLISH.md
@@ -443,5 +443,5 @@ claude mcp add archilyzer \
```
`archilyzer mcp` starts the same server as `pnpm --filter yt-dlp-transcript-mcp exec
-tsx src/index.ts` (the form [mcp/README.md](mcp/README.md) uses), with the
-environment passed through and nothing on stdout but the protocol.
+tsx src/index.ts`, with the environment passed through and nothing on stdout but the
+protocol; [mcp/README.md](mcp/README.md) has the other ways to run and register it.
diff --git a/README.md b/README.md
@@ -57,20 +57,20 @@ It is a local tool you run yourself, it only reads already-published JSON, and i
never modifies the archive:
```bash
-# point it at a published instance over HTTP
-TRANSCRIPT_SITE_URL=https://jeralyzer.pages.dev \
- pnpm --filter yt-dlp-transcript-mcp exec tsx src/index.ts
+# point it at a published instance over HTTP (from the repo root)
+TRANSCRIPT_SITE_URL=https://jeralyzer.pages.dev pnpm archilyzer mcp
```
-There is nothing to compile — it runs from source through `tsx`. To register it with
-Claude Code:
+There is nothing to compile — it runs from source through `tsx`. `archilyzer mcp` is
+the repo's CLI starting `mcp/`'s server; stdout carries only the MCP protocol. To
+register it with Claude Code:
```bash
claude mcp add archilyzer \
--env TRANSCRIPT_SITE_URL=https://jeralyzer.pages.dev \
--env ARCHILYZER_EDITOR_URL=http://localhost:3001 \
--env WORKER_TOKEN=… \
- -- pnpm -C /ABS/PATH/TO/this/repo --filter yt-dlp-transcript-mcp exec tsx src/index.ts
+ -- pnpm -C /ABS/PATH/TO/this/repo archilyzer mcp
```
The two editor lines are optional: they let `fetch_clip` ask a local editor for clip
@@ -323,13 +323,14 @@ claude mcp add archilyzer \
--env TRANSCRIPT_SITE_URL=https://jeralyzer.pages.dev \
--env ARCHILYZER_EDITOR_URL=http://localhost:3001 \
--env WORKER_TOKEN=… \
- -- pnpm -C "$PWD" --filter yt-dlp-transcript-mcp exec tsx src/index.ts
+ -- pnpm -C "$PWD" archilyzer mcp
claude # then try: /ask what has he said about magic tournaments?
```
The two editor lines are optional: they let `fetch_clip` ask a local editor for clip
media (`WORKER_TOKEN` is the editor's own). Leave them out for research alone.
-`-- pnpm -C "$PWD" archilyzer mcp` starts the same server through the repo's CLI.
+`archilyzer mcp` is `pnpm --filter yt-dlp-transcript-mcp exec tsx src/index.ts`
+through the repo's CLI; either form registers the same server.
> **Register the server as `archilyzer`.** The shipped commands call
> `mcp__archilyzer__ask_plan` / `mcp__archilyzer__sweep_plan`, and that tool name
diff --git a/mcp/README.md b/mcp/README.md
@@ -365,9 +365,9 @@ treated as no filter, so planning can never make a whole-corpus scan slower.
### Benchmark
-`mcp/bench/` drives the **real server over stdio**, through the same
-`pnpm --filter … exec tsx src/index.ts` command line the client is registered
-with, and times a fixed query set:
+`mcp/bench/` drives the **real server over stdio**, through
+`pnpm --filter … exec tsx src/index.ts` — the command `archilyzer mcp`, which a
+client is registered with, runs — and times a fixed query set:
```bash
pnpm --filter yt-dlp-transcript-mcp bench
@@ -501,30 +501,34 @@ of the package entirely.
## Run it
-From the monorepo (cwd is set to the package dir by `pnpm --filter … exec`, so
-the TypeScript path alias resolves):
+From the monorepo root, through the repo's CLI. `archilyzer mcp`
+(`common/bin/mcp.ts`) starts the server exactly as `pnpm --filter
+yt-dlp-transcript-mcp exec tsx src/index.ts` does — mcp's own `tsx`, cwd this
+package's dir (so the TypeScript path alias resolves), the environment and every
+argument after `mcp` passed through:
```sh
# a deployed site
-pnpm --filter yt-dlp-transcript-mcp exec tsx src/index.ts --remote https://rekietalyzer.pages.dev
+pnpm archilyzer mcp --remote https://rekietalyzer.pages.dev
# a hub, federating every member site
-pnpm --filter yt-dlp-transcript-mcp exec tsx src/index.ts --hub https://archilyzer-hub.pages.dev
+pnpm archilyzer mcp --hub https://archilyzer-hub.pages.dev
-# local shards on disk
-pnpm --filter yt-dlp-transcript-mcp exec tsx src/index.ts --local ../export/public
+# local shards on disk (a relative path resolves from mcp/, so give an absolute one)
+pnpm archilyzer mcp --local "$PWD/export/public"
```
-Logs go to stderr; stdout is the MCP JSON-RPC channel.
+Logs go to stderr; stdout is the MCP JSON-RPC channel. pnpm's own `$ …` line goes
+to stderr too, so nothing precedes the protocol.
## Add to Claude Code
```sh
-claude mcp add rekietalyzer \
+claude mcp add archilyzer \
--env TRANSCRIPT_SITE_URL=https://rekietalyzer.pages.dev \
--env ARCHILYZER_EDITOR_URL=http://localhost:3001 \
--env WORKER_TOKEN=… \
- -- pnpm -C /ABS/PATH/TO/yt-dlp-transcript-browser --filter yt-dlp-transcript-mcp exec tsx src/index.ts
+ -- pnpm -C /ABS/PATH/TO/yt-dlp-transcript-browser archilyzer mcp
```
The two editor lines are optional: they let `fetch_clip` ask a local editor for
@@ -534,23 +538,20 @@ the same; `fetch_clip` then says it has no editor and fetches nothing.
**The `/sweep` and `/ask` commands.** `.claude/commands/{sweep,ask}.md` in this
repo call `mcp__archilyzer__sweep_plan` / `mcp__archilyzer__ask_plan` — the tool
-name embeds the MCP server name **as you registered it**, so if you used another
-name (`rekietalyzer` above), change the `mcp__<name>__` prefix in those two
-files to match. `foo:bar` namespacing is plugin-only, so what you type stays
-`/sweep`, not `/archilyzer:sweep`.
+name embeds the MCP server name **as you registered it**, which is why the example
+registers it as `archilyzer` whatever archive it reads. Under another name (say
+`rekietalyzer`), change the `mcp__<name>__` prefix in those two files to match.
+`foo:bar` namespacing is plugin-only, so what you type stays `/sweep`, not
+`/archilyzer:sweep`.
## Add to any MCP client (mcp.json)
```json
{
"mcpServers": {
- "rekietalyzer": {
+ "archilyzer": {
"command": "pnpm",
- "args": [
- "-C", "/ABS/PATH/TO/yt-dlp-transcript-browser",
- "--filter", "yt-dlp-transcript-mcp",
- "exec", "tsx", "src/index.ts"
- ],
+ "args": ["-C", "/ABS/PATH/TO/yt-dlp-transcript-browser", "archilyzer", "mcp"],
"env": {
"TRANSCRIPT_SITE_URL": "https://rekietalyzer.pages.dev",
"ARCHILYZER_EDITOR_URL": "http://localhost:3001",
