{"_id":"@authjoyio/mcp-server","name":"@authjoyio/mcp-server","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@authjoyio/mcp-server","version":"0.1.0","description":"Model Context Protocol server for AuthJoy authentication","type":"module","main":"./dist/index.js","bin":{"authjoy-mcp":"dist/index.js"},"scripts":{"build":"tsc","dev":"tsx src/index.ts","start":"node dist/index.js","type-check":"tsc --noEmit"},"keywords":["mcp","model-context-protocol","authentication","authjoy","ai-tools"],"author":"","license":"MIT","repository":{"type":"git","url":"git+https://github.com/Emberfield/authjoy.git","directory":"packages/mcp-server"},"publishConfig":{"access":"public"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.4","axios":"^1.6.5","dotenv":"^16.4.0","zod":"^3.22.4"},"devDependencies":{"@types/node":"^20.11.5","tsx":"^4.7.0","typescript":"^5.3.3"},"_id":"@authjoyio/mcp-server@0.1.0","gitHead":"42732438cd3961c1f24487872bb1b9d9b081ee43","types":"./dist/index.d.ts","bugs":{"url":"https://github.com/Emberfield/authjoy/issues"},"homepage":"https://github.com/Emberfield/authjoy#readme","_nodeVersion":"22.16.0","_npmVersion":"11.4.1","dist":{"integrity":"sha512-bk5EvmDyCLrzxCBoNSUEBYpQQwdvxniBZ1ZoceK/lwmItKuZMk+QNuhytYxGzSWFT9XRa+hzPAM9rLHkxu8MJQ==","shasum":"f286b84534d47cf829f7905d0deaf2296899a454","tarball":"https://registry.npmjs.org/@authjoyio/mcp-server/-/mcp-server-0.1.0.tgz","fileCount":6,"unpackedSize":38726,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCID85gMizr133v4SXhKJKqvvjT/S8wDeJ4pCYrO5Mm1k2AiAJeyR+6bCERGzu1/WgISsMbvQtmkDQXKLvxRpxbL+/fA=="}]},"_npmUser":{"name":"agentfactor","email":"cal@agentfactor.io"},"directories":{},"maintainers":[{"name":"agentfactor","email":"cal@agentfactor.io"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-server_0.1.0_1766080254639_0.32867939560503623"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-18T17:50:54.509Z","0.1.0":"2025-12-18T17:50:54.788Z","modified":"2025-12-18T17:50:55.143Z"},"maintainers":[{"name":"agentfactor","email":"cal@agentfactor.io"}],"description":"Model Context Protocol server for AuthJoy authentication","homepage":"https://github.com/Emberfield/authjoy#readme","keywords":["mcp","model-context-protocol","authentication","authjoy","ai-tools"],"repository":{"type":"git","url":"git+https://github.com/Emberfield/authjoy.git","directory":"packages/mcp-server"},"bugs":{"url":"https://github.com/Emberfield/authjoy/issues"},"license":"MIT","readme":"# AuthJoy MCP Server\n\n**Model Context Protocol server for AuthJoy authentication**\n\nExpose AuthJoy's powerful authentication API as tools for AI coding agents like Claude, enabling them to perform authentication operations programmatically.\n\n---\n\n## 🎯 What is This?\n\nThe AuthJoy MCP Server implements the [Model Context Protocol](https://modelcontextprotocol.io/) to expose AuthJoy's authentication capabilities as tools that AI agents can use. This allows Claude (and other MCP-compatible AI assistants) to:\n\n- Register new users\n- Authenticate users\n- Manage passwords\n- Enable/disable MFA\n- Handle sessions\n- Send magic links\n- Generate social OAuth URLs\n- ...and more!\n\n---\n\n## 🚀 Quick Start\n\n### 1. Installation\n\n```bash\ncd packages/mcp-server\npnpm install\n```\n\n### 2. Configuration\n\nCreate a `.env` file:\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env` with your AuthJoy credentials:\n\n```env\nAUTHJOY_API_URL=http://localhost:3000\nAUTHJOY_TENANT_ID=your-tenant-id\nAUTHJOY_API_KEY=aj_live_xxxxxxxxxx\n```\n\n### 3. Build\n\n```bash\npnpm build\n```\n\n### 4. Test Locally\n\n```bash\npnpm dev\n```\n\n---\n\n## 🔌 Integration with Claude Desktop\n\n### Install in Claude Desktop\n\nAdd this configuration to your Claude Desktop config file:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"authjoy\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/authjoy/packages/mcp-server/dist/index.js\"],\n      \"env\": {\n        \"AUTHJOY_API_URL\": \"http://localhost:3000\",\n        \"AUTHJOY_TENANT_ID\": \"your-tenant-id\",\n        \"AUTHJOY_API_KEY\": \"your-api-key\"\n      }\n    }\n  }\n}\n```\n\n**Or use the dev version (no build required):**\n\n```json\n{\n  \"mcpServers\": {\n    \"authjoy\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"tsx\", \"/absolute/path/to/authjoy/packages/mcp-server/src/index.ts\"],\n      \"env\": {\n        \"AUTHJOY_API_URL\": \"http://localhost:3000\",\n        \"AUTHJOY_TENANT_ID\": \"your-tenant-id\",\n        \"AUTHJOY_API_KEY\": \"your-api-key\"\n      }\n    }\n  }\n}\n```\n\n### Restart Claude Desktop\n\nAfter updating the config, restart Claude Desktop for changes to take effect.\n\n---\n\n## 🛠️ Available Tools\n\nThe MCP server exposes these authentication tools:\n\n### User Management\n\n#### `user_signup`\nRegister a new user account.\n\n**Parameters:**\n- `email` (string, required) - User email address\n- `password` (string, required) - Password (min 8 chars)\n- `displayName` (string, optional) - Display name\n- `sendEmailVerification` (boolean, optional) - Send verification email\n\n**Example:**\n```\nUse the user_signup tool to create a new account for test@example.com\n```\n\n#### `user_signin`\nAuthenticate a user with email/password.\n\n**Parameters:**\n- `email` (string, required) - User email\n- `password` (string, required) - User password\n\n**Example:**\n```\nSign in the user test@example.com with password \"secret123\"\n```\n\n#### `user_get`\nGet user profile information.\n\n**Parameters:**\n- `userId` (string, required) - User ID or UID\n\n#### `user_update`\nUpdate user profile.\n\n**Parameters:**\n- `userId` (string, required) - User ID\n- `displayName` (string, optional) - New display name\n- `photoURL` (string, optional) - New photo URL\n\n#### `user_delete`\nDelete a user account.\n\n**Parameters:**\n- `userId` (string, required) - User ID\n\n---\n\n### Password Management\n\n#### `password_reset_request`\nRequest a password reset email.\n\n**Parameters:**\n- `email` (string, required) - User email address\n\n**Example:**\n```\nSend a password reset email to test@example.com\n```\n\n#### `password_reset_confirm`\nComplete password reset with token.\n\n**Parameters:**\n- `token` (string, required) - Reset token from email\n- `newPassword` (string, required) - New password (min 8 chars)\n\n#### `password_update`\nUpdate password for authenticated user.\n\n**Parameters:**\n- `userId` (string, required) - User ID\n- `currentPassword` (string, required) - Current password\n- `newPassword` (string, required) - New password (min 8 chars)\n\n---\n\n### Multi-Factor Authentication (MFA)\n\n#### `mfa_enroll`\nEnroll user in MFA (returns QR code for TOTP).\n\n**Parameters:**\n- `userId` (string, required) - User ID\n- `method` (string, optional) - Method: 'totp', 'sms', or 'email' (default: 'totp')\n\n**Example:**\n```\nEnroll user-123 in TOTP multi-factor authentication\n```\n\n#### `mfa_verify`\nVerify MFA code.\n\n**Parameters:**\n- `userId` (string, required) - User ID\n- `code` (string, required) - 6-digit MFA code\n- `enrollmentId` (string, optional) - Enrollment ID if verifying enrollment\n\n**Example:**\n```\nVerify MFA code 123456 for user-123\n```\n\n#### `mfa_unenroll`\nDisable MFA for a user.\n\n**Parameters:**\n- `userId` (string, required) - User ID\n\n---\n\n### Session Management\n\n#### `session_list`\nList all active sessions for a user.\n\n**Parameters:**\n- `userId` (string, required) - User ID\n\n**Example:**\n```\nShow me all active sessions for user-123\n```\n\n#### `session_revoke`\nRevoke a specific session.\n\n**Parameters:**\n- `sessionId` (string, required) - Session ID to revoke\n\n#### `session_revoke_all`\nSign out user from all devices.\n\n**Parameters:**\n- `userId` (string, required) - User ID\n\n**Example:**\n```\nSign out user-123 from all devices\n```\n\n---\n\n### Passwordless Authentication\n\n#### `magic_link_send`\nSend a magic link (passwordless login) email.\n\n**Parameters:**\n- `email` (string, required) - User email address\n- `redirectUrl` (string, optional) - Redirect URL after auth\n\n**Example:**\n```\nSend a magic link to test@example.com\n```\n\n#### `social_auth_url`\nGet OAuth URL for social authentication.\n\n**Parameters:**\n- `provider` (string, required) - Provider: 'google', 'github', 'facebook', 'twitter', 'microsoft'\n- `redirectUrl` (string, optional) - Redirect URL after auth\n\n**Example:**\n```\nGet Google OAuth sign-in URL\n```\n\n---\n\n## 💬 Example Conversations with Claude\n\nOnce configured, you can interact with AuthJoy through Claude:\n\n### Example 1: User Registration\n```\nYou: Create a new user account with email john@example.com and password SecurePass123\n\nClaude: I'll create a new user account using the AuthJoy MCP server.\n[Uses user_signup tool]\n✓ Successfully created user account for john@example.com\nUser ID: user-abc123\nEmail verified: false\n```\n\n### Example 2: Enable MFA\n```\nYou: Enable TOTP multi-factor authentication for user user-abc123\n\nClaude: I'll enroll this user in TOTP-based MFA.\n[Uses mfa_enroll tool]\n✓ MFA enrollment successful!\nQR Code: [displays QR code URL]\nSecret: JBSWY3DPEHPK3PXP\nBackup codes: [list of 10 codes]\n\nScan the QR code with Google Authenticator or Authy to complete setup.\n```\n\n### Example 3: Session Management\n```\nYou: Show me all active sessions for user user-abc123 and sign them out from all devices\n\nClaude: I'll first list the active sessions, then revoke them all.\n[Uses session_list tool]\nFound 3 active sessions:\n- Session 1: Chrome on macOS (last active 5 mins ago)\n- Session 2: Firefox on Windows (last active 2 hours ago)\n- Session 3: Mobile Safari on iOS (last active 1 day ago)\n\n[Uses session_revoke_all tool]\n✓ All sessions revoked. User has been signed out from all devices.\n```\n\n### Example 4: Password Reset Flow\n```\nYou: User forgot their password. Email is jane@example.com\n\nClaude: I'll send a password reset email.\n[Uses password_reset_request tool]\n✓ Password reset email sent to jane@example.com\nCheck your inbox for the reset link (valid for 1 hour).\n```\n\n---\n\n## 🧪 Testing with MCP Inspector\n\nUse the official MCP Inspector to test your server:\n\n```bash\nnpx @modelcontextprotocol/inspector node dist/index.js\n```\n\nThis opens a web interface where you can:\n- View all available tools\n- Test tool calls interactively\n- See request/response payloads\n- Debug errors\n\n---\n\n## 🔧 Development\n\n### Project Structure\n\n```\npackages/mcp-server/\n├── src/\n│   └── index.ts          # Main MCP server implementation\n├── dist/                 # Compiled JavaScript\n├── package.json          # Dependencies & scripts\n├── tsconfig.json         # TypeScript configuration\n├── .env.example          # Example environment variables\n└── README.md             # This file\n```\n\n### Build\n\n```bash\npnpm build\n```\n\n### Development Mode (with auto-reload)\n\n```bash\npnpm dev\n```\n\n### Type Checking\n\n```bash\npnpm type-check\n```\n\n---\n\n## 📚 Resources\n\n- **MCP Specification**: https://modelcontextprotocol.io/\n- **MCP TypeScript SDK**: https://github.com/modelcontextprotocol/typescript-sdk\n- **MCP Inspector**: https://modelcontextprotocol.io/docs/tools/inspector\n- **AuthJoy API Docs**: `../api/docs/API_REFERENCE.md`\n\n---\n\n## 🔐 Security Considerations\n\n### API Key Protection\n- **Never commit** `.env` file to version control\n- Use environment variables in production\n- Rotate API keys regularly\n\n### Permissions\n- MCP server has **full access** to AuthJoy API\n- Only give Claude access to MCP server in trusted environments\n- Consider creating a separate tenant for testing\n\n### Rate Limiting\n- AuthJoy API has rate limits per endpoint\n- MCP server respects these limits\n- High-frequency operations may be throttled\n\n---\n\n## 🐛 Troubleshooting\n\n### \"AUTHJOY_TENANT_ID and AUTHJOY_API_KEY must be set\"\n**Solution**: Create `.env` file with valid credentials\n\n### \"Connection refused\" or \"Network error\"\n**Solution**: Ensure AuthJoy API is running at the configured URL\n\n### Claude doesn't see the tools\n**Solution**:\n1. Restart Claude Desktop after config changes\n2. Check absolute paths in config are correct\n3. View Claude logs: `~/Library/Logs/Claude/mcp*.log` (macOS)\n\n### Tool calls fail with 401 Unauthorized\n**Solution**: Verify API key is correct and has proper permissions\n\n---\n\n## 📝 License\n\nMIT\n\n---\n\n## 🤝 Contributing\n\nContributions welcome! Please check the main AuthJoy repository for contribution guidelines.\n\n---\n\n**Built with ❤️ using the Model Context Protocol**\n","readmeFilename":"README.md","_rev":"1-c631179bb58d8eaa1e2ed9cba9e9d303"}