@hidechae/eztab-mcp 0.1.2 → 0.3.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.
- package/README.md +75 -41
- package/dist/server.js +938 -382
- package/package.json +3 -4
package/README.md
CHANGED
|
@@ -1,28 +1,29 @@
|
|
|
1
|
-
# EZTab MCP server
|
|
1
|
+
# EZTab MCP server
|
|
2
2
|
|
|
3
3
|
An [MCP](https://modelcontextprotocol.io) server that lets an AI agent (e.g.
|
|
4
|
-
Claude)
|
|
5
|
-
|
|
6
|
-
The server holds the authoritative document and runs a localhost WebSocket
|
|
7
|
-
**hub**. The desktop app connects to it (toggle **Live** in the toolbar) and
|
|
8
|
-
syncs both ways: the agent's tool calls appear in the app instantly, and your
|
|
9
|
-
edits in the app are visible to the agent.
|
|
4
|
+
Claude) build and edit guitar/bass tablature using EZTab's data model.
|
|
10
5
|
|
|
11
6
|
## How it works
|
|
12
7
|
|
|
13
8
|
```
|
|
14
|
-
Claude ──stdio──> MCP server
|
|
15
|
-
|
|
16
|
-
|
|
9
|
+
Claude ──stdio──> MCP server ──> in-memory document
|
|
10
|
+
│ EZTAB_TOKEN (MCP 連携トークン)
|
|
11
|
+
▼
|
|
12
|
+
eztab-sync ── GET /tabs, GET /tabs/:id (list_tabs / open_tab)
|
|
13
|
+
└─ POST /inbox (send_to_eztab)
|
|
14
|
+
▲ ポーリング
|
|
15
|
+
EZTab アプリ: 画面上部のバナーで挿入 / 新規タブ / 修正版の反映
|
|
17
16
|
```
|
|
18
17
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
18
|
+
エージェントのツール呼び出しがメモリ上のドキュメントを書き換え、`get_tab` が
|
|
19
|
+
ASCII レンダリングを返します。`send_to_eztab` で結果をアプリの inbox に送ると、
|
|
20
|
+
アプリ側で「カーソルの後に挿入」「新規タブとして作成」「(open_tab で開いたタブの)
|
|
21
|
+
修正版を反映」を選べます。挿入・反映は未保存の編集として入り、Save するまで確定
|
|
22
|
+
しません。MCP からライブラリを直接書き換える経路はありません。
|
|
24
23
|
|
|
25
|
-
|
|
24
|
+
連携トークンはアプリの Settings → MCP 連携 で発行します(1ユーザー1本、再発行で
|
|
25
|
+
旧トークンは失効)。トークンで使えるのはタブ一覧・取得と inbox への投函だけです。
|
|
26
|
+
トークン無しでも、ライブラリ連携以外のツールは今まで通り使えます。
|
|
26
27
|
|
|
27
28
|
## Install (published package)
|
|
28
29
|
|
|
@@ -31,31 +32,37 @@ Published to npm as **`@hidechae/eztab-mcp`**. Add it to any MCP client:
|
|
|
31
32
|
```json
|
|
32
33
|
{
|
|
33
34
|
"mcpServers": {
|
|
34
|
-
"eztab": {
|
|
35
|
+
"eztab": {
|
|
36
|
+
"command": "npx",
|
|
37
|
+
"args": ["-y", "@hidechae/eztab-mcp"],
|
|
38
|
+
"env": { "EZTAB_TOKEN": "eztab_…" }
|
|
39
|
+
}
|
|
35
40
|
}
|
|
36
41
|
}
|
|
37
42
|
```
|
|
38
43
|
|
|
39
|
-
Requires the EZTab desktop app (toggle **Live** in its toolbar) on the same
|
|
40
|
-
machine — the server runs a localhost WebSocket hub the app connects to.
|
|
41
|
-
|
|
42
44
|
### Releasing a new version
|
|
43
45
|
|
|
44
46
|
npm versions are immutable, so publishing is deliberate (tag-driven):
|
|
45
47
|
|
|
46
48
|
```sh
|
|
47
49
|
# bump mcp/package.json "version", commit, then:
|
|
48
|
-
git tag mcp-
|
|
50
|
+
git tag mcp-vX.Y.Z origin/main && git push origin mcp-vX.Y.Z
|
|
49
51
|
```
|
|
50
52
|
|
|
51
|
-
The `Publish MCP to npm` GitHub Action builds and publishes on `mcp-v*` tags
|
|
52
|
-
(
|
|
53
|
+
The `Publish MCP to npm` GitHub Action builds and publishes on `mcp-v*` tags.
|
|
54
|
+
認証は npm の Trusted Publishing(GitHub Actions の OIDC)で、トークンの Secret は不要。
|
|
55
|
+
npmjs.com のパッケージ設定で `hidechae/eztab` の `publish-mcp.yml` を Trusted Publisher に
|
|
56
|
+
登録してある前提。タグ名と `mcp/package.json` の version が一致しないと公開しない。
|
|
57
|
+
公開に失敗したタグをやり直すときは、失敗した run の re-run ではなく(古いワークフローのまま
|
|
58
|
+
再実行される)、`Publish MCP to npm` を workflow_dispatch し、`tag` にそのタグを指定する
|
|
59
|
+
(`gh workflow run publish-mcp.yml -f tag=mcp-vX.Y.Z`)。指定したタグの中身が公開される。
|
|
53
60
|
|
|
54
61
|
## Setup (local dev)
|
|
55
62
|
|
|
56
63
|
Dependencies are in the repo's `package.json` (`npm install`). This repo ships a
|
|
57
64
|
project-scoped `.mcp.json`, so Claude Code running here offers the `eztab`
|
|
58
|
-
server automatically (approve it when asked).
|
|
65
|
+
server automatically (approve it when asked).
|
|
59
66
|
|
|
60
67
|
For Claude Desktop or elsewhere:
|
|
61
68
|
|
|
@@ -75,32 +82,59 @@ Run standalone for testing: `task mcp` (or `npx tsx mcp/server.ts`).
|
|
|
75
82
|
|
|
76
83
|
## Tools
|
|
77
84
|
|
|
78
|
-
These act on the live shared document (no file path needed):
|
|
79
|
-
|
|
80
85
|
| Tool | What it does |
|
|
81
86
|
|------|--------------|
|
|
82
|
-
| `
|
|
83
|
-
| `
|
|
84
|
-
| `
|
|
85
|
-
| `
|
|
86
|
-
| `new_tab` |
|
|
87
|
-
| `open_in_app` | Ask the connected app to open a tab by path (the app reads/saves it — the server never touches the filesystem) |
|
|
87
|
+
| `list_tabs` | ライブラリの一覧(アプリで編集中のタブは端末名つき)。要 `EZTAB_TOKEN` |
|
|
88
|
+
| `open_tab` | ライブラリのタブをこのセッションに読み込む(修正用)。要 `EZTAB_TOKEN` |
|
|
89
|
+
| `send_to_eztab` | 今のドキュメントをアプリの inbox に送る。`open_tab` で開いたものは修正版として届く(`as_new` で新規扱い)。要 `EZTAB_TOKEN` |
|
|
90
|
+
| `get_tab` | Readable ASCII rendering of the document under edit (`from`/`to` で小節範囲を絞れる) |
|
|
91
|
+
| `new_tab` | Start a fresh document (title, artist, tuning/preset, measures, tempo) |
|
|
88
92
|
| `set_title` | Set the document title |
|
|
89
93
|
| `set_artist` | Set the document artist |
|
|
90
|
-
| `
|
|
91
|
-
| `
|
|
94
|
+
| `write_measures` | 小節単位の一括入力。1拍を1文字列で書き(`"6:5 6:~7"` など)、列番号への割り付けはサーバ側で行う。譜面・画像からの書き起こし向け |
|
|
95
|
+
| `set_cells` | Set tab cells: a fret number, `rest`, `mute` (cutting "x"), or `clear` (empty = sustain). Optional `bend` (0.5/1/1.5) chokes a fret note; optional `tie` ties/slurs it to the previous note (same pitch = just sustain); optional `pm` palm-mutes it |
|
|
96
|
+
| `set_chords` | Set chord labels per column |
|
|
92
97
|
| `set_key` / `remove_key` | Set/add or remove a key (key change) at a measure |
|
|
93
98
|
| `set_section` | Set/remove a section marker (e.g. "Verse", "Chorus") |
|
|
94
99
|
| `set_tempo` | Set playback BPM |
|
|
95
|
-
| `
|
|
100
|
+
| `set_time_signature` | Set a measure's time signature |
|
|
101
|
+
| `set_resolution` | Set a measure's subdivisions per beat (8th/16th/triplets/quintuplets) |
|
|
96
102
|
| `add_measures` / `remove_measure` | Insert/remove measures (keys & sections re-anchored) |
|
|
97
|
-
| `set_tuning` | Replace tuning / string count |
|
|
103
|
+
| `set_tuning` | Replace tuning / string count (`track` で対象パートを指定) |
|
|
104
|
+
| `add_track` / `remove_track` | パート(ベース・2本目のギターなど)の追加・削除。メインを含めて最大4、track 0(メイン)は削除不可 |
|
|
105
|
+
|
|
106
|
+
### 複数パート(トラック)
|
|
107
|
+
|
|
108
|
+
1つのタブにメインを含めて最大4パートを持てる(docs/design/0001-multiple-tracks.md)。
|
|
109
|
+
|
|
110
|
+
- `set_cells` / `write_measures` / `set_resolution` / `set_tuning` は任意の `track`(0 始まり、既定 0 = メイン)を取る
|
|
111
|
+
- 小節と拍子は全パート共通。`add_measures` / `remove_measure` / `set_time_signature` は全パートに作用し、
|
|
112
|
+
`write_measures` で末尾に書き足すと全パートに小節が増える。分割(subdivisions)はパートごと
|
|
113
|
+
- コードは track 0 のもの(`set_chords` は track 0 の列で指定)。`write_measures(track > 0)` ではコード指定と、
|
|
114
|
+
既存小節の拍子を変える `time` を拒否する
|
|
115
|
+
- `get_tab` は全パートを小節ごとに並べて表示する(`track` で1パートに絞れる)
|
|
116
|
+
- `send_to_eztab` は `x-eztab-format-revision: 2` を付けて送る。0.2.0 以前の MCP は複数パートのタブを
|
|
117
|
+
送り返せない(サーバが 409 で拒否する)。新しい形式のタブ(リビジョン 3 以降)は読めるが編集・送信できない
|
|
98
118
|
|
|
99
119
|
These cover the editor's current model: variable string count, per-beat chords,
|
|
100
|
-
keys with mid-piece changes, section markers, per-measure resolution,
|
|
101
|
-
title/artist metadata. (Playback, the on-screen keypad,
|
|
102
|
-
library/archive are app-only UI concerns and intentionally
|
|
120
|
+
keys with mid-piece changes, section markers, per-measure resolution, time
|
|
121
|
+
signature, tempo, and title/artist metadata. (Playback, the on-screen keypad,
|
|
122
|
+
undo/redo and the library/archive are app-only UI concerns and intentionally
|
|
123
|
+
have no MCP tools.)
|
|
103
124
|
|
|
104
125
|
Indices are 0-based. `string` 0 is the top line; tuning is ordered high→low.
|
|
105
|
-
|
|
106
|
-
|
|
126
|
+
例外として `write_measures` の弦番号はギターの呼び方どおり 1 始まり(1 = TAB の一番上の線)
|
|
127
|
+
で、`get_tab` の行ラベルと一致する。
|
|
128
|
+
|
|
129
|
+
## Prompts
|
|
130
|
+
|
|
131
|
+
| Prompt | What it does |
|
|
132
|
+
|--------|--------------|
|
|
133
|
+
| `import_tab_from_image` | 添付した TAB 譜画像(通常 TAB・コードフォーム図・YouTube の TAB・バンドスコア1ページ)を書き起こす手順。引数 `part`(例: `Guitar II`)でバンドスコアのパートを指定、`notes` で補足 |
|
|
134
|
+
|
|
135
|
+
Claude Desktop では入力欄の「＋」→ eztab → `import_tab_from_image`、Claude Code
|
|
136
|
+
では `/mcp__eztab__import_tab_from_image` で呼び出し、画像を添付して送る。
|
|
137
|
+
|
|
138
|
+
EZTab のモデルに無い記譜(スライド・ハンマリング・プリング → タイ/スラー、
|
|
139
|
+
ハーモニクス・ビブラート・装飾音 → 主音のみ等)の寄せ方は手順書
|
|
140
|
+
([prompts.ts](prompts.ts))に書いてあり、書き起こし後に簡略化した箇所を報告させる。
|