refactor, improve docs
This commit is contained in:
Basil Hosmer
parent
dc6c2a00e9
commit
112997d352
1 changed files with 30079 additions and 1640 deletions
135
embedded-oauth/README.md
Normal file
135
embedded-oauth/README.md
Normal file
|
|
@ -0,0 +1,135 @@
|
|||
# Embedded OAuth - MCP Feature Reference Server
|
||||
|
||||
This is a **complete, standalone implementation** of an MCP server with self-hosted OAuth authentication. Everything you need is in this directory.
|
||||
|
||||
## Overview
|
||||
|
||||
Per the [MCP specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization), "the authorization server may be hosted with the resource server." This mode demonstrates a self-hosted OAuth 2.1 authorization server running in the same process as the MCP server.
|
||||
|
||||
**Pattern demonstrated**: OAuth server that delegates user authentication to an upstream identity provider (corporate SSO, LDAP, Active Directory).
|
||||
|
||||
**Real-world use case**: Enterprise deployments that need control over OAuth token issuance while leveraging existing corporate identity infrastructure.
|
||||
|
||||
For the OAuth-as-a-Service pattern (using Auth0/Okta directly), see [external-oauth](../external-oauth/README.md).
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# 1. Make sure Redis is running (from repo root)
|
||||
docker compose up -d
|
||||
|
||||
# 2. Install dependencies (if not already done)
|
||||
npm install
|
||||
|
||||
# 3. Start the server
|
||||
npm run dev
|
||||
|
||||
# 4. Test with MCP Inspector
|
||||
npx -y @modelcontextprotocol/inspector
|
||||
# Connect to: http://localhost:3232/mcp
|
||||
```
|
||||
|
||||
## Available Commands
|
||||
|
||||
```bash
|
||||
npm run dev # Start with hot reload
|
||||
npm run dev:break # Start with debugger
|
||||
npm run build # Build to dist/
|
||||
npm start # Run built version
|
||||
npm test # Run 85 unit tests
|
||||
npm run lint # Lint code
|
||||
npm run typecheck # Check types
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Environment variables are in `.env`:
|
||||
```bash
|
||||
BASE_URI=http://localhost:3232
|
||||
PORT=3232
|
||||
REDIS_URL=redis://localhost:6379
|
||||
```
|
||||
|
||||
## What This Demonstrates
|
||||
|
||||
**OAuth + MCP integration**:
|
||||
- Self-hosted OAuth 2.1 server with PKCE
|
||||
- Upstream identity provider delegation (simulated via `/mock-upstream-idp/*`)
|
||||
- Complete authorization flow in one codebase
|
||||
|
||||
**MCP features**:
|
||||
- Tools (7), resources (100), prompts (3), sampling, logging, completions
|
||||
- Streamable HTTP and SSE transports
|
||||
- Redis-backed horizontal scaling
|
||||
- Session isolation and user ownership
|
||||
|
||||
## Understanding the Upstream Delegation Pattern
|
||||
|
||||
This implementation demonstrates a common enterprise OAuth pattern:
|
||||
|
||||
```
|
||||
MCP Client This Server Simulated Upstream
|
||||
│ │ │
|
||||
│──1. /authorize───────────────>│ │
|
||||
│<───(show auth page)───────────│ │
|
||||
│ │ │
|
||||
│──2. Click "Continue"──────────>│ │
|
||||
│<──redirect /mock-upstream-idp─│ │
|
||||
│ │ │
|
||||
│──3. /mock-upstream-idp/authorize──────────────────────────────>│
|
||||
│<──(show user selection)───────────────────────────────────────│
|
||||
│──4. Select user───────────────────────────────────────────────>│
|
||||
│<──redirect with userId────────────────────────────────────────│
|
||||
│ │ │
|
||||
│──5. /mock-upstream-idp/callback──>│ │
|
||||
│ │──(validate userId) │
|
||||
│ │──(issue MCP tokens) │
|
||||
│<──redirect with auth code─────│ │
|
||||
│ │ │
|
||||
│──6. /token (exchange code)────>│ │
|
||||
│<──MCP access token────────────│ │
|
||||
```
|
||||
|
||||
**In production**, `/mock-upstream-idp/*` would be replaced by corporate SSO (Okta, Azure AD, etc.).
|
||||
|
||||
## Code Organization
|
||||
|
||||
```
|
||||
src/
|
||||
├── index.ts # Main entry point (MCP + OAuth + routing)
|
||||
├── auth/
|
||||
│ ├── provider.ts # FeatureReferenceAuthProvider (OAuth server logic)
|
||||
│ └── auth-core.ts # Token generation, PKCE utilities
|
||||
├── services/
|
||||
│ ├── mcp.ts # MCP server with all features
|
||||
│ ├── auth.ts # Auth service wrappers
|
||||
│ ├── redis-auth.ts # Redis auth operations
|
||||
│ └── redisTransport.ts # Redis-backed transport
|
||||
├── handlers/
|
||||
│ ├── shttp.ts # Streamable HTTP handler
|
||||
│ ├── sse.ts # SSE handler
|
||||
│ ├── mock-upstream-idp.ts # Mock upstream IDP simulation
|
||||
│ └── common.ts # Shared middleware
|
||||
└── utils/
|
||||
└── logger.ts # Structured logging
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Modify `src/services/mcp.ts` to add custom tools and resources
|
||||
- See [external-oauth](../external-oauth/README.md) for external OAuth pattern
|
||||
- See [docs/oauth-flow.md](../docs/oauth-flow.md) for detailed OAuth flow analysis
|
||||
|
||||
## Testing
|
||||
|
||||
```bash
|
||||
npm test # 85 unit tests
|
||||
npm run test:e2e:integrated # E2E test (from repo root)
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
- [MCP Authorization Spec](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization)
|
||||
- [OAuth 2.1 Draft](https://oauth.net/2.1/)
|
||||
- [RFC 6749: OAuth 2.0 Framework](https://datatracker.ietf.org/doc/html/rfc6749)
|
||||
- [docs/oauth-flow.md](../docs/oauth-flow.md) - Detailed flow analysis with mode differences
|
||||
Loading…
Reference in a new issue