mcp-auth-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 milisp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# MCP Auth Core
+
+Universal Authentication for MCP Servers - The standard that everyone should follow.
+
+A lightweight, modular authentication library that provides OAuth2 support for popular providers like Google, GitHub, Slack, and Microsoft.
+
+## Installation
+
+```bash
+npm install mcp-auth-core
+```
+
+## Quick Start
+
+```typescript
+import { MCPAuth, PROVIDERS } from 'mcp-auth-core';
+
+// Create auth instance
+const auth = new MCPAuth();
+
+// Register a service with Google OAuth
+auth.registerService('my-app', {
+  clientId: 'your-google-client-id',
+  clientSecret: 'your-google-client-secret',
+  redirectUri: 'http://localhost:3000/callback',
+  scopes: ['profile', 'email'],
+  provider: PROVIDERS.google
+});
+
+// Get authorization URL
+const authUrl = auth.getAuthUrl('my-app');
+console.log('Visit this URL to authorize:', authUrl);
+
+// Handle callback (in your server)
+const token = await auth.handleCallback('my-app', authorizationCode);
+
+// Make authenticated requests
+const response = await auth.makeRequest('my-app', userId, 'https://api.example.com/data');
+```
+
+## Supported Providers
+
+- **Google** - Full OAuth2 support with user info
+- **GitHub** - OAuth2 with user profile
+- **Slack** - OAuth2 for Slack apps
+- **Microsoft** - Azure AD OAuth2
+
+## Highlights
+
+🎯 **MCP-Auth: The Universal Standard**
+
+✅ No more custom OAuth for each service  
+✅ Automatic token refresh  
+✅ Secure storage  
+✅ Easy service integration  
+✅ One API to rule them all
+
+## Features
+
+- 🔐 **OAuth2 Support** - Complete OAuth2 flow implementation
+- 🔄 **Token Refresh** - Automatic token refresh when expired
+- 💾 **Flexible Storage** - Customizable token storage
+- 🏗️ **Modular Design** - Easy to extend with custom providers
+- 📦 **TypeScript** - Full TypeScript support with types
+- 🌐 **Universal** - Works in Node.js and browser environments
+
+## API Reference
+
+### MCPAuth Class
+
+The main authentication class that handles OAuth flows.
+
+#### Constructor
+```typescript
+new MCPAuth(storage?: AuthStorage)
+```
+
+#### Methods
+
+- `registerService(serviceId: string, config: MCPAuthConfig)` - Register a service configuration
+- `getAuthUrl(serviceId: string, state?: string)` - Get authorization URL
+- `handleCallback(serviceId: string, code: string)` - Handle OAuth callback
+- `getToken(serviceId: string, userId: string)` - Get valid access token
+- `makeRequest(serviceId: string, userId: string, url: string, options?)` - Make authenticated request
+
+### Types
+
+- `MCPAuthConfig` - Service configuration
+- `AuthToken` - Token information
+- `AuthProvider` - OAuth provider configuration
+- `AuthStorage` - Storage interface for tokens
+
+## Examples
+
+See the `examples/` directory for complete usage examples.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { MCPAuth } from './mcp-auth';
+export type { MCPAuthConfig, AuthToken, AuthProvider, AuthStorage, } from './types';
+export { PROVIDERS } from './providers';
+export { PROVIDERS as providers } from './providers';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAGrC,YAAY,EACV,aAAa,EACb,SAAS,EACT,YAAY,EACZ,WAAW,GACZ,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,OAAO,EAAE,SAAS,IAAI,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+// MCP-Auth: Universal Authentication for MCP Servers
+// The standard that everyone should follow
+// Export main class
+export { MCPAuth } from './mcp-auth';
+// Export built-in providers
+export { PROVIDERS } from './providers';
+// Re-export providers for convenience
+export { PROVIDERS as providers } from './providers';

package/dist/mcp-auth.d.ts

@@ -0,0 +1,19 @@
+import type { MCPAuthConfig, AuthToken, AuthStorage } from './types';
+export declare class MCPAuth {
+    private storage?;
+    private tokens;
+    private configs;
+    constructor(storage?: AuthStorage | undefined);
+    registerService(serviceId: string, config: MCPAuthConfig): void;
+    getAuthUrl(serviceId: string, state?: string): string;
+    handleCallback(serviceId: string, code: string): Promise<AuthToken>;
+    getToken(serviceId: string, userId: string): Promise<string>;
+    makeRequest(serviceId: string, userId: string, url: string, options?: RequestInit): Promise<Response>;
+    private refreshToken;
+    private exchangeCodeForToken;
+    private getUserId;
+    private generateState;
+    private loadTokens;
+    private saveTokens;
+}
+//# sourceMappingURL=mcp-auth.d.ts.map

