@nshipster/sosumi 1.0.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.
Files changed (34) hide show
  1. package/LICENSE.md +19 -0
  2. package/README.md +304 -0
  3. package/bin/sosumi.mjs +76 -0
  4. package/package.json +53 -0
  5. package/public/_headers +2 -0
  6. package/public/favicon.ico +0 -0
  7. package/public/favicon.svg +7 -0
  8. package/public/icons/square.and.pencil.svg +15 -0
  9. package/public/index.html +898 -0
  10. package/public/llms.txt +184 -0
  11. package/public/sosumi.m4a +0 -0
  12. package/src/cli.ts +214 -0
  13. package/src/index.ts +507 -0
  14. package/src/lib/cli-endpoints.ts +106 -0
  15. package/src/lib/external/fetch.ts +133 -0
  16. package/src/lib/external/index.ts +8 -0
  17. package/src/lib/external/policy.ts +308 -0
  18. package/src/lib/external/types.ts +10 -0
  19. package/src/lib/fetch.ts +43 -0
  20. package/src/lib/hig/fetch.ts +186 -0
  21. package/src/lib/hig/index.ts +9 -0
  22. package/src/lib/hig/render.ts +514 -0
  23. package/src/lib/hig/types.ts +206 -0
  24. package/src/lib/hig/util.ts +30 -0
  25. package/src/lib/mcp.ts +315 -0
  26. package/src/lib/reference/fetch.ts +53 -0
  27. package/src/lib/reference/index.ts +8 -0
  28. package/src/lib/reference/render.ts +739 -0
  29. package/src/lib/reference/types.ts +31 -0
  30. package/src/lib/search.ts +221 -0
  31. package/src/lib/types.ts +334 -0
  32. package/src/lib/url.ts +55 -0
  33. package/src/lib/video/index.ts +179 -0
  34. package/wrangler.jsonc +27 -0
