@soundbi/sound-connect 0.1.0

package/README.md

@@ -0,0 +1,111 @@
+# Sound Connect Bridge
+
+Local stdio MCP server that connects Claude Desktop and Claude Code to your Sound Connect workspace.
+
+---
+
+## Quick start
+
+> **Important:** You must sign in **before** starting Claude. The bridge runs as a background process launched by Claude — its output is not visible to you, so a login prompt there would cause a silent hang. Always log in from a separate terminal first.
+
+### Step 1 — Install Node (if needed)
+
+The bridge requires Node.js 18 or later. Download from [nodejs.org](https://nodejs.org).
+
+### Step 2 — Sign in (terminal only)
+
+Open a terminal (not inside Claude) and run:
+
+```
+npx @soundbi/sound-connect login
+```
+
+You will see a URL and a short code. Open the URL in a browser, enter the code, and sign in with your Sound BI Microsoft account. When the terminal shows "Signed in as: ...", you are done.
+
+Your token is stored securely in the OS credential store (Windows Credential Manager / macOS Keychain). You only need to do this once — the bridge refreshes tokens silently on subsequent starts.
+
+### Step 3 — Configure Claude
+
+**Claude Code** — add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "sound-connect": {
+      "command": "npx",
+      "args": ["@soundbi/sound-connect"],
+      "env": {
+        "SC_BACKEND_URL": "https://<your-backend-url>",
+        "SC_CLIENT_SLUG": "<your-client-slug>"
+      }
+    }
+  }
+}
+```
+
+**Claude Desktop** — add to `claude_desktop_config.json` (location varies by OS):
+
+```json
+{
+  "mcpServers": {
+    "sound-connect": {
+      "command": "npx",
+      "args": ["@soundbi/sound-connect"],
+      "env": {
+        "SC_BACKEND_URL": "https://<your-backend-url>",
+        "SC_CLIENT_SLUG": "<your-client-slug>"
+      }
+    }
+  }
+}
+```
+
+Replace `<your-backend-url>` and `<your-client-slug>` with the values provided by your workspace admin.
+
+### Step 4 — Start Claude
+
+Start (or restart) Claude Desktop / reload the MCP server in Claude Code. The bridge will connect silently using your cached token.
+
+If you see the error `Not signed in — run 'npx @soundbi/sound-connect login' in a terminal`, go back to Step 2.
+
+---
+
+## Signing out
+
+To clear your stored token:
+
+```
+npx @soundbi/sound-connect logout
+```
+
+After signing out, run `login` again before your next Claude session.
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| Tools return "Not signed in" | Run `npx @soundbi/sound-connect login` in a terminal, then restart Claude |
+| Token expired after a long break | Run `npx @soundbi/sound-connect login` again |
+| Wrong account signed in | Run `logout`, then `login` with the correct account |
+| Bridge not showing in Claude | Check that `SC_BACKEND_URL` and `SC_CLIENT_SLUG` are set correctly in your config |
+
+---
+
+## Configuration reference
+
+| Variable | CLI arg | Required | Description |
+|---|---|---|---|
+| `SC_BACKEND_URL` | `--backend-url` | Yes | Base URL of the Sound Connect backend |
+| `SC_CLIENT_SLUG` | `--client-slug` | Yes | Your client workspace identifier |
+| `SC_ENTRA_CLIENT_ID` | — | No | Override the Entra app registration client ID |
+| `SC_AUTH_SCOPE` | — | No | Override the OAuth scope (default: `api://sound-connect/.default`) |
+
+---
+
+## Why is login a separate command?
+
+Claude launches the bridge as a background stdio process. The MCP protocol uses the process's stdout for message framing — anything else written to stdout (including a browser login prompt) is never shown to you. Running the device-code flow inside the Claude-spawned process would cause a silent hang that looks like "it doesn't work."
+
+The solution: `login` is always a separate terminal command you run once. After that, every Claude session authenticates silently from the cached token.

package/dist/__tests__/ingest.test.d.ts

@@ -0,0 +1,18 @@
+/**
+ * STORY-011 / STORY-012 — ingest_file / ingest_folder unit tests.
+ *
+ * Tests the pure logic functions in src/ingest.ts:
+ *   - validateAndResolvePath: path confinement and extension check (AC3)
+ *   - normalizeMarkdown: normalization (AC1)
+ *   - chunkContent: chunking (AC1)
+ *   - sha256: hash computation (AC2)
+ *   - sourceTypeForExt: source_type derivation (STORY-012 AC2)
+ *   - parseGlobToExtensions: glob filter parsing (STORY-012 AC1)
+ *   - enumerateFolder: folder file enumeration (STORY-012 AC1)
+ *   - ingestFolder: full folder ingest pipeline with mocked backend (STORY-012)
+ *
+ * Network-touching code (postChunk / ingestMarkdownFile / ingestFolder) is tested
+ * via fetch mocks rather than live backend calls.
+ */
+export {};
+//# sourceMappingURL=ingest.test.d.ts.map

package/dist/__tests__/ingest.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/ingest.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG"}