# Infor Birst MCP Server

An MCP (Model Context Protocol) server that exposes Infor Birst's analytics platform capabilities as AI-consumable tools.

## Features

**41 MCP Tools** enabled by default, organized in 7 tiers (up to 46 with optional features):

### Tier 1: Core Query Tools (0-5 tools, optional)

These tools execute queries against live data and are **disabled by default** as a safeguard. Enable them explicitly when needed.

**GenAI Tools** (require Birst AI entitlement - set `BIRST_ENABLE_GENAI=true`):
- `birst_generate_bql` - Convert natural language to BQL queries
- `birst_search_data` - Search data warehouse with natural language
- `birst_generate_chart` - Generate chart specifications from text

**ICW Tools** (require application provisioning - set `BIRST_ENABLE_ICW=true`):
- `birst_execute_query` - Execute BQL queries and return results
- `birst_validate_query` - Validate BQL syntax before execution

> **Why disabled by default?** These tools can execute arbitrary queries against your data warehouse. Requiring explicit opt-in ensures you consciously enable query execution capabilities.

### Tier 2: Discovery Tools (8 tools)
- `birst_list_spaces` - List all accessible analytical spaces
- `birst_get_space` - Get detailed space information
- `birst_list_reports` - List reports in a space (with pagination)
- `birst_get_report` - Get detailed report information
- `birst_list_dashboards` - List dashboards in collections
- `birst_get_dashboard` - Get detailed dashboard information
- `birst_list_collections` - List collections in a space
- `birst_search_catalog` - Search catalog entities

### Tier 3: Infrastructure Tools (17 tools)
- `birst_list_connections` - List data connections
- `birst_list_sources` - List data sources
- `birst_get_source` - Get source details
- `birst_create_source` - Create a new source
- `birst_update_source` - Update source configuration
- `birst_delete_source` - Delete a source
- `birst_list_joins` - List joins between sources
- `birst_create_join` - Create a join relationship
- `birst_delete_join` - Delete a join relationship
- `birst_list_variables` - List space variables (includes GUID for CRUD)
- `birst_create_variable` - Create a new variable
- `birst_update_variable` - Update a variable
- `birst_delete_variable` - Delete a variable
- `birst_list_hierarchies` - List dimensional hierarchies
- `birst_create_hierarchy` - Create a hierarchy
- `birst_add_hierarchy_level` - Add level to hierarchy
- `birst_get_dataflow` - Get data flow visualization

### Tier 4: Workflow Tools (4 tools)
- `birst_list_workflows` - List available workflows
- `birst_run_workflow` - Trigger workflow execution
- `birst_get_workflow_status` - Monitor workflow status
- `birst_list_workflow_runs` - Get workflow execution history

### Tier 5: Administration Tools (5 tools)
- `birst_list_users` - List users in account
- `birst_list_space_users` - List users with space access
- `birst_list_account_groups` - List account groups
- `birst_list_space_groups` - List space groups
- `birst_space_action` - Perform space actions (replicate, publish, clear cache, etc.)

### Tier 6: Job Tracking Tools (2 tools)
- `birst_get_job_status` - Get status of a running/completed job
- `birst_job_action` - Cancel or clear job status

### Tier 7: Package Management Tools (5 tools)
- `birst_list_packages` - List packages in a space
- `birst_list_available_packages` - List packages available for import
- `birst_import_package` - Import a package into a space
- `birst_create_package` - Create a new package
- `birst_delete_package` - Delete a package

## Installation

```bash
npm install
```

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `BIRST_ENV` | Environment to use (TST, PRD, TRN) | TST |
| `BIRST_IONAPI_PATH` | Custom path to .ionapi file | Auto-detected |
| `BIRST_LOG_LEVEL` | Log level (debug, info, warn, error) | info |
| `BIRST_ENABLE_GENAI` | Enable GenAI tools (requires Birst AI entitlement) | false |
| `BIRST_ENABLE_ICW` | Enable ICW query tools (requires app provisioning) | false |

### ION API Credentials

Place your `.ionapi` files in the project root or `credentials/` directory:

```
infor-birst-mcp/
├── TST.ionapi    # Test environment
├── PRD.ionapi    # Production environment
└── TRN.ionapi    # Training environment
```

The `.ionapi` file is obtained from Infor Cloud Suite and contains OAuth2 credentials.

## Usage

### Development

```bash
npm run dev
```

### Production

```bash
npm run build
npm start
```

### Claude Code Configuration

Add to your Claude Code MCP settings:

```json
{
  "mcpServers": {
    "infor-birst": {
      "command": "node",
      "args": ["/path/to/infor-birst-mcp/dist/index.js"],
      "env": {
        "BIRST_ENV": "TST"
      }
    }
  }
}
```

To enable query execution tools:

```json
{
  "mcpServers": {
    "infor-birst": {
      "command": "node",
      "args": ["/path/to/infor-birst-mcp/dist/index.js"],
      "env": {
        "BIRST_ENV": "TST",
        "BIRST_ENABLE_ICW": "true",
        "BIRST_ENABLE_GENAI": "true"
      }
    }
  }
}
```

### Testing with MCP Inspector

Use the MCP Inspector to test tools interactively:

```bash
# Basic (41 tools)
BIRST_ENV=TST npx @modelcontextprotocol/inspector node dist/index.js

# With query tools enabled (46 tools)
BIRST_ENV=TST BIRST_ENABLE_ICW=true BIRST_ENABLE_GENAI=true npx @modelcontextprotocol/inspector node dist/index.js
```

This opens a web UI where you can call any tool and see responses.

## Example Usage

Once configured, you can use the tools in Claude:

```
"List all my Birst spaces"
→ Uses birst_list_spaces

"Show me reports in this space"
→ Uses birst_list_reports

"What workflows are scheduled to run?"
→ Uses birst_list_workflows with filter=isScheduled

"Who has access to this space?"
→ Uses birst_list_space_users
```

With GenAI enabled (`BIRST_ENABLE_GENAI=true`):
```
"Show me sales by region for 2024"
→ Uses birst_generate_bql + birst_execute_query
```

## Supported Environments

- **TST** - Test environment
- **PRD** - Production environment
- **TRN** - Training environment

Switch environments by setting the `BIRST_ENV` variable or using the default (TST).

## API Coverage

This MCP server interfaces with 3 Birst APIs:

| API | Endpoints | Description |
|-----|-----------|-------------|
| REST API | 156 | Space management, users, workflows |
| GenAI API | 3 | Natural language to BQL, chart generation |
| ICW API | 5 | Query execution and validation |

## Security

- Credentials are stored in `.ionapi` files (gitignored)
- OAuth2 tokens are automatically refreshed
- All API calls are authenticated via Bearer token
- Sensitive data is never logged

## License

MIT