fletchshot-mcp 0.1.1 → 0.1.3

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 CHANGED
@@ -14,9 +14,8 @@ macOS only. Requires [FletchShot](https://fletchshot.app/) (Mac App Store
14
14
  build, bundle id `app.fletchshot.FletchShot`) to be installed, and Node.js 18+
15
15
  to run this package.
16
16
 
17
- > **Note:** drafts need a FletchShot version newer than 2.3.3, which is in App
18
- > Store review. Older versions open the draft as a plain image without the
19
- > Return button.
17
+ > **Note:** drafts need FletchShot 2.4.0 or later. Older versions open the
18
+ > draft as a plain image without the Return button.
20
19
 
21
20
  ## Install
22
21
 
@@ -68,6 +67,10 @@ No other permission, entitlement, or FletchShot setting is required — and
68
67
  nothing is configured inside FletchShot's own Settings window for this (see
69
68
  FletchShot's help page for why).
70
69
 
70
+ If the Screen Recording permission is missing, `capture` fails with a message
71
+ telling you to grant it (System Settings → Privacy & Security → Screen
72
+ Recording) to the process that launched this server and relaunch it.
73
+
71
74
  ## Tools
72
75
 
73
76
  1. **`capture`** — take a screenshot. `mode: "window"` matches a window by
@@ -76,19 +79,63 @@ FletchShot's help page for why).
76
79
  the whole screen; `mode: "region"` captures a screen-coordinate rectangle
77
80
  after a delay (for menus/popovers, which can't be captured as a standalone
78
81
  window — ask the human to open the menu within the delay). Returns the
79
- file path, pixel size, scale (Retina = 2x, etc.), and the image itself
80
- (unless it's too large to inline).
82
+ file path and pixel size of the **original** image (that's the coordinate
83
+ space `open_draft` always uses), plus a downscaled preview (long edge
84
+ capped at 1568px — see "Preview images" below) embedded as the tool's
85
+ image content.
81
86
  2. **`open_draft`** — take the path `capture` returned plus a list of simple
82
- annotations (`arrow`, `text`, `rect`, `ellipse`, `mosaic`, `number`, all in
83
- image-pixel, top-left-origin coordinates) and open it in FletchShot as an
84
- editable draft. The human adjusts it, then presses **Return to agent**
85
- (⌘-Return).
87
+ annotations (`arrow`, `text`, `rect`, `ellipse`, `mosaic`, `number`) and
88
+ open it in FletchShot as an editable draft. The human adjusts it, then
89
+ presses **Return to agent** (⌘-Return). Coordinates can be given either as
90
+ numeric image pixels (`{x,y}` or `[x,y]`, top-left origin) or as a **text
91
+ anchor** `{text: "some label"}` — see "Text anchors" below. If a text
92
+ anchor doesn't resolve to exactly one match, the call fails with the list
93
+ of strings it did recognize (with `occurrence` numbers) so the agent can
94
+ retry.
86
95
  3. **`wait_for_return`** — wait until the human returns the draft (or a
87
- timeout), then return the finished image.
96
+ timeout), then return the finished image (same preview-downscaling as
97
+ `capture`, unless `includeImage: false` is passed, in which case only the
98
+ path and pixel size are returned).
88
99
 
89
100
  Typical flow: `capture` → `open_draft` → (human edits, presses ⌘-Return) →
90
101
  `wait_for_return`.
91
102
 
