mcp-synchro 1.0.4__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.
@@ -0,0 +1,8 @@
1
+ # this_file: src/mcp_synchro/__init__.py
2
+ """mcp-synchro: Synchronize MCP server configurations across AI agents."""
3
+
4
+ try:
5
+ from mcp_synchro._version import __version__, __version_tuple__
6
+ except ImportError:
7
+ __version__ = "0.0.0"
8
+ __version_tuple__ = (0, 0, 0)
@@ -0,0 +1,7 @@
1
+ # this_file: src/mcp_synchro/__main__.py
2
+ """Entry point for python -m mcp_synchro."""
3
+
4
+ from mcp_synchro.cli import main
5
+
6
+ if __name__ == "__main__":
7
+ main()
@@ -0,0 +1,24 @@
1
+ # file generated by vcs-versioning
2
+ # don't change, don't track in version control
3
+ from __future__ import annotations
4
+
5
+ __all__ = [
6
+ "__version__",
7
+ "__version_tuple__",
8
+ "version",
9
+ "version_tuple",
10
+ "__commit_id__",
11
+ "commit_id",
12
+ ]
13
+
14
+ version: str
15
+ __version__: str
16
+ __version_tuple__: tuple[int | str, ...]
17
+ version_tuple: tuple[int | str, ...]
18
+ commit_id: str | None
19
+ __commit_id__: str | None
20
+
21
+ __version__ = version = '1.0.4'
22
+ __version_tuple__ = version_tuple = (1, 0, 4)
23
+
24
+ __commit_id__ = commit_id = None
@@ -0,0 +1,429 @@
1
+ {
2
+ "agents": {
3
+ "5ire": {
4
+ "name": "5ire",
5
+ "description": "5ire AI assistant",
6
+ "config_format": "json",
7
+ "mcp_key": "mcpServers",
8
+ "paths": {
9
+ "darwin": "~/Library/Application Support/5ire/mcp.json",
10
+ "win32": "%APPDATA%/5ire/mcp.json",
11
+ "linux": "~/.config/5ire/mcp.json"
12
+ }
13
+ },
14
+ "ai-panel": {
15
+ "name": "AI Panel",
16
+ "description": "AI Panel by Omata",
17
+ "config_format": "json",
18
+ "mcp_key": "mcpServers",
19
+ "paths": {
20
+ "darwin": "~/Library/Application Support/io-omata-ai-panel/mcp/mcp.json",
21
+ "win32": "%APPDATA%/io-omata-ai-panel/mcp/mcp.json",
22
+ "linux": "~/.config/io-omata-ai-panel/mcp/mcp.json"
23
+ }
24
+ },
25
+ "ai-panel-idsn": {
26
+ "name": "AI Panel IDSN",
27
+ "description": "AI Panel IDSN by Omata",
28
+ "config_format": "json",
29
+ "mcp_key": "mcpServers",
30
+ "paths": {
31
+ "darwin": "~/Library/Application Support/io-omata-ai-panel-idsn/mcp/mcp.json",
32
+ "win32": "%APPDATA%/io-omata-ai-panel-idsn/mcp/mcp.json",
33
+ "linux": "~/.config/io-omata-ai-panel-idsn/mcp/mcp.json"
34
+ }
35
+ },
36
+ "amp": {
37
+ "name": "Amp",
38
+ "description": "Amp AI coding agent (settings file)",
39
+ "config_format": "json",
40
+ "mcp_key": "mcpServers",
41
+ "mcp_wrapper_key": "amp",
42
+ "paths": {
43
+ "darwin": "~/.config/amp/settings.json",
44
+ "win32": "%USERPROFILE%/.config/amp/settings.json",
45
+ "linux": "~/.config/amp/settings.json"
46
+ }
47
+ },
48
+ "augment": {
49
+ "name": "Augment",
50
+ "description": "Augment Code AI",
51
+ "config_format": "json",
52
+ "mcp_key": "mcpServers",
53
+ "paths": {
54
+ "darwin": "~/.augment/settings.json",
55
+ "win32": "%USERPROFILE%/.augment/settings.json",
56
+ "linux": "~/.augment/settings.json"
57
+ }
58
+ },
59
+ "boltai": {
60
+ "name": "BoltAI",
61
+ "description": "BoltAI macOS app",
62
+ "config_format": "json",
63
+ "mcp_key": "mcpServers",
64
+ "paths": {
65
+ "darwin": "~/.boltai/mcp.json",
66
+ "win32": "%USERPROFILE%/.boltai/mcp.json",
67
+ "linux": "~/.boltai/mcp.json"
68
+ }
69
+ },
70
+ "claude-code": {
71
+ "name": "Claude Code",
72
+ "description": "Anthropic Claude Code CLI",
73
+ "config_format": "json",
74
+ "mcp_key": "mcpServers",
75
+ "paths": {
76
+ "darwin": "~/.claude.json",
77
+ "win32": "%USERPROFILE%/.claude.json",
78
+ "linux": "~/.claude.json"
79
+ }
80
+ },
81
+ "claude-desktop": {
82
+ "name": "Claude Desktop",
83
+ "description": "Anthropic Claude Desktop application",
84
+ "config_format": "json",
85
+ "mcp_key": "mcpServers",
86
+ "paths": {
87
+ "darwin": "~/Library/Application Support/Claude/claude_desktop_config.json",
88
+ "win32": "%APPDATA%/Claude/claude_desktop_config.json",
89
+ "linux": "~/.config/Claude/claude_desktop_config.json"
90
+ }
91
+ },
92
+ "cline-vscode": {
93
+ "name": "Cline (VS Code)",
94
+ "description": "Cline extension for VS Code",
95
+ "config_format": "json",
96
+ "mcp_key": "mcpServers",
97
+ "paths": {
98
+ "darwin": "~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json",
99
+ "win32": "%APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json",
100
+ "linux": "~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json"
101
+ }
102
+ },
103
+ "codex": {
104
+ "name": "Codex CLI",
105
+ "description": "OpenAI Codex CLI (TOML config)",
106
+ "config_format": "toml",
107
+ "mcp_key": "mcp_servers",
108
+ "paths": {
109
+ "darwin": "~/.codex/config.toml",
110
+ "win32": "%USERPROFILE%/.codex/config.toml",
111
+ "linux": "~/.codex/config.toml"
112
+ }
113
+ },
114
+ "continue": {
115
+ "name": "Continue",
116
+ "description": "Continue VS Code extension",
117
+ "config_format": "json",
118
+ "mcp_key": "mcpServers",
119
+ "server_format": "array",
120
+ "paths": {
121
+ "darwin": "~/.continue/config.json",
122
+ "win32": "~/.continue/config.json",
123
+ "linux": "~/.continue/config.json"
124
+ }
125
+ },
126
+ "copilot-cli": {
127
+ "name": "GitHub Copilot CLI",
128
+ "description": "GitHub Copilot CLI MCP settings",
129
+ "config_format": "json",
130
+ "mcp_key": "mcpServers",
131
+ "paths": {
132
+ "darwin": "~/.copilot/mcp-config.json",
133
+ "win32": "%USERPROFILE%/.copilot/mcp-config.json",
134
+ "linux": "~/.copilot/mcp-config.json"
135
+ }
136
+ },
137
+ "crush": {
138
+ "name": "Crush",
139
+ "description": "Crush AI terminal assistant",
140
+ "config_format": "json",
141
+ "mcp_key": "mcp",
142
+ "paths": {
143
+ "darwin": "~/.config/crush/crush.json",
144
+ "win32": "%USERPROFILE%/.config/crush/crush.json",
145
+ "linux": "~/.config/crush/crush.json"
146
+ }
147
+ },
148
+ "cursor": {
149
+ "name": "Cursor",
150
+ "description": "Cursor AI code editor",
151
+ "config_format": "json",
152
+ "mcp_key": "mcpServers",
153
+ "paths": {
154
+ "darwin": "~/.cursor/mcp.json",
155
+ "win32": "%USERPROFILE%/.cursor/mcp.json",
156
+ "linux": "~/.cursor/mcp.json"
157
+ }
158
+ },
159
+ "gemini-cli": {
160
+ "name": "Gemini CLI",
161
+ "description": "Google Gemini CLI",
162
+ "config_format": "json",
163
+ "mcp_key": "mcpServers",
164
+ "paths": {
165
+ "darwin": "~/.gemini/settings.json",
166
+ "win32": "%USERPROFILE%/.gemini/settings.json",
167
+ "linux": "~/.gemini/settings.json"
168
+ }
169
+ },
170
+ "jan": {
171
+ "name": "Jan",
172
+ "description": "Jan AI assistant",
173
+ "config_format": "json",
174
+ "mcp_key": "mcpServers",
175
+ "paths": {
176
+ "darwin": "~/jan/mcp_config.json",
177
+ "win32": "%USERPROFILE%/jan/mcp_config.json",
178
+ "linux": "~/jan/mcp_config.json"
179
+ }
180
+ },
181
+ "kilo-antigravity": {
182
+ "name": "Kilo Code (Antigravity)",
183
+ "description": "Kilo Code extension for Antigravity",
184
+ "config_format": "json",
185
+ "mcp_key": "mcpServers",
186
+ "paths": {
187
+ "darwin": "~/Library/Application Support/Antigravity/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json",
188
+ "win32": "%APPDATA%/Antigravity/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json",
189
+ "linux": "~/.config/Antigravity/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json"
190
+ }
191
+ },
192
+ "kilo-cli": {
193
+ "name": "Kilo Code CLI",
194
+ "description": "Kilo Code CLI MCP settings",
195
+ "config_format": "json",
196
+ "mcp_key": "mcpServers",
197
+ "paths": {
198
+ "darwin": "~/.kilocode/cli/global/settings/mcp_settings.json",
199
+ "win32": "%USERPROFILE%/.kilocode/cli/global/settings/mcp_settings.json",
200
+ "linux": "~/.kilocode/cli/global/settings/mcp_settings.json"
201
+ }
202
+ },
203
+ "kilo-cursor": {
204
+ "name": "Kilo Code (Cursor)",
205
+ "description": "Kilo Code extension for Cursor",
206
+ "config_format": "json",
207
+ "mcp_key": "mcpServers",
208
+ "paths": {
209
+ "darwin": "~/Library/Application Support/Cursor/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json",
210
+ "win32": "%APPDATA%/Cursor/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json",
211
+ "linux": "~/.config/Cursor/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json"
212
+ }
213
+ },
214
+ "kilo-trae": {
215
+ "name": "Kilo Code (Trae)",
216
+ "description": "Kilo Code extension for Trae",
217
+ "config_format": "json",
218
+ "mcp_key": "mcpServers",
219
+ "paths": {
220
+ "darwin": "~/Library/Application Support/Trae/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json",
221
+ "win32": "%APPDATA%/Trae/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json",
222
+ "linux": "~/.config/Trae/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json"
223
+ }
224
+ },
225
+ "kilo-vscode": {
226
+ "name": "Kilo Code (VS Code)",
227
+ "description": "Kilo Code extension for VS Code",
228
+ "config_format": "json",
229
+ "mcp_key": "mcpServers",
230
+ "paths": {
231
+ "darwin": "~/Library/Application Support/Code/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json",
232
+ "win32": "%APPDATA%/Code/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json",
233
+ "linux": "~/.config/Code/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json"
234
+ }
235
+ },
236
+ "kilo-vscode-insiders": {
237
+ "name": "Kilo Code (VS Code Insiders)",
238
+ "description": "Kilo Code extension for VS Code Insiders",
239
+ "config_format": "json",
240
+ "mcp_key": "mcpServers",
241
+ "paths": {
242
+ "darwin": "~/Library/Application Support/Code - Insiders/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json",
243
+ "win32": "%APPDATA%/Code - Insiders/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json",
244
+ "linux": "~/.config/Code - Insiders/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json"
245
+ }
246
+ },
247
+ "kilo-windsurf": {
248
+ "name": "Kilo Code (Windsurf)",
249
+ "description": "Kilo Code extension for Windsurf",
250
+ "config_format": "json",
251
+ "mcp_key": "mcpServers",
252
+ "paths": {
253
+ "darwin": "~/Library/Application Support/Windsurf/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json",
254
+ "win32": "%APPDATA%/Windsurf/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json",
255
+ "linux": "~/.config/Windsurf/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json"
256
+ }
257
+ },
258
+ "mate": {
259
+ "name": "MATE",
260
+ "description": "MATE AI assistant",
261
+ "config_format": "json",
262
+ "mcp_key": "mcpServers",
263
+ "paths": {
264
+ "darwin": "~/Library/Application Support/MATE/MATE PS Data/mcp/mcp.json",
265
+ "win32": "%APPDATA%/MATE/MATE PS Data/mcp/mcp.json",
266
+ "linux": "~/.config/MATE/MATE PS Data/mcp/mcp.json"
267
+ }
268
+ },
269
+ "mcp-sync": {
270
+ "name": "MCP Sync",
271
+ "description": "MCP Sync global config",
272
+ "config_format": "json",
273
+ "mcp_key": "mcpServers",
274
+ "paths": {
275
+ "darwin": "~/Library/Application Support/mcp-sync/global.json",
276
+ "win32": "%APPDATA%/mcp-sync/global.json",
277
+ "linux": "~/.config/mcp-sync/global.json"
278
+ }
279
+ },
280
+ "opencode": {
281
+ "name": "OpenCode",
282
+ "description": "OpenCode AI terminal assistant",
283
+ "config_format": "json",
284
+ "mcp_key": "mcp",
285
+ "command_as_array": true,
286
+ "env_key": "environment",
287
+ "paths": {
288
+ "darwin": "~/.config/opencode/opencode.json",
289
+ "win32": "%USERPROFILE%/.config/opencode/opencode.json",
290
+ "linux": "~/.config/opencode/opencode.json"
291
+ }
292
+ },
293
+ "qwen": {
294
+ "name": "Qwen Code",
295
+ "description": "Qwen Code CLI",
296
+ "config_format": "json",
297
+ "mcp_key": "mcpServers",
298
+ "paths": {
299
+ "darwin": "~/.qwen/settings.json",
300
+ "win32": "%USERPROFILE%/.qwen/settings.json",
301
+ "linux": "~/.qwen/settings.json"
302
+ }
303
+ },
304
+ "roo-antigravity": {
305
+ "name": "Roo Code (Antigravity)",
306
+ "description": "Roo Code extension for Antigravity",
307
+ "config_format": "json",
308
+ "mcp_key": "mcpServers",
309
+ "paths": {
310
+ "darwin": "~/Library/Application Support/Antigravity/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json",
311
+ "win32": "%APPDATA%/Antigravity/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json",
312
+ "linux": "~/.config/Antigravity/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json"
313
+ }
314
+ },
315
+ "roo-cursor": {
316
+ "name": "Roo Code (Cursor)",
317
+ "description": "Roo Code extension for Cursor",
318
+ "config_format": "json",
319
+ "mcp_key": "mcpServers",
320
+ "paths": {
321
+ "darwin": "~/Library/Application Support/Cursor/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json",
322
+ "win32": "%APPDATA%/Cursor/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json",
323
+ "linux": "~/.config/Cursor/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json"
324
+ }
325
+ },
326
+ "roo-trae": {
327
+ "name": "Roo Code (Trae)",
328
+ "description": "Roo Code extension for Trae",
329
+ "config_format": "json",
330
+ "mcp_key": "mcpServers",
331
+ "paths": {
332
+ "darwin": "~/Library/Application Support/Trae/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json",
333
+ "win32": "%APPDATA%/Trae/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json",
334
+ "linux": "~/.config/Trae/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json"
335
+ }
336
+ },
337
+ "roo-vscode": {
338
+ "name": "Roo Code (VS Code)",
339
+ "description": "Roo Code extension for VS Code",
340
+ "config_format": "json",
341
+ "mcp_key": "mcpServers",
342
+ "paths": {
343
+ "darwin": "~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json",
344
+ "win32": "%APPDATA%/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json",
345
+ "linux": "~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json"
346
+ }
347
+ },
348
+ "roo-vscode-insiders": {
349
+ "name": "Roo Code (VS Code Insiders)",
350
+ "description": "Roo Code extension for VS Code Insiders",
351
+ "config_format": "json",
352
+ "mcp_key": "mcpServers",
353
+ "paths": {
354
+ "darwin": "~/Library/Application Support/Code - Insiders/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json",
355
+ "win32": "%APPDATA%/Code - Insiders/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json",
356
+ "linux": "~/.config/Code - Insiders/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json"
357
+ }
358
+ },
359
+ "roo-windsurf": {
360
+ "name": "Roo Code (Windsurf)",
361
+ "description": "Roo Code extension for Windsurf",
362
+ "config_format": "json",
363
+ "mcp_key": "mcpServers",
364
+ "paths": {
365
+ "darwin": "~/Library/Application Support/Windsurf/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json",
366
+ "win32": "%APPDATA%/Windsurf/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json",
367
+ "linux": "~/.config/Windsurf/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json"
368
+ }
369
+ },
370
+ "trae": {
371
+ "name": "Trae",
372
+ "description": "Bytedance Trae editor",
373
+ "config_format": "json",
374
+ "mcp_key": "mcpServers",
375
+ "paths": {
376
+ "darwin": "~/Library/Application Support/Trae/User/mcp.json",
377
+ "win32": "%APPDATA%/Trae/User/mcp.json",
378
+ "linux": "~/.config/Trae/User/mcp.json"
379
+ }
380
+ },
381
+ "vscode": {
382
+ "name": "VS Code",
383
+ "description": "Visual Studio Code MCP settings",
384
+ "config_format": "json",
385
+ "mcp_key": "servers",
386
+ "mcp_wrapper_key": "mcp",
387
+ "paths": {
388
+ "darwin": "~/.vscode/mcp.json",
389
+ "win32": "%APPDATA%/Code/User/mcp.json",
390
+ "linux": "~/.vscode/mcp.json"
391
+ }
392
+ },
393
+ "vscode-insiders": {
394
+ "name": "VS Code Insiders",
395
+ "description": "Visual Studio Code Insiders MCP settings",
396
+ "config_format": "json",
397
+ "mcp_key": "servers",
398
+ "paths": {
399
+ "darwin": "~/Library/Application Support/Code - Insiders/User/mcp.json",
400
+ "win32": "%APPDATA%/Code - Insiders/User/mcp.json",
401
+ "linux": "~/.config/Code - Insiders/User/mcp.json"
402
+ }
403
+ },
404
+ "vtcode": {
405
+ "name": "VTCode",
406
+ "description": "VTCode AI terminal editor",
407
+ "config_format": "toml",
408
+ "mcp_key": "providers",
409
+ "mcp_wrapper_key": "mcp",
410
+ "server_format": "array",
411
+ "paths": {
412
+ "darwin": "~/.vtcode/vtcode.toml",
413
+ "win32": "%USERPROFILE%/.vtcode/vtcode.toml",
414
+ "linux": "~/.vtcode/vtcode.toml"
415
+ }
416
+ },
417
+ "windsurf": {
418
+ "name": "Windsurf",
419
+ "description": "Codeium Windsurf editor",
420
+ "config_format": "json",
421
+ "mcp_key": "mcpServers",
422
+ "paths": {
423
+ "darwin": "~/.codeium/windsurf/mcp_config.json",
424
+ "win32": "%USERPROFILE%/.codeium/windsurf/mcp_config.json",
425
+ "linux": "~/.codeium/windsurf/mcp_config.json"
426
+ }
427
+ }
428
+ }
429
+ }
mcp_synchro/agents.py ADDED
@@ -0,0 +1,163 @@
1
+ # this_file: src/mcp_synchro/agents.py
2
+ """The hunting dogs. Defines where each AI agent hides its config file and how to sniff it out."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import json
7
+ import os
8
+ import sys
9
+ from dataclasses import dataclass
10
+ from pathlib import Path
11
+ from typing import Any
12
+
13
+ from loguru import logger
14
+
15
+
16
+ @dataclass
17
+ class AgentDef:
18
+ """A dossier on a specific AI agent.
19
+
20
+ Tells us what format it expects (JSON, TOML), what key holds the servers
21
+ (e.g., `mcpServers` or `mcp_servers`), and where it hides its config on
22
+ Mac, Windows, and Linux.
23
+ """
24
+
25
+ id: str
26
+ name: str
27
+ description: str
28
+ config_format: str # "json" or "toml"
29
+ mcp_key: str # "mcpServers", "mcp_servers", "mcp", "servers", "providers"
30
+ paths: dict[str, str] # platform -> path template
31
+ mcp_wrapper_key: str | None = (
32
+ None # e.g., "mcp" for VS Code's {"mcp": {"servers": ...}}
33
+ )
34
+ command_as_array: bool = False # OpenCode uses ["cmd", "arg1", ...] for command
35
+ env_key: str | None = None # OpenCode uses "environment" instead of "env"
36
+ server_format: str = "dict" # "dict" (default) or "array" (VTCode)
37
+
38
+ @property
39
+ def is_toml(self) -> bool:
40
+ """Does this agent speak TOML instead of JSON?"""
41
+ return self.config_format == "toml"
42
+
43
+ def get_path_template(self) -> str | None:
44
+ """Grabs the raw file path template for the OS we\'re currently running on."""
45
+ return self.paths.get(sys.platform)
46
+
47
+ def resolve_path(self) -> Path | None:
48
+ """Turns a path template into a real, absolute path.
49
+
50
+ Expands `~` on Unix and `%APPDATA%` or `%USERPROFILE%` on Windows.
51
+ Returns None if we don\'t know where this agent lives on this OS.
52
+ """
53
+ template = self.get_path_template()
54
+ if template is None:
55
+ return None
56
+
57
+ # Expand environment variables on Windows
58
+ if sys.platform == "win32":
59
+ for var in ("APPDATA", "USERPROFILE", "LOCALAPPDATA"):
60
+ placeholder = f"%{var}%"
61
+ if placeholder in template:
62
+ env_val = os.environ.get(var, "")
63
+ template = template.replace(placeholder, env_val)
64
+
65
+ # Expand ~ for home directory
66
+ path = Path(template).expanduser()
67
+ return path
68
+
69
+ def config_exists(self) -> bool:
70
+ """Is the file actually sitting on the disk right now?"""
71
+ path = self.resolve_path()
72
+ return path is not None and path.exists()
73
+
74
+
75
+ @dataclass
76
+ class DiscoveredAgent:
77
+ """A pairing of an Agent dossier with the actual physical file we found on disk."""
78
+
79
+ agent: AgentDef
80
+ path: Path
81
+
82
+
83
+ def load_agents_json(path: Path) -> dict[str, Any]:
84
+ """Reads an `agents.json` map from disk."""
85
+ with path.open("r", encoding="utf-8") as f:
86
+ return json.load(f)
87
+
88
+
89
+ def get_builtin_agents_path() -> Path:
90
+ """Finds our baked-in `agents.json` that ships with the package."""
91
+ return Path(__file__).parent / "agents.json"
92
+
93
+
94
+ def parse_agent_defs(data: dict[str, Any]) -> list[AgentDef]:
95
+ """Translates the raw JSON payload into a list of strongly-typed AgentDefs."""
96
+ agents_data = data.get("agents", {})
97
+ result: list[AgentDef] = []
98
+ for agent_id, agent_info in agents_data.items():
99
+ result.append(
100
+ AgentDef(
101
+ id=agent_id,
102
+ name=agent_info["name"],
103
+ description=agent_info.get("description", ""),
104
+ config_format=agent_info.get("config_format", "json"),
105
+ mcp_key=agent_info.get("mcp_key", "mcpServers"),
106
+ paths=agent_info.get("paths", {}),
107
+ mcp_wrapper_key=agent_info.get("mcp_wrapper_key"),
108
+ command_as_array=agent_info.get("command_as_array", False),
109
+ env_key=agent_info.get("env_key"),
110
+ server_format=agent_info.get("server_format", "dict"),
111
+ )
112
+ )
113
+ return result
114
+
115
+
116
+ def load_all_agent_defs(user_agents_path: Path | None = None) -> list[AgentDef]:
117
+ """Compiles the master list of all known AI agents.
118
+
119
+ Loads our built-in list first, then layers any custom user definitions
120
+ on top. User configs always win ties.
121
+ """
122
+ # Load built-in
123
+ builtin_path = get_builtin_agents_path()
124
+ builtin_data = load_agents_json(builtin_path)
125
+ agents_by_id: dict[str, AgentDef] = {}
126
+ for agent in parse_agent_defs(builtin_data):
127
+ agents_by_id[agent.id] = agent
128
+
129
+ # Load user override if provided
130
+ if user_agents_path and user_agents_path.exists():
131
+ logger.debug(f"Loading user agent definitions from {user_agents_path}")
132
+ user_data = load_agents_json(user_agents_path)
133
+ for agent in parse_agent_defs(user_data):
134
+ agents_by_id[agent.id] = agent
135
+
136
+ return sorted(agents_by_id.values(), key=lambda a: a.name)
137
+
138
+
139
+ def discover_agents(agent_defs: list[AgentDef] | None = None) -> list[DiscoveredAgent]:
140
+ """Scours the hard drive for every known AI agent.
141
+
142
+ If we find a config file exactly where the AgentDef said it would be,
143
+ we add it to the discovered list.
144
+
145
+ Args:
146
+ agent_defs: A custom list of targets to hunt. If None, we hunt everything.
147
+
148
+ Returns:
149
+ A list of confirmed hits.
150
+ """
151
+ if agent_defs is None:
152
+ agent_defs = load_all_agent_defs()
153
+
154
+ discovered: list[DiscoveredAgent] = []
155
+ for agent in agent_defs:
156
+ path = agent.resolve_path()
157
+ if path is not None and path.exists():
158
+ discovered.append(DiscoveredAgent(agent=agent, path=path))
159
+ logger.debug(f"Found {agent.name}: {path}")
160
+ else:
161
+ logger.debug(f"Not found: {agent.name} ({path})")
162
+
163
+ return discovered