mcp-server-blog

# MCP Server Demo: OAuth, TypeScript & Firestore Patterns [](https://opensource.org/licenses/MIT) This repository provides a stripped-down, illustrative implementation of a Model Context Protocol (MCP) server. It showcases the architectural patterns, security considerations (OAuth 2.0), and development practices (TypeScript, Firestore, Zod) detailed in our accompanying article: **➡️ Read the full story: "[Building a Production-Ready MCP Server with OAuth, TypeScript, and Our Battle Scars](https://portal.one/blog/mcp-server-with-oauth-typescript/)"** This demo focuses on the **MCP Resource Server** component and assumes you have a separate OAuth 2.0 Authorization Server. Update: MCP SDK version 1.12.0 introduced the Authorization Server Metadata (/.well-known/oauth-authorization-server) support and removes the need to proxy the oauth calls through the MCP resource server. ## Purpose This repository is intended as a learning resource to: - Demonstrate a practical implementation of an MCP server using the TypeScript MCP SDK. - Illustrate how to integrate OAuth 2.0 for securing tool calls. - Showcase patterns for managing workspace context and multi-tenancy. - Provide examples of using Zod for schema definition and validation. - Offer insights into structuring tools, using Higher-Order Components (HOCs) for common logic, and interacting with Firestore. **This is NOT a production-ready, plug-and-play server for all use cases.** It omits specific business logic and assumes a pre-existing OAuth Authorization Server. ## Key Features & Patterns Demonstrated - **MCP TypeScript SDK Integration:** Core server setup and tool registration. - **OAuth 2.0 Token Validation:** Securely handling Bearer tokens (via the SDK middleware). - **Workspace Context Management:** - Explicit `workspace_id` in tool arguments. - `withWorkspaceAccess` Higher-Order Component (HOC) for authentication and workspace authorization. - **Firestore Integration:** - Fetching user data, OAuth token information (conceptual), and tool-specific data. - Using Firestore emulators for local development and testing. - **Zod for Schemas & Validation:** Defining input schemas for tools and leveraging Zod for runtime validation. - **Type-Safe Development:** Leveraging TypeScript for robust code. - **Utility Functions:** Examples of `fetchResourceList` for DRY data fetching. - **Standardized Error Handling:** Using `throw new Error()` for clear error propagation. - **Example Tool Structures:** Basic tool definitions showcasing the patterns. - **Environment Variable Configuration:** For database and OAuth settings. ## Architectural Overview This demo represents the **MCP Resource Server**. It expects OAuth 2.0 Bearer tokens issued by a separate **OAuth Authorization Server**. ``` [Client / LLM with MCP Client SDK] | | (HTTPS Request with Bearer Token) v [This MCP Resource Server (Node.js / TypeScript)] | 1. MCP SDK Middleware (parses request, extracts token) | 2. `withWorkspaceAccess` HOC | a. Using the userId associated with the token | b. Validates the user can access the workspace_id in the request | 3. Tool Handler Execution (interacts with Firestore based on validated context) | v [Google Firestore (Database)] ``` The OAuth Authorization Server (which you would provide or have existing) is responsible for: - Authenticating users. - Issuing OAuth tokens (Access Tokens, Refresh Tokens). - Managing OAuth clients (Dynamic Discovery). This Resource Server then validates the tokens received from clients. ## Prerequisites - Node.js (v18.x or later recommended) - npm or yarn - Access to a Google Cloud Project with Firestore enabled OR Google Cloud SDK configured for Firestore Emulator. - An existing OAuth 2.0 Authorization Server. ## Getting Started 1. **Clone the repository:** ```bash git clone https://github.com/portal-labs-infrastructure/mcp-server-blog cd mcp-server-blog ``` 2. **Install dependencies:** ```bash npm install # or yarn install ``` 3. **Set up Environment Variables:** Copy the `.env.example` file to a new file named `.env`: ```bash cp .env.example .env ``` Now, edit `.env` and fill in the required configuration values: ```dotenv # Firestore Configuration # If using Firestore Emulator, these might not all be strictly needed, # but ensure your gcloud CLI is configured or provide necessary emulator host. PROJECT_ID="your-gcp-project-id" # FIRESTORE_EMULATOR_HOST="localhost:8081" # Uncomment if using emulator and not relying on gcloud config # OAuth 2.0 Configuration (for this Resource Server to validate tokens) # This depends on your OAuth Authorization Server's setup. OAUTH_ISSUER_URL="https_your_auth_server_com" # MCP Server Configuration BASE_URL="http://localhost:8080" # URL this server is accessible at ``` **Important:** The OAuth configuration is crucial. This server needs to know how to validate tokens issued by your Authorization Server. Consult your Auth Server's documentation. 4. **(Optional) Seed Firestore Data:** If you have seed scripts or want to manually add some sample users, OAuth tokens (matching what your Auth server would issue), and workspace data to your Firestore instance/emulator, do so now. This will make testing the tools more meaningful. ## Running the Server - **Development Mode (with Nodemon for auto-restarts):** ```bash npm run dev ``` - **Production Mode:** `bash npm run build npm start ` The server will typically start on `http://localhost:8080` (or the port specified in `.env`). ## Running with Firestore Emulator 1. Ensure Google Cloud SDK is installed and configured. 2. Start the Firestore emulator in a separate terminal: ```bash gcloud emulators firestore start --host-port=localhost:8081 ``` (Adjust port if needed and update `FIRESTORE_EMULATOR_HOST` in `.env` or ensure your application automatically detects it via `gcloud` environment variables). 3. Run the MCP server as described above. It should connect to the emulator. ## Key Patterns & Concepts Demonstrated in Code Look for these patterns in the `src` directory: - **`src/index.ts`:** Main MCP server setup. - **`src/controllers/mcpController.ts`:** Tool registration and MCP controller handling incoming requests. - **`src/services/`:** Service layer for handling Firestore interactions. - **`src/tools/`:** Example tool definitions. - Each tool will have an `inputSchema` (Zod) and a `handler`. - Handlers will likely be wrapped with `withWorkspaceAccess`. - **`src/utils/withWorkspaceAccess.ts`:** The Higher-Order Component for workspace checks. - **`src/utils/fetchResourceList.ts`:** Example of reusable data fetching utility. - **`src/utils/types.ts`:** Shared TypeScript types and Zod schemas (e.g., for `EntityType`, `ResourceType`). ## Directory Structure ``` . ├── src/ │ ├── tools/ # Tool definitions │ │ ├── getAgentTool.ts │ │ └── ... │ ├── utils/ # Shared utilities, HOCs, types │ │ ├── withWorkspaceAccess.ts │ │ ├── types.ts │ │ └── ... │ ├── services/ # Interaction logic │ │ ├── firestoreService.ts # Firestore interaction logic │ │ └── ... │ ├── config/ # Configuration loading │ └── index.ts # Main server setup ├── .env.example # Example environment variables ├── .env # Your local environment variables (ignored by git) ├── package.json ├── tsconfig.json └── ... ``` ## What This Demo Is (and Isn't) - **IS:** A demonstration of server-side patterns for building a secure, multi-tenant MCP Resource Server. - **IS:** A way to see TypeScript, Zod, Firestore, and OAuth concepts applied in an MCP context. - **IS NOT:** A complete, production-ready OAuth Authorization Server (you need to provide that). - **IS NOT:** A library or SDK to be directly consumed (it's an example application). - **IS NOT:** Filled with complex business logic (tools are illustrative). ## Contributing This is primarily a demo repository. However, if you find bugs or have suggestions for improving the clarity of the demonstrated patterns, feel free to open an issue or submit a pull request. ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## Acknowledgements This demo is heavily inspired by the experiences and patterns discussed in the article: "[Building a Production-Ready MCP Server with OAuth, TypeScript, and Our Battle Scars](https://portal.one/blog/mcp-server-with-oauth-typescript/)".