# MCP Client Template

This is a base template for MCP (Model Context Protocol) client projects, featuring a Vite + TypeScript frontend and an Express backend. It allows you to add, manage, and interact with MCP servers via a web interface.

**OAuth2.1 support:**
The template natively supports OAuth2.1 authentication for secure access and integration, as described in the official documentation.

## OAuth2.1 Authentication Flow

When connecting to an MCP server that requires authentication, the frontend will provide an authentication link. Follow these steps:

1. Attempt to connect to the server from the web interface.
2. If authentication is required, a link will appear in the frontend.
3. Copy the link and paste it into a new tab in your browser.
4. Complete the authentication process in the new tab (OAuth2.1 redirect flow).
5. Once authenticated, return to the MCP Client Template interface to continue using the server.

This manual copy-paste flow is present because this project is only a template.

## Project Structure

- `public/`: Static files and resources (favicon, images, OAuth callback).
- `src/`: TypeScript frontend and CSS.
  - `main.ts`: UI logic for adding servers, sending commands, and displaying output.
  - `style.css`: Interface styling.
- `server/`: Express backend.
  - `index.ts`: REST API for MCP server management, command forwarding, authentication handling.
  - `authTokensStore.ts`, `mcpTypes.ts`: Token management and MCP types.
- `index.html`: Main page structure.
- `package.json`: Dependencies and scripts (dev, build, preview, server startup).
- `tsconfig.json`: TypeScript configuration.

> The `data/` folder contains runtime memory and configuration and should not be modified manually.

## Requirements
- Node.js (recommended version >=18)

## Installation

1. Clone the repository:
   ```powershell
   git clone <url-repo>
   cd mcp-client-template
   ```
2. Install dependencies:
   ```powershell
   npm install
   ```

## Development & Usage

- Start the frontend:
  ```powershell
  npm run dev
  ```
- Start the backend:
  ```powershell
  npm run dev:server
  ```

## Customization & Extension

- To add new frontend features, edit files in `src/`.
- To extend the backend, work in `server/`.
- You can add new endpoints, authentication logic, and advanced MCP server management.

## Forking & Reuse

You are encouraged to fork this repository to use it as a starting point for your own MCP client projects. After forking:

- Rename the project and update metadata as needed in `package.json` and documentation files.
- Customize the frontend and backend logic to fit your requirements.
- Remove or adapt example code and endpoints as needed.

This template is designed to be easily extended for more complex MCP projects.

## Additional Notes

- The `data/` folder is ignored and should not be manually edited.

---

For questions or suggestions, open an issue or contact the maintainer.