From 695f9f68ae9f402ee747e7de3a8dc95fed879c3c Mon Sep 17 00:00:00 2001 From: Basil Hosmer Date: Tue, 7 Oct 2025 17:08:10 -0400 Subject: [PATCH] Add customization guide and fix broken doc references - Create docs/customization-guide.md with guidance on replacing demo functionality - Add customization section to main README - Fix all references to renamed oauth-architecture-patterns.md - Update repository structure comments to clarify what to replace vs keep --- README.md | 19 ++++-- auth-server/README.md | 2 +- docs/customization-guide.md | 117 ++++++++++++++++++++++++++++++++++++ mcp-server/README.md | 3 +- 4 files changed, 133 insertions(+), 8 deletions(-) create mode 100644 docs/customization-guide.md diff --git a/README.md b/README.md index 2331bf6..7ffec88 100644 --- a/README.md +++ b/README.md @@ -53,10 +53,10 @@ For detailed instructions, see [Installation](#installation). This repository demonstrates a production-ready MCP deployment pattern with separate authorization and resource servers: ``` -auth-server/ # OAuth 2.0 authorization server +auth-server/ # OAuth 2.0 authorization server (demo only - replace in production) └── src/ # Authorization endpoints and token management -mcp-server/ # MCP resource server +mcp-server/ # MCP resource server (customize tools/resources/prompts) └── src/ # MCP protocol implementation with external auth scripts/ # Testing and deployment scripts @@ -64,7 +64,13 @@ docs/ # Architecture and API documentation examples/ # Example code and usage patterns ``` -The architecture separates authentication concerns from MCP functionality, allowing you to integrate with existing OAuth providers (Auth0, Okta, etc.) or deploy your own authorization server. +The architecture separates authentication concerns from MCP functionality, allowing you to integrate with commercial OAuth providers (Auth0, Okta, etc.). + +## Customizing for Your Use Case + +This is a reference implementation with demo tools, resources, and prompts. To adapt it for production: +- **Replace MCP features:** See [Customization Guide](docs/customization-guide.md) for replacing demo functionality with your own +- **Integrate OAuth provider:** See [OAuth Architecture Patterns](docs/oauth-architecture-patterns.md) for production authentication setup ## Usage Examples @@ -174,7 +180,7 @@ sequenceDiagram Client->>User: 9. Results ``` -The auth server is separate so you can easily replace it with Auth0, Okta, or any OAuth provider. See [docs/oauth-patterns.md](docs/oauth-patterns.md) for alternative architectures. +The auth server is separate so you can easily replace it with Auth0, Okta, or any OAuth provider. See [docs/oauth-architecture-patterns.md](docs/oauth-architecture-patterns.md) for integration guidance. ## Table of Contents @@ -320,7 +326,7 @@ This architecture pattern: - **Scales independently**: Auth and MCP servers can scale based on their load - **Follows standards**: Uses OAuth 2.0 and token introspection (RFC 7662) -For alternative patterns like embedded OAuth, see [docs/oauth-patterns.md](docs/oauth-patterns.md). +For alternative patterns like embedded OAuth, see [docs/oauth-architecture-patterns.md](docs/oauth-architecture-patterns.md). ### OAuth Flow @@ -361,9 +367,10 @@ The `/mock-upstream-idp` endpoints simulate what a real identity provider (Googl ├── scripts/ # Testing and deployment │ └── test-e2e.sh # End-to-end OAuth + MCP verification ├── docs/ +│ ├── customization-guide.md # How to adapt this for your use case │ ├── endpoints.md # API endpoint reference │ ├── oauth-flow.md # OAuth flow documentation -│ ├── oauth-patterns.md # Alternative OAuth patterns +│ ├── oauth-architecture-patterns.md # OAuth integration guidance │ └── session-ownership.md # Session management details ├── examples/ # Example code and usage patterns │ ├── client.js # Node.js client example diff --git a/auth-server/README.md b/auth-server/README.md index d2a6aff..333df9b 100644 --- a/auth-server/README.md +++ b/auth-server/README.md @@ -119,5 +119,5 @@ This server stores in Redis: - [Main README](../README.md) - Complete project documentation - [MCP Server README](../mcp-server/README.md) - How MCP server uses these tokens -- [OAuth Patterns](../docs/oauth-patterns.md) - OAuth architecture patterns +- [OAuth Architecture Patterns](../docs/oauth-architecture-patterns.md) - OAuth integration options - [OAuth Flow](../docs/oauth-flow.md) - Detailed OAuth flow analysis diff --git a/docs/customization-guide.md b/docs/customization-guide.md new file mode 100644 index 0000000..374e9d7 --- /dev/null +++ b/docs/customization-guide.md @@ -0,0 +1,117 @@ +# Customization Guide + +This reference implementation includes demo functionality to showcase MCP features. Here's how to adapt it for your own use case. + +## Overview: What to Customize vs. Keep + +**Replace with your own:** +- MCP tools, resources, and prompts (your business logic) +- Authentication provider (use commercial OAuth provider) + +**Keep as-is (infrastructure):** +- Redis transport and session management +- HTTP handlers and routing +- Security middleware and rate limiting +- Logging infrastructure + +--- + +## Customizing MCP Functionality + +All MCP feature implementations live in **`mcp-server/src/services/mcp.ts`**. This is where you define what your server can do. + +### Tools + +Replace the 7 demo tools (echo, add, etc.) with your actual tools: + +**Location:** `createMcpServer()` function, look for the `CallToolRequestSchema` handler + +**What to change:** +- Tool definitions: name, description, input schema (using Zod) +- Tool execution logic: what happens when the tool is called +- Return format: text, images, or embedded resources + +**Pattern:** Each tool validates input with a Zod schema and returns content in MCP format. + +### Resources + +Replace the 100 fake resources with your actual data sources: + +**Location:** `createMcpServer()` function, resource-related handlers: +- `ListResourcesRequestSchema` - List available resources +- `ReadResourceRequestSchema` - Read specific resources +- `SubscribeRequestSchema` / `UnsubscribeRequestSchema` - Resource updates + +**What to change:** +- Resource URIs and names +- Data fetching logic +- Pagination if needed +- Update notifications for subscribed resources + +**Pattern:** Resources use URIs (e.g., `db://users/123`) and return content as text, JSON, or binary. + +### Prompts + +Replace the 3 demo prompts with useful prompts for your domain: + +**Location:** `createMcpServer()` function, prompt-related handlers: +- `ListPromptsRequestSchema` - List available prompts +- `GetPromptRequestSchema` - Return prompt content + +**What to change:** +- Prompt names and descriptions +- Prompt arguments and validation +- Prompt content and embedded resources + +**Pattern:** Prompts can include dynamic arguments and reference resources. + +--- + +## Customizing Authentication + +**Replace the demo auth server** with a commercial OAuth provider (Auth0, Okta, Azure AD, AWS Cognito, Google, GitHub, etc.). + +See [OAuth Architecture Patterns](oauth-architecture-patterns.md#using-a-commercial-auth-provider) for detailed integration steps. + +**Do not repurpose the demo auth server** - it's designed for development/testing only. Commercial providers offer better security, reliability, and user management. + +--- + +## Configuration + +Update environment variables for your deployment: + +**MCP Server** (`mcp-server/.env`): +```bash +BASE_URI=https://your-mcp-server.com +PORT=443 +AUTH_SERVER_URL=https://your-tenant.auth0.com +REDIS_URL=redis://your-redis-server:6379 +``` + +**Auth Server** (only if using the demo server for development): +```bash +AUTH_SERVER_URL=http://localhost:3001 +BASE_URI=https://your-mcp-server.com +``` + +--- + +## Testing Your Customizations + +1. **Unit tests:** Add tests for your tools/resources in `mcp-server/src/services/` +2. **Integration tests:** Test with MCP Inspector or client.js +3. **Build and lint:** Run `npm run build && npm run lint` +4. **End-to-end:** Use the examples to verify OAuth and MCP flows + +--- + +## Next Steps + +1. Fork/clone this repository +2. Replace tools, resources, and prompts in `mcp-server/src/services/mcp.ts` +3. Integrate with your OAuth provider (see OAuth Architecture Patterns doc) +4. Update environment variables for your deployment +5. Test thoroughly before deploying + +For questions about the MCP protocol itself, see the [MCP specification](https://modelcontextprotocol.io/specification). diff --git a/mcp-server/README.md b/mcp-server/README.md index 57d707f..8ac32dc 100644 --- a/mcp-server/README.md +++ b/mcp-server/README.md @@ -130,7 +130,8 @@ To use a commercial OAuth provider instead of the demo auth server, see [OAuth A ## Related Documentation - [Main README](../README.md) - Complete project documentation +- [Customization Guide](../docs/customization-guide.md) - How to adapt this for your use case - [Auth Server README](../auth-server/README.md) - The demo OAuth provider -- [OAuth Patterns](../docs/oauth-patterns.md) - OAuth architecture patterns +- [OAuth Architecture Patterns](../docs/oauth-architecture-patterns.md) - OAuth integration options - [OAuth Flow](../docs/oauth-flow.md) - Detailed OAuth flow analysis - [Session Ownership](../docs/session-ownership.md) - Session management details