103
+ ### Text anchors
104
+
105
+ Any point (`arrow.from`/`arrow.to`, `text.at`, `number.at`) or region
106
+ (`rect`/`ellipse`/`mosaic`) can be given as `{text: "label", occurrence?: n}`
107
+ instead of numeric coordinates. `open_draft` runs on-device OCR (macOS
108
+ Vision, `VNRecognizeTextRequest`, Japanese + English) over the image to find
109
+ that string and computes the coordinates itself — so if the target has
110
+ visible text, there's no need to zoom into the screenshot, measure pixels, or
111
+ write a script to find its position; just pass the string you can read.
112
+ Targets without text (icons, shapes, …) still need an approximate numeric
113
+ position — that's fine, the human fine-tunes it in FletchShot anyway.
114
+
115
+ - `arrow.to` as a text anchor docks the arrowhead just outside the nearest
116
+ edge of the text (not centered on it, so it doesn't cover the label); if
117
+ `arrow.from` is omitted, it's placed automatically outside the text in
118
+ whichever diagonal direction stays on-screen.
119
+ - `text.at` / `number.at` as a text anchor are placed just next to the target
120
+ (to the right by default) instead of on top of it.
121
+ - `rect` / `ellipse` / `mosaic` as a text anchor become the text's bounding
122
+ box plus a small margin (`margin`, default 12px).
123
+ - If the string matches more than once, the call fails and returns every
124
+ match found with its `occurrence` number; pass that number to disambiguate.
125
+ - For scale: at the default annotation size, text is drawn about 55px tall
126
+ and an arrowhead is about 120px long × 100px wide on a 2x (Retina) capture.
127
+
128
+ ### Preview images
129
+
130
+ The images embedded in `capture` and `wait_for_return` are downscaled copies
131
+ (long edge capped at 1568px by default, via macOS `sips`; the original file
132
+ on disk is untouched) — this is what keeps a single screenshot from costing
133
+ tens of thousands of tokens. `open_draft` coordinates are always in the
134
+ **original** image's pixel space (`capture`'s `widthPx`/`heightPx`), never
135
+ the preview's; the tool results also return `previewScaleFactor` (preview
136
+ pixels × `previewScaleFactor` = original pixels) in case you need to reason
137
+ about the preview image itself.
138
+
92
139
  ## Privacy
93
140
 
94
141
  This server does not use the network at all (stdio transport only). Captured
@@ -115,7 +162,7 @@ FletchShot's own help page documents this in more detail:
115
162
  macOS 専用です。[FletchShot](https://fletchshot.app/)(Mac App Store 版、バンドルID
116
163
  `app.fletchshot.FletchShot`)のインストールと、このパッケージを動かす Node.js 18 以上が必要です。
117
164
 
118
- > **注意:** 下書きを開くには、2.3.3 より新しい FletchShot(App Store の審査中)が必要です。
165
+ > **注意:** 下書きを開くには、FletchShot 2.4.0 以降が必要です。
119
166
  > それより前の版では、下書きは「返す」ボタンのない普通の画像として開きます。
120
167
 
121
168
  ## 導入
@@ -166,21 +213,60 @@ args = ["-y", "fletchshot-mcp"]
166
213
  これ以外の許可・entitlement・FletchShot側の設定は不要です。FletchShotの設定画面にも、この
167
214
  機能のための項目は置いていません(理由はFletchShotのヘルプページを参照してください)。
168
215
 
216
+ 「画面収録」の許可が無い場合、`capture` は許可の付与場所(システム設定 > プライバシーと
217
+ セキュリティ > 画面収録)と、起動元プロセスを再起動する必要がある旨を案内するメッセージで
218
+ 失敗します。
219
+
169
220
  ## ツール
170
221
 
171
222
  1. **`capture`** — 画面を撮る。`mode: "window"` はアプリ名・ウィンドウタイトルの部分一致で
172
223
  ウィンドウ単体を撮る(一致なし・複数一致なら撮らずに候補一覧を返す)。`mode: "screen"` は
173
224
  画面全体。`mode: "region"` は画面座標の矩形を遅延つきで撮る(メニュー・ポップオーバー用。
174
- ウィンドウ単体では撮れないため、遅延の間に人へメニューを開いてもらう)。戻り値はファイルパス・
175
- ピクセルの幅高さ・倍率(Retinaなら2倍等)と、大きすぎない限り画像そのもの。
225
+ ウィンドウ単体では撮れないため、遅延の間に人へメニューを開いてもらう)。戻り値のファイルパス・
226
+ 幅高さは**元画像**のもの(open_draftの座標は常にこちらが基準)。埋め込む画像は長辺最大1568px
227
+ に縮小したプレビュー(後述「プレビュー画像」)。
176
228
  2. **`open_draft`** — `capture` が返したパスと、簡易な注釈(`arrow`・`text`・`rect`・
177
- `ellipse`・`mosaic`・`number`。すべて画像ピクセル・左上原点で指定)を受け取り、FletchShotで
178
- 掴める下書きとして開く。人が直して「エージェントに返す」(⌘↩)を押す。
229
+ `ellipse`・`mosaic`・`number`)を受け取り、FletchShotで掴める下書きとして開く。人が直して
230
+ 「エージェントに返す」(⌘↩)を押す。座標は数値({x,y}・[x,y]・画像ピクセル・左上原点)か、
231
+ **文字アンカー** `{text: "対象の文字列"}`(後述)のいずれかで指定する。文字アンカーが一意に
232
+ 解決できないときは、認識できた候補一覧(occurrence番号つき)とともに失敗するので、
233
+ occurrenceを指定して呼び直せる。
179
234
  3. **`wait_for_return`** — 人が下書きを返す(または時間切れになる)まで待ち、仕上がり画像を
