Air Agent

A static AI agent chat interface with direct client-side OpenAI API integration. This is a fully client-side application that can be deployed to GitHub Pages with no backend required.

Features

🤖 AI Chat Interface - Interactive chat with OpenAI models
🛠️ Automatic Tool Calling - AI can automatically use tools/functions with streaming responses
📊 Built-in Tools - Calculator, time, and easy to add custom tools
🔄 Streaming Responses - Real-time streaming of AI responses
🔌 MCP Client Support - Full Model Context Protocol integration for browser-based tool discovery
🌐 MCP Server Configuration - Configure and manage MCP servers directly in the browser
🎛️ Per-Chat MCP Control - Enable/disable MCP and select servers per conversation
🖥️ Built-in MCP Server - Expose tools via MCP HTTP transport with compliant session management
🎨 Theme Support - Light, Dark, and System themes (similar to shadcn.com/create)
⚙️ Configurable Settings - API key, base URL, and model selection
💾 Local Storage - All settings stored in browser localStorage
🎯 Modern UI - Built with shadcn/ui components

Screenshots

Light Theme

Dark Theme

Settings Dialog

Theme Selector

MCP Configuration

Getting Started

Prerequisites

Node.js 20 or higher
npm or yarn

Installation

Clone the repository:

git clone https://github.com/poly-workshop/air-agent.git
cd air-agent

Install dependencies:

npm install

Run the development server:

npm run dev

Open http://localhost:3000 in your browser

Building for Production

Build the static site:

npm run build

The static files will be generated in the out directory.

Configuration

Click the settings icon (⚙️) in the top right corner to configure:

OpenAI API Key

Your OpenAI API key (required). Get one from OpenAI Platform.

OpenAI Base URL (Optional)

Custom API endpoint if you're using a different OpenAI-compatible service. Default: https://api.openai.com/v1

Theme

Choose between Light, Dark, or System theme.

All settings are stored locally in your browser's localStorage and never sent to any server except the OpenAI API.

MCP (Model Context Protocol) Configuration

Air Agent supports the Model Context Protocol, allowing you to connect to external MCP servers to extend the AI's capabilities with custom tools and resources.

Setting Up MCP Servers

