@answerai/answeragent-mcp/README.md

A lightweight Model Context Protocol (MCP) server for Answer AI chatflow and document store management

# @answerai/answeragent-mcp

[![npm version](https://badge.fury.io/js/@answerai%2Fansweragent-mcp.svg)](https://badge.fury.io/js/@answerai%2Fansweragent-mcp)

A lightweight Model Context Protocol (MCP) server for Answer AI chatflow and document store management. This server exposes Answer AI's powerful features through standardized MCP tools and prompts, allowing you to manage chatflows, document stores, assistants, and more directly from your MCP-compatible AI clients.

## Installation

Install globally via npm:

```bash
npm install -g @answerai/answeragent-mcp
```

Or use with npx (no installation required):

```bash
npx @answerai/answeragent-mcp
```

## Quick Start

1. **Get Your Answer AI Credentials**:
   - API Base URL (e.g., `https://your-instance.studio.theanswer.ai`)
   - API Token (JWT token from your Answer AI instance)

2. **Test the Server**:
   ```bash
   npx @modelcontextprotocol/inspector @answerai/answeragent-mcp
   ```

## Client Configuration

### Cursor IDE

Add this configuration to your `~/.cursor/mcp.json` file:

```json
{
  "mcpServers": {
    "answerai-mcp": {
      "command": "node",
      "args": [
        "/path/to/your/project/dist/index.js"
      ],
      "env": {
        "ANSWERAGENT_AI_API_BASE_URL": "https://your-instance.studio.theanswer.ai",
        "ANSWERAGENT_AI_API_TOKEN": "your-jwt-token-here"
      }
    }
  }
}
```

**For NPM installed version:**
```json
{
  "mcpServers": {
    "answerai-mcp": {
      "command": "npx",
      "args": ["@answerai/answeragent-mcp"],
      "env": {
        "ANSWERAGENT_AI_API_BASE_URL": "https://your-instance.studio.theanswer.ai",
        "ANSWERAGENT_AI_API_TOKEN": "your-jwt-token-here"
      }
    }
  }
}
```

### Claude Desktop

Add this to your Claude Desktop MCP settings file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "answerai": {
      "command": "npx",
      "args": ["@answerai/answeragent-mcp"],
      "env": {
        "ANSWERAGENT_AI_API_BASE_URL": "https://your-instance.studio.theanswer.ai",
        "ANSWERAGENT_AI_API_TOKEN": "your-jwt-token-here"
      }
    }
  }
}
```

### Other MCP Clients (Cline, etc.)

Most MCP clients follow the same pattern:

```json
{
  "command": "npx",
  "args": ["@answerai/answeragent-mcp"],
  "env": {
    "ANSWERAGENT_AI_API_BASE_URL": "https://your-instance.studio.theanswer.ai",
    "ANSWERAGENT_AI_API_TOKEN": "your-jwt-token-here"
  }
}
```

## Configuration

The server requires two environment variables:

- `ANSWERAGENT_AI_API_BASE_URL`: Your Answer AI instance base URL (without `/api/v1`)
- `ANSWERAGENT_AI_API_TOKEN`: Your Answer AI JWT authentication token

**Important**: 
- Don't include `/api/v1` in the base URL - the server adds this automatically
- Make sure you're using a JWT token, not an API key
- The token must have appropriate permissions for the operations you want to perform

## Available Tools

### Chatflow Management
- `create_chatflow` - Create new chatflows
- `get_chatflow` - Retrieve chatflow details
- `update_chatflow` - Update existing chatflows
- `delete_chatflow` - Remove chatflows
- `list_chatflows` - List all chatflows

### Document Store Management
- `create_document_store` - Create document stores
- `get_document_store` - Get store details
- `delete_document_store` - Remove document stores
- `list_document_stores` - List all stores
- `query_vector_store` - Query document stores
- `upsert_document` - Add/update documents
- `refresh_document_store` - Refresh store contents

### Assistant Management
- `create_assistant` - Create AI assistants
- `get_assistant` - Get assistant details
- `update_assistant` - Update assistants
- `delete_assistant` - Remove assistants
- `list_assistants` - List all assistants

### Tool Management
- `create_tool` - Create custom tools
- `get_tool` - Get tool details
- `update_tool` - Update tools
- `delete_tool` - Remove tools
- `list_tools` - List all tools

### Document Loader Management
- `get_loader_chunks` - Get document chunks
- `update_loader_chunk` - Update chunks
- `delete_loader_chunk` - Remove chunks
- `delete_loader` - Remove loaders

## Intelligent Prompts

The server provides AI-powered prompts for advanced analysis and management:

### `analyze_chatflow`
Analyzes chatflow configuration and provides optimization recommendations.

**Arguments:**
- `chatflowId` (required): The chatflow ID to analyze
- `focusAreas` (optional): Array of specific areas to focus on

### `analyze_document_store`
Analyzes document store configuration, loaders, and usage patterns.

**Arguments:**
- `documentStoreId` (required): The document store ID to analyze
- `focusAreas` (optional): Array of specific areas to focus on

### `manage_document_store`
Provides step-by-step guidance for document store operations.

**Arguments:**
- `action` (required): One of "setup", "optimize", "troubleshoot", "migrate"
- `documentStoreId` (optional): Target document store ID
- `context` (optional): Additional context for the operation

## Usage Examples

### With Cursor IDE

After configuring in Cursor, you can use natural language commands:

1. **List your chatflows**:
   > "Show me all my Answer AI chatflows"

2. **Analyze a specific chatflow**:
   > "Analyze the 'RDS Call Analysis' chatflow and suggest optimizations"

3. **Create a document store**:
   > "Create a new document store called 'Customer Support KB' for storing help articles"

4. **Query documents**:
   > "Search my 'Contracts' document store for information about payment terms"

### With Claude Desktop

After adding to your Claude Desktop configuration:

1. **Analyze a chatflow**:
   > "Please analyze my chatflow with ID 'df23d39c-a25b-4842-8997-dce3afed88f4' and focus on performance optimization"

2. **Document store management**:
   > "Help me troubleshoot my document store that's not syncing properly"

3. **Assistant management**:
   > "Show me details about my 'Document Reader' assistant and suggest improvements"

### With MCP Inspector

Test and explore the server capabilities:

```bash
npx @modelcontextprotocol/inspector @answerai/answeragent-mcp
```

## Troubleshooting

### Common Issues

1. **401 Unauthorized Error**:
   - Check that your JWT token is valid and not expired
   - Ensure you're using a JWT token, not an API key
   - Verify the token has the necessary permissions

2. **Connection Issues**:
   - Confirm your base URL is correct (without `/api/v1`)
   - Check that your Answer AI instance is accessible
   - Verify environment variables are set correctly

3. **Tool Not Found**:
   - Restart your MCP client after configuration changes
   - Check the server logs for any startup errors
   - Verify the package is properly installed

## Requirements

- Node.js 18+
- Valid Answer AI JWT token with appropriate permissions
- MCP-compatible client (Claude Desktop, Cursor, Cline, etc.)

## Support

For issues and feature requests, visit our [GitHub repository](https://github.com/bradtaylor/answerai-mcp).

## License

ISC