package/dist/mcp-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-auth.d.ts","sourceRoot":"","sources":["../src/mcp-auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAErE,qBAAa,OAAO;IAIN,OAAO,CAAC,OAAO,CAAC;IAH5B,OAAO,CAAC,MAAM,CAAqC;IACnD,OAAO,CAAC,OAAO,CAAyC;gBAEpC,OAAO,CAAC,EAAE,WAAW,YAAA;IAKzC,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa;IAKxD,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM;IAgB/C,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAqBnE,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAmB5D,WAAW,CACf,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,QAAQ,CAAC;YAYN,YAAY;YA+BZ,oBAAoB;YAqBpB,SAAS;IAcvB,OAAO,CAAC,aAAa;YAIP,UAAU;YAcV,UAAU;CAMzB"}

package/dist/mcp-auth.js

@@ -0,0 +1,140 @@
+export class MCPAuth {
+    constructor(storage) {
+        this.storage = storage;
+        this.tokens = new Map();
+        this.configs = new Map();
+        this.loadTokens();
+    }
+    // Register a service configuration
+    registerService(serviceId, config) {
+        this.configs.set(serviceId, config);
+    }
+    // Get authorization URL - this is what the user clicks
+    getAuthUrl(serviceId, state) {
+        const config = this.configs.get(serviceId);
+        if (!config)
+            throw new Error(`Service ${serviceId} not configured`);
+        const params = new URLSearchParams({
+            client_id: config.clientId,
+            redirect_uri: config.redirectUri,
+            scope: config.scopes.join(" "),
+            response_type: "code",
+            state: state || this.generateState(),
+        });
+        return `${config.provider.authUrl}?${params.toString()}`;
+    }
+    // Handle the callback after user authorizes
+    async handleCallback(serviceId, code) {
+        const config = this.configs.get(serviceId);
+        if (!config)
+            throw new Error(`Service ${serviceId} not configured`);
+        const tokenData = await this.exchangeCodeForToken(config, code);
+        const token = {
+            accessToken: tokenData.access_token,
+            refreshToken: tokenData.refresh_token,
+            expiresAt: new Date(Date.now() + tokenData.expires_in * 1000),
+            scopes: config.scopes,
+            userId: await this.getUserId(config, tokenData.access_token),
+        };
+        const tokenKey = `${serviceId}:${token.userId}`;
+        this.tokens.set(tokenKey, token);
+        await this.saveTokens();
+        return token;
+    }
+    // Get valid token for a user and service
+    async getToken(serviceId, userId) {
+        const tokenKey = `${serviceId}:${userId}`;
+        let token = this.tokens.get(tokenKey);
+        if (!token) {
+            throw new Error(`No token found for ${serviceId}:${userId}`);
+        }
+        // Check if token is expired and refresh if needed
+        if (token.expiresAt < new Date() && token.refreshToken) {
+            token = await this.refreshToken(serviceId, token);
+            this.tokens.set(tokenKey, token);
+            await this.saveTokens();
+        }
+        return token.accessToken;
+    }
+    // Make authenticated request - this is the magic
+    async makeRequest(serviceId, userId, url, options = {}) {
+        const token = await this.getToken(serviceId, userId);
+        const headers = {
+            ...options.headers,
+            Authorization: `Bearer ${token}`,
+        };
+        return fetch(url, { ...options, headers });
+    }
+    // Refresh expired token
+    async refreshToken(serviceId, token) {
+        const config = this.configs.get(serviceId);
+        if (!config || !token.refreshToken) {
+            throw new Error("Cannot refresh token");
+        }
+        const response = await fetch(config.provider.tokenUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({
+                grant_type: "refresh_token",
+                refresh_token: token.refreshToken,
+                client_id: config.clientId,
+                client_secret: config.clientSecret || "",
+            }),
+        });
+        const tokenData = await response.json();
+        return {
+            ...token,
+            accessToken: tokenData.access_token,
+            refreshToken: tokenData.refresh_token || token.refreshToken,
+            expiresAt: new Date(Date.now() + tokenData.expires_in * 1000),
+        };
+    }
+    // Exchange authorization code for token
+    async exchangeCodeForToken(config, code) {
+        const response = await fetch(config.provider.tokenUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({
+                grant_type: "authorization_code",
+                code,
+                redirect_uri: config.redirectUri,
+                client_id: config.clientId,
+                client_secret: config.clientSecret || "",
+            }),
+        });
+        if (!response.ok) {
+            throw new Error(`Token exchange failed: ${response.statusText}`);
+        }
+        return response.json();
+    }
+    // Get user ID from provider
+    async getUserId(config, accessToken) {
+        if (!config.provider.userInfoUrl)
+            return "default";
+        const response = await fetch(config.provider.userInfoUrl, {
+            headers: { Authorization: `Bearer ${accessToken}` },
+        });
+        const userInfo = await response.json();
+        return userInfo.id || userInfo.login || userInfo.email || "default";
+    }
+    generateState() {
+        return Math.random().toString(36).substring(2, 15);
+    }
+    async loadTokens() {
+        if (this.storage) {
+            const saved = await this.storage.load();
+            if (saved) {
+                this.tokens = new Map(Object.entries(saved).map(([k, v]) => [
+                    k,
+                    { ...v, expiresAt: new Date(v.expiresAt) },
+                ]));
+            }
+        }
+    }
+    async saveTokens() {
+        if (this.storage) {
+            const toSave = Object.fromEntries(this.tokens.entries());
+            await this.storage.save(toSave);
+        }
+    }
+}

