FastMCP React Client

A modern React application that demonstrates integration with FastMCP servers using OAuth authentication. This project provides a clean, TypeScript-based interface for calling MCP tools and displaying results.

Features

• FastMCP Integration: Full support for MCP (Model Context Protocol) tool calling with OAuth authentication
• Search Interface: Ready-to-use search component with multiple search types (hybrid, semantic, keyword)
• Modern UI: Responsive interface with loading states and comprehensive error handling
• TypeScript: Fully typed for better development experience and code safety
• Multiple Results Display: Shows all search results with metadata

Getting Started

Prerequisites

• Node.js (v14 or higher)
• npm or yarn
• Access to a FastMCP server
• OAuth access token from your FastMCP provider
• MCP Server Requirement: Your MCP server must expose a tool named search_api that returns responses in the Claude API format with a Content field

Expected Response Format

The MCP server's search_api tool should return responses in the following format:

{
  "id": "msg_1234567890",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "This is Claude's response to your question. It contains the actual answer or information you requested."
    }
  ],
  "model": "claude-sonnet-4-5-20250929",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 42,
    "output_tokens": 156
  }
}

The client extracts and displays only the Content field from the response. The markdown parser will automatically format the content using all supported markdown features (headings, bold, italic, code blocks, links, lists, etc.).

Installation

1. Clone the repository:

git clone <repository-url>
cd fastmcp_react_oauth_client_md

1. Install dependencies:

npm install

1. Configure environment variables:

   Create a .env file in the project root:

   REACT_APP_MCP_SERVER_URL=https://your-mcp-server.com/mcp
   

   Replace https://your-mcp-server.com/mcp with your actual FastMCP server URL.

2. Start the development server:

npm start

1. Open http://localhost:3000 in your browser.

2. Enter your OAuth access token when prompted.

Usage

Search Interface

1. Enter Query: Type your search query in the search input field
2. Select Search Type: Choose between:
   • Hybrid: Combines multiple search strategies
   • Semantic: Semantic similarity search
   • Keyword: Traditional keyword matching
3. Execute Search: Click "Search" or press Enter
4. View Results: All matching results are displayed with content and scores
5. Clear Auth: Use "Clear Auth" to reset your stored authentication token

Project Structure

src/
├── components/
│   ├── SearchComponent.tsx    # Main search interface component
│   └── SearchComponent.css    # Component styles
├── services/
│   └── FastMCPClient.ts       # FastMCP client and API integration
├── App.tsx                    # Root app component
├── App.css                    # App-level styles
├── index.tsx                  # Application entry point
└── index.css                  # Global styles

Configuration

Environment Variables

The application requires one environment variable:

• REACT_APP_MCP_SERVER_URL: The URL of your FastMCP server (e.g., https://your-server.com/mcp)

OAuth Authentication

The application uses OAuth token-based authentication:

1. Tokens are securely stored in browser localStorage
2. Tokens expire after 1 hour by default
3. Users are prompted to re-authenticate when tokens expire
4. The "Clear Auth" button allows manual token removal

Features

FastMCPClient API

The FastMCPClient class provides:

• search(query, type): Execute search queries with specified search type
• testConnection(): Verify connection to the MCP server
• callTool(name, parameters): Call any MCP tool with parameters
• clearAuth(): Clear stored authentication tokens
• initializeAuth(): Initialize OAuth authentication flow

Search Types

• Hybrid: Combines multiple search approaches for balanced results
• Semantic: Uses semantic similarity for finding related content
• Keyword: Traditional text matching

Markdown Parser

The application includes a comprehensive markdown parser that formats all search results with rich text formatting. The parser supports the following markdown features:

Headings (6 Levels)

All heading levels are supported with decreasing font sizes:

# Heading 1 - Largest heading
## Heading 2 - Second level
### Heading 3 - Third level
#### Heading 4 - Fourth level
##### Heading 5 - Fifth level
###### Heading 6 - Smallest heading

Visual Styles:

• H1: 1.8rem with underline accent and colored border
• H2: 1.4rem
• H3: 1.2rem
• H4: 1.1rem
• H5: 1.0rem
• H6: 0.95rem

Text Formatting

Bold Text

**bold text**
__also bold__

Italic Text

*italic text*
_also italic_

Strikethrough

~~strikethrough text~~

Code

Inline Code

Inline code is styled with a light gray background and pink text:

`code snippet`

Code Blocks

Fenced code blocks with syntax highlighting:

```python
def hello():
    print("Hello, World!")

**Visual Features:**
- Dark theme background (#2d2d2d)
- Monospace font (Courier New, Fira Code, Consolas)
- Rounded corners with shadow
- Syntax-aware class names for future highlighting

### Links

Links are automatically converted to clickable elements that open in new tabs:
```markdown
[link text](https://example.com)

Security: Links automatically include target="_blank" and rel="noopener noreferrer" for security.

Horizontal Rules

Multiple styles are supported:

---
***
___

Blockquotes

Blockquotes are styled with a left border and light background:

> This is a blockquote
> It can span multiple lines

Visual Features:

• Left border accent (4px solid #667eea)
• Light gray background (#f8f9fa)
• Italic text styling
• Rounded corners

Lists

Unordered Lists

Multiple list markers are supported:

- Item 1
* Item 2
+ Item 3

Ordered Lists

1. First item
2. Second item
3. Third item

Visual Features:

• Proper indentation (30px)
• Line height of 1.8 for readability
• Spacing between items (8px)
• Disc bullets for unordered, decimal for ordered

Paragraphs

Paragraphs are automatically formatted:

• Double newlines (\n\n) create paragraph breaks
• Single newlines within paragraphs are preserved
• Proper spacing between paragraphs (15px margin)

Markdown Parser Implementation

The parser is implemented in SearchComponent.tsx and uses a line-by-line processing approach:

1. Code Block Extraction: Code blocks are extracted first and replaced with placeholders to prevent markdown formatting from being applied
2. Line-by-Line Processing: Each line is analyzed to determine its type (heading, list item, blockquote, etc.)
3. State Management: The parser tracks whether it's currently inside lists or blockquotes
4. Inline Formatting: Bold, italic, strikethrough, links, and inline code are processed last
5. HTML Generation: Clean HTML is generated with proper opening and closing tags

CSS Styling

All markdown elements are styled in SearchComponent.css with:

• Consistent color scheme matching the app theme
• Responsive font sizes
• Proper margins and padding
• Hover effects for interactive elements
• Dark mode code blocks
• Professional typography

Supported Formatting Summary

Development

Available Scripts

• npm start - Runs the app in development mode
• npm run build - Creates an optimized production build
• npm test - Launches the test runner
• npm eject - Ejects from Create React App (irreversible)

Tech Stack

• React 18: Modern React with hooks
• TypeScript: Type safety and enhanced developer experience
• Axios: HTTP client for API requests
• CSS3: Modern styling with animations

Production Deployment

1. Build the application:

npm run build

1. Deploy the build folder to your hosting service:

   • Netlify
   • Vercel
   • AWS S3 + CloudFront
   • Any static hosting provider

2. Set environment variables in your hosting platform's configuration.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please open an issue on GitHub.