Open MCP Configuration: Click the MCP configuration icon (⚙️) next to the settings icon in the top right corner
Add a Server: Click "Add Server" to configure a new MCP server
Configure Server Details:
- Server Name: A friendly name for your MCP server
- Server URL: Full URL to your MCP server endpoint (e.g., https://mcp-server.example.com)
- Description: Optional description of what the server provides
- API Key: Optional authentication token (if your server requires it)
- Enable: Toggle to enable/disable the server
Save: Click "Add Server" to save the configuration

Using MCP in Chat

Once you have configured MCP servers:

Enable MCP: Click the "MCP Disabled" button in the chat interface to enable MCP
Select Server: Choose which MCP server to use from the dropdown
Start Chatting: The AI will automatically discover and use tools from the connected MCP server

Connection Status

The chat interface shows the MCP connection status:

MCP Connected: Successfully connected to the server and tools are available
MCP Connecting...: Attempting to connect to the server
MCP Error: Connection failed (check the error message for details)

Requirements for MCP Servers

Since Air Agent is a browser-only application, your MCP server must:

Support HTTP/SSE Transport: Use the Streamable HTTP transport protocol
Enable CORS: Configure CORS headers to allow browser access from your deployment domain
Be Publicly Accessible: The server must be reachable from your browser (localhost won't work for deployed apps)

Session Management

Air Agent follows the MCP protocol standard for session management:

How it works:

When connecting to an MCP server, the client receives a session ID from the server
The session ID is automatically stored in browser localStorage
On reconnection or page reload, the stored session ID is reused to resume the session
The session ID is included in all MCP requests via the mcp-session-id header

Session Persistence:

Sessions persist across page reloads automatically via localStorage
Each MCP server URL has its own session ID
Session IDs are managed transparently by the client

This enables seamless session resumption without manual intervention.

Troubleshooting MCP Connections

Connection Failed / CORS Error

Ensure your MCP server has CORS properly configured
Check that the server URL is correct and publicly accessible
Verify that the server supports the Streamable HTTP transport

Tools Not Appearing

Make sure the MCP server is enabled in the configuration
Check that MCP is enabled for the current chat
Verify the server is returning tools in its tools/list response

Authentication Errors

Check that the API key is correct
Ensure the server expects Bearer token authentication
Verify the token has the necessary permissions

Tool Support

Air Agent now supports automatic tool calling with streaming responses. When the AI needs to use a tool:

The AI decides which tool to call based on the conversation
The tool executes automatically (e.g., calculator, time check)
Results are sent back to the AI
The AI continues its response with the tool results
All happens seamlessly in one conversation flow

Built-in Tools

Calculator: Performs arithmetic operations (add, subtract, multiply, divide)
Get Current Time: Returns current date and time with timezone support

Adding Custom Tools

See TOOL_IMPLEMENTATION.md for detailed documentation on:

Creating custom tools
MCP (Model Context Protocol) compatibility
Tool architecture and API
Best practices and examples

MCP Server

Air Agent includes a built-in MCP server that exposes tools and capabilities via the MCP HTTP transport protocol. This allows external MCP-compliant clients to connect to Air Agent and use its tools.

Note: The MCP server is opt-in and requires manual setup. It works when running npm run dev or when deployed to Node.js platforms (Vercel, Netlify, etc.). It is not available in static export mode (GitHub Pages).

MCP Server Features

✅ MCP HTTP Transport Compliant - Follows the official MCP specification
✅ Stateful Session Management - Secure session handling with unique session IDs
✅ Descriptive Error Messages - Clear, actionable error messages for integration issues
✅ SSE Streaming Support - Server-sent events for real-time notifications
✅ Tool Discovery - Clients can discover and call available tools
✅ Session Lifecycle Management - Proper initialization, usage, and cleanup

Enabling the MCP Server

To enable the MCP server, you need to manually create the API route:

1. Create the API route:

mkdir -p app/api/mcp
cat > app/api/mcp/route.ts << 'EOF'
import { handleMcpRequest } from "@/server/mcp/handler"

export const GET = handleMcpRequest
export const POST = handleMcpRequest
export const DELETE = handleMcpRequest
EOF

2. Run in development:

npm run dev

3. Or deploy to Node.js platforms:

npm run build
npm run start

MCP Server Endpoint

When running locally:

http://localhost:3000/api/mcp

When deployed to Node.js platforms:

https://your-domain.com/api/mcp

Quick Start

Initialize a session:

curl -X POST http://localhost:3000/api/mcp \
  -H "Content-Type: application/json" \
  -D - \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0.0"}}}'

Save the Mcp-Session-Id from the response headers
List available tools:

curl -X POST http://localhost:3000/api/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: <your-session-id>" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Call a tool:

curl -X POST http://localhost:3000/api/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: <your-session-id>" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"greet","arguments":{"name":"Alice"}}}'

Documentation

For complete documentation including:

Session management lifecycle
Error handling and troubleshooting
All available tools
Integration examples
Security considerations

See MCP_SERVER.md

Deployment

GitHub Pages

This repository includes a GitHub Actions workflow for automatic deployment to GitHub Pages.

Enable GitHub Pages in your repository settings:
- Go to Settings → Pages
- Set Source to "GitHub Actions"
Push to the main branch:

git push origin main

The site will be automatically built and deployed to https://<username>.github.io/air-agent/

Manual Deployment

You can deploy the out directory to any static hosting service:

Vercel: vercel --prod
Netlify: Drag and drop the out folder
AWS S3: Upload the out folder to your bucket
Any static host: Upload the contents of out directory

Technology Stack

Framework: Next.js 16 with App Router
AI Integration: Direct OpenAI API calls (client-side)
UI Components: shadcn/ui
Styling: Tailwind CSS v3
Theme: next-themes
Icons: Lucide React
Language: TypeScript

Privacy & Security

All API keys are stored locally in your browser
No data is sent to any third-party services except OpenAI
The application is completely client-side with no backend
Your conversations are not logged or stored anywhere

Development

Project Structure

air-agent/
├── app/                    # Next.js app directory
│   ├── globals.css        # Global styles
│   ├── layout.tsx         # Root layout
│   └── page.tsx           # Main page
├── components/            # React components
│   ├── ui/               # shadcn/ui components
│   ├── chat-interface.tsx
│   ├── settings-dialog.tsx
│   ├── theme-provider.tsx
│   └── theme-selector.tsx
├── lib/                   # Utility functions
│   └── utils.ts
├── public/               # Static assets
├── .github/
│   └── workflows/
│       └── deploy.yml    # GitHub Pages deployment
└── next.config.ts        # Next.js configuration

Available Scripts

npm run dev - Start development server
npm run build - Build for production
npm run start - Start production server (not needed for static export)
npm run lint - Run ESLint

License

MIT

Contributing

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

Name		Name	Last commit message	Last commit date
Latest commit History 38 Commits
.github/workflows		.github/workflows
.kiro/specs/chat-session-storage		.kiro/specs/chat-session-storage
.vscode		.vscode
__tests__		__tests__
app		app
components		components
docs		docs
lib		lib
public		public
scripts		scripts
server/mcp		server/mcp
.gitignore		.gitignore
README.md		README.md
SKILL.md		SKILL.md
components.json		components.json
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

Air Agent

Features

Screenshots

Light Theme

Dark Theme

Settings Dialog

Theme Selector

MCP Configuration

Getting Started

Prerequisites

Installation

Building for Production

Configuration

OpenAI API Key

OpenAI Base URL (Optional)

Theme

MCP (Model Context Protocol) Configuration

Setting Up MCP Servers

Using MCP in Chat

Connection Status

Requirements for MCP Servers

Session Management

Troubleshooting MCP Connections

Connection Failed / CORS Error

Tools Not Appearing

Authentication Errors

Tool Support

Built-in Tools

Adding Custom Tools

MCP Server

MCP Server Features

Enabling the MCP Server

MCP Server Endpoint

Quick Start

Documentation

Deployment

GitHub Pages

Manual Deployment

Technology Stack

Privacy & Security

Development

Project Structure

Available Scripts

License

Contributing

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages