{"id":"1f217507-86b1-494f-93d8-4cd71894e7ec","slug":"calvinw-llm-chat","kind":"mcp","name":"llm-chat","summary":"","owner":"calvinw","repoUrl":"https://github.com/calvinw/llm-chat","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2025-07-25T23:11:39.000Z","addedAt":"2026-10-21T15:38:03.195Z","logoUrl":"https://avatars.githubusercontent.com/u/2001105?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["communication"],"tags":[],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-23T06:36:11.148Z","sample":false,"url":"https://conduits.dev/tools/calvinw-llm-chat","language":"JavaScript","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# LLM Chat Interface\n\nA modern, feature-rich React chat interface for Large Language Models using the OpenRouter API. Built with React 19, Vite, Tailwind CSS, and Radix UI components.\n\n## Features\n\n- **Multiple LLM Support** - Access GPT-4, Claude, Gemini, Llama, and more via OpenRouter\n- **Streaming Responses** - Real-time message streaming with throttled updates\n- **Tool Calling** - Support for function calling with parallel execution\n- **MCP Integration** - Model Context Protocol support for remote tool servers\n- **Math Rendering** - LaTeX expressions with MathJax ($inline$ and $$display$$)\n- **Markdown Support** - Full markdown rendering with syntax highlighting\n- **Responsive Design** - Mobile-friendly interface with configurable sidebar\n- **Radix UI Components** - Accessible, customizable UI components\n- **Tailwind CSS v4** - Modern utility-first styling\n\n## Quick Start\n\n### Prerequisites\n\n- Node.js 18+ and npm\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone <repository-url>\ncd llm-chat\n\n# Install dependencies\nnpm install\n```\n\n### Development\n\n```bash\n# Start development server (http://localhost:8081)\nnpm run dev\n```\n\n### Build for Production\n\n```bash\n# Build to /docs directory (GitHub Pages ready)\nnpm run build\n\n# Preview production build\nnpm run preview\n```\n\n## Project Structure\n\n```\nllm-chat/\n├── src/\n│   ├── main.jsx                    # Application entry point\n│   ├── LLMChatInterface.jsx        # Main chat component\n│   ├── index.css                   # Global styles\n│   ├── components/                 # React components\n│   │   ├── Sidebar.jsx            # Settings and model selection\n│   │   ├── MessagesContainer.jsx  # Message display area\n│   │   ├── MessageInput.jsx       # User input component\n│   │   ├── Message.jsx            # Individual message display\n│   │   ├── ErrorDisplay.jsx       # Error handling UI\n│   │   ├── TabHeader.jsx          # Tab navigation\n│   │   ├── SystemPromptTab.jsx    # System prompt configuration\n│   │   ├── ui/                    # Radix UI components\n│   │   └── ai-elements/           # AI-specific UI elements\n│   ├── hooks/                     # Custom React hooks\n│   │   ├── useChatEngine.jsx      # Core chat logic\n│   │   ├── useModelManager.jsx    # Model fetching/management\n│   │   ├── useMarkdownRenderer.jsx # Markdown + MathJax\n│   │   ├── useToolManager.jsx     # Tool execution\n│   │   ├── useMCPManager.jsx      # MCP protocol handling\n│   │   └── useStreamingEngine.jsx # Streaming responses\n│   ├── utils/                     # Utility modules\n│   │   ├── apiClient.jsx          # OpenRouter API client\n│   │   ├── mcpClient.jsx          # MCP protocol client\n│   │   ├── httpClient.jsx         # HTTP utilities\n│   │   ├── mathProcessor.jsx      # MathJax integration\n│   │   └── constants.jsx          # App constants\n│   └── lib/\n│       └── utils.js               # Helper functions\n├── docs/                          # Production build output\n├── index.html                     # HTML entry point\n├── vite.config.js                 # Vite configuration\n├── package.json                   # Dependencies and scripts\n└── README.md                      # This file\n```\n\n## Usage\n\n### Basic Usage\n\nThe `LLMChatInterface` component can be used standalone or integrated into larger applications:\n\n```jsx\nimport LLMChatInterface from './LLMChatInterface.jsx';\n\nfunction App() {\n  return (\n    <LLMChatInterface\n      defaultModel=\"openai/gpt-4o-mini\"\n      height=\"100vh\"\n    />\n  );\n}\n```\n\n### Component Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `apiKey` | string | null | OpenRouter API key (uses localStorage if not provided) |\n| `defaultModel` | string | \"openai/gpt-4o-mini\" | Default model to use |\n| `systemPrompt` | string | \"\" | System prompt for the conversation |\n| `tools` | array | null | Tool definitions (OpenAI format) |\n| `toolHandlers` | object | null | Tool implementation functions |\n| `enableTools` | boolean | false | Enable tool calling |\n| `toolChoice` | string | \"auto\" | Tool choice strategy |\n| `parallelToolCalls` | boolean | true | Allow parallel tool execution |\n| `onToolCall` | function | null | Callback for tool execution |\n| `customModels` | array | null | Custom model list (overrides OpenRouter) |\n| `className` | string | \"\" | Additional CSS classes |\n| `height` | string | \"600px\" | Component height |\n| `showHeader` | boolean | true | Show header section |\n| `showModelSelector` | boolean | true | Show model selector |\n| `showClearButton` | boolean | true | Show clear messages button |\n| `showDisplayModeToggle` | boolean | true | Show markdown/text toggle |\n| `onMessage` | function | null | Callback for new messages |\n| `onError` | function | null | Callback for errors |\n| `theme` | string | \"light\" | UI theme |\n| `sidebarPosition` | string | \"right\" | Sidebar position (\"left\" or \"right\") |\n\n### Tool Calling Example\n\n```jsx\nconst tools = [\n  {\n    type: \"function\",\n    function: {\n      name: \"get_weather\",\n      description: \"Get current weather for a location\",\n      parameters: {\n        type: \"object\",\n        properties: {\n          location: {\n            type: \"string\",\n            description: \"City name\"\n          }\n        },\n        required: [\"location\"]\n      }\n    }\n  }\n];\n\nconst toolHandlers = {\n  get_weather: ({ location }) => {\n    // Your implementation\n    return { temperature: 72, condition: \"sunny\" };\n  }\n};\n\n<LLMChatInterface\n  tools={tools}\n  toolHandlers={toolHandlers}\n  enableTools={true}\n  onToolCall={(name, args, result, error) => {\n    console.log(`Tool ${name} executed:`, result);\n  }}\n/>\n```\n\n### MCP Server Integration\n\nThe interface supports the Model Context Protocol for remote tool servers:\n\n1. **Start an MCP server** (Python example provided in `mcp_server.py`):\n   ```bash\n   python mcp_server.py\n   ```\n\n2. **Configure in the UI**:\n   - Enter MCP server URL in the sidebar\n   - Select transport type (SSE or HTTP)\n   - Click \"Connect to MCP\"\n   - Available remote tools will be loaded automatically\n\n## API Configuration\n\n### OpenRouter API Key\n\nGet your API key from [OpenRouter](https://openrouter.ai/):\n\n1. Sign up at openrouter.ai\n2. Generate an API key\n3. Enter it in the sidebar (stored in localStorage)\n\n### Supported Models\n\nThe interface fetches available models from OpenRouter automatically, including:\n- OpenAI (GPT-4, GPT-3.5)\n- Anthropic (Claude 3.5, Claude 3)\n- Google (Gemini Pro)\n- Meta (Llama models)\n- And many more\n\n## Development\n\n### Tech Stack\n\n- **React 19.2.1** - UI framework\n- **Vite 7** - Build tool and dev server\n- **Tailwind CSS 4.0** - Utility-first CSS\n- **Radix UI** - Accessible component primitives\n- **MathJax 3** - Math typesetting\n- **Markdown-it** - Markdown rendering\n\n### Architecture\n\nThe application uses a custom hooks architecture for state management:\n\n- **`useChatEngine`** - Core chat logic, message management, API integration\n- **`useModelManager`** - Model fetching and selection\n- **`useMarkdownRenderer`** - Markdown and math rendering\n- **`useToolManager`** - Local tool execution with error handling\n- **`useMCPManager`** - MCP protocol and remote tool management\n- **`useStreamingEngine`** - Streaming response handling\n\n### Key Features\n\n**Streaming Responses**\n- Server-Sent Events (SSE) for real-time updates\n- Throttled updates to prevent UI overload\n- Automatic fallback to non-streaming mode\n\n**Tool Execution**\n- Parallel and sequential tool calling\n- Error handling and validation\n- Support for both local and remote (MCP) tools\n- Tool execution logging and debugging\n\n**Math Rendering**\n- Inline math with `$...$`\n- Display math with `$$...$$`\n- Automatic MathJax typesetting after render\n\n## Deployment\n\n### GitHub Pages\n\nThe project is configured to build to the `/docs` directory for easy GitHub Pages deployment:\n\n1. Build the project:\n   ```bash\n   npm run build\n   ```\n\n2. Commit the `/docs` directory:\n   ```bash\n   git add docs/\n   git commit -m \"Build for deployment\"\n   git push\n   ```\n\n3. Enable GitHub Pages in repository settings:\n   - Source: Deploy from a branch\n   - Branch: main\n   - Folder: /docs\n\n### Other Hosting Platforms\n\nThe built files in `/docs` can be deployed to:\n- Netlify\n- Vercel\n- Cloudflare Pages\n- Any static hosting service\n\n## MCP Server (Optional)\n\nA Python MCP server example is included (`mcp_server.py`) with:\n- SSE and HTTP transport support\n- Example calculator tool\n- CORS configuration for browser access\n\n```bash\n# SSE transport (default)\npython mcp_server.py\n\n# HTTP transport\npython mcp_server.py --transport http\n\n# Custom port\npython mcp_server.py --port 5001\n```\n\n## Browser Support\n\n- Chrome/Edge 90+\n- Firefox 88+\n- Safari 14+\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Test with `npm run dev`\n5. Build with `npm run build`\n6. Submit a pull request\n\n## License\n\nMIT License - see LICENSE file for details\n\n## Troubleshooting\n\n### API Key Issues\n- Ensure your OpenRouter API key is valid\n- Check that it's properly saved in localStorage\n- Try refreshing the page\n\n### Tool Calling Issues\n- Verify tool definitions match OpenAI format\n- Check that tool handlers are properly implemented\n- Enable console logging to debug tool execution\n\n### MCP Connection Issues\n- Verify MCP server is running\n- Check URL and port are correct\n- Ensure CORS is properly configured on the server\n- Try both SSE and HTTP transports\n\n### Math Rendering Issues\n- MathJax loads asynchronously - wait for page load\n- Check browser console for MathJax errors\n- Ensure proper LaTeX syntax in messages\n\n## Acknowledgments\n\n- Built with [React](https://react.dev/)\n- Powered by [OpenRouter](https://openrouter.ai/)\n- UI components from [Radix UI](https://www.radix-ui.com/)\n- Styled with [Tailwind CSS](https://tailwindcss.com/)\n- Math rendering by [MathJax](https://www.mathjax.org/)\n"}