insta-edits 0.1.0__py3-none-any.whl
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.
- insta_edits/__init__.py +3 -0
- insta_edits/__main__.py +4 -0
- insta_edits/bridge.py +150 -0
- insta_edits/cli.py +74 -0
- insta_edits/compat.py +65 -0
- insta_edits/config.py +68 -0
- insta_edits/doctor.py +199 -0
- insta_edits/transport.py +140 -0
- insta_edits-0.1.0.dist-info/METADATA +229 -0
- insta_edits-0.1.0.dist-info/RECORD +13 -0
- insta_edits-0.1.0.dist-info/WHEEL +4 -0
- insta_edits-0.1.0.dist-info/entry_points.txt +2 -0
- insta_edits-0.1.0.dist-info/licenses/LICENSE +21 -0
insta_edits/__init__.py
ADDED
insta_edits/__main__.py
ADDED
insta_edits/bridge.py
ADDED
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
"""Stdio <-> Streamable HTTP bridge between an MCP client and the Edits automation server.
|
|
2
|
+
|
|
3
|
+
Edits swaps its whole tool set with the screen (about 30 tools at home, about 270 in the editor) and
|
|
4
|
+
declares `tools.listChanged`, but never sends the notification. MCP clients such as Claude Code only
|
|
5
|
+
re-read the tool list when told, so they stay on the home-screen tools. After every tool call the
|
|
6
|
+
bridge re-reads the list itself and sends `notifications/tools/list_changed` when it differs.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
import json
|
|
12
|
+
import sys
|
|
13
|
+
import threading
|
|
14
|
+
from typing import Any, Callable, Optional, TextIO
|
|
15
|
+
|
|
16
|
+
from . import compat
|
|
17
|
+
from .transport import EditsClient, EditsHTTPError, EditsUnreachable
|
|
18
|
+
|
|
19
|
+
HINT_UNREACHABLE = "Open Edits and turn on Settings > Automation > Enable Automation Server."
|
|
20
|
+
HINT_AUTH = (
|
|
21
|
+
"The access token was rejected. Copy the current one from Edits > Settings > Automation "
|
|
22
|
+
"and update it (run: insta-edits set-token)."
|
|
23
|
+
)
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
class Writer:
|
|
27
|
+
"""Thread-safe line writer: client replies and stream notifications share stdout."""
|
|
28
|
+
|
|
29
|
+
def __init__(self, stream: TextIO):
|
|
30
|
+
self._stream = stream
|
|
31
|
+
self._lock = threading.Lock()
|
|
32
|
+
|
|
33
|
+
def write(self, message: Any) -> None:
|
|
34
|
+
line = json.dumps(compat.fix_message(message), ensure_ascii=False)
|
|
35
|
+
with self._lock:
|
|
36
|
+
self._stream.write(line + "\n")
|
|
37
|
+
self._stream.flush()
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def _error_for(message: Any, code: int, text: str) -> Optional[dict]:
|
|
41
|
+
if isinstance(message, dict) and "id" in message and "method" in message:
|
|
42
|
+
return {"jsonrpc": "2.0", "id": message["id"], "error": {"code": code, "message": text}}
|
|
43
|
+
return None
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
def _describe_http_error(err: EditsHTTPError) -> str:
|
|
47
|
+
if err.status in (401, 403):
|
|
48
|
+
return f"Edits refused the request (HTTP {err.status}). {HINT_AUTH}"
|
|
49
|
+
return f"Edits returned HTTP {err.status}: {err.body[:200]}"
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
LIST_CHANGED = {"jsonrpc": "2.0", "method": "notifications/tools/list_changed"}
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def _tool_names(result: Any) -> Optional[frozenset]:
|
|
56
|
+
if not isinstance(result, dict) or not isinstance(result.get("tools"), list) or result.get("nextCursor"):
|
|
57
|
+
return None
|
|
58
|
+
return frozenset(t.get("name") for t in result["tools"] if isinstance(t, dict))
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
class ToolSync:
|
|
62
|
+
"""Tells the client when Edits' tool set changed, because Edits itself never does."""
|
|
63
|
+
|
|
64
|
+
def __init__(self, client: EditsClient, log: Callable[[str], None]):
|
|
65
|
+
self._client = client
|
|
66
|
+
self._log = log
|
|
67
|
+
self._known: Optional[frozenset] = None
|
|
68
|
+
self._n = 0
|
|
69
|
+
|
|
70
|
+
def seen(self, result: Any) -> None:
|
|
71
|
+
names = _tool_names(result)
|
|
72
|
+
if names is not None:
|
|
73
|
+
self._known = names
|
|
74
|
+
|
|
75
|
+
def changed_after_call(self) -> bool:
|
|
76
|
+
self._n += 1
|
|
77
|
+
rid = f"insta-edits:tools:{self._n}"
|
|
78
|
+
try:
|
|
79
|
+
replies = self._client.post({"jsonrpc": "2.0", "id": rid, "method": "tools/list", "params": {}})
|
|
80
|
+
except Exception as err: # never let the sync check break the real call
|
|
81
|
+
self._log(f"tool sync skipped: {err}")
|
|
82
|
+
return False
|
|
83
|
+
reply = next((r for r in replies if isinstance(r, dict) and r.get("id") == rid), None)
|
|
84
|
+
names = _tool_names(reply.get("result")) if reply else None
|
|
85
|
+
if names is None:
|
|
86
|
+
return False
|
|
87
|
+
before, self._known = self._known, names
|
|
88
|
+
return before is not None and names != before
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def serve(
|
|
92
|
+
client: EditsClient,
|
|
93
|
+
stdin: TextIO = sys.stdin,
|
|
94
|
+
stdout: TextIO = sys.stdout,
|
|
95
|
+
log: Callable[[str], None] = lambda msg: None,
|
|
96
|
+
listen: bool = True,
|
|
97
|
+
sync_tools: bool = True,
|
|
98
|
+
) -> int:
|
|
99
|
+
writer = Writer(stdout)
|
|
100
|
+
stop = threading.Event()
|
|
101
|
+
listener: Optional[threading.Thread] = None
|
|
102
|
+
sync = ToolSync(client, log) if sync_tools else None
|
|
103
|
+
|
|
104
|
+
for raw in stdin:
|
|
105
|
+
raw = raw.strip()
|
|
106
|
+
if not raw:
|
|
107
|
+
continue
|
|
108
|
+
try:
|
|
109
|
+
incoming = json.loads(raw)
|
|
110
|
+
except json.JSONDecodeError:
|
|
111
|
+
log("ignored a line that is not JSON")
|
|
112
|
+
continue
|
|
113
|
+
messages = incoming if isinstance(incoming, list) else [incoming]
|
|
114
|
+
for message in messages:
|
|
115
|
+
try:
|
|
116
|
+
replies = client.post(message)
|
|
117
|
+
except EditsUnreachable as err:
|
|
118
|
+
log(f"cannot reach Edits at {client.url}: {err}")
|
|
119
|
+
reply = _error_for(message, -32001, f"Cannot reach Edits at {client.url}. {HINT_UNREACHABLE}")
|
|
120
|
+
if reply:
|
|
121
|
+
writer.write(reply)
|
|
122
|
+
continue
|
|
123
|
+
except EditsHTTPError as err:
|
|
124
|
+
log(_describe_http_error(err))
|
|
125
|
+
reply = _error_for(message, -32002, _describe_http_error(err))
|
|
126
|
+
if reply:
|
|
127
|
+
writer.write(reply)
|
|
128
|
+
continue
|
|
129
|
+
method = message.get("method") if isinstance(message, dict) else None
|
|
130
|
+
for reply in replies:
|
|
131
|
+
if sync and method == "tools/list" and isinstance(reply, dict):
|
|
132
|
+
sync.seen(reply.get("result"))
|
|
133
|
+
writer.write(reply)
|
|
134
|
+
if sync and method == "tools/call" and sync.changed_after_call():
|
|
135
|
+
log("Edits changed its tool set; notifying the client")
|
|
136
|
+
writer.write(LIST_CHANGED)
|
|
137
|
+
if (
|
|
138
|
+
listen
|
|
139
|
+
and listener is None
|
|
140
|
+
and isinstance(message, dict)
|
|
141
|
+
and message.get("method") == "initialize"
|
|
142
|
+
and client.session_id
|
|
143
|
+
):
|
|
144
|
+
listener = threading.Thread(
|
|
145
|
+
target=client.listen, args=(writer.write, stop, log), name="edits-notifications", daemon=True
|
|
146
|
+
)
|
|
147
|
+
listener.start()
|
|
148
|
+
|
|
149
|
+
stop.set()
|
|
150
|
+
return 0
|
insta_edits/cli.py
ADDED
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
"""Command line: `insta-edits [serve|doctor|set-token|version]`."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import argparse
|
|
6
|
+
import getpass
|
|
7
|
+
import sys
|
|
8
|
+
from typing import List, Optional
|
|
9
|
+
|
|
10
|
+
from . import __version__, config, doctor
|
|
11
|
+
from .bridge import serve
|
|
12
|
+
from .transport import EditsClient
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def _log(message: str) -> None:
|
|
16
|
+
"""Diagnostics go to stderr, which MCP clients show in their server logs; stdout is the protocol."""
|
|
17
|
+
sys.stderr.write(f"[insta-edits] {message}\n")
|
|
18
|
+
sys.stderr.flush()
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def cmd_serve(args: argparse.Namespace) -> int:
|
|
22
|
+
token = config.load_token()
|
|
23
|
+
if not token:
|
|
24
|
+
_log(f"no access token: run `insta-edits set-token` or set {config.ENV_TOKEN}. Edits will refuse requests.")
|
|
25
|
+
client = EditsClient(config.server_url(), token.value if token else None)
|
|
26
|
+
return serve(client, log=_log, listen=not args.no_stream, sync_tools=not args.no_sync)
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def cmd_doctor(args: argparse.Namespace) -> int:
|
|
30
|
+
report = doctor.run_doctor()
|
|
31
|
+
print(doctor.as_json(report) if args.json else doctor.render(report))
|
|
32
|
+
return 0 if report.ok else 1
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def cmd_set_token(args: argparse.Namespace) -> int:
|
|
36
|
+
print("Paste the access token from Edits > Settings > Automation (input is hidden).")
|
|
37
|
+
value = getpass.getpass("Token: ").strip()
|
|
38
|
+
if not value:
|
|
39
|
+
print("No token entered; nothing saved.", file=sys.stderr)
|
|
40
|
+
return 1
|
|
41
|
+
path = config.save_token(value)
|
|
42
|
+
print(f"Saved to {path} (readable only by you).")
|
|
43
|
+
print("Run `insta-edits doctor` to check the connection.")
|
|
44
|
+
return 0
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def build_parser() -> argparse.ArgumentParser:
|
|
48
|
+
parser = argparse.ArgumentParser(
|
|
49
|
+
prog="insta-edits",
|
|
50
|
+
description="Connect Claude Code (or any MCP client) to Instagram Edits for Mac's automation server.",
|
|
51
|
+
)
|
|
52
|
+
parser.add_argument("--version", action="version", version=f"insta-edits {__version__}")
|
|
53
|
+
sub = parser.add_subparsers(dest="command")
|
|
54
|
+
|
|
55
|
+
p_serve = sub.add_parser("serve", help="run the stdio MCP bridge (default)")
|
|
56
|
+
p_serve.add_argument("--no-stream", action="store_true", help="don't open the notification stream")
|
|
57
|
+
p_serve.add_argument("--no-sync", action="store_true", help="don't check for tool-set changes after each call")
|
|
58
|
+
p_serve.set_defaults(func=cmd_serve)
|
|
59
|
+
|
|
60
|
+
p_doc = sub.add_parser("doctor", help="check the app, server, token and tools")
|
|
61
|
+
p_doc.add_argument("--json", action="store_true", help="machine-readable output for bug reports (no secrets)")
|
|
62
|
+
p_doc.set_defaults(func=cmd_doctor)
|
|
63
|
+
|
|
64
|
+
p_tok = sub.add_parser("set-token", help="save the Edits access token to a private file")
|
|
65
|
+
p_tok.set_defaults(func=cmd_set_token)
|
|
66
|
+
return parser
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def main(argv: Optional[List[str]] = None) -> int:
|
|
70
|
+
parser = build_parser()
|
|
71
|
+
args = parser.parse_args(argv)
|
|
72
|
+
if not getattr(args, "func", None):
|
|
73
|
+
args = parser.parse_args(["serve", *(argv or [])])
|
|
74
|
+
return args.func(args)
|
insta_edits/compat.py
ADDED
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
"""Normalise Edits replies that some MCP clients reject.
|
|
2
|
+
|
|
3
|
+
Edits for Mac (build 454, November 2026) marks every result `"resultType": "complete"` but does
|
|
4
|
+
not send the caching fields (`ttlMs`, `cacheScope`) that newer MCP schemas pair with it. Some
|
|
5
|
+
Claude Code builds rejected the whole tool list because of it:
|
|
6
|
+
|
|
7
|
+
Invalid result for tools/list:
|
|
8
|
+
"ttlMs" expected number, received undefined
|
|
9
|
+
"cacheScope" expected one of "public" | "private"
|
|
10
|
+
|
|
11
|
+
Claude Code 2.1.296 accepts the reply as is. For older clients the bridge drops `resultType`
|
|
12
|
+
when the caching fields are missing or malformed, and drops malformed caching fields. Everything
|
|
13
|
+
else passes through untouched.
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
from __future__ import annotations
|
|
17
|
+
|
|
18
|
+
from typing import Any, Dict, List
|
|
19
|
+
|
|
20
|
+
VALID_CACHE_SCOPES = ("public", "private")
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def cache_hint_problems(result: Any) -> List[str]:
|
|
24
|
+
"""Describe what is wrong with the caching hints in a result, if anything."""
|
|
25
|
+
if not isinstance(result, dict):
|
|
26
|
+
return []
|
|
27
|
+
problems = []
|
|
28
|
+
has_scope = "cacheScope" in result
|
|
29
|
+
has_ttl = "ttlMs" in result
|
|
30
|
+
if has_scope and result["cacheScope"] not in VALID_CACHE_SCOPES:
|
|
31
|
+
problems.append(f"cacheScope={result['cacheScope']!r} (expected 'public' or 'private')")
|
|
32
|
+
if has_ttl and not _is_number(result["ttlMs"]):
|
|
33
|
+
problems.append(f"ttlMs={result['ttlMs']!r} (expected a number)")
|
|
34
|
+
if has_scope and not has_ttl:
|
|
35
|
+
problems.append("ttlMs missing while cacheScope is set")
|
|
36
|
+
return problems
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def needs_fix(result: Any) -> bool:
|
|
40
|
+
if not isinstance(result, dict):
|
|
41
|
+
return False
|
|
42
|
+
if cache_hint_problems(result):
|
|
43
|
+
return True
|
|
44
|
+
# Only the plain "complete" marker; other result types (such as async tasks) pass through.
|
|
45
|
+
return result.get("resultType") == "complete" and not ("ttlMs" in result and "cacheScope" in result)
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def fix_message(message: Any) -> Any:
|
|
49
|
+
"""Return the JSON-RPC message with an unsupported resultType and malformed caching hints removed."""
|
|
50
|
+
if not isinstance(message, dict):
|
|
51
|
+
return message
|
|
52
|
+
result = message.get("result")
|
|
53
|
+
if not needs_fix(result):
|
|
54
|
+
return message
|
|
55
|
+
drop = {"resultType"} if result.get("resultType") == "complete" else set()
|
|
56
|
+
if cache_hint_problems(result):
|
|
57
|
+
drop |= {"cacheScope", "ttlMs"}
|
|
58
|
+
cleaned: Dict[str, Any] = {k: v for k, v in result.items() if k not in drop}
|
|
59
|
+
message = dict(message)
|
|
60
|
+
message["result"] = cleaned
|
|
61
|
+
return message
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def _is_number(value: Any) -> bool:
|
|
65
|
+
return isinstance(value, (int, float)) and not isinstance(value, bool)
|
insta_edits/config.py
ADDED
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
"""Where the bridge finds the Edits server and its access token."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import os
|
|
6
|
+
import stat
|
|
7
|
+
from dataclasses import dataclass
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
from typing import Optional
|
|
10
|
+
|
|
11
|
+
DEFAULT_URL = "http://127.0.0.1:19501/mcp"
|
|
12
|
+
DEFAULT_TOKEN_FILE = Path("~/.config/insta-edits/token").expanduser()
|
|
13
|
+
|
|
14
|
+
ENV_URL = "EDITS_MCP_URL"
|
|
15
|
+
ENV_TOKEN = "EDITS_MCP_TOKEN"
|
|
16
|
+
ENV_TOKEN_FILE = "EDITS_MCP_TOKEN_FILE"
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
@dataclass(frozen=True)
|
|
20
|
+
class Token:
|
|
21
|
+
value: str
|
|
22
|
+
source: str # human-readable: "environment" or the file path
|
|
23
|
+
|
|
24
|
+
def __repr__(self) -> str: # never leak the secret in logs or tracebacks
|
|
25
|
+
return f"Token(source={self.source!r}, value=<redacted>)"
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def server_url() -> str:
|
|
29
|
+
return os.environ.get(ENV_URL, DEFAULT_URL).strip() or DEFAULT_URL
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def token_file() -> Path:
|
|
33
|
+
raw = os.environ.get(ENV_TOKEN_FILE, "").strip()
|
|
34
|
+
return Path(raw).expanduser() if raw else DEFAULT_TOKEN_FILE
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def load_token() -> Optional[Token]:
|
|
38
|
+
"""Token from $EDITS_MCP_TOKEN, else from the token file. None when neither is set."""
|
|
39
|
+
env = os.environ.get(ENV_TOKEN, "").strip()
|
|
40
|
+
# Claude Code leaves an unresolved ${user_config...} literal when the option is unset.
|
|
41
|
+
if env and not env.startswith("${"):
|
|
42
|
+
return Token(env, "environment")
|
|
43
|
+
path = token_file()
|
|
44
|
+
try:
|
|
45
|
+
value = path.read_text(encoding="utf-8").strip()
|
|
46
|
+
except OSError:
|
|
47
|
+
return None
|
|
48
|
+
return Token(value, str(path)) if value else None
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def token_file_is_private(path: Path) -> bool:
|
|
52
|
+
"""True when nobody but the owner can read the token file."""
|
|
53
|
+
try:
|
|
54
|
+
mode = path.stat().st_mode
|
|
55
|
+
except OSError:
|
|
56
|
+
return False
|
|
57
|
+
return not (mode & (stat.S_IRWXG | stat.S_IRWXO))
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
def save_token(value: str, path: Optional[Path] = None) -> Path:
|
|
61
|
+
"""Write the token with 0600 permissions, creating a 0700 parent directory."""
|
|
62
|
+
path = path or token_file()
|
|
63
|
+
path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
|
|
64
|
+
fd = os.open(str(path), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
|
|
65
|
+
with os.fdopen(fd, "w", encoding="utf-8") as fh:
|
|
66
|
+
fh.write(value.strip())
|
|
67
|
+
os.chmod(path, 0o600)
|
|
68
|
+
return path
|
insta_edits/doctor.py
ADDED
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
"""`insta-edits doctor`: check every link between Claude and Edits, one line per check."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import json
|
|
6
|
+
import platform
|
|
7
|
+
import shutil
|
|
8
|
+
import subprocess
|
|
9
|
+
from dataclasses import asdict, dataclass, field
|
|
10
|
+
from pathlib import Path
|
|
11
|
+
from typing import List, Optional
|
|
12
|
+
|
|
13
|
+
from . import __version__, compat, config
|
|
14
|
+
from .transport import EditsClient, EditsHTTPError, EditsUnreachable
|
|
15
|
+
|
|
16
|
+
BUNDLE_ID = "com.burbn.basel.mac"
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
@dataclass
|
|
20
|
+
class Check:
|
|
21
|
+
name: str
|
|
22
|
+
status: str # "ok" | "warn" | "fail" | "skip"
|
|
23
|
+
detail: str = ""
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
@dataclass
|
|
27
|
+
class Report:
|
|
28
|
+
version: str = __version__
|
|
29
|
+
checks: List[Check] = field(default_factory=list)
|
|
30
|
+
|
|
31
|
+
def add(self, name: str, status: str, detail: str = "") -> Check:
|
|
32
|
+
check = Check(name, status, detail)
|
|
33
|
+
self.checks.append(check)
|
|
34
|
+
return check
|
|
35
|
+
|
|
36
|
+
@property
|
|
37
|
+
def ok(self) -> bool:
|
|
38
|
+
return all(c.status in ("ok", "warn", "skip") for c in self.checks)
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def _edits_app() -> Optional[str]:
|
|
42
|
+
for path in ("/Applications/Edits.app", str(Path("~/Applications/Edits.app").expanduser())):
|
|
43
|
+
if Path(path).exists():
|
|
44
|
+
return path
|
|
45
|
+
if shutil.which("mdfind"):
|
|
46
|
+
out = subprocess.run(
|
|
47
|
+
["mdfind", f"kMDItemCFBundleIdentifier == '{BUNDLE_ID}'"], capture_output=True, text=True, timeout=10
|
|
48
|
+
).stdout.strip()
|
|
49
|
+
if out:
|
|
50
|
+
return out.splitlines()[0]
|
|
51
|
+
return None
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def run_doctor() -> Report:
|
|
55
|
+
report = Report()
|
|
56
|
+
url = config.server_url()
|
|
57
|
+
|
|
58
|
+
if platform.system() == "Darwin":
|
|
59
|
+
report.add("macOS", "ok", platform.mac_ver()[0] or platform.release())
|
|
60
|
+
else:
|
|
61
|
+
report.add("macOS", "warn", f"{platform.system()}: Edits for Mac only runs on macOS (Apple silicon)")
|
|
62
|
+
|
|
63
|
+
app = _edits_app() if platform.system() == "Darwin" else None
|
|
64
|
+
report.add("Edits app installed", "ok" if app else "fail", app or "not found; download it from edits.com/desktop")
|
|
65
|
+
|
|
66
|
+
probe = EditsClient(url, token=None, timeout=5)
|
|
67
|
+
try:
|
|
68
|
+
probe.post({"jsonrpc": "2.0", "id": 0, "method": "ping"})
|
|
69
|
+
report.add("Automation server", "ok", f"answering at {url}")
|
|
70
|
+
except EditsHTTPError as err:
|
|
71
|
+
report.add("Automation server", "ok", f"answering at {url} (HTTP {err.status} without a token, as expected)")
|
|
72
|
+
except EditsUnreachable:
|
|
73
|
+
report.add(
|
|
74
|
+
"Automation server", "fail", f"nothing at {url}. In Edits: Settings > Automation > Enable Automation Server"
|
|
75
|
+
)
|
|
76
|
+
return report
|
|
77
|
+
|
|
78
|
+
token = config.load_token()
|
|
79
|
+
if not token:
|
|
80
|
+
report.add("Access token", "fail", f"not set. Run `insta-edits set-token` or set {config.ENV_TOKEN}")
|
|
81
|
+
return report
|
|
82
|
+
if token.source == "environment":
|
|
83
|
+
report.add("Access token", "ok", "from the environment")
|
|
84
|
+
else:
|
|
85
|
+
private = config.token_file_is_private(Path(token.source))
|
|
86
|
+
report.add(
|
|
87
|
+
"Access token",
|
|
88
|
+
"ok" if private else "warn",
|
|
89
|
+
f"from {token.source}" + ("" if private else " (readable by other users: run chmod 600 on it)"),
|
|
90
|
+
)
|
|
91
|
+
|
|
92
|
+
client = EditsClient(url, token.value, timeout=15)
|
|
93
|
+
try:
|
|
94
|
+
replies = client.post(
|
|
95
|
+
{
|
|
96
|
+
"jsonrpc": "2.0",
|
|
97
|
+
"id": 1,
|
|
98
|
+
"method": "initialize",
|
|
99
|
+
"params": {
|
|
100
|
+
"protocolVersion": "2025-06-18",
|
|
101
|
+
"capabilities": {},
|
|
102
|
+
"clientInfo": {"name": "insta-edits-doctor", "version": __version__},
|
|
103
|
+
},
|
|
104
|
+
}
|
|
105
|
+
)
|
|
106
|
+
except EditsHTTPError as err:
|
|
107
|
+
status = "fail"
|
|
108
|
+
if err.status in (401, 403):
|
|
109
|
+
detail = "token rejected: copy the current token from Edits > Settings > Automation and run set-token"
|
|
110
|
+
else:
|
|
111
|
+
detail = f"HTTP {err.status}"
|
|
112
|
+
report.add("Sign-in", status, detail)
|
|
113
|
+
return report
|
|
114
|
+
init = next((r for r in replies if isinstance(r, dict) and r.get("id") == 1), {})
|
|
115
|
+
announces_changes = bool(
|
|
116
|
+
(((init.get("result") or {}).get("capabilities") or {}).get("tools") or {}).get("listChanged")
|
|
117
|
+
)
|
|
118
|
+
info = (init.get("result") or {}).get("serverInfo") or {}
|
|
119
|
+
if "error" in init or not info:
|
|
120
|
+
report.add("Sign-in", "fail", json.dumps(init.get("error") or init)[:200])
|
|
121
|
+
return report
|
|
122
|
+
report.add(
|
|
123
|
+
"Sign-in", "ok", f"{info.get('name', '?')} {info.get('version', '')}, protocol {client.protocol_version}"
|
|
124
|
+
)
|
|
125
|
+
client.post({"jsonrpc": "2.0", "method": "notifications/initialized"})
|
|
126
|
+
|
|
127
|
+
tools_reply = next(
|
|
128
|
+
(r for r in client.post({"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}) if r.get("id") == 2),
|
|
129
|
+
{},
|
|
130
|
+
)
|
|
131
|
+
result = tools_reply.get("result") or {}
|
|
132
|
+
tools = result.get("tools") or []
|
|
133
|
+
in_editor = any(t.get("name") == "addText" for t in tools)
|
|
134
|
+
where = "a project is open" if in_editor else "home screen; Edits offers more once a project is open"
|
|
135
|
+
report.add("Tools", "ok" if tools else "warn", f"{len(tools)} on the current screen ({where})")
|
|
136
|
+
report.add(
|
|
137
|
+
"Reply format",
|
|
138
|
+
"ok",
|
|
139
|
+
"normalised for older Claude Code builds (resultType without caching fields)"
|
|
140
|
+
if compat.needs_fix(result)
|
|
141
|
+
else "standard; nothing to normalise",
|
|
142
|
+
)
|
|
143
|
+
|
|
144
|
+
names = {t.get("name") for t in tools if isinstance(t, dict)}
|
|
145
|
+
if "getCapabilities" in names:
|
|
146
|
+
caps = next(
|
|
147
|
+
(
|
|
148
|
+
r
|
|
149
|
+
for r in client.post(
|
|
150
|
+
{
|
|
151
|
+
"jsonrpc": "2.0",
|
|
152
|
+
"id": 3,
|
|
153
|
+
"method": "tools/call",
|
|
154
|
+
"params": {"name": "getCapabilities", "arguments": {}},
|
|
155
|
+
}
|
|
156
|
+
)
|
|
157
|
+
if r.get("id") == 3
|
|
158
|
+
),
|
|
159
|
+
{},
|
|
160
|
+
)
|
|
161
|
+
text = "".join(
|
|
162
|
+
c.get("text", "") for c in ((caps.get("result") or {}).get("content") or []) if isinstance(c, dict)
|
|
163
|
+
)
|
|
164
|
+
try:
|
|
165
|
+
schema = json.loads(text).get("schemaVersion")
|
|
166
|
+
except (ValueError, AttributeError):
|
|
167
|
+
schema = None
|
|
168
|
+
if schema:
|
|
169
|
+
report.add("Edits automation schema", "ok", str(schema))
|
|
170
|
+
|
|
171
|
+
stream = client.stream_supported()
|
|
172
|
+
if stream:
|
|
173
|
+
report.add("Tool-change notifications", "ok", "Edits streams them; new tools appear as soon as a project opens")
|
|
174
|
+
elif announces_changes:
|
|
175
|
+
report.add(
|
|
176
|
+
"Tool-change notifications",
|
|
177
|
+
"ok",
|
|
178
|
+
"Edits announces them but never sends any; the bridge checks after each call and tells Claude",
|
|
179
|
+
)
|
|
180
|
+
else:
|
|
181
|
+
report.add("Tool-change notifications", "ok", "the bridge checks after each call and tells Claude")
|
|
182
|
+
return report
|
|
183
|
+
|
|
184
|
+
|
|
185
|
+
MARK = {"ok": "✓", "warn": "!", "fail": "✗", "skip": "-"}
|
|
186
|
+
|
|
187
|
+
|
|
188
|
+
def render(report: Report) -> str:
|
|
189
|
+
width = max(len(c.name) for c in report.checks) if report.checks else 0
|
|
190
|
+
lines = [f"insta-edits {report.version} doctor", ""]
|
|
191
|
+
for c in report.checks:
|
|
192
|
+
lines.append(f" {MARK[c.status]} {c.name.ljust(width)} {c.detail}")
|
|
193
|
+
lines.append("")
|
|
194
|
+
lines.append("All good. Claude can drive Edits." if report.ok else "Fix the ✗ items above, then run doctor again.")
|
|
195
|
+
return "\n".join(lines)
|
|
196
|
+
|
|
197
|
+
|
|
198
|
+
def as_json(report: Report) -> str:
|
|
199
|
+
return json.dumps(asdict(report), indent=2)
|
insta_edits/transport.py
ADDED
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
"""Minimal MCP Streamable HTTP client for the Edits automation server (standard library only)."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import json
|
|
6
|
+
import threading
|
|
7
|
+
import urllib.error
|
|
8
|
+
import urllib.request
|
|
9
|
+
from typing import Any, Callable, Iterable, Iterator, List, Optional
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class EditsError(Exception):
|
|
13
|
+
"""The Edits server could not be used."""
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class EditsUnreachable(EditsError):
|
|
17
|
+
"""Nothing answered at the server URL: Edits is closed or its automation server is off."""
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
class EditsHTTPError(EditsError):
|
|
21
|
+
def __init__(self, status: int, body: str):
|
|
22
|
+
super().__init__(f"HTTP {status}")
|
|
23
|
+
self.status = status
|
|
24
|
+
self.body = body
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
def iter_sse(lines: Iterable[str]) -> Iterator[Any]:
|
|
28
|
+
"""Yield decoded JSON payloads from server-sent-event lines."""
|
|
29
|
+
data: List[str] = []
|
|
30
|
+
for raw in lines:
|
|
31
|
+
line = raw.rstrip("\r\n")
|
|
32
|
+
if not line:
|
|
33
|
+
if data:
|
|
34
|
+
yield json.loads("\n".join(data))
|
|
35
|
+
data = []
|
|
36
|
+
continue
|
|
37
|
+
if line.startswith(":"):
|
|
38
|
+
continue
|
|
39
|
+
field, _, value = line.partition(":")
|
|
40
|
+
if field == "data":
|
|
41
|
+
data.append(value[1:] if value.startswith(" ") else value)
|
|
42
|
+
if data:
|
|
43
|
+
yield json.loads("\n".join(data))
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
def _flatten(payload: Any) -> List[Any]:
|
|
47
|
+
return list(payload) if isinstance(payload, list) else [payload]
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
class EditsClient:
|
|
51
|
+
def __init__(self, url: str, token: Optional[str], timeout: float = 600.0):
|
|
52
|
+
self.url = url
|
|
53
|
+
self._token = token
|
|
54
|
+
self.timeout = timeout
|
|
55
|
+
self.session_id: Optional[str] = None
|
|
56
|
+
self.protocol_version: Optional[str] = None
|
|
57
|
+
|
|
58
|
+
def _headers(self, accept: str) -> dict:
|
|
59
|
+
headers = {"Accept": accept}
|
|
60
|
+
if self._token:
|
|
61
|
+
headers["Authorization"] = "Bearer " + self._token
|
|
62
|
+
if self.session_id:
|
|
63
|
+
headers["Mcp-Session-Id"] = self.session_id
|
|
64
|
+
if self.protocol_version:
|
|
65
|
+
headers["MCP-Protocol-Version"] = self.protocol_version
|
|
66
|
+
return headers
|
|
67
|
+
|
|
68
|
+
def post(self, message: Any) -> List[Any]:
|
|
69
|
+
"""Send one JSON-RPC message (or a batch) and return every message the server sends back."""
|
|
70
|
+
body = json.dumps(message).encode("utf-8")
|
|
71
|
+
headers = self._headers("application/json, text/event-stream")
|
|
72
|
+
headers["Content-Type"] = "application/json"
|
|
73
|
+
request = urllib.request.Request(self.url, data=body, headers=headers, method="POST")
|
|
74
|
+
try:
|
|
75
|
+
with urllib.request.urlopen(request, timeout=self.timeout) as response:
|
|
76
|
+
session = response.headers.get("Mcp-Session-Id")
|
|
77
|
+
if session:
|
|
78
|
+
self.session_id = session
|
|
79
|
+
ctype = (response.headers.get("Content-Type") or "").lower()
|
|
80
|
+
text = response.read().decode("utf-8", "replace")
|
|
81
|
+
except urllib.error.HTTPError as err:
|
|
82
|
+
raise EditsHTTPError(err.code, err.read().decode("utf-8", "replace")[:500]) from None
|
|
83
|
+
except (urllib.error.URLError, ConnectionError, OSError) as err:
|
|
84
|
+
raise EditsUnreachable(str(getattr(err, "reason", err))) from None
|
|
85
|
+
if not text.strip():
|
|
86
|
+
return []
|
|
87
|
+
if "text/event-stream" in ctype:
|
|
88
|
+
messages: List[Any] = []
|
|
89
|
+
for payload in iter_sse(text.splitlines()):
|
|
90
|
+
messages.extend(_flatten(payload))
|
|
91
|
+
else:
|
|
92
|
+
messages = _flatten(json.loads(text))
|
|
93
|
+
self._remember_protocol(messages)
|
|
94
|
+
return messages
|
|
95
|
+
|
|
96
|
+
def _remember_protocol(self, messages: List[Any]) -> None:
|
|
97
|
+
for msg in messages:
|
|
98
|
+
result = msg.get("result") if isinstance(msg, dict) else None
|
|
99
|
+
if isinstance(result, dict) and isinstance(result.get("protocolVersion"), str) and "serverInfo" in result:
|
|
100
|
+
self.protocol_version = result["protocolVersion"]
|
|
101
|
+
|
|
102
|
+
def stream_supported(self, timeout: float = 3.0) -> Optional[bool]:
|
|
103
|
+
"""True if the server offers a GET event stream, False if it refuses, None if unknown."""
|
|
104
|
+
request = urllib.request.Request(self.url, headers=self._headers("text/event-stream"), method="GET")
|
|
105
|
+
try:
|
|
106
|
+
with urllib.request.urlopen(request, timeout=timeout) as response:
|
|
107
|
+
return response.status == 200
|
|
108
|
+
except urllib.error.HTTPError as err:
|
|
109
|
+
return False if err.code in (404, 405) else None
|
|
110
|
+
except Exception:
|
|
111
|
+
return None
|
|
112
|
+
|
|
113
|
+
def listen(self, on_message: Callable[[Any], None], stop: threading.Event, log: Callable[[str], None]) -> None:
|
|
114
|
+
"""Forward server-initiated messages (such as tools/list_changed) until stopped.
|
|
115
|
+
|
|
116
|
+
Reconnects with backoff. Gives up quietly if the server has no GET stream.
|
|
117
|
+
"""
|
|
118
|
+
delay = 1.0
|
|
119
|
+
while not stop.is_set():
|
|
120
|
+
request = urllib.request.Request(self.url, headers=self._headers("text/event-stream"), method="GET")
|
|
121
|
+
try:
|
|
122
|
+
with urllib.request.urlopen(request, timeout=None) as response:
|
|
123
|
+
delay = 1.0
|
|
124
|
+
lines = (raw.decode("utf-8", "replace") for raw in response)
|
|
125
|
+
for payload in iter_sse(lines):
|
|
126
|
+
for msg in _flatten(payload):
|
|
127
|
+
on_message(msg)
|
|
128
|
+
if stop.is_set():
|
|
129
|
+
return
|
|
130
|
+
except urllib.error.HTTPError as err:
|
|
131
|
+
if err.code in (404, 405):
|
|
132
|
+
log("server has no notification stream; tool-list changes will show on the next request")
|
|
133
|
+
return
|
|
134
|
+
log(f"notification stream error HTTP {err.code}; retrying")
|
|
135
|
+
except Exception as err: # connection dropped, Edits restarted, etc.
|
|
136
|
+
if stop.is_set():
|
|
137
|
+
return
|
|
138
|
+
log(f"notification stream closed ({err}); retrying")
|
|
139
|
+
stop.wait(delay)
|
|
140
|
+
delay = min(delay * 2, 30.0)
|
|
@@ -0,0 +1,229 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: insta-edits
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Let Claude Code and other MCP clients edit Instagram Reels in Edits for Mac, through its built-in MCP server.
|
|
5
|
+
Project-URL: Homepage, https://github.com/faisalkhanzemi/insta-edits-for-claude
|
|
6
|
+
Project-URL: Issues, https://github.com/faisalkhanzemi/insta-edits-for-claude/issues
|
|
7
|
+
Project-URL: Changelog, https://github.com/faisalkhanzemi/insta-edits-for-claude/blob/main/CHANGELOG.md
|
|
8
|
+
Author: Faisal Khan
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: claude,claude-code,edits,instagram,instagram-edits,instagram-reels,macos,mcp,mcp-server,model-context-protocol,reels,video-editing
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Operating System :: MacOS
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
18
|
+
Classifier: Topic :: Multimedia :: Video :: Non-Linear Editor
|
|
19
|
+
Requires-Python: >=3.9
|
|
20
|
+
Provides-Extra: dev
|
|
21
|
+
Requires-Dist: pytest>=8; extra == 'dev'
|
|
22
|
+
Requires-Dist: ruff>=0.6; extra == 'dev'
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
|
|
25
|
+
# Insta Edits for Claude
|
|
26
|
+
|
|
27
|
+
<!-- mcp-name: io.github.faisalkhanzemi/insta-edits -->
|
|
28
|
+
|
|
29
|
+
**Let Claude Code edit in Instagram Edits for Mac, with the full editor and not just the home screen.**
|
|
30
|
+
|
|
31
|
+
[](https://github.com/faisalkhanzemi/insta-edits-for-claude/actions/workflows/ci.yml)
|
|
32
|
+

|
|
33
|
+

|
|
34
|
+
[](https://github.com/faisalkhanzemi/insta-edits-for-claude/blob/main/LICENSE)
|
|
35
|
+
|
|
36
|
+
<p align="center"><a href="https://github.com/faisalkhanzemi/insta-edits-for-claude/blob/main/assets/hero.mp4"><img src="https://raw.githubusercontent.com/faisalkhanzemi/insta-edits-for-claude/main/assets/hero.gif" alt="A real Claude Code session making a beat-synced Dubai in 15 seconds reel inside Instagram Edits for Mac: clips cut on the beat, punch-in zooms, a speed ramp, a title and labels, frame checks, then export" width="100%"></a></p>
|
|
37
|
+
|
|
38
|
+
<p align="center"><sub>One prompt, a real Claude Code session, nothing scripted. Edits found no beats, so Claude analysed the music itself (122 BPM), cut every clip on a beat, checked its own frames and exported the reel. <a href="https://github.com/faisalkhanzemi/insta-edits-for-claude/blob/main/assets/hero.mp4">Watch with sound</a>.</sub></p>
|
|
39
|
+
|
|
40
|
+
Edits for Mac, which Meta launched on 5 November 2026, has a built-in automation server that speaks MCP: in Meta's words, you can connect AI agents "to the desktop editor through MCP so they can help with your projects". You can point Claude Code at it directly, but you only get part of it.
|
|
41
|
+
|
|
42
|
+
Edits changes its tools with the screen. The home screen offers **32 tools**: projects, imports and catalogs. Open a project and it offers **274**, with text, captions, effects, transitions, keyframes, audio and export. Edits says it will announce that change (`tools.listChanged: true`) but never sends the notification. Claude keeps the 32 home tools for the whole session and never sees the editor.
|
|
43
|
+
|
|
44
|
+
This bridge sits between the two. After every tool call it asks Edits which tools it offers now. If the set has changed, it tells Claude, and Claude refreshes the list. It also fixes a reply format that some Claude Code builds reject, gives readable errors, and keeps your token out of config files.
|
|
45
|
+
|
|
46
|
+
```
|
|
47
|
+
Claude Code ──stdio──▶ insta-edits ──HTTP──▶ Edits for Mac (127.0.0.1:19501)
|
|
48
|
+
◀── tools/list_changed ──┘ checks the tool set after each call
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
**Works with** Claude Code in the terminal and in the Code tab of the Claude desktop app. It's a standard stdio MCP server, so other MCP clients (the Claude desktop chat, Cursor, Codex) can run `insta-edits serve` too, though we've only tested Claude Code.
|
|
52
|
+
|
|
53
|
+
## What you get
|
|
54
|
+
|
|
55
|
+
- **The full editor.** Claude receives `notifications/tools/list_changed` as soon as Edits moves between home (32 tools) and the editor (274). Without the bridge, that notification never arrives.
|
|
56
|
+
- **Replies that every Claude Code build accepts.** Edits marks each result `"resultType": "complete"` without the caching fields that newer MCP schemas pair with it. Some Claude Code builds then dropped every tool, with `Invalid result for tools/list: ttlMs … cacheScope`. The bridge removes the marker only when those fields are missing.
|
|
57
|
+
- **Your token stays private.** The plugin keeps it in the macOS keychain. The CLI keeps it in a `0600` file. It never appears in `~/.claude.json`, in logs or in error messages.
|
|
58
|
+
- **Errors you can act on.** "Cannot reach Edits: open it and enable the Automation Server" replaces a stack trace. A rejected token says how to update it.
|
|
59
|
+
- **`doctor` checks every link** from the app to the sign-in, and `--json` gives you a report to attach to a bug.
|
|
60
|
+
- **An `edits` skill** that teaches Claude how the server behaves: discover before guessing, work in normalised canvas coordinates, check rendered frames, and **never publish without your explicit go-ahead**.
|
|
61
|
+
- **Python standard library only.** Nothing to `pip install` for the plugin, and it runs on the `python3` that comes with macOS.
|
|
62
|
+
|
|
63
|
+
## Requirements
|
|
64
|
+
|
|
65
|
+
- A Mac with Apple silicon (M1 or later) and [Edits for Mac](https://edits.instagram.com/desktop), free and signed in to Instagram
|
|
66
|
+
- Claude Code
|
|
67
|
+
- `python3` 3.9 or newer. Run `xcode-select --install` if macOS asks for the command line tools.
|
|
68
|
+
|
|
69
|
+
## Install
|
|
70
|
+
|
|
71
|
+
### 1. Turn on the automation server in Edits
|
|
72
|
+
|
|
73
|
+
Go to **Edits › Settings › Automation**, switch on **Enable Automation Server**, and copy the **Access token**. Keep Edits open while Claude works.
|
|
74
|
+
|
|
75
|
+
### 2a. As a Claude Code plugin (recommended)
|
|
76
|
+
|
|
77
|
+
Start `claude` in a terminal and type:
|
|
78
|
+
|
|
79
|
+
```
|
|
80
|
+
/plugin marketplace add faisalkhanzemi/insta-edits-for-claude
|
|
81
|
+
/plugin install insta-edits@insta-edits
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Claude Code asks for the access token with a masked prompt and stores it in your keychain. Restart Claude Code, then run `/mcp`: `edits` should show as connected. The plugin also installs the `edits` skill.
|
|
85
|
+
|
|
86
|
+
<details>
|
|
87
|
+
<summary>Installing from a shell script, or using the Claude desktop app</summary>
|
|
88
|
+
|
|
89
|
+
The shell commands do the same thing but don't prompt for the token, so set it afterwards with `/plugin configure insta-edits@insta-edits` inside Claude Code:
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
claude plugin marketplace add faisalkhanzemi/insta-edits-for-claude
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
claude plugin install insta-edits@insta-edits
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
A plugin installed this way, at user scope, also shows up in the Code tab of the Claude desktop app, which reads the same settings.
|
|
100
|
+
</details>
|
|
101
|
+
|
|
102
|
+
### 2b. As a standalone MCP server
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
pipx install git+https://github.com/faisalkhanzemi/insta-edits-for-claude
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
insta-edits set-token
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
claude mcp add --scope user edits -- insta-edits serve
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
`set-token` asks for the token with a hidden prompt and saves it to `~/.config/insta-edits/token` with `0600` permissions. Never put the token itself on the `claude mcp add` line: it would end up in plain text in `~/.claude.json` and in your shell history.
|
|
117
|
+
|
|
118
|
+
## Check the connection
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
insta-edits doctor
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
```
|
|
125
|
+
insta-edits 0.1.0 doctor
|
|
126
|
+
|
|
127
|
+
✓ macOS 27.0.1
|
|
128
|
+
✓ Edits app installed /Applications/Edits.app
|
|
129
|
+
✓ Automation server answering at http://127.0.0.1:19501/mcp (HTTP 403 without a token, as expected)
|
|
130
|
+
✓ Access token from ~/.config/insta-edits/token
|
|
131
|
+
✓ Sign-in metapilot-native 1.0.0, protocol 2025-06-18
|
|
132
|
+
✓ Tools 32 on the current screen (home screen; Edits offers more once a project is open)
|
|
133
|
+
✓ Reply format normalised for older Claude Code builds (resultType without caching fields)
|
|
134
|
+
✓ Edits automation schema 2026.10.19-1
|
|
135
|
+
✓ Tool-change notifications Edits announces them but never sends any; the bridge checks after each call and tells Claude
|
|
136
|
+
|
|
137
|
+
All good. Claude can drive Edits.
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Each `✗` line names its fix. Plugin users who want `doctor` can install the CLI as in 2b. The plugin token lives in the keychain, so without `set-token` the doctor checks stop at the sign-in step.
|
|
141
|
+
|
|
142
|
+
## Using it
|
|
143
|
+
|
|
144
|
+
Ask for edits in plain words:
|
|
145
|
+
|
|
146
|
+
> Open my latest Edits project and tell me what's on the timeline.
|
|
147
|
+
|
|
148
|
+
> Import `~/Movies/broll/` into a new project, cut it to the beat of the voice-over, and add word-by-word captions in a clean sans.
|
|
149
|
+
|
|
150
|
+
> Add a soft zoom on every product close-up and a whoosh on each cut, then render a preview so I can check the frames.
|
|
151
|
+
|
|
152
|
+
Claude opens the project, the editor tools appear, and it works from them. It doesn't post. Publishing stays in the Edits window unless you explicitly tell Claude to share a specific video.
|
|
153
|
+
|
|
154
|
+
## How it works
|
|
155
|
+
|
|
156
|
+
| Step | What happens |
|
|
157
|
+
| --- | --- |
|
|
158
|
+
| Session | The bridge forwards `initialize`, keeps Edits' `Mcp-Session-Id`, and sends `MCP-Protocol-Version` on every request. |
|
|
159
|
+
| Replies | It accepts both JSON and `text/event-stream` replies and batch requests, and normalises `resultType` only when the caching fields are missing. |
|
|
160
|
+
| Tool sync | After each `tools/call` it sends its own `tools/list` to Edits, using an id Claude never sees, and compares the tool names. If they changed, it writes `notifications/tools/list_changed` to Claude. Turn this off with `serve --no-sync`. |
|
|
161
|
+
| Notifications | If a future Edits build opens a server-to-client stream, the bridge listens on it and forwards what arrives. Edits doesn't offer one today, so the bridge stops trying after the first refusal. Turn it off with `serve --no-stream`. |
|
|
162
|
+
| Errors | When Edits is closed the bridge returns JSON-RPC `-32001`. When Edits returns an HTTP error it returns `-32002`. Both carry a one-line fix. |
|
|
163
|
+
|
|
164
|
+
Settings come from the environment: `EDITS_MCP_URL` (default `http://127.0.0.1:19501/mcp`), `EDITS_MCP_TOKEN`, and `EDITS_MCP_TOKEN_FILE`. Logs go to stderr.
|
|
165
|
+
|
|
166
|
+
## Tested with
|
|
167
|
+
|
|
168
|
+
| | Version |
|
|
169
|
+
| --- | --- |
|
|
170
|
+
| Edits for Mac | 454.0.0 (server `metapilot-native` 1.0.0, automation schema 2026.10.19-1) |
|
|
171
|
+
| Claude Code | 2.1.296 |
|
|
172
|
+
| macOS | 27.0.1 |
|
|
173
|
+
| Python | 3.9.6 (system), 3.11, 3.13 in CI |
|
|
174
|
+
|
|
175
|
+
Edits updates often and its automation server is undocumented. If a new build breaks something, run `insta-edits doctor --json` and [open an issue](https://github.com/faisalkhanzemi/insta-edits-for-claude/issues/new/choose) with the output. It contains no token.
|
|
176
|
+
|
|
177
|
+
## Troubleshooting
|
|
178
|
+
|
|
179
|
+
| Symptom | Fix |
|
|
180
|
+
| --- | --- |
|
|
181
|
+
| `Cannot reach Edits` | Open Edits and switch on Settings › Automation › Enable Automation Server. |
|
|
182
|
+
| HTTP 401 or 403 | The token changed in Edits. Update it in `/plugin`, or run `insta-edits set-token`. |
|
|
183
|
+
| Only home tools, even with a project open | Check that `edits` in `/mcp` points to the bridge and not straight at `127.0.0.1:19501`, and that you didn't start it with `--no-sync`. |
|
|
184
|
+
| Import fails with `file not found: ~/…` | Edits doesn't expand `~`. Pass the full path, such as `/Users/you/Movies/clip.mp4`. |
|
|
185
|
+
| Import fails with `Sandbox bookmark unavailable` | Edits is sandboxed. In our tests it imported from `~/Movies` and refused `~/Downloads`, `~/Desktop`, temp folders and project folders. Move the footage into `~/Movies` and import it from there. |
|
|
186
|
+
| Exported video is silent where the song should be | Songs from Edits' music library come in as licensed tracks, and exports started through automation leave them out: the music bed was silent in every test, while our own audio files exported fine. Export or post from the Edits window when a library song matters. |
|
|
187
|
+
| `addSongToComposition` adds a different song | Passing a track id sometimes added another track. Passing the exact title added the right song in our test. |
|
|
188
|
+
|
|
189
|
+
## Security
|
|
190
|
+
|
|
191
|
+
- The bridge only connects to the URL you configure, which defaults to `127.0.0.1`. It sends nothing anywhere else and has no telemetry.
|
|
192
|
+
- The token is redacted in every log line, error message and `repr`. `doctor --json` reports where the token came from, never its value.
|
|
193
|
+
- Edits is signed in to your Instagram account. The bundled skill tells Claude never to publish, share or schedule without your explicit go-ahead for that specific post.
|
|
194
|
+
- Report vulnerabilities privately as described in [SECURITY.md](https://github.com/faisalkhanzemi/insta-edits-for-claude/blob/main/SECURITY.md).
|
|
195
|
+
|
|
196
|
+
## FAQ
|
|
197
|
+
|
|
198
|
+
**How do I connect Claude to Instagram Edits?** Install Edits for Mac, switch on Settings › Automation › Enable Automation Server, then add this plugin with the two `/plugin` lines under [Install](#install). Claude can then open your projects and edit them.
|
|
199
|
+
|
|
200
|
+
**Can Claude edit Instagram Reels?** Yes, inside Edits for Mac. It can import clips, cut them on the beat, add captions, text, transitions, zooms and speed ramps, check rendered frames and export. You post the reel from Edits yourself.
|
|
201
|
+
|
|
202
|
+
**Does it work with claude.ai in the browser?** No. Edits runs on your Mac and only listens locally, so it needs Claude Code (or another MCP client) running on the same Mac.
|
|
203
|
+
|
|
204
|
+
**Is this official?** No. It's an independent open-source project, not affiliated with or endorsed by Meta, Instagram or Anthropic. "Instagram" and "Edits" are trademarks of Meta Platforms, Inc.
|
|
205
|
+
|
|
206
|
+
**Does it work on Windows or with the Edits phone app?** No. Edits on desktop is only available on macOS, and the automation server only exists there.
|
|
207
|
+
|
|
208
|
+
**Do I still need this if my Claude Code build accepts Edits' replies?** Yes, for the editor tools. Edits never announces that its tools changed, and no client can find that out without asking.
|
|
209
|
+
|
|
210
|
+
**Can Claude post to Instagram for me?** The bridge won't stop Claude from calling Edits' share tools, but the bundled skill tells it to wait for your explicit go-ahead. Posting from the Edits window is the safer default.
|
|
211
|
+
|
|
212
|
+
## Development
|
|
213
|
+
|
|
214
|
+
```bash
|
|
215
|
+
git clone https://github.com/faisalkhanzemi/insta-edits-for-claude && cd insta-edits-for-claude
|
|
216
|
+
python3 -m venv .venv && . .venv/bin/activate
|
|
217
|
+
pip install -e . pytest ruff
|
|
218
|
+
pytest && ruff check . && ruff format --check .
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
The tests run against `tests/fake_edits.py`, a stand-in that behaves like the real server: it sends no notifications, changes its tool set when a project opens, and replies with `resultType`. You don't need a Mac or Edits to run them. See [CONTRIBUTING.md](https://github.com/faisalkhanzemi/insta-edits-for-claude/blob/main/CONTRIBUTING.md).
|
|
222
|
+
|
|
223
|
+
## Credits
|
|
224
|
+
|
|
225
|
+
Demo footage: stock clips from [Pexels](https://www.pexels.com/license/) (Pexels License). Music: "Tech House vibes" by Alejandro Magaña, [Mixkit](https://mixkit.co/license/) (Mixkit License).
|
|
226
|
+
|
|
227
|
+
## License
|
|
228
|
+
|
|
229
|
+
[MIT](https://github.com/faisalkhanzemi/insta-edits-for-claude/blob/main/LICENSE) © Faisal Khan
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
insta_edits/__init__.py,sha256=LczYqddPP0c4FFC2wVn3663RwNmDODtd7LarSLsPEhA,124
|
|
2
|
+
insta_edits/__main__.py,sha256=MHKZ_ae3fSLGTLUUMOx15fWdeOnJSHhq-zslRP5F5Lc,79
|
|
3
|
+
insta_edits/bridge.py,sha256=H5wt6xNC-xpUW6mN0QOwetQm50n2MJFvcqzwaHyQKi4,5714
|
|
4
|
+
insta_edits/cli.py,sha256=L6meP2OVwnGCBo12LtEYFBhubXx4YLn7rvtZezOrwv4,2888
|
|
5
|
+
insta_edits/compat.py,sha256=KPW5OZTkeO2ky6ljU8BDxTSLdXw38nE57mpj4vh7Rw8,2565
|
|
6
|
+
insta_edits/config.py,sha256=UhJzF_x_Xowt1XIwumGW0FwmFIbiqTqq_xNnNqGfAfM,2169
|
|
7
|
+
insta_edits/doctor.py,sha256=mYLXkeyePr6ksFY9Qz4C14SxS4PNf5pXvhSzn2BpF4g,7270
|
|
8
|
+
insta_edits/transport.py,sha256=Kt6qCnJjuwGzyYisubh_GXX7aFb_5RQwhzHGJvtLKnQ,5914
|
|
9
|
+
insta_edits-0.1.0.dist-info/METADATA,sha256=2TwYEXiqpKsTkfgUQeBS_ndipV9CWIuZFjHrCnZBhVI,14843
|
|
10
|
+
insta_edits-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
11
|
+
insta_edits-0.1.0.dist-info/entry_points.txt,sha256=nPGe8uU13lL72qo1pItr7EPCn9qQaxVJRj8M_aQAX1U,53
|
|
12
|
+
insta_edits-0.1.0.dist-info/licenses/LICENSE,sha256=bP6oxjWt9PKPABAENkFnJs99joOFVsEJapENfd9GLN8,1068
|
|
13
|
+
insta_edits-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Faisal Khan
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|