package/public/index.html ADDED
@@ -0,0 +1,898 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+
4
+ <head>
5
+ <meta charset="UTF-8">
6
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
7
+ <title>sosumi.ai - Apple Docs for LLMs</title>
8
+ <meta name="description"
9
+ content="sosumi.ai provides Apple Developer documentation in an AI-readable format by converting JavaScript-rendered pages into Markdown.">
10
+ <meta name="author" content="sosumi.ai">
11
+ <meta name="robots" content="index, follow">
12
+
13
+ <link rel="canonical" href="https://sosumi.ai/">
14
+
15
+ <meta property="og:title" content="sosumi.ai - Apple Docs for LLMs">
16
+ <meta property="og:description"
17
+ content="sosumi.ai provides Apple Developer documentation in an AI-readable format by converting JavaScript-rendered pages into Markdown.">
18
+ <meta property="og:url" content="https://sosumi.ai/">
19
+ <meta property="og:site_name" content="sosumi.ai">
20
+ <meta property="og:type" content="website">
21
+
22
+ <meta name="twitter:card" content="summary">
23
+ <meta name="twitter:title" content="sosumi.ai - Apple Docs for LLMs">
24
+ <meta name="twitter:description"
25
+ content="sosumi.ai provides Apple Developer documentation in an AI-readable format by converting JavaScript-rendered pages into Markdown.">
26
+
27
+ <meta name="theme-color" content="#d68d6e" media="(prefers-color-scheme: light)">
28
+ <meta name="theme-color" content="#ec9b7f" media="(prefers-color-scheme: dark)">
29
+
30
+ <meta name="mobile-web-app-capable" content="yes">
31
+ <meta name="apple-mobile-web-app-status-bar-style" content="default">
32
+ <meta name="apple-mobile-web-app-title" content="sosumi.ai">
33
+
34
+ <link rel="icon" href="/favicon.svg" type="image/svg+xml">
35
+ <link rel="alternate icon" href="/favicon.ico">
36
+
37
+ <link rel="preload" href="/sosumi.m4a" as="audio" type="audio/mp4">
38
+
39
+ <style>
40
+ :root {
41
+ color-scheme: light dark;
42
+
43
+ --font-sans: -apple-system, BlinkMacSystemFont, 'SF Pro Text', sans-serif;
44
+ --font-mono: 'SF Mono', monospace;
45
+
46
+ --text: oklch(15% 0 0);
47
+ --text-secondary: oklch(35% 0 0);
48
+ --text-tertiary: oklch(55% 0 0);
49
+
50
+ --surface: oklch(98% 0 0);
51
+ --surface-inset: oklch(95% 0.02 70);
52
+ --surface-inset-deep: oklch(90% 0.05 70);
53
+
54
+ --border: oklch(20% 0.1 70);
55
+
56
+ --link: oklch(65% 0.15 70);
57
+ --accent: oklch(78% 0.18 70);
58
+ --accent-hover: oklch(85% 0.2 70);
59
+
60
+ --code-key-color: oklch(60% 0.15 70);
61
+ --code-string-color: oklch(55% 0.2 70);
62
+ --code-punctuation-color: var(--text-tertiary);
63
+ }
64
+
65
+ @media (prefers-color-scheme: dark) {
66
+ :root {
67
+ --text: oklch(92% 0.02 70);
68
+ --text-secondary: oklch(75% 0.05 70);
69
+ --text-tertiary: oklch(55% 0.08 70);
70
+
71
+ --surface: oklch(18% 0 0);
72
+ --surface-inset: oklch(12% 0.02 70);
73
+ --surface-inset-deep: oklch(15% 0.05 70);
74
+
75
+ --border: oklch(25% 0.1 70);
76
+ --accent: oklch(85% 0.2 70);
77
+ --accent-hover: oklch(92% 0.22 70);
78
+
79
+ --code-key-color: oklch(75% 0.15 70);
80
+ --code-string-color: oklch(70% 0.2 70);
81
+ }
82
+ }
83
+
84
+ html {
85
+ font-size: 100%;
86
+ }
87
+
88
+ body {
89
+ font-family: var(--font-sans);
90
+ color: var(--text);
91
+ background-color: var(--surface);
92
+ max-width: 52rem;
93
+ margin: 3rem auto;
94
+ padding: 1.5rem;
95
+ line-height: 1.6;
96
+ }
97
+
98
+ h1 {
99
+ font-size: 3rem;
100
+ margin-bottom: 0;
101
+ display: flex;
102
+ align-items: baseline;
103
+ justify-content: space-between;
104
+ gap: 0.5rem;
105
+ }
106
+
107
+ h1 a {
108
+ color: var(--text) !important;
109
+
110
+ }
111
+
112
+ h1 svg {
113
+ width: 2rem;
114
+ height: 2rem;
115
+ color: var(--accent);
116
+ cursor: cell;
117
+ user-select: none;
118
+ }
119
+
120
+ h2 {
121
+ margin-top: 1.5625rem;
122
+ margin-bottom: 0.625rem;
123
+ color: var(--text-secondary);
124
+ }
125
+
126
+ h3 {
127
+ margin-top: 1.5625rem;
128
+ margin-bottom: 0.625rem;
129
+ color: var(--text-secondary);
130
+ }
131
+
132
+ dl code {
133
+ padding: 0;
134
+ }
135
+
136
+ dt {
137
+ font-weight: 500;
138
+ }
139
+
140
+ dt code {
141
+ padding-left: 0.25rem;
142
+ padding-right: 0.25rem;
143
+ margin-left: -0.25rem;
144
+ }
145
+
146
+ dd {
147
+ margin-left: 0;
148
+ }
149
+
150
+ dd+dt {
151
+ margin-top: 0.9375rem;
152
+ }
153
+
154
+ var {
155
+ font-style: normal;
156
+ font-weight: 500;
157
+ font-family: var(--font-mono);
158
+ color: var(--accent);
159
+ }
160
+
161
+ .icon {
162
+ width: 1rem;
163
+ height: 1rem;
164
+ vertical-align: middle;
165
+ padding-bottom: 0.125rem;
166
+ }
167
+
168
+ .install-button img {
169
+ display: inline-block;
170
+ border-radius: 0.5rem;
171
+ border: 1px solid transparent;
172
+ transition: border 0.2s, background 0.2s;
173
+ }
174
+
175
+ .install-button img:hover {
176
+ text-decoration: none;
177
+ border: 1px solid var(--accent);
178
+ }
179
+
180
+ figure {
181
+ margin: 0;
182
+ }
183
+
184
+ code.no-wrap {
185
+ white-space: nowrap;
186
+ }
187
+
188
+ #clients {
189
+ margin-top: 1.5rem;
190
+ }
191
+
192
+ #mcp ul {
193
+ display: flex;
194
+ flex-direction: column;
195
+ gap: 0.5rem;
196
+ padding-left: 1rem;
197
+ list-style: none;
198
+ }
199
+
200
+ #mcp ul li {
201
+ margin-bottom: 1rem;
202
+ }
203
+
204
+ #mcp dd {
205
+ color: var(--text-secondary);
206
+ }
207
+
208
+ #mcp dd strong {
209
+ font-weight: 400;
210
+ color: var(--text);
211
+ display: inline-block;
212
+ padding-bottom: 0.5rem;
213
+ }
214
+
215
+ #clients .editor-config {
216
+ margin-top: 1.5rem;
217
+ }
218
+
219
+ #clients .config-tabs {
220
+ display: flex;
221
+ flex-direction: column;
222
+ gap: 2rem;
223
+ }
224
+
225
+ #clients .interface-tabs,
226
+ #clients .client-tabs {
227
+ background: var(--surface-inset);
228
+ border-radius: 0.5rem;
229
+ overflow: hidden;
230
+ }
231
+
232
+ #clients .tab-buttons {
233
+ display: flex;
234
+ border-bottom: 1px solid var(--border);
235
+ }
236
+
237
+ #clients .tab-button {
238
+ flex: 1;
239
+ padding: 1rem 1.5rem;
240
+ background: transparent;
241
+ border: none;
242
+ color: var(--text-secondary);
243
+ font-family: var(--font-sans);
244
+ font-size: 1rem;
245
+ cursor: pointer;
246
+ transition: all 0.2s ease;
247
+ border-bottom: 2px solid transparent;
248
+ }
249
+
250
+ #clients .tab-button:hover {
251
+ color: var(--text);
252
+ background: var(--surface-inset-deep);
253
+ }
254
+
255
+ #clients .tab-button.active {
256
+ color: var(--text);
257
+ border-bottom-color: var(--accent);
258
+ background: var(--surface);
259
+ }
260
+
261
+ #clients .tab-content {
262
+ position: relative;
263
+ }
264
+
265
+ #clients .tab-pane {
266
+ display: none;
267
+ padding: 1.5rem;
268
+ }
269
+
270
+ #clients .tab-pane.active {
271
+ display: block;
272
+ }
273
+
274
+ #clients .tab-pane h3 {
275
+ margin-top: 0;
276
+ margin-bottom: 1rem;
277
+ color: var(--text);
278
+ }
279
+
280
+ #clients .tab-pane h4 {
281
+ margin-top: 1.5rem;
282
+ margin-bottom: 0.75rem;
283
+ color: var(--text-secondary);
284
+ font-size: 1rem;
285
+ }
286
+
287
+ #clients .tab-pane ol {
288
+ margin: 0.75rem 0;
289
+ padding-left: 1.5rem;
290
+ }
291
+
292
+ #clients .tab-pane li {
293
+ margin-bottom: 0.5rem;
294
+ }
295
+
296
+ #clients .tab-pane p {
297
+ margin: 0.75rem 0;
298
+ }
299
+
300
+ #clients .tab-pane em {
301
+ color: var(--text-secondary);
302
+ font-style: italic;
303
+ }
304
+
305
+ @media (max-width: 768px) {
306
+ #clients .tab-buttons {
307
+ flex-direction: column;
308
+ }
309
+
310
+ #clients .tab-button {
311
+ border-bottom: 1px solid var(--border);
312
+ border-right: none;
313
+ }
314
+
315
+ #clients .tab-button.active {
316
+ border-bottom-color: var(--border);
317
+ border-right: 2px solid var(--accent);
318
+ }
319
+ }
320
+
321
+ .tagline {
322
+ color: var(--text-secondary);
323
+ font-size: 1.25rem;
324
+ margin-bottom: 2.5rem;
325
+ line-height: 1.2;
326
+ }
327
+
328
+ .tagline span {
329
+ display: inline-block;
330
+ }
331
+
332
+ .tagline em {
333
+ font-size: smaller;
334
+ opacity: 0.8;
335
+ }
336
+
337
+ code {
338
+ background: var(--surface-inset);
339
+ padding: 0.125rem;
340
+ font-family: var(--font-mono);
341
+ word-break: break-all;
342
+ overflow-wrap: break-word;
343
+ }
344
+
345
+ main header {
346
+ margin-bottom: 2rem;
347
+ }
348
+
349
+ code a {
350
+ word-break: break-word;
351
+ overflow-wrap: anywhere;
352
+ }
353
+
354
+ h4 {
355
+ margin-top: 1.5625rem;
356
+ margin-bottom: 0.625rem;
357
+ color: var(--text-secondary);
358
+ }
359
+
360
+ q {
361
+ font-style: italic;
362
+ }
363
+
364
+ footer {
365
+ margin-top: 3.75rem;
366
+ padding-top: 1.25rem;
367
+ border-top: 1px solid var(--border);
368
+ color: var(--text-tertiary);
369
+ font-size: 0.875rem;
370
+ display: flex;
371
+ flex-direction: row;
372
+ gap: 1.25rem;
373
+ }
374
+
375
+ footer #disclaimer {
376
+ flex: 1;
377
+ }
378
+
379
+ footer aside {
380
+ flex: 1;
381
+ }
382
+
383
+ main>section {
384
+ border-top: 1px solid var(--border);
385
+ padding-bottom: 1rem;
386
+ padding-top: 2rem;
387
+ }
388
+
389
+ section header {
390
+ background: var(--surface-inset);
391
+ padding: 1.25rem;
392
+ }
393
+
394
+ a {
395
+ color: var(--link);
396
+ text-decoration: none;
397
+ transition: color 0.2s ease;
398
+ }
399
+
400
+ a picture {
401
+ cursor: pointer;
402
+ }
403
+
404
+ a:hover {
405
+ color: var(--accent);
406
+ text-decoration: underline;
407
+ }
408
+
409
+ pre code .key {
410
+ color: var(--code-key-color);
411
+ }
412
+
413
+ pre code .string {
414
+ color: var(--code-string-color);
415
+ }
416
+
417
+ pre code .punctuation {
418
+ color: var(--code-punctuation-color);
419
+ }
420
+
421
+ pre code .sosumi-entry {
422
+ background-color: var(--surface-inset-deep);
423
+ display: block;
424
+ border-radius: 0.5rem;
425
+ }
426
+
427
+ pre code .dimmed {
428
+ opacity: 0.6;
429
+ }
430
+
431
+ section header> :first-child {
432
+ margin-top: 0;
433
+ }
434
+
435
+ #disclaimer {
436
+ color: var(--text-secondary);
437
+ }
438
+
439
+ #haiku {
440
+ display: flex;
441
+ justify-content: center;
442
+ align-items: start;
443
+ flex-wrap: wrap;
444
+ position: relative;
445
+ flex-direction: row-reverse;
446
+ font-size: 1.25rem;
447
+ line-height: 1.8;
448
+ letter-spacing: 0.1em;
449
+ }
450
+
451
+ #haiku span {
452
+ writing-mode: vertical-rl;
453
+ }
454
+
455
+ #haiku figcaption {
456
+ writing-mode: vertical-rl;
457
+ text-orientation: mixed;
458
+ font-weight: bold;
459
+ font-size: 1.5rem;
460
+ position: absolute;
461
+ right: 0;
462
+ top: 0;
463
+ display: flex;
464
+ align-items: center;
465
+ }
466
+
467
+ #haiku figcaption ruby {
468
+ line-height: 1;
469
+ }
470
+
471
+ #haiku figcaption rt {
472
+ font-size: 1rem;
473
+ }
474
+
475
+ @media (max-width: 768px) {
476
+ footer {
477
+ display: block;
478
+ }
479
+
480
+ #haiku {
481
+ font-size: 1.5rem;
482
+ padding-top: 2rem;
483
+ margin: 1rem auto;
484
+ }
485
+
486
+ #haiku figcaption {
487
+ position: static;
488
+ margin-right: 1rem;
489
+ height: auto;
490
+ }
491
+ }
492
+
493
+ /* Custom text selection colors */
494
+ ::selection {
495
+ background-color: var(--accent);
496
+ color: var(--surface);
497
+ }
498
+
499
+ ::-moz-selection {
500
+ background-color: var(--accent);
501
+ color: var(--surface);
502
+ }
503
+ </style>
504
+
505
+ <script>
506
+ document.addEventListener('DOMContentLoaded', function () {
507
+ const logo = document.querySelector('.logo');
508
+ const audio = new Audio('./sosumi.m4a');
509
+
510
+ logo.addEventListener('click', function () {
511
+ audio.currentTime = 0; // Reset to beginning
512
+ audio.play().catch(function (error) {
513
+ console.log('Audio playback failed:', error);
514
+ });
515
+ });
516
+
517
+ // Client tabs (Cursor, VSCode, etc.)
518
+ const clientTabButtons = document.querySelectorAll('.client-tabs .tab-button');
519
+ const clientTabPanes = document.querySelectorAll('.client-tabs .tab-pane');
520
+ clientTabButtons.forEach(button => {
521
+ button.addEventListener('click', function () {
522
+ const targetTab = this.getAttribute('data-tab');
523
+
524
+ // Remove active class from all client buttons and panes
525
+ clientTabButtons.forEach(btn => btn.classList.remove('active'));
526
+ clientTabPanes.forEach(pane => pane.classList.remove('active'));
527
+
528
+ // Add active class to clicked button and corresponding pane
529
+ this.classList.add('active');
530
+ document.getElementById(targetTab + '-tab').classList.add('active');
531
+ });
532
+ });
533
+ });
534
+ </script>
535
+ </head>
536
+
537
+ <body>
538
+ <header>
539
+ <h1>
540
+ <a href="/" accesskey="1">sosumi.ai</a>
541
+
542
+ <svg class="logo" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" role="img"
543
+ aria-label="sosumi.ai logo" title="You couldn't sue a face like this, right?">
544
+ <!-- https://www.streamlinehq.com/icons/pixel?icon=ico_girK3NdW2U5HOWO0 -->
545
+ <path fill="currentColor"
546
+ d="M21.72 4.575V0H10.29v1.14H5.715v1.148H2.287v8.002h-1.14v2.28H0V24h24V4.575zM5.715 22.86H1.148v-6.863h4.567zm0-8.002h-2.28V3.428h2.28zm1.148-12.57h3.427v1.14H8.003v11.43h-1.14zm3.427 2.287v10.282H9.15V4.575zm1.14 18.285H6.863v-6.863h4.567zm11.43 0H12.578v-8.003H11.43V1.14h9.143v3.435h-3.428v1.14h5.715z" />
547
+ <path fill="currentColor"
548
+ d="M19.433 15.997h1.14v1.148h-1.14zM19.433 13.717h1.14v1.14h-1.14zM17.145 17.145h2.287v1.14h-2.287zM16.005 15.997h1.14v1.148h-1.14zM16.005 13.717h1.14v1.14h-1.14zM16.005 5.715h1.14v2.287h-1.14zM14.857 8.002h1.148v2.288h-1.147zM13.717 10.29h1.14v2.28h-1.14zM13.717 2.287h1.14v1.14h-1.14zM12.578 12.57h1.14v2.287h-1.14zM8.002 18.285h2.288v2.287H8.003zM2.287 18.285h2.288v2.287H2.287z" />
549
+ </svg>
550
+ </h1>
551
+ <p class="tagline">
552
+ <span>Making Apple docs AI-readable.</span>
553
+ <wbr />
554
+ <span>So sue me.</span>
555
+ <br />
556
+ <em>(Please don't actually sue me)</em>
557
+ </p>
558
+ </header>
559
+
560
+ <main>
561
+ <header>
562
+ <p>Ever notice Claude struggling to write Swift code? It might not be their fault!</p>
563
+ <p>
564
+ Apple Developer docs are locked behind JavaScript,
565
+ making them invisible to most LLMs.
566
+ If they try to fetch it, all they see is
567
+ <q>This page requires JavaScript. Please turn on JavaScript in your browser and refresh the page to view
568
+ its content.</q>
569
+ <br />
570
+ </p>
571
+ <p>
572
+ This service translates Apple Developer documentation, Human Interface Guidelines, WWDC sessions, and external Swift-DocC sites into AI-friendly Markdown.
573
+ </p>
574
+ </header>
575
+
576
+ <section id="http">
577
+ <header>
578
+ <h2>HTTP Usage</h2>
579
+ <p>Replace <code>developer.apple.com</code> with <code>sosumi.ai</code>:</p>
580
+
581
+ <dl>
582
+ <dt>Original</dt>
583
+ <dd>
584
+ <code><a href="https://developer.apple.com/documentation/swift/array"
585
+ rel="noopener noreferrer">https://&#8203;developer.apple.com&#8203;/&#8203;documentation&#8203;/&#8203;swift&#8203;/&#8203;array</a></code>
586
+ </dd>
587
+ <dt>AI-readable</dt>
588
+ <dd>
589
+ <code><a
590
+ href="https://sosumi.ai/documentation/swift/array">https://&#8203;sosumi.ai&#8203;/&#8203;documentation&#8203;/&#8203;swift&#8203;/&#8203;array</a></code>
591
+ </dd>
592
+ </dl>
593
+ </header>
594
+
595
+ <section class="examples">
596
+ <h2>Examples</h2>
597
+ <ul>
598
+ <li><a href="/documentation/swift">Swift</a></li>
599
+ <li><a href="/documentation/swiftui">SwiftUI</a></li>
600
+ <li><a href="/design/human-interface-guidelines/">Human Interface Guidelines</a></li>
601
+ <li><a href="/videos/play/wwdc2021/10133">WWDC21: Protect mutable state with Swift actors</a></li>
602
+ <li><a
603
+ href="/external/https://apple.github.io/swift-argument-parser/documentation/argumentparser/">Swift
604
+ Argument Parser (hosted on GitHub Pages)</a></li>
605
+ <li><a
606
+ href="/external/https://swiftpackageindex.com/pointfreeco/swift-composable-architecture/1.23.1/documentation/composablearchitecture">The
607
+ Composable Architecture (hosted on Swift Package Index)</a></li>
608
+ </ul>
609
+ </section>
610
+ </section>
611
+
612
+
613
+ <section id="bot">
614
+ <header>
615
+ <h2>Bot & Crawling Policy</h2>
616
+ <p>
617
+ Fetches are made with the user agent
618
+ <code class="no-wrap">sosumi-ai/1.0 (+https://sosumi.ai/#bot)</code>.
619
+ </p>
620
+ <p>
621
+ For external Swift-DocC hosts, sosumi honors
622
+ <code class="no-wrap">robots.txt</code> rules and opt-out response directives such as
623
+ <code class="no-wrap">X-Robots-Tag: noai</code>.
624
+ </p>
625
+ <p>
626
+ Questions or issues: <a href="mailto:info@sosumi.ai">info@sosumi.ai</a>
627
+ </p>
628
+ </header>
629
+ </section>
630
+
631
+
632
+ <section id="mcp">
633
+ <header>
634
+ <h2>MCP Usage</h2>
635
+ <p>
636
+ Connect your <abbr title="Model Context Protocol">MCP</abbr> client to
637
+ <code class="no-wrap">https://sosumi.ai/mcp</code>.
638
+ </p>
639
+
640
+ <figure id="clients">
641
+ <div class="client-tabs">
642
+ <div class="tab-buttons">
643
+ <button class="tab-button active" data-tab="copilot-xcode">GitHub Copilot for Xcode</button>
644
+ <button class="tab-button" data-tab="cursor">Cursor</button>
645
+ <button class="tab-button" data-tab="vscode">VSCode</button>
646
+ <button class="tab-button" data-tab="claude-desktop">Claude Desktop</button>
647
+ <button class="tab-button" data-tab="claude-code">Claude Code</button>
648
+ <button class="tab-button" data-tab="other">Other</button>
649
+ </div>
650
+
651
+ <div class="tab-content">
652
+ <div class="tab-pane active" id="copilot-xcode-tab">
653
+ <h3>GitHub Copilot for Xcode</h3>
654
+ <ol>
655
+ <li>Open <strong>GitHub Copilot for Xcode</strong> and go to
656
+ <strong>Settings…</strong>
657
+ </li>
658
+ <li>Select the <strong>MCP</strong> tab</li>
659
+ <li>Click <span>
660
+ <img class="icon" src="/icons/square.and.pencil.svg" alt="Edit Config"
661
+ width="16" height="16" />
662
+ Edit Config
663
+ </span></li>
664
+ <li>Enter the following configuration:</li>
665
+ </ol>
666
+ <pre><code class="mcp-config"><span class="dimmed"><span class="punctuation">{</span></span>
667
+ <span class="dimmed"> <span class="key">"servers"</span><span class="punctuation">:</span> <span class="punctuation">{</span></span> <span class="sosumi-entry"> <span class="key">"sosumi"</span><span class="punctuation">:</span> <span class="punctuation">{</span>
668
+ <span class="key">"type"</span><span class="punctuation">:</span> <span class="string">"http"</span><span class="punctuation">,</span>
669
+ <span class="key">"url"</span><span class="punctuation">:</span> <span class="string">"https://sosumi.ai/mcp"</span>
670
+ <span class="punctuation">}</span></span><span class="dimmed"> <span class="punctuation">}</span></span>
671
+ <span class="dimmed"><span class="punctuation">}</span></span></code></pre>
672
+ <p>For more information, see the <a href="https://github.com/github/CopilotForXcode"
673
+ rel="noopener noreferrer">GitHub Copilot for Xcode README</a>.</p>
674
+ </div>
675
+
676
+ <div class="tab-pane" id="cursor-tab">
677
+ <h3>Cursor</h3>
678
+ <p>Click the button below to automatically install the sosumi MCP server:</p>
679
+
680
+ <a class="install-button"
681
+ href="cursor://anysphere.cursor-deeplink/mcp/install?name=sosumi&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vc29zdW1pLmFpL21jcCJ9">
682
+ <picture>
683
+ <source srcset="https://cursor.com/deeplink/mcp-install-light.svg"
684
+ media="(prefers-color-scheme: light)">
685
+ <source srcset="https://cursor.com/deeplink/mcp-install-dark.svg"
686
+ media="(prefers-color-scheme: dark)">
687
+ <img src="https://cursor.com/deeplink/mcp-install-dark.svg"
688
+ alt="Add sosumi MCP server to Cursor" height="32" />
689
+ </picture>
690
+ </a>
691
+
692
+ <p>For more information, see the <a href="https://www.cursor.com/docs/install-mcp"
693
+ rel="noopener noreferrer">Cursor documentation</a>.</p>
694
+ </div>
695
+
696
+ <div class="tab-pane" id="vscode-tab">
697
+ <h3>VSCode</h3>
698
+ <p>Create a <code>.vscode/mcp.json</code> file in your workspace and enter the following
699
+ configuration:</p>
700
+
701
+ <pre><code class="mcp-config"><span class="dimmed"><span class="punctuation">{</span></span>
702
+ <span class="dimmed"> <span class="key">"servers"</span><span class="punctuation">:</span> <span class="punctuation">{</span></span> <span class="sosumi-entry"> <span class="key">"sosumi"</span><span class="punctuation">:</span> <span class="punctuation">{</span>
703
+ <span class="key">"type"</span><span class="punctuation">:</span> <span class="string">"http"</span><span class="punctuation">,</span>
704
+ <span class="key">"url"</span><span class="punctuation">:</span> <span class="string">"https://sosumi.ai/mcp"</span>
705
+ <span class="punctuation">}</span></span><span class="dimmed"> <span class="punctuation">}</span></span>
706
+ <span class="dimmed"><span class="punctuation">}</span></span></code></pre>
707
+
708
+ <p>For more information, see the <a
709
+ href="https://code.visualstudio.com/docs/copilot/customization/mcp-servers"
710
+ rel="noopener noreferrer">VSCode documentation</a>.</p>
711
+ </div>
712
+
713
+ <div class="tab-pane" id="claude-desktop-tab">
714
+ <h3>Claude Desktop</h3>
715
+ <ol>
716
+ <li>Open <strong>Claude Desktop</strong></li>
717
+ <li>Go to <strong>Settings → Connectors</strong></li>
718
+ <li>Click <strong>"Add custom connector"</strong></li>
719
+ <li>Set <strong>"Name"</strong> to <var>sosumi</var></li>
720
+ <li>Set <strong>"Remote MCP server URL"</strong> to
721
+ <var>https://sosumi.ai/mcp</var>
722
+ </li>
723
+ <li>Click "Add"</li>
724
+ </ol>
725
+ <p>See the <a
726
+ href="https://support.anthropic.com/en/articles/11725091-when-to-use-desktop-and-web-connectors"
727
+ rel="noopener noreferrer">Claude Desktop documentation</a> for more information.
728
+ </p>
729
+ </div>
730
+
731
+ <div class="tab-pane" id="claude-code-tab">
732
+ <h3>Claude Code</h3>
733
+ <p>Run the following command in your terminal:</p>
734
+ <pre><code>claude mcp add --transport http sosumi https://sosumi.ai/mcp</code></pre>
735
+ <p>For more information, see the
736
+ <a href="https://docs.anthropic.com/en/docs/claude-code/mcp"
737
+ rel="noopener noreferrer">Claude Code MCP documentation</a>.
738
+ </p>
739
+ </div>
740
+
741
+ <div class="tab-pane" id="other-tab">
742
+ <h3>Other MCP Clients</h3>
743
+ <p>Sosumi's MCP server supports Streamable HTTP and Server-Sent Events (SSE) transport.
744
+ If your client supports either of these,
745
+ configure it to connect directly to <code>https://sosumi.ai/mcp</code>.</p>
746
+
747
+ <p>Otherwise,
748
+ you can run this command to proxy over stdio:</p>
749
+
750
+ <pre><code class="mcp-config"><span class="dimmed"><span class="punctuation">{</span></span>
751
+ <span class="dimmed"> <span class="key">"mcpServers"</span><span class="punctuation">:</span> <span class="punctuation">{</span></span>
752
+ <span class="sosumi-entry"> <span class="key">"sosumi"</span><span class="punctuation">:</span> <span class="punctuation">{</span>
753
+ <span class="key">"command"</span><span class="punctuation">:</span> <span class="string">"npx"</span><span class="punctuation">,</span>
754
+ <span class="key">"args"</span><span class="punctuation">:</span> <span class="punctuation">[</span>
755
+ <span class="string">"-y"</span><span class="punctuation">,</span>
756
+ <span class="string">"mcp-remote"</span><span class="punctuation">,</span>
757
+ <span class="string">"https://sosumi.ai/mcp"</span>
758
+ <span class="punctuation">]</span>
759
+ <span class="punctuation">}</span></span><span class="dimmed"> <span class="punctuation">}</span></span>
760
+ <span class="dimmed"><span class="punctuation">}</span></span></code></pre>
761
+ </div>
762
+ </div>
763
+ </div>
764
+ </figure>
765
+ </header>
766
+
767
+
768
+ <div class="tools">
769
+ <h3>Available Tools</h3>
770
+ <ul>
771
+ <li>
772
+ <dl>
773
+ <dt><code>searchAppleDocumentation</code></dt>
774
+ <dd><strong>Searches Apple Developer documentation</strong>
775
+ <br>Parameters: <code>query</code> (string)
776
+ <br><em>Returns structured results with titles, URLs, descriptions, breadcrumbs, and
777
+ tags</em>
778
+ </dd>
779
+ </dl>
780
+ </li>
781
+ <li>
782
+ <dl>
783
+ <dt><code>fetchAppleDocumentation</code></dt>
784
+ <dd><strong>Fetches Apple Developer documentation and Human Interface Guidelines by path</strong>
785
+ <br>Parameters: <code>path</code> (string) - Documentation path (e.g., '/documentation/swift', 'design/human-interface-guidelines/foundations/color')
786
+ <br><em>Returns content as Markdown</em>
787
+ </dd>
788
+ </dl>
789
+ </li>
790
+ <li>
791
+ <dl>
792
+ <dt><code>fetchAppleVideoTranscript</code></dt>
793
+ <dd><strong>Fetches video transcripts, including WWDC sessions, by video path</strong>
794
+ <br>Parameters: <code>path</code> (string) - video path (e.g., '/videos/play/wwdc2021/10133', '/videos/play/meet-with-apple/208')
795
+ <br><em>Returns content as Markdown</em>
796
+ </dd>
797
+ </dl>
798
+ </li>
799
+ <li>
800
+ <dl>
801
+ <dt><code>fetchExternalDocumentation</code></dt>
802
+ <dd><strong>Fetches external Swift-DocC documentation by absolute HTTPS URL</strong>
803
+ <br>Parameters: <code>url</code> (string) - External URL (e.g., 'https://apple.github.io/swift-argument-parser/documentation/argumentparser')
804
+ <br><em>Returns content as Markdown</em>
805
+ </dd>
806
+ </dl>
807
+ </li>
808
+ </ul>
809
+ </div>
810
+ </section>
811
+
812
+
813
+ <div class="troubleshooting">
814
+ <h3>Troubleshooting</h3>
815
+ <p>
816
+ If you're experiencing connection timeouts or network issues with the MCP server,
817
+ you may need to configure a proxy.
818
+ This is particularly common in corporate environments
819
+ or regions with restricted internet access.
820
+ </p>
821
+ <p>
822
+ Configure your MCP client to use a proxy by adding environment variables:
823
+ </p>
824
+ <pre><code class="mcp-config"><span class="dimmed"><span class="punctuation">{</span></span>
825
+ <span class="dimmed"> <span class="key">"mcpServers"</span><span class="punctuation">:</span> <span class="punctuation">{</span></span>
826
+ <span class="sosumi-entry"> <span class="key">"sosumi"</span><span class="punctuation">:</span> <span class="punctuation">{</span>
827
+ <span class="key">"command"</span><span class="punctuation">:</span> <span class="string">"npx"</span><span class="punctuation">,</span>
828
+ <span class="key">"args"</span><span class="punctuation">:</span> <span class="punctuation">[</span>
829
+ <span class="string">"-y"</span><span class="punctuation">,</span>
830
+ <span class="string">"mcp-remote"</span><span class="punctuation">,</span>
831
+ <span class="string">"https://sosumi.ai/mcp"</span>
832
+ <span class="punctuation">]</span><span class="punctuation">,</span>
833
+ <span class="key">"env"</span><span class="punctuation">:</span> <span class="punctuation">{</span>
834
+ <span class="key">"HTTP_PROXY"</span><span class="punctuation">:</span> <span class="string">"http://proxy.example.com:8080"</span><span class="punctuation">,</span>
835
+ <span class="key">"HTTPS_PROXY"</span><span class="punctuation">:</span> <span class="string">"http://proxy.example.com:8080"</span>
836
+ <span class="punctuation">}</span>
837
+ <span class="punctuation">}</span></span><span class="dimmed"> <span class="punctuation">}</span></span>
838
+ <span class="dimmed"><span class="punctuation">}</span></span></code></pre>
839
+ <p>
840
+ Replace <code>proxy.example.com:8080</code> with your actual proxy server details.
841
+ For authenticated proxies, use the format:
842
+ <code>http://username:password@proxy.example.com:8080</code>
843
+ </p>
844
+ </div>
845
+ </section>
846
+ </main>
847
+
848
+
849
+ <footer>
850
+ <div id="disclaimer">
851
+ <p>
852
+ <strong>Disclaimer:</strong>
853
+ This is an unofficial, independent project
854
+ and is not affiliated with or endorsed by Apple Inc.
855
+ "Apple", "Xcode", and related marks are trademarks of Apple Inc.
856
+ </p>
857
+ <p>
858
+ This project is open source and available on
859
+ <a href="https://github.com/NSHipster/sosumi.ai" rel="noopener noreferrer">GitHub</a>.
860
+ </p>
861
+ <p>
862
+ This service is an accessibility-first, on-demand renderer.
863
+ It converts a single Apple Developer page to Markdown only when requested by a user.
864
+ It does not crawl, spider, or bulk download;
865
+ it does not attempt to bypass authentication or security;
866
+ and it implements rate limiting to avoid imposing unreasonable load.
867
+ </p>
868
+ <p>
869
+ Content is fetched transiently and may be cached briefly to improve performance.
870
+ No permanent archives are maintained.
871
+ All copyrights and other rights in the underlying content remain with Apple Inc.
872
+ Each page links back to the original source.
873
+ </p>
874
+ <p>
875
+ Your use of this service must comply with Apple's Terms of Use and applicable law.
876
+ You are solely responsible for how you access and use Apple's content through this tool.
877
+ Do not use this service to circumvent technical measures or for redistribution.
878
+ </p>
879
+ <p>
880
+ <strong>Contact:</strong> <a href="mailto:info@sosumi.ai">info@sosumi.ai</a>
881
+ </p>
882
+ </div>
883
+
884
+ <aside>
885
+ <figure id="haiku" lang="ja"
886
+ title="Sosumi: With plain ink I write / Apple's wisdom to machines— / Bridge-building autumn">
887
+ <span>素墨で書く</span>
888
+ <span>林檎の知恵を機械へ</span>
889
+ <span>橋渡す秋</span>
890
+ <figcaption>
891
+ <ruby>素墨<rt>そすみ</rt></ruby>
892
+ </figcaption>
893
+ </figure>
894
+ </aside>
895
+ </footer>
896
+ </body>
897
+
898
+ </html>