npm package: @prosci/kaiya-mcp-server
Description: MCP server for Kaiya AI assistant integration
Latest version: 0.1.2

# Kaiya MCP Server

A Model Context Protocol (MCP) server that provides integration with the Kaiya AI assistant. This server allows MCP-compatible clients (like Claude Desktop) to interact with your Kaiya AI backend through a standardized protocol.

## Features

- 🤖 **AI Chat Integration**: Direct communication with Kaiya AI assistant
- 🔐 **Bearer Token Authentication**: Secure API authentication using environment variables
- 📝 **Session Support**: Optional chat session ID for conversation continuity
- 🔍 **Debug Logging**: Built-in request/response logging for troubleshooting

## Prerequisites

- Node.js 22.0.0 or higher
- Valid Bearer token for Kaiya API authentication

## Installation

1. Clone or download this repository
2. Install dependencies:
   ```bash
   npm install
   ```

## Configuration

The server uses environment variables for configuration:

### Required
- `KAIYA_API_KEY`: Your Bearer token for Kaiya API authentication

### Setting Environment Variables

#### Option 1: .env File (Recommended for development)
Create a `.env` file in the project root:
```bash
KAIYA_API_KEY=your-bearer-token-here
```

#### Option 2: System Environment Variables
```bash
export KAIYA_API_KEY=your-bearer-token-here
```

## Usage

### Testing with MCP Inspector

For development and testing, use the MCP Inspector:

```bash
# With .env file
npx @modelcontextprotocol/inspector index.js

# Or with inline environment variables
KAIYA_API_KEY=your-token npx @modelcontextprotocol/inspector index.js
```

The inspector will start:
- **Client UI**: http://localhost:5173 (default)
- **MCP Proxy Server**: http://localhost:3000 (default)

### Integration with Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "kaiya-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/kaiya-mcp-server/index.js"],
      "env": {
        "KAIYA_API_KEY": "your-bearer-token-here"
      }
    }
  }
}
```

**Important**: Use absolute paths in the configuration file.

## Available Tools

### `kaiya_chat`

Chat with the Kaiya AI assistant.

**Parameters:**
- `prompt` (required): The message/prompt to send to Kaiya
- `chat_session_id` (optional): Session identifier for conversation continuity

**Example:**
```json
{
  "prompt": "How can I improve my project management skills?",
  "chat_session_id": "session_123"
}
```

**Response:**
Returns the Kaiya AI response as formatted JSON.

## API Endpoint

The server communicates with your Rails API at:
```
POST {RAILS_BASE_URL}/api/v1/kaiya/chat
```

**Request Format:**
```json
{
  "prompt": "user message",
  "chat_session_id": "optional_session_id"
}
```

**Headers:**
- `Content-Type: application/json`
- `Accept: */*`
- `Authorization: Bearer {KAIYA_API_KEY}`

## Development

### Running the Server Directly
```bash
node index.js
```

### With Auto-reload (Development)
```bash
npm run dev
```

### Debug Mode
The server automatically logs:
- Request URLs and payloads
- API key presence (without exposing the actual key)
- Response status

## Troubleshooting

### Common Issues

1. **401 Unauthorized Error**
   - Check that `KAIYA_API_KEY` is set correctly
   - Verify the Bearer token is valid
   - Ensure your Rails API is running and accessible

2. **Connection Refused**
   - Verify `RAILS_BASE_URL` points to your running Rails server
   - Check that the Rails server is accepting connections
   - Ensure the `/api/v1/kaiya/chat` endpoint exists

3. **MCP Inspector Not Connecting**
   - Make sure you're using Node.js 22.0.0 or higher
   - Try restarting the inspector
   - Check console logs for error messages

4. **Environment Variables Not Loading**
   - Ensure `.env` file is in the project root
   - Check that `dotenv/config` is imported correctly
   - Verify environment variable names match exactly

### Debug Logging

The server logs important information to stderr:
- Request details (URL, payload)
- Authentication status
- API responses

Monitor these logs when troubleshooting issues.

## Project Structure

```
kaiya-mcp-server/
├── index.js              # Main server implementation
├── package.json          # Node.js dependencies and scripts
├── package-lock.json     # Dependency lock file
├── .env                  # Environment variables (create this)
└── README.md            # This file
```

## Dependencies

- `@modelcontextprotocol/sdk`: MCP protocol implementation
- `node-fetch`: HTTP client for API requests
- `dotenv`: Environment variable loading

## License

This project is licensed under the MIT License.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with MCP Inspector
5. Submit a pull request

## Support

For issues and questions:
1. Check the troubleshooting section above
2. Review server logs for error details
3. Verify your Rails API is responding correctly
4. Test with MCP Inspector before integrating with other clients

---

**Note**: This MCP server is designed to work with the Kaiya AI Rails backend. Ensure your Rails API implements the expected `/api/v1/kaiya/chat` endpoint with Bearer token authentication.