# Appian MCP Server

A Model Context Protocol (MCP) server for seamless integration with Appian APIs using Node.js.

## Overview

This MCP server provides a standardized interface to interact with Appian applications, allowing AI applications to:
- Query and manage records
- Create, update, and delete records
- Execute processes
- Query reports

## Features

- **Record Management**: Get, create, update, and delete Appian records
- **Process Execution**: Execute Appian processes with input parameters
- **Report Querying**: Query Appian reports with filters
- **TypeScript Support**: Built with TypeScript for type safety
- **Error Handling**: Comprehensive error handling and logging
- **Configurable Authentication**: Support for API keys and OAuth

## Prerequisites

- Node.js 16 or higher
- npm or yarn
- Appian configuration (tenant, credentials)

## Installation

1. Clone or navigate to the project directory
2. Install dependencies:
```bash
npm install
```

3. Set up environment variables:
```bash
cp .env.example .env
# Edit .env with your Appian credentials
```

## Configuration

### Environment Variables

- `APPIAN_TENANT`: Your Appian tenant name (e.g., "mycompany")
- `APPIAN_API_KEY`: API key for authentication (recommended)
- `APPIAN_CLIENT_ID`: OAuth client ID (alternative authentication)
- `APPIAN_CLIENT_SECRET`: OAuth client secret (alternative authentication)
- `APPIAN_BASE_URL`: Custom Appian API base URL (optional)

### MCP Configuration

The `.vscode/mcp.json` file configures the MCP server for use with LLM applications:

```json
{
  "servers": {
    "appian-mcp-server": {
      "type": "stdio",
      "command": "node",
      "args": ["dist/index.js"]
    }
  }
}
```

## Available Tools

### get_records
Retrieve records from an Appian record type.

**Parameters:**
- `recordType` (string, required): The name of the Appian record type
- `limit` (integer, optional): Maximum number of records to return (default: 100)
- `offset` (integer, optional): Number of records to skip for pagination (default: 0)

### create_record
Create a new record in an Appian application.

**Parameters:**
- `recordType` (string, required): The name of the Appian record type
- `data` (object, required): The record data to create

### update_record
Update an existing record.

**Parameters:**
- `recordType` (string, required): The name of the Appian record type
- `recordId` (string, required): The ID of the record to update
- `data` (object, required): The fields to update

### delete_record
Delete a record from an Appian application.

**Parameters:**
- `recordType` (string, required): The name of the Appian record type
- `recordId` (string, required): The ID of the record to delete

### execute_process
Execute an Appian process.

**Parameters:**
- `processName` (string, required): The name of the Appian process
- `inputs` (object, optional): Input parameters for the process

### query_report
Query an Appian report.

**Parameters:**
- `reportName` (string, required): The name of the Appian report
- `filters` (object, optional): Filters to apply to the report

## Building

Build the TypeScript source to JavaScript:

```bash
npm run build
```

## Development

For development with automatic compilation:

```bash
npm run watch
```

Then in another terminal, start the server:

```bash
npm start
```

## Running the MCP Server

### Direct Execution

```bash
npm run dev
```

### In VS Code

1. Ensure the project is built: `npm run build`
2. Use the MCP inspector tool or connect through an LLM application
3. The server will communicate via stdio

## API Integration

The server uses axios for HTTP communication with Appian REST APIs. Update the `appian-client.ts` file to add additional Appian operations as needed.

## Error Handling

The server includes comprehensive error handling for:
- Network failures
- Authentication errors
- Invalid record types or IDs
- API validation errors

Errors are returned in the MCP response format with detailed error messages.

## Extending the Server

To add new Appian operations:

1. Add a new method to `AppianClient` in `src/appian-client.ts`
2. Add a new tool definition in the `ListToolsRequestSchema` handler in `src/index.ts`
3. Add a new case in the `CallToolRequestSchema` handler to call your method
4. Rebuild: `npm run build`

## Security Considerations

- Store API keys securely (use environment variables or secret management)
- Never commit `.env` files to version control
- Use HTTPS for all Appian API communication
- Implement proper access controls in your LLM application

## Troubleshooting

### Connection Issues
- Verify your `APPIAN_TENANT` is correct
- Ensure your API key is valid and has necessary permissions
- Check that your Appian instance is accessible from your network

### Authentication Errors
- Verify credentials in your `.env` file
- Check that the API key hasn't expired
- Confirm proper authentication method is configured

### Build Errors
- Ensure TypeScript is installed: `npm install`
- Check for TypeScript compilation errors: `npm run build`

## License

MIT

## Resources

- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
- [Appian REST API Documentation](https://docs.appian.com/suite/help/latest/cheatsheet/a_cheatsheet_for_the_appian_apis.html)
- [TypeScript MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk)