@nshipster/sosumi 1.0.8 → 1.1.0

package/README.md

@@ -86,6 +86,28 @@ you can run this command to proxy over stdio:
 
 See [the website](https://sosumi.ai/#clients) for client-specific instructions.
 
+#### Plugin
+
+The [`plugin`](plugin) folder packages the MCP server and the [agent skill](#ai-agent-skill)
+for Claude Code, Cursor, and [Agent Plugins](https://agent-plugins.org) clients
+such as ChatGPT and Codex.
+
+In Claude Code, run:
+
+```text
+/plugin marketplace add NSHipster/sosumi.ai
+/plugin install sosumi@sosumi-ai
+```
+
+`public/SKILL.md` is the source of the skill.
+After you edit it, copy it into the plugin:
+
+```bash
+cp public/SKILL.md plugin/skills/sosumi/SKILL.md
+```
+
+A test fails when the two files differ.
+
 #### Available Tools
 
 - `searchAppleDocumentation` - Searches Apple Developer documentation
@@ -334,6 +356,32 @@ Publishing is handled by `.github/workflows/release.yml`.
 - Release step: `gh release create "$TAG_NAME" --generate-notes`
 - Publish auth: npm trusted publishing via OIDC (`id-token: write`)
 - Publish command: `npm publish --provenance --access public`
+- MCP Registry: after `npm publish`, the workflow publishes `server.json`
+  to the [MCP Registry](https://registry.modelcontextprotocol.io)
+  as `ai.sosumi/sosumi`.
+
+Keep `version` in `server.json` equal to `version` in `package.json`;
+a test fails when they differ.
+
+The registry step uses
+[HTTP authentication](https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/authentication.mdx#http-authentication)
+for the `sosumi.ai` domain.
+It skips with a notice until the `MCP_REGISTRY_PRIVATE_KEY` secret is set.
+To set it up, generate an Ed25519 key pair with OpenSSL 3
+(macOS's LibreSSL does not support Ed25519):
+
+```bash
+openssl genpkey -algorithm Ed25519 -out key.pem
+# Public key: add to "vars" in wrangler.jsonc as MCP_REGISTRY_PUBLIC_KEY, then deploy
+openssl pkey -in key.pem -pubout -outform DER | tail -c 32 | base64
+# Private key (hex): save as the MCP_REGISTRY_PRIVATE_KEY repository secret
+openssl pkey -in key.pem -noout -text | grep -A3 "priv:" | tail -n +2 | tr -d ' :\n'
+```
+
+The Worker then serves `v=MCPv1; k=ed25519; p=<public key>`
+at `/.well-known/mcp-registry-auth`.
+Without the variable, that path returns 404.
+Delete `key.pem` after you save both values.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nshipster/sosumi",
-  "version": "1.0.8",
+  "version": "1.1.0",
   "description": "Making Apple docs AI-readable",
   "license": "MIT",
   "author": "NSHipster",

package/public/SKILL.md

@@ -85,6 +85,7 @@ Use these when Sosumi is configured as an MCP server (`https://sosumi.ai/mcp`):
 - Fetch targeted symbol pages for coding questions.
 - Keep source links in answers so users can verify details quickly.
 - Use Sosumi paths directly in responses whenever referencing Apple documentation pages.
+- Don't rely on conformance conditions, such as "Conforms when `Element` conforms to `Hashable`." Apple's documentation data leaves some out and gets some wrong. When a condition matters, read the declaration in the module's `.swiftinterface` file in the SDK.
 
 ## Troubleshooting
 

package/public/index.html

@@ -11,6 +11,8 @@
     <meta name="robots" content="index, follow">
 
     <link rel="canonical" href="https://sosumi.ai/">
+    <link rel="ard" href="/.well-known/ard.json" type="application/ai-catalog+json">
+    <link rel="ai-catalog" href="/.well-known/ai-catalog.json" type="application/ai-catalog+json">
 
     <meta property="og:title" content="sosumi.ai - Apple Docs for LLMs">
     <meta property="og:description"
@@ -179,6 +181,29 @@
             border: 1px solid var(--accent);
         }
 
+        .install-buttons {
+            display: flex;
+            flex-wrap: wrap;
+            gap: 0.75rem;
+        }
+
+        a.link-button {
+            display: inline-block;
+            padding: 0.375rem 0.875rem;
+            border-radius: 0.5rem;
+            border: 1px solid var(--border);
+            background: var(--surface);
+            color: var(--text);
+            font-weight: 500;
+            transition: border 0.2s;
+        }
+
+        a.link-button:hover {
+            color: var(--text);
+            text-decoration: none;
+            border-color: var(--accent);
+        }
+
         figure {
             margin: 0;
         }
@@ -724,7 +749,18 @@
 
                             <div class="tab-pane" id="vscode-tab">
                                 <h3>VSCode</h3>
-                                <p>Create a <code>.vscode/mcp.json</code> file in your workspace and enter the following
+                                <p>Click a button below to install the sosumi MCP server:</p>
+
+                                <p class="install-buttons">
+                                    <a class="link-button"
+                                        href="https://vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522sosumi%2522%252C%2522type%2522%253A%2522http%2522%252C%2522url%2522%253A%2522https%253A%252F%252Fsosumi.ai%252Fmcp%2522%257D">Install
+                                        in VS Code</a>
+                                    <a class="link-button"
+                                        href="https://vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522sosumi%2522%252C%2522type%2522%253A%2522http%2522%252C%2522url%2522%253A%2522https%253A%252F%252Fsosumi.ai%252Fmcp%2522%257D">Install
+                                        in VS Code Insiders</a>
+                                </p>
+
+                                <p>Or create a <code>.vscode/mcp.json</code> file in your workspace and enter the following
                                     configuration:</p>
 
                                 <pre><code class="mcp-config"><span class="dimmed"><span class="punctuation">{</span></span>
@@ -759,11 +795,17 @@
 
                             <div class="tab-pane" id="claude-code-tab">
                                 <h3>Claude Code</h3>
-                                <p>Run the following command in your terminal:</p>
+                                <p>Install the sosumi plugin, which adds the MCP server and the Sosumi skill.
+                                    Run these commands in Claude Code:</p>
+                                <pre><code>/plugin marketplace add NSHipster/sosumi.ai
+/plugin install sosumi@sosumi-ai</code></pre>
+                                <p>To add only the MCP server, run this command in your terminal:</p>
                                 <pre><code>claude mcp add --transport http sosumi https://sosumi.ai/mcp</code></pre>
-                                <p>For more information, see the
+                                <p>For more information, see the Claude Code documentation for
+                                    <a href="https://code.claude.com/docs/en/plugins/install"
+                                        rel="noopener noreferrer">plugins</a> and
                                     <a href="https://docs.anthropic.com/en/docs/claude-code/mcp"
-                                        rel="noopener noreferrer">Claude Code MCP documentation</a>.
+                                        rel="noopener noreferrer">MCP</a>.
                                 </p>
                             </div>
 
@@ -1041,6 +1083,11 @@ curl -o ~/.agents/skills/sosumi/SKILL.md https://sosumi.ai/SKILL.md</code></pre>
             <p>
                 <strong>Contact:</strong> <a href="mailto:info@sosumi.ai">info@sosumi.ai</a>
             </p>
+            <p>
+                <a href="/privacy">Privacy</a> ·
+                <a href="/terms">Terms</a> ·
+                <a href="/support">Support</a>
+            </p>
         </div>
 
         <aside>
@@ -1057,4 +1104,4 @@ curl -o ~/.agents/skills/sosumi/SKILL.md https://sosumi.ai/SKILL.md</code></pre>
     </footer>
 </body>
 
-</html>
+</html>

package/public/llms.txt

@@ -64,7 +64,12 @@ Open this deep link to automatically install the sosumi MCP server:
 
 ### VSCode
 
-Create a `.vscode/mcp.json` file in your workspace and enter the following configuration:
+Open one of these links to install the sosumi MCP server:
+
+- [Install in VS Code](https://vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522sosumi%2522%252C%2522type%2522%253A%2522http%2522%252C%2522url%2522%253A%2522https%253A%252F%252Fsosumi.ai%252Fmcp%2522%257D)
+- [Install in VS Code Insiders](https://vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522sosumi%2522%252C%2522type%2522%253A%2522http%2522%252C%2522url%2522%253A%2522https%253A%252F%252Fsosumi.ai%252Fmcp%2522%257D)
+
+Or create a `.vscode/mcp.json` file in your workspace and enter the following configuration:
 
 ```json
 {
@@ -88,7 +93,15 @@ Create a `.vscode/mcp.json` file in your workspace and enter the following confi
 
 ### Claude Code
 
-Run the following command in your terminal:
+Install the sosumi plugin, which adds the MCP server and the Sosumi skill.
+Run these commands in Claude Code:
+
+```text
+/plugin marketplace add NSHipster/sosumi.ai
+/plugin install sosumi@sosumi-ai
+```
+
+To add only the MCP server, run this command in your terminal:
 
 ```shell
 claude mcp add --transport http sosumi https://sosumi.ai/mcp
@@ -336,3 +349,5 @@ For external Swift-DocC hosts, sosumi honors `robots.txt` rules
 and opt-out response directives such as `X-Robots-Tag: noai`.
 
 **Contact:** <info@sosumi.ai>
+
+[Privacy](https://sosumi.ai/privacy) · [Terms](https://sosumi.ai/terms) · [Support](https://sosumi.ai/support)

package/public/page.css

@@ -0,0 +1,104 @@
+/* Shared styles for the policy pages. Colors and type match index.html. */
+:root {
+    color-scheme: light dark;
+
+    --font-sans: -apple-system, BlinkMacSystemFont, 'SF Pro Text', sans-serif;
+    --font-mono: 'SF Mono', monospace;
+
+    --text: oklch(15% 0 0);
+    --text-secondary: oklch(35% 0 0);
+    --text-tertiary: oklch(55% 0 0);
+
+    --surface: oklch(98% 0 0);
+    --surface-inset: oklch(95% 0.02 70);
+
+    --border: oklch(20% 0.1 70);
+
+    --link: oklch(65% 0.15 70);
+    --accent: oklch(78% 0.18 70);
+}
+
+@media (prefers-color-scheme: dark) {
+    :root {
+        --text: oklch(92% 0.02 70);
+        --text-secondary: oklch(75% 0.05 70);
+        --text-tertiary: oklch(55% 0.08 70);
+
+        --surface: oklch(18% 0 0);
+        --surface-inset: oklch(12% 0.02 70);
+
+        --border: oklch(25% 0.1 70);
+        --accent: oklch(85% 0.2 70);
+    }
+}
+
+body {
+    font-family: var(--font-sans);
+    color: var(--text);
+    background-color: var(--surface);
+    max-width: 52rem;
+    margin: 3rem auto;
+    padding: 1.5rem;
+    line-height: 1.6;
+}
+
+body > header {
+    margin-bottom: 2rem;
+}
+
+body > header p {
+    margin: 0;
+    font-size: 1.5rem;
+    font-weight: bold;
+}
+
+body > header a {
+    color: var(--text);
+}
+
+h1 {
+    font-size: 2.5rem;
+    margin-bottom: 0.25rem;
+}
+
+h2 {
+    margin-top: 2rem;
+    margin-bottom: 0.625rem;
+    color: var(--text-secondary);
+}
+
+.updated {
+    color: var(--text-tertiary);
+    margin-top: 0;
+}
+
+code {
+    background: var(--surface-inset);
+    padding: 0.125rem;
+    font-family: var(--font-mono);
+    overflow-wrap: break-word;
+}
+
+a {
+    color: var(--link);
+    text-decoration: none;
+    transition: color 0.2s ease;
+}
+
+a:hover {
+    color: var(--accent);
+    text-decoration: underline;
+}
+
+footer {
+    margin-top: 3.75rem;
+    padding-top: 1.25rem;
+    border-top: 1px solid var(--border);
+    color: var(--text-tertiary);
+    font-size: 0.875rem;
+}
+
+::selection {
+    background-color: var(--accent);
+    color: var(--surface);
+}

package/public/privacy.html

@@ -0,0 +1,111 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Privacy Policy - sosumi.ai</title>
+    <meta name="description" content="What sosumi.ai collects, who receives it, and how long it is kept.">
+    <link rel="canonical" href="https://sosumi.ai/privacy">
+    <meta name="theme-color" content="#d68d6e" media="(prefers-color-scheme: light)">
+    <meta name="theme-color" content="#ec9b7f" media="(prefers-color-scheme: dark)">
+    <link rel="icon" href="/favicon.svg" type="image/svg+xml">
+    <link rel="alternate icon" href="/favicon.ico">
+    <link rel="stylesheet" href="/page.css">
+</head>
+
+<body>
+    <header>
+        <p><a href="/">sosumi.ai</a></p>
+    </header>
+
+    <main>
+        <h1>Privacy Policy</h1>
+        <p class="updated">Last updated November 7, 2026</p>
+
+        <p>
+            Sosumi is a free service that converts Apple Developer documentation to Markdown.
+            It has no accounts, and it doesn't ask for your name, email address, or other personal information.
+            This page applies to the website, the HTTP API, and the MCP server at <code>https://sosumi.ai/mcp</code>.
+        </p>
+
+        <h2>What Sosumi keeps</h2>
+        <p>
+            Sosumi doesn't set cookies.
+            It doesn't have a database,
+            and it doesn't save the requests it receives or the pages it returns.
+        </p>
+        <p>
+            Sosumi runs on Cloudflare Workers with
+            <a href="https://developers.cloudflare.com/workers/observability/logs/workers-logs/" rel="noopener noreferrer">Workers Logs</a>
+            turned on.
+            For each request, Cloudflare logs the request's URL and other request and response details,
+            and it logs any errors that Sosumi reports.
+            A URL can include what you asked for, such as a documentation path or a search query.
+            Cloudflare keeps these logs for up to 7 days.
+            Sosumi's maintainers can read them to find and fix problems.
+        </p>
+
+        <h2>Who receives your requests</h2>
+        <p>
+            To answer a request, Sosumi's servers fetch the page from developer.apple.com
+            or send your search query to Apple's documentation search service.
+            For an external Swift-DocC page, Sosumi fetches from the host in the URL you give.
+            Those services receive the path, query, or URL from Sosumi's servers.
+            Sosumi makes these requests with its own headers.
+            It doesn't forward your IP address, cookies, or request headers.
+        </p>
+        <p>
+            When you use Sosumi through an MCP client or plugin,
+            your client sends Sosumi the tool's input,
+            such as a search query, documentation path, or URL.
+            Sosumi handles that input in the same way as any other request.
+        </p>
+        <p>
+            Responses include <code>Cache-Control</code> headers.
+            Cloudflare, your client, and proxies between you and Sosumi can keep a copy of a response
+            for as long as those headers allow.
+            For documentation and search responses, that is at most 24 hours.
+        </p>
+        <p>
+            The home page shows Cursor's install button images, which load from cursor.com.
+            When you view the home page, your browser requests those images from Cursor.
+        </p>
+        <p>
+            The <code>sosumi</code> command-line tool runs on your computer.
+            It fetches documentation directly from Apple and doesn't send requests to sosumi.ai.
+        </p>
+
+        <h2>Monitoring</h2>
+        <p>
+            A separate monitoring service checks that sosumi.ai works every 5 minutes.
+            It saves whether the last check passed.
+            When a check fails or recovers, it saves an alert email with the check's error message
+            until the email is sent to the maintainers.
+            It doesn't save anything about visitors.
+        </p>
+
+        <h2>Changes and questions</h2>
+        <p>
+            When this policy changes, the date at the top of this page changes too.
+            The page's history is public in the
+            <a href="https://github.com/NSHipster/sosumi.ai/commits/main/public/privacy.html" rel="noopener noreferrer">sosumi.ai repository</a>.
+            For questions, see <a href="/support">Support</a>.
+        </p>
+    </main>
+
+    <footer>
+        <p>
+            <a href="/privacy">Privacy</a> ·
+            <a href="/terms">Terms</a> ·
+            <a href="/support">Support</a> ·
+            <a href="https://github.com/NSHipster/sosumi.ai" rel="noopener noreferrer">GitHub</a>
+        </p>
+        <p>
+            Sosumi is an unofficial, independent project
+            and is not affiliated with or endorsed by Apple Inc.
+        </p>
+    </footer>
+</body>
+
+</html>

package/public/robots.txt

@@ -1,5 +1,6 @@
 User-agent: *
 Content-Signal: search=yes, ai-input=yes, ai-train=no
+Content-Usage: train-ai=n, search=y
 Allow: /
 Disallow: /documentation/
 Disallow: /external/
@@ -7,3 +8,4 @@ Disallow: /design/human-interface-guidelines
 Disallow: /videos/play/
 
 Sitemap: https://sosumi.ai/sitemap.xml
+Agentmap: https://sosumi.ai/.well-known/ard.json

package/public/sitemap.xml

@@ -3,4 +3,13 @@
   <url>
     <loc>https://sosumi.ai/</loc>
   </url>
+  <url>
+    <loc>https://sosumi.ai/privacy</loc>
+  </url>
+  <url>
+    <loc>https://sosumi.ai/terms</loc>
+  </url>
+  <url>
+    <loc>https://sosumi.ai/support</loc>
+  </url>
 </urlset>

package/public/support.html

@@ -0,0 +1,65 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Support - sosumi.ai</title>
+    <meta name="description" content="How to get help with sosumi.ai and report problems.">
+    <link rel="canonical" href="https://sosumi.ai/support">
+    <meta name="theme-color" content="#d68d6e" media="(prefers-color-scheme: light)">
+    <meta name="theme-color" content="#ec9b7f" media="(prefers-color-scheme: dark)">
+    <link rel="icon" href="/favicon.svg" type="image/svg+xml">
+    <link rel="alternate icon" href="/favicon.ico">
+    <link rel="stylesheet" href="/page.css">
+</head>
+
+<body>
+    <header>
+        <p><a href="/">sosumi.ai</a></p>
+    </header>
+
+    <main>
+        <h1>Support</h1>
+
+        <h2>Report a problem or ask a question</h2>
+        <p>
+            Open an issue on
+            <a href="https://github.com/NSHipster/sosumi.ai/issues" rel="noopener noreferrer">GitHub</a>.
+            Include the URL or MCP tool input that you used,
+            the client that you used (for example, Claude Code, Cursor, or ChatGPT),
+            and what you expected to see.
+        </p>
+
+        <h2>Contact</h2>
+        <p>
+            For anything you don't want to post in public, including security reports,
+            email <a href="mailto:info@sosumi.ai">info@sosumi.ai</a>.
+            This is the contact in
+            <a href="/.well-known/security.txt"><code>security.txt</code></a>.
+        </p>
+
+        <h2>Set up</h2>
+        <p>
+            Instructions for each MCP client, the command-line tool, and the agent skill are on the
+            <a href="/#mcp">home page</a>.
+            If your host serves Swift-DocC documentation and you want Sosumi to stop fetching it,
+            see <a href="/#bot">how Sosumi fetches pages</a>.
+        </p>
+    </main>
+
+    <footer>
+        <p>
+            <a href="/privacy">Privacy</a> ·
+            <a href="/terms">Terms</a> ·
+            <a href="/support">Support</a> ·
+            <a href="https://github.com/NSHipster/sosumi.ai" rel="noopener noreferrer">GitHub</a>
+        </p>
+        <p>
+            Sosumi is an unofficial, independent project
+            and is not affiliated with or endorsed by Apple Inc.
+        </p>
+    </footer>
+</body>
+
+</html>

package/public/terms.html

@@ -0,0 +1,73 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Terms of Use - sosumi.ai</title>
+    <meta name="description" content="The terms for using sosumi.ai.">
+    <link rel="canonical" href="https://sosumi.ai/terms">
+    <meta name="theme-color" content="#d68d6e" media="(prefers-color-scheme: light)">
+    <meta name="theme-color" content="#ec9b7f" media="(prefers-color-scheme: dark)">
+    <link rel="icon" href="/favicon.svg" type="image/svg+xml">
+    <link rel="alternate icon" href="/favicon.ico">
+    <link rel="stylesheet" href="/page.css">
+</head>
+
+<body>
+    <header>
+        <p><a href="/">sosumi.ai</a></p>
+    </header>
+
+    <main>
+        <h1>Terms of Use</h1>
+        <p class="updated">Last updated November 7, 2026</p>
+
+        <p>
+            These terms apply to the website, the HTTP API, and the MCP server at <code>https://sosumi.ai/mcp</code>.
+        </p>
+
+        <h2>The service</h2>
+        <p>
+            Sosumi is free to use.
+            It is provided "as is", without warranty of any kind.
+            It can change, slow down, or stop at any time, and its output can be incomplete or wrong.
+            Check important details against the original page, which each response links to.
+        </p>
+
+        <h2>The code</h2>
+        <p>
+            Sosumi's source code is available under the
+            <a href="https://github.com/NSHipster/sosumi.ai/blob/main/LICENSE.md" rel="noopener noreferrer">MIT license</a>.
+        </p>
+
+        <h2>The documentation</h2>
+        <p>
+            Documentation content belongs to its owners.
+            Apple Inc. owns the content of Apple Developer documentation,
+            the Human Interface Guidelines, and Apple's videos.
+            The owners of external Swift-DocC sites own their content.
+            Sosumi converts a page only when you request it, and it doesn't grant you any rights to that content.
+        </p>
+
+        <h2>Your use</h2>
+        <p>
+            Your use of Sosumi must comply with Apple's terms of use, the terms of any other site you request, and applicable law.
+        </p>
+    </main>
+
+    <footer>
+        <p>
+            <a href="/privacy">Privacy</a> ·
+            <a href="/terms">Terms</a> ·
+            <a href="/support">Support</a> ·
+            <a href="https://github.com/NSHipster/sosumi.ai" rel="noopener noreferrer">GitHub</a>
+        </p>
+        <p>
+            Sosumi is an unofficial, independent project
+            and is not affiliated with or endorsed by Apple Inc.
+        </p>
+    </footer>
+</body>
+
+</html>