package/dist/providers.d.ts

@@ -0,0 +1,3 @@
+import type { AuthProvider } from './types';
+export declare const PROVIDERS: Record<string, AuthProvider>;
+//# sourceMappingURL=providers.d.ts.map

package/dist/providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../src/providers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAG5C,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CA0BlD,CAAC"}

package/dist/providers.js

@@ -0,0 +1,28 @@
+// Built-in providers - the ones everyone actually uses
+export const PROVIDERS = {
+    google: {
+        name: "Google",
+        authUrl: "https://accounts.google.com/o/oauth2/v2/auth",
+        tokenUrl: "https://oauth2.googleapis.com/token",
+        userInfoUrl: "https://www.googleapis.com/oauth2/v2/userinfo",
+        revokeUrl: "https://oauth2.googleapis.com/revoke",
+    },
+    github: {
+        name: "GitHub",
+        authUrl: "https://github.com/login/oauth/authorize",
+        tokenUrl: "https://github.com/login/oauth/access_token",
+        userInfoUrl: "https://api.github.com/user",
+    },
+    slack: {
+        name: "Slack",
+        authUrl: "https://slack.com/oauth/v2/authorize",
+        tokenUrl: "https://slack.com/api/oauth.v2.access",
+        userInfoUrl: "https://slack.com/api/auth.test",
+    },
+    microsoft: {
+        name: "Microsoft",
+        authUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
+        tokenUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/token",
+        userInfoUrl: "https://graph.microsoft.com/v1.0/me",
+    },
+};

package/dist/types.d.ts

@@ -0,0 +1,26 @@
+export interface MCPAuthConfig {
+    clientId: string;
+    clientSecret?: string;
+    redirectUri: string;
+    scopes: string[];
+    provider: AuthProvider;
+}
+export interface AuthToken {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt: Date;
+    scopes: string[];
+    userId: string;
+}
+export interface AuthProvider {
+    name: string;
+    authUrl: string;
+    tokenUrl: string;
+    userInfoUrl?: string;
+    revokeUrl?: string;
+}
+export interface AuthStorage {
+    save(tokens: Record<string, any>): Promise<void>;
+    load(): Promise<Record<string, any> | null>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,YAAY,CAAC;CACxB;AAED,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,IAAI,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAGD,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;CAC7C"}

package/dist/types.js

@@ -0,0 +1,3 @@
+// MCP-Auth: Universal Authentication for MCP Servers
+// Type definitions
+export {};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "mcp-auth-core",
+  "version": "0.1.0",
+  "description": "Universal Authentication for MCP Servers - The standard that everyone should follow",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "module": "dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "mcp",
+    "authentication",
+    "oauth",
+    "oauth2",
+    "auth",
+    "google",
+    "github",
+    "slack",
+    "microsoft"
+  ],
+  "author": "milisp",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/milisp/mcp-auth-core.git"
+  },
+  "bugs": {
+    "url": "https://github.com/milisp/mcp-auth-core/issues"
+  },
+  "homepage": "https://github.com/milisp/mcp-auth-core#readme",
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}