180
- 返す。
235
+ 返す(captureと同様、埋め込みは縮小プレビュー。`includeImage: false` ならパスと幅高さだけ
236
+ 返す)。
181
237
 
182
238
  典型的な流れ: `capture` → `open_draft` →(人が直して⌘↩)→ `wait_for_return`。
183
239
 
240
+ ### 文字アンカー
241
+
242
+ 点座標(`arrow.from`/`arrow.to`・`text.at`・`number.at`)や範囲(`rect`・`ellipse`・`mosaic`)は、
243
+ 数値座標の代わりに `{text: "対象の文字列", occurrence?: n}` で指定できる。`open_draft` は
244
+ 画像に対してmacOS Vision(`VNRecognizeTextRequest`、日本語・英語)でオンデバイスの文字認識を
245
+ 行い、その文字列を探して座標を自動算出する——つまり対象に文字が写っていれば、画像を拡大して
246
+ 画素を確認したり座標を測るスクリプトを書いたりせずに、見えている文字列をそのまま渡せばよい。
247
+ 文字の無い対象(アイコンや図形など)はおおまかな数値座標で構わない(人がFletchShot上で微調整
248
+ する前提)。
249
+
250
+ - `arrow.to` を文字アンカーにすると、矢頭は文字の中心ではなく、文字の縁から少し外側(文字を
251
+ 隠さない位置)に自動配置する。`arrow.from` を省略すると、画像の端に出ない範囲で対象の外側・
252
+ 斜め方向から自動で引く。
253
+ - `text.at`・`number.at` を文字アンカーにすると、対象に重ねず近く(既定で右側)に自動で置く。
254
+ - `rect`・`ellipse`・`mosaic` を文字アンカーにすると、文字の枠に余白(`margin`、既定12px)を
255
+ 足した範囲になる。
256
+ - 同じ文字列が複数見つかった場合は失敗し、見つかった候補すべてをoccurrence番号つきで返す。
257
+ その番号を指定して呼び直せばよい。
258
+ - 目安: 既定の注釈サイズでは、文字の高さは約55px、矢頭は長さ約120px・幅約100px(2倍=Retina
259
+ 撮影時)。
260
+
261
+ ### プレビュー画像
262
+
263
+ `capture`・`wait_for_return` が埋め込む画像は、長辺最大1568px(既定値)に縮小したコピー
264
+ (macOS標準の`sips`を使用。ディスク上の元ファイルは書き換えない)——1枚のスクリーンショットだけで
265
+ 数万トークンを消費してしまうのを防ぐための縮小。`open_draft`の座標は常に**元画像**のピクセル
266
+ 座標(`capture`が返す`widthPx`/`heightPx`基準)であり、プレビューの座標ではない。戻り値の
267
+ `previewScaleFactor`(プレビュー座標×`previewScaleFactor`=元画像ピクセル)は、プレビュー画像
268
+ そのものについて考える必要があるときのために返している。
269
+
184
270
  ## プライバシー
185
271
 
186
272
  本サーバーは通信を一切行いません(stdioのみ)。撮影した画像・下書きはディスクの一時ディレクトリへ
package/dist/src/index.js CHANGED
@@ -35,7 +35,7 @@ function windowListText(candidates) {
35
35
  .map((w) => `- ${w.owner} / "${w.name}" (id=${w.id}, ${w.width}x${w.height} at ${w.x},${w.y})`)
36
36
  .join("\n");
37
37
  }
38
- const server = new McpServer({ name: "fletchshot-mcp", version: "0.1.0" });
38
+ const server = new McpServer({ name: "fletchshot-mcp", version: "0.1.2" });
39
39
  // --- 1. capture -----------------------------------------------------------
40
40
  server.registerTool("capture", {
41
41
  title: "Capture a screenshot",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "fletchshot-mcp",
3
- "version": "0.1.1",
3
+ "version": "0.1.3",
4
4
  "description": "FletchShot (macOS screenshot annotation app) agent draft MCP server: capture a screenshot, open it in FletchShot as an editable draft, and wait for a human to return the finished image.",
5
5
  "type": "module",
6
6
  "license": "MIT",