PROJECT OVERVIEW:
This project is to build a Single Page Application (SPA) called 'MCP Connect' using React and Tailwind CSS. MCP Connect aims to solve the problem of integrating Large Language Models (LLMs) with various services. The core issue addressed is the complexity and overhead associated with current methods like creating dedicated CLIs or using "Skills" which often lack the flexibility and directness needed for robust service integration. MCP Connect provides an architectural choice that favors the Model Context Protocol (MCP), an API abstraction layer, enabling LLMs to interact with services pragmatically without needing to understand the underlying implementation details. The primary value proposition is to simplify and streamline the process of giving LLMs access to real-world services, fostering a more efficient and practical AI ecosystem. It acts as a centralized hub for managing and connecting LLM capabilities to external services via MCP.
TECH STACK:
- Frontend Framework: React (using Vite for fast development)
- Styling: Tailwind CSS for rapid and utility-first styling.
- State Management: Zustand for efficient and simple global state management.
- Routing: React Router DOM for navigation within the SPA.
- API Calls: Axios for making HTTP requests.
- UI Components: Headless UI for accessible and unstyled components that integrate well with Tailwind CSS.
- Icons: Heroicons for a clean and consistent icon set.
- Form Handling: React Hook Form with Zod for validation.
- Animation Library: Framer Motion for subtle and engaging UI animations.
CORE FEATURES:
1. **MCP Service Definition:**
* **User Flow:** Users navigate to the 'Services' section. They click 'Add New Service'. A form appears allowing them to input service name, description, OpenAPI/Swagger spec URL or manual endpoint details (URL, method, params, body schema). They can optionally define input/output mappings for the LLM. Upon saving, the service configuration is stored.
* **Details:** This feature allows users to define how an external service can be accessed. It needs to handle both automated discovery via spec URLs and manual configuration. Input/output mapping is crucial for tailoring the service interaction to the LLM's context.
2. **API Connection Management:**
* **User Flow:** Within the 'Services' list, users can click on a defined service. They are presented with options to 'Connect Service'. This might involve entering API keys, authentication tokens, or selecting pre-configured credentials. Once authenticated, the connection status is displayed.
* **Details:** Securely managing credentials and authentication is paramount. This module will handle different auth methods (API Key, OAuth, etc.) and store sensitive information securely (e.g., using environment variables or a secure vault). The connection status provides immediate feedback to the user.
3. **LLM Integration Module:**
* **User Flow:** Users go to the 'Integrations' section. They select their preferred LLM (e.g., OpenAI, Claude API). They then choose which of their configured MCP services they want to expose to this LLM. The system generates or updates the necessary configuration/prompting strategy for the LLM to recognize and utilize these services via MCP.
* **Details:** This is the core of the value proposition. It acts as an adapter, translating the LLM's intent into MCP calls and the service's response back into a format the LLM understands. It might involve generating specific function calling definitions or structured prompts based on the MCP service definitions.
4. **Monitoring & Logging:**
* **User Flow:** Users access the 'Dashboard' or 'Logs' section. They see an overview of recent service calls, success/error rates, latency metrics, and detailed logs for individual requests. They can filter logs by service, LLM, or date.
* **Details:** Provides visibility into the performance and reliability of the integrations. Essential for debugging and understanding how the LLM is interacting with services.
UI/UX DESIGN:
- **Layout:** A clean, modern dashboard layout. Sidebar navigation for 'Services', 'Integrations', 'Dashboard', 'Settings'. Main content area displays the selected section. Minimalistic header.
- **Color Palette:** Primary: Deep Navy Blue (#0B1320). Secondary: Teal (#1EC3A3). Accent: Light Grey (#E0E0E0). Text: Dark Grey (#333333) and White (#FFFFFF). Use subtle gradients for emphasis.
- **Typography:** Sans-serif fonts. Headings: Inter (Bold). Body Text: Inter (Regular). Ensure good readability and hierarchy.
- **Responsive Design:** Mobile-first approach. Sidebar collapses into a hamburger menu on smaller screens. Content reflows fluidly. Use Tailwind's responsive prefixes (sm:, md:, lg:). Ensure all forms and tables are usable on mobile.
- **Interactions:** Subtle hover effects on buttons and links. Smooth transitions for modal popups and route changes. Clear loading indicators (spinners, skeleton screens) for asynchronous operations. Micro-interactions for form validation feedback.
COMPONENT BREAKDOWN:
- **`Layout.jsx`:** Main layout component. Includes `Sidebar.jsx` and `Header.jsx`. Renders children based on the route.
- Props: `children` (ReactNode)
- **`Sidebar.jsx`:** Navigation menu component.
- Props: `isOpen` (boolean), `onClose` (function)
- **`Header.jsx`:** Top bar with logo and user actions.
- Props: None
- **`ServiceList.jsx`:** Displays a list of defined MCP services.
- Props: `services` (array of Service objects)
- **`ServiceForm.jsx`:** Form for adding/editing MCP service definitions.
- Props: `onSubmit` (function), `initialData` (Service object, optional)
- **`ConnectionForm.jsx`:** Form for managing service authentication details.
- Props: `serviceId` (string), `onSubmit` (function)
- **`LLMIntegrationForm.jsx`:** Form for connecting services to a specific LLM.
- Props: `llmOptions` (array), `serviceOptions` (array), `onSubmit` (function)
- **`LogViewer.jsx`:** Displays logs and monitoring data.
- Props: `logs` (array of Log objects)
- **`Button.jsx`:** Reusable button component.
- Props: `onClick` (function), `children` (ReactNode), `variant` (string, e.g., 'primary', 'secondary'), `isLoading` (boolean)
- **`Input.jsx`:** Reusable input field component.
- Props: `label` (string), `type` (string), `value` (string), `onChange` (function), `error` (string, optional)
- **`Modal.jsx`:** Reusable modal component.
- Props: `isOpen` (boolean), `onClose` (function), `children` (ReactNode), `title` (string)
DATA MODEL:
- **`Service` Object:**
```json
{
"id": "svc_123xyz",
"name": "WeatherAPI",
"description": "Provides current weather data for any location.",
"specUrl": "https://api.example.com/weather/v1/openapi.json",
"manualConfig": {
"baseUrl": "https://api.example.com/weather/v1",
"endpoints": [
{
"path": "/current",
"method": "GET",
"params": [{"name": "city", "type": "string", "required": true}]
}
]
},
"inputMapping": { "user_query.location": "params.city" },
"outputMapping": { "weather_data.temp": "response.data.temperature" },
"credentials": null // Or an object representing auth details
}
```
- **`LogEntry` Object:**
```json
{
"id": "log_abc789",
"timestamp": "2023-10-27T10:30:00Z",
"serviceId": "svc_123xyz",
"llmName": "OpenAI-GPT4",
"request": {"prompt": "What's the weather in London?", "payload": {...}},
"response": {"status": 200, "body": {...}},
"latencyMs": 1500,
"status": "success" // 'success', 'error'
}
```
- **State Management (Zustand):**
- `useServiceStore`: manages the list of `Service` objects.
- `useLogStore`: manages the list of `LogEntry` objects.
- `useIntegrationStore`: manages LLM to Service mappings.
- `useAuthStore`: manages authentication states and credentials.
ANIMATIONS:
- **Hover Effects:** Subtle background color change or slight scale-up on buttons, links, and service cards on hover.
- **Transitions:** Smooth fade-in/fade-out for modals and content area changes. Slide-in animation for the sidebar menu on mobile.
- **Loading States:** Use `react-spinners` or custom SVG spinners within buttons when an action is processing. Skeleton loaders for data fetching (service list, logs).
- **Micro-interactions:** Input field focus states. Success/error checkmarks or X icons appearing after form submission validation.
EDGE CASES:
- **Empty States:** Display informative messages and clear call-to-actions when there are no services defined, no logs yet, or no integrations set up. E.g., "No services found. Click 'Add New Service' to get started."
- **Error Handling:** Gracefully handle API errors (network issues, invalid responses, auth failures). Display user-friendly error messages. Implement retry mechanisms where appropriate. Log errors comprehensively.
- **Validation:** Implement real-time form validation using Zod and React Hook Form for service definitions, connection details, and integration settings. Provide clear inline error messages.
- **Accessibility (a11y):** Use semantic HTML. Ensure proper ARIA attributes are used for interactive elements and custom components (modals, sidebars). Keyboard navigability for all interactive elements. Sufficient color contrast.
- **Security:** Sanitize all user inputs. Securely handle and store API keys and tokens (e.g., using environment variables, possibly integrating with a secret manager for production).
SAMPLE DATA:
1. **Service Definition (Weather):**
```json
{
"id": "svc_weather_001",
"name": "CurrentWeather",
"description": "Get current weather conditions for a specified city.",
"specUrl": "https://api.example-weather.com/v3/openapi.json",
"inputMapping": {"query.city_name": "params.city"},
"outputMapping": {"weather.temperature": "response.data.main.temp", "weather.description": "response.data.weather[0].description"}
}
```
2. **Service Definition (Stock):**
```json
{
"id": "svc_stocks_002",
"name": "StockTicker",
"description": "Fetch real-time stock price for a given symbol.",
"manualConfig": {
"baseUrl": "https://api.example-stocks.com/v1",
"endpoints": [
{"path": "/quote", "method": "GET", "params": [{"name": "symbol", "type": "string", "required": true}]}
]
},
"inputMapping": {"query.stock_symbol": "params.symbol"},
"outputMapping": {"stock.price": "response.data.price", "stock.change": "response.data.change_percent"}
}
```
3. **Service Definition (Calendar):**
```json
{
"id": "svc_calendar_003",
"name": "UpcomingEvents",
"description": "List upcoming events from user's calendar.",
"specUrl": null, // Requires OAuth setup
"manualConfig": {"baseUrl": "https://api.example-calendar.com/v2", "endpoints": [{"path": "/events", "method": "GET", "params": [{"name": "limit", "type": "integer", "required": false}]}]},
"inputMapping": {"query.max_events": "params.limit"},
"outputMapping": {"events.list": "response.data.events"}
}
```
4. **Log Entry (Success):**
```json
{
"id": "log_wthr_scc_1",
"timestamp": "2023-10-27T11:05:15Z",
"serviceId": "svc_weather_001",
"llmName": "Claude-3-Opus",
"request": {"prompt": "What is the weather like in Paris?", "payload": {"city": "Paris"}},
"response": {"status": 200, "body": {"main": {"temp": 18.5}, "weather": [{"description": "Clear sky"}]}},
"latencyMs": 450,
"status": "success"
}
```
5. **Log Entry (Error):**
```json
{
"id": "log_stock_err_1",
"timestamp": "2023-10-27T11:07:00Z",
"serviceId": "svc_stocks_002",
"llmName": "GPT-4",
"request": {"prompt": "Price for GOOG?", "payload": {"symbol": "GOOG"}},
"response": {"status": 401, "body": {"error": "Unauthorized"}},
"latencyMs": 200,
"status": "error"
}
```
6. **Integration Mapping:**
```json
{
"llmProvider": "OpenAI",
"modelName": "gpt-4-turbo",
"enabledServices": ["svc_weather_001", "svc_stocks_002"]
}
```
DEPLOYMENT NOTES:
- Use Vite's build command (`npm run build`) for optimized production builds.
- Configure environment variables for API endpoints, authentication secrets (use `.env` files locally and appropriate CI/CD variables in production).
- Consider a CDN for serving static assets.
- Implement caching strategies for frequently accessed, non-critical data.
- Ensure the backend API (if any, for storing services/logs persistently) is scalable and secure.
- Monitor build sizes and optimize dependencies.
- Set up basic health checks for the application.
- For production, consider using a service like Vercel or Netlify for easy deployment and scaling of the frontend SPA.