@tostudy-ai/mcp-setup 1.0.0

package/README.md

@@ -0,0 +1,149 @@
+# @tostudy-ai/mcp-setup
+
+CLI to configure Claude Code to connect to the Catalyst MCP server.
+
+## Installation
+
+```bash
+npx @tostudy-ai/mcp-setup
+```
+
+## Commands
+
+### Default Setup
+
+```bash
+npx @tostudy-ai/mcp-setup                        # Interactive setup
+npx @tostudy-ai/mcp-setup --api-key <key>         # Setup with API key
+npx @tostudy-ai/mcp-setup --url <url>             # Custom platform URL
+npx @tostudy-ai/mcp-setup --uninstall             # Remove configuration
+```
+
+### Wizard (Step-by-Step)
+
+```bash
+npx @tostudy-ai/mcp-setup wizard                  # Interactive wizard
+npx @tostudy-ai/mcp-setup wizard --api-key <key>  # Wizard with API key
+npx @tostudy-ai/mcp-setup wizard --url <url>      # Custom platform URL
+npx @tostudy-ai/mcp-setup wizard --skip-diagnostics  # Skip verification step
+npx @tostudy-ai/mcp-setup wizard --auto-repair    # Auto-fix detected issues
+```
+
+The wizard guides through 4 steps:
+1. Environment detection (Claude Code, IDEs)
+2. API key configuration and validation
+3. Save configuration
+4. Diagnostics and verification
+
+### Diagnose
+
+```bash
+npx @tostudy-ai/mcp-setup diagnose                # Run diagnostics
+npx @tostudy-ai/mcp-setup diagnose --json         # JSON output
+```
+
+Exits with code 1 if issues are found.
+
+### Repair
+
+```bash
+npx @tostudy-ai/mcp-setup repair                  # Auto-repair issues
+npx @tostudy-ai/mcp-setup repair --api-key <key>  # Repair with API key
+npx @tostudy-ai/mcp-setup repair --url <url>      # Custom platform URL
+npx @tostudy-ai/mcp-setup repair --json           # JSON output
+```
+
+### Install (Non-Interactive)
+
+Used by the web setup wizard to configure a specific IDE in a single command:
+
+```bash
+npx @tostudy-ai/mcp-setup install --ide <ide> --key <key>
+npx @tostudy-ai/mcp-setup install --ide cursor --key <key>
+npx @tostudy-ai/mcp-setup install --ide vscode --key <key> --url http://localhost:3700
+```
+
+Supported IDEs: `claude-code`, `cursor`, `vscode`, `desktop`, `opencode`, `manual`
+
+| IDE | Config Location | Config Key |
+|-----|----------------|------------|
+| `claude-code` | Terminal (`claude mcp add`) | N/A |
+| `cursor` | `~/.cursor/mcp.json` | `mcpServers` |
+| `vscode` | `.vscode/mcp.json` | `servers` |
+| `desktop` | Claude Desktop config | `mcpServers` |
+| `opencode` | `~/.opencode/opencode.json` | `mcp` |
+| `manual` | stdout (prints config) | N/A |
+
+Each handler reads-then-merges config to preserve other MCP servers.
+
+### Setup via Environment Variable
+
+```bash
+export TOSTUDY_API_KEY="your-api-key"
+export TOSTUDY_PLATFORM_URL="https://tostudy.com"  # optional
+npx @tostudy-ai/mcp-setup
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `TOSTUDY_API_KEY` | Platform API key | - |
+| `TOSTUDY_PLATFORM_URL` | Platform URL | `https://tostudy.com` |
+
+## Getting Your API Key
+
+1. Go to [tostudy.com/student/settings/mcp](https://tostudy.com/student/settings/mcp)
+2. The setup wizard auto-detects your OS
+3. Choose your IDE (step 2)
+4. An API key is generated automatically (step 3)
+5. Copy the `npx` command and run it in your terminal
+
+## What the CLI Does
+
+The CLI modifies the Claude Code configuration file:
+
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+Adds the following configuration:
+
+```json
+{
+  "mcpServers": {
+    "tostudy": {
+      "command": "npx",
+      "args": ["-y", "@tostudy-ai/mcp-server"],
+      "env": {
+        "TOSTUDY_API_KEY": "your-api-key",
+        "TOSTUDY_PLATFORM_URL": "https://tostudy.com"
+      }
+    }
+  }
+}
+```
+
+## After Setup
+
+1. Restart Claude Code
+2. The MCP server will start automatically
+3. Use `/courses` to see your enrolled courses
+
+## Scripts
+
+| Command | Description |
+|---------|-------------|
+| `pnpm build` | Build CLI |
+| `pnpm type-check` | TypeScript validation |
+| `pnpm test` | Run wizard e2e test |
+| `pnpm test:e2e` | Run shell e2e test |
+| `pnpm test:diagnostic-repair` | Run diagnostic/repair e2e test |
+| `pnpm test:ide-handlers` | Run IDE handler unit tests |
+| `pnpm test:install` | Run install command unit tests |
+| `pnpm test:all` | Run all tests |
+
+## Support
+
+- Documentation: [tostudy.com/docs/mcp](https://tostudy.com/docs/mcp)
+- Support: support@tostudy.com

package/bin/cli.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import('../dist/index.js').catch((err) => {
+  process.stderr.write(`Failed to load CLI: ${err.message}\n`);
+  process.exit(1);
+});

package/dist/__tests__/e2e-diagnostic-repair-flow.test.d.ts

@@ -0,0 +1,52 @@
+/**
+ * E2E Test: Diagnostic and Repair Flow
+ *
+ * This test verifies the end-to-end diagnostic and repair flow:
+ * 1. Simulate common issues (port conflict, missing config, invalid JSON, etc.)
+ * 2. Run mcp-setup diagnose command
+ * 3. Verify issue detected with clear description
+ * 4. Run mcp-setup repair command
+ * 5. Verify issue fixed and MCP configuration is valid
+ *
+ * NOTE: Port conflict tests require elevated permissions on some systems.
+ * Run with: npx tsx src/__tests__/e2e-diagnostic-repair-flow.test.ts
+ */
+/**
+ * Step 1: Test detection of missing config file
+ */
+declare function testMissingConfigDetection(): Promise<void>;
+/**
+ * Step 2: Test detection of invalid JSON config
+ */
+declare function testInvalidJsonDetection(): Promise<void>;
+/**
+ * Step 3: Test detection of missing MCP configuration
+ */
+declare function testMissingMcpConfigDetection(): Promise<void>;
+/**
+ * Step 4: Test detection of API key issues
+ */
+declare function testApiKeyIssuesDetection(): Promise<void>;
+/**
+ * Step 5: Test detection of server URL issues
+ */
+declare function testServerUrlIssuesDetection(): Promise<void>;
+/**
+ * Step 6: Test detection of duplicate servers
+ */
+declare function testDuplicateServersDetection(): Promise<void>;
+/**
+ * Step 7: Test port conflict detection
+ */
+declare function testPortConflictDetection(): Promise<void>;
+/**
+ * Step 8: Complete diagnostic and repair flow
+ */
+declare function testCompleteFlow(): Promise<void>;
+/**
+ * Step 9: Test issue helper functions
+ */
+declare function testHelperFunctions(): Promise<void>;
+declare function main(): Promise<void>;
+export { testMissingConfigDetection, testInvalidJsonDetection, testMissingMcpConfigDetection, testApiKeyIssuesDetection, testServerUrlIssuesDetection, testDuplicateServersDetection, testPortConflictDetection, testCompleteFlow, testHelperFunctions, main as runDiagnosticRepairE2ETests, };
+//# sourceMappingURL=e2e-diagnostic-repair-flow.test.d.ts.map

package/dist/__tests__/e2e-diagnostic-repair-flow.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"e2e-diagnostic-repair-flow.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/e2e-diagnostic-repair-flow.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA2RH;;GAEG;AACH,iBAAe,0BAA0B,IAAI,OAAO,CAAC,IAAI,CAAC,CAuCzD;AAED;;GAEG;AACH,iBAAe,wBAAwB,IAAI,OAAO,CAAC,IAAI,CAAC,CA4CvD;AAED;;GAEG;AACH,iBAAe,6BAA6B,IAAI,OAAO,CAAC,IAAI,CAAC,CA0C5D;AAED;;GAEG;AACH,iBAAe,yBAAyB,IAAI,OAAO,CAAC,IAAI,CAAC,CAkDxD;AAED;;GAEG;AACH,iBAAe,4BAA4B,IAAI,OAAO,CAAC,IAAI,CAAC,CAwD3D;AAED;;GAEG;AACH,iBAAe,6BAA6B,IAAI,OAAO,CAAC,IAAI,CAAC,CAoC5D;AAED;;GAEG;AACH,iBAAe,yBAAyB,IAAI,OAAO,CAAC,IAAI,CAAC,CAmCxD;AAED;;GAEG;AACH,iBAAe,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAoF/C;AAED;;GAEG;AACH,iBAAe,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CA4ElD;AAsCD,iBAAe,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAwCnC;AAQD,OAAO,EACL,0BAA0B,EAC1B,wBAAwB,EACxB,6BAA6B,EAC7B,yBAAyB,EACzB,4BAA4B,EAC5B,6BAA6B,EAC7B,yBAAyB,EACzB,gBAAgB,EAChB,mBAAmB,EACnB,IAAI,IAAI,2BAA2B,GACpC,CAAC"}