suitecrm-mcp-server/README.md

Model Context Protocol server for SuiteCRM integration with natural language SQL reporting

# SuiteCRM MCP Server

A Model Context Protocol (MCP) server for SuiteCRM integration using TypeScript and the official MCP SDK.

## Features

- ✅ Full MCP Protocol Implementation using @modelcontextprotocol/sdk
- ✅ TypeScript with strict type checking
- ✅ OAuth 2.0 Authentication with client credentials flow
- ✅ Four Core Tools:
  - `authenticate_crm` - Authenticate with SuiteCRM
  - `get_modules` - Fetch available CRM modules
  - `get_module_schema` - Get detailed module schemas
  - `execute_query` - Execute SQL queries with security validation
- ✅ Security Features: SQL injection prevention, query validation
- ✅ Performance: Token caching, schema caching, connection pooling
- ✅ Production-ready logging with Winston

## Quick Start

### Prerequisites

- Node.js 18.0.0 or higher
- SuiteCRM instance with REST API enabled
- OAuth 2.0 client credentials

### Installation

1. **Install dependencies**
   ```bash
   npm install
   ```

2. **Configure environment**
   ```bash
   cp .env.example .env
   # Edit .env with your SuiteCRM credentials
   ```

3. **Build and start**
   ```bash
   npm run build
   npm start
   ```

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `SUITECRM_URL` | SuiteCRM instance URL | `http://localhost/suitecrm` |
| `SUITECRM_CLIENT_ID` | OAuth client ID | - |
| `SUITECRM_CLIENT_SECRET` | OAuth client secret | - |
| `LOG_LEVEL` | Logging level | `info` |
| `MAX_QUERY_ROWS` | Maximum rows per query | `100` |

## API Tools

### 1. authenticate_crm
Authenticate with SuiteCRM using client credentials.

**Parameters:** `crm_url`, `client_id`, `client_secret`

### 2. get_modules
Fetch available CRM modules.

**Parameters:** `crm_url`, `access_token`

### 3. get_module_schema
Get detailed schema for a specific module.

**Parameters:** `crm_url`, `access_token`, `module_name`

### 4. execute_query
Execute SQL query against CRM database.

**Parameters:** `crm_url`, `access_token`, `sql_query`

## Security

- SQL injection prevention
- Query complexity analysis
- Input sanitization
- Audit logging
- Query limits and timeouts

## Development

```bash
npm run dev      # Development mode
npm run build    # Build TypeScript
npm test         # Run tests
npm run lint     # Run ESLint
```

## License

MIT License