Metadata-Version: 2.4
Name: mcp-server-table
Version: 0.1.0
Summary: Model Context Protocol (MCP) server for AI-driven ServiceNow table data export to XML attachments.
Author-email: Divya Shah <shah.divya.2206@example.com>
License: MIT
Project-URL: Homepage, https://github.com/divyashah0510/mcp-servicenow-exporter
Project-URL: Issues, https://github.com/divyashah0510/mcp-servicenow-exporter/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.116.1
Requires-Dist: mcp[cli]>=1.12.0
Requires-Dist: uvicorn>=0.35.0
Requires-Dist: zeep>=4.3.1
Dynamic: license-file

<div align="center">

# 🚀 ServiceNow MCP Server - AI-Powered Data Export Tool

[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue?style=for-the-badge&logo=python)](https://www.python.org/)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green?style=for-the-badge&logo=microsoft)](https://modelcontextprotocol.io/)
[![ServiceNow](https://img.shields.io/badge/ServiceNow-API-red?style=for-the-badge&logo=servicenow)](https://www.servicenow.com/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](https://opensource.org/licenses/MIT)
[![Status](https://img.shields.io/badge/Status-Active-brightgreen?style=for-the-badge)]()

**🎯 Transform ServiceNow data access with natural language commands**

*Export ServiceNow table data effortlessly using voice commands and AI - no complex APIs needed!*

[🚀 Quick Start](#-quick-start) • [📖 Documentation](#-documentation) • [💡 Examples](#-usage-examples) • [🤝 Contributing](#-contributing)

---

</div>

## 📋 Table of Contents

- [🌟 Overview](#-overview)
- [✨ Key Features](#-key-features)
- [🏗️ Architecture](#️-architecture)
- [⚡ Quick Start](#-quick-start)
- [🔧 Installation](#-installation)
- [⚙️ Configuration](#️-configuration)
- [💡 Usage Examples](#-usage-examples)
- [🎛️ Available Tools](#️-available-tools)
- [📊 Supported Formats](#-supported-formats)
- [🗺️ Table Mappings](#-table-mappings)
- [🔒 Authentication](#-authentication)
- [🐛 Troubleshooting](#-troubleshooting)
- [🤝 Contributing](#-contributing)
- [📄 License](#-license)

## 🌟 Overview

The **ServiceNow MCP Server** is a cutting-edge Model Context Protocol server that revolutionizes how you interact with ServiceNow data. By combining the power of AI with intuitive natural language processing, this tool transforms complex ServiceNow API operations into simple conversational commands.

<div align="center">

```mermaid
graph TD
    A[👤 User Voice Command] --> B[🤖 Claude AI]
    B --> C[🔧 MCP Server]
    C --> D[🌐 ServiceNow API]
    D --> E[📊 Data Processing]
    E --> F[📁 File Export]
    F --> G[💾 Downloads Folder]
```

</div>

### 🎯 Why Choose ServiceNow MCP Server?

- **🗣️ Voice-Controlled**: Use natural language commands instead of complex API calls
- **🧠 AI-Powered**: Intelligent table name resolution from conversational descriptions
- **⚡ Lightning Fast**: Optimized async operations for rapid data retrieval
- **🔒 Secure**: Built-in authentication and error handling
- **📱 Cross-Platform**: Works on Windows, macOS, and Linux
- **🎨 Multiple Formats**: Export to CSV, XML, or both simultaneously

## ✨ Key Features

<table>
<tr>
<td>

### 🎤 Natural Language Interface
- Convert "export server data" to actual table queries
- **NEW: [table_name] bracket syntax support**
- **Command: "Export data from Server[cmdb_ci_server] table"**
- Voice command support through Claude AI integration

</td>
<td>

### 📊 Smart Data Export
- Multiple export formats (CSV, XML, both)
- **XML format as default (per requirements)**
- Automatic file naming with timestamps
- **File attachment support for Claude AI**

</td>
</tr>
<tr>
<td>

### 🔧 Advanced API Support
- **REST API integration (default)**
- **SOAP API support (new)**
- **🚀 UNLIMITED RECORD EXPORT - Handles millions of records**
- **📊 Pagination and chunked processing for memory efficiency**
- Custom query filters with ServiceNow syntax
- Field selection for targeted exports

</td>
<td>

### 🛡️ Enterprise Ready
- Robust error handling and logging
- Secure authentication with environment variables
- Production-ready async architecture
- Cross-platform file handling

</td>
</tr>
</table>

## 🏗️ Architecture

<details>
<summary><strong>🔍 Click to expand architecture details</strong></summary>

### System Components

```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Claude AI     │───▶│   MCP Server     │───▶│   ServiceNow    │
│                 │    │                  │    │                 │
│ • NL Processing │    │ • Table Mapping  │    │ • REST API      │
│ • Tool Calling  │    │ • Data Export    │    │ • Authentication│
│ • User Interface│    │ • File Generation│    │ • Data Storage  │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌──────────────────┐
                       │ Local File System│
                       │                  │
                       │ • Downloads Folder│
                       │ • CSV/XML Files  │
                       │ • Auto Naming    │
                       └──────────────────┘
```

### Data Flow
1. **Input**: User provides natural language command
2. **Processing**: Claude AI interprets and calls appropriate MCP tool
3. **Resolution**: MCP server resolves table names and builds queries
4. **Retrieval**: Secure API calls to ServiceNow instance
5. **Transformation**: Data converted to requested format(s)
6. **Output**: Files saved to Downloads folder with confirmation

</details>

## ⚡ Quick Start

### 🚀 1-Minute Setup

```bash
# Clone the repository
git clone https://github.com/yourusername/servicenow-mcp-server.git
cd servicenow-mcp-server

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env with your ServiceNow credentials

# Run the server
python main.py
```

### 🎯 First Export

Once configured, try these natural language commands:

> **"Export the server table"**
> 
> **"Get me incident data in XML format"**
> 
> **"Export users with both CSV and XML"**

## 🔧 Installation

### Prerequisites

<div align="center">

| Requirement | Version | Purpose |
|-------------|---------|---------|
| Python | 3.8+ | Runtime environment |
| ServiceNow Instance | Any | Data source |
| Claude AI Access | Latest | Natural language interface |

</div>

### Step-by-Step Installation

<details>
<summary><strong>📦 Detailed Installation Guide</strong></summary>

1. **Clone Repository**
   ```bash
   git clone https://github.com/yourusername/servicenow-mcp-server.git
   cd servicenow-mcp-server
   ```

2. **Create Virtual Environment**
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

3. **Install Dependencies**
   ```bash
   pip install -r requirements.txt
   ```

4. **Environment Setup**
   ```bash
   cp .env.example .env
   ```
   
   Edit `.env` file:
   ```env
   SERVICENOW_INSTANCE=https://your-instance.service-now.com
   SERVICENOW_USERNAME=your_username
   SERVICENOW_PASSWORD=your_password
   ```

5. **Verify Installation**
   ```bash
   python -c "import main; print('✅ Installation successful!')"
   ```

</details>

### Requirements

```python
# Core dependencies
fastmcp>=0.1.0
httpx>=0.24.0
python-dotenv>=1.0.0

# Optional enhancements
rich>=13.0.0        # Better console output
typer>=0.9.0        # CLI interface
pytest>=7.0.0       # Testing framework
```

## ⚙️ Configuration

### Environment Variables

| Variable | Description | Example | Required |
|----------|-------------|---------|----------|
| `SERVICENOW_INSTANCE` | Your ServiceNow instance URL | `https://dev12345.service-now.com` | ✅ |
| `SERVICENOW_USERNAME` | ServiceNow username | `admin` | ✅ |
| `SERVICENOW_PASSWORD` | ServiceNow password | `your_password` | ✅ |

</details>

### 🎤 Voice Commands

<div align="center">

| Command | Result | Format |
|---------|--------|--------|
| *"Export the server table"* | ➡️ `cmdb_ci_server_export.csv` | CSV |
| *"Get incident data as XML"* | ➡️ `incident_export.xml` | XML |
| *"Export users in both formats"* | ➡️ Both CSV & XML files | Both |

</div>

### 📝 Detailed Examples

<details>
<summary><strong>🔍 Click to see detailed examples</strong></summary>

#### Basic Export
```python
# Command: "Export the server table"
# Result: Downloads/cmdb_ci_server_export_20241201_143022.csv
```

#### Filtered Export
```python
# Command: "Export active incidents from last week"
# Translates to query filter and exports matching records
```

#### Multi-Format Export
```python
# Command: "Export user data in both CSV and XML"
# Creates:
# - Downloads/sys_user_export_20241201_143022.csv
# - Downloads/sys_user_export_20241201_143022.xml
```

#### Custom Fields
```python
# Advanced usage through tool parameters:
# - table_description: "server table"
# - fields: "name,ip_address,sys_id"
# - max_records: 500
```

</details>

### 🔧 Primary Tools

<div align="center">

| Tool | Purpose | Input | Output |
|------|---------|-------|--------|
| `export_servicenow_data` | 🎯 Main export with bracket syntax | "[table_name] command" | XML attachment |
| `export_with_bracket_syntax` | 📋 Specialized bracket parser | Bracket syntax command | XML file |
| `export_table_to_xml` | 📄 Direct XML export | Table name | XML file |
| `list_common_tables` | 📋 Show table mappings | None | Table reference |

</div>

### 🆕 New Features for Unlimited Data Export

#### 1. Unlimited Record Processing
```python
# Now handles ANY number of records - 10K, 100K, 1M+
"Export ALL data from Server[cmdb_ci_server] table"
# Automatically uses pagination to fetch ALL records
```

#### 2. Memory-Efficient Processing
```python
# Chunked processing prevents memory overload
# - Fetches data in 1000-record chunks
# - Processes CSV in 5000-record chunks
# - Progress tracking for large datasets
```

#### 3. Performance Optimizations
```python
# Smart processing based on dataset size
# - Small datasets: Direct processing
# - Large datasets: Chunked processing with progress tracking
# - Memory management and garbage collection
```

#### 4. Enterprise-Scale Support
```python
# Production-ready for enterprise environments
# - Handles ServiceNow instances with millions of records
# - Automatic pagination and memory management
# - Robust error handling and recovery
```

## 🔒 Authentication

### 🛡️ Security Best Practices

<div align="center">

| ✅ Recommended | ❌ Avoid |
|----------------|----------|
| Environment variables | Hardcoded credentials |
| Dedicated service account | Personal accounts |
| Minimal required permissions | Admin privileges |
| Regular password rotation | Static passwords |

</div>

### ServiceNow Permissions

Required roles and permissions:
- **`rest_service`** - Access REST APIs
- **`table_reader`** - Read table data
- **Read access** to target tables (e.g., `cmdb_ci_server`, `incident`)
- **`itil`** - For incident management tables


<details>
<summary><strong>🔧 Detailed Permission Setup</strong></summary>

1. **Create Service Account**
   ```
   Navigate to: User Administration > Users
   Create new user with appropriate roles
   ```

2. **Assign Roles**
   ```
   Required roles:
   - rest_service
   - table_reader
   - Custom roles for specific tables if needed
   ```

3. **Test Access**
   ```bash
   curl -u username:password \
     "https://your-instance.service-now.com/api/now/table/incident?sysparm_limit=1"
   ```

</details>

## 🐛 Troubleshooting

### 🔍 Common Issues

<details>
<summary><strong>❌ Authentication Errors</strong></summary>

**Problem**: `HTTP 401 Unauthorized`

**Solutions**:
- ✅ Verify credentials in `.env` file
- ✅ Check ServiceNow instance URL format
- ✅ Ensure account has required roles
- ✅ Test with ServiceNow's REST API Explorer

</details>

<details>
<summary><strong>❌ Table Not Found</strong></summary>

**Problem**: `Table 'xyz' doesn't exist`

**Solutions**:
- ✅ Use `list_common_tables` tool to see available mappings
- ✅ Check table name spelling
- ✅ Verify table exists in your instance
- ✅ Ensure read permissions on the table

</details>

<details>
<summary><strong>❌ Export Failures</strong></summary>

**Problem**: Export process fails or incomplete

**Solutions**:
- ✅ Check network connectivity
- ✅ Reduce `max_records` parameter
- ✅ Verify Downloads folder permissions
- ✅ Review ServiceNow instance performance

</details>

### 🔧 Debug Mode

Enable detailed logging:
```bash
export DEBUG=1
python main.py
```

### 📞 Support

Need help? Check these resources:
- **[shah.divya.2206@gmail.com](mailto:shah.divya.2206@gmail.com)**


### 📋 Development Setup

<details>
<summary><strong>🔧 Development Environment Setup</strong></summary>

```bash
# Clone and setup
git clone https://github.com/yourusername/servicenow-mcp-server.git
cd servicenow-mcp-server

# Development environment
python -m venv dev-env
source dev-env/bin/activate  # Windows: dev-env\Scripts\activate

# Install dev dependencies
uv sync
```

</details>

## 📄 License

<div align="center">

This project is licensed under the **MIT License**.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

See the [LICENSE](LICENSE) file for details.

</div>

---

<div align="center">

### 🌟 Made with ❤️ by Divya Shah

**[⭐ Star this repo](https://github.com/divyashah0510/mcp-servicenow-exporter)** • **[🐛 Report Bug](https://github.com/divyashah0510/mcp-servicenow-exporter/issues)** • **[✨ Request Feature](https://github.com/divyashah0510/mcp-servicenow-exporter/issues)**

---

**Connect with me:**

[![GitHub](https://img.shields.io/badge/GitHub-100000?style=for-the-badge&logo=github&logoColor=white)](https://github.com/divyashah0510)
[![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/divya-d-shah)
[![Twitter](https://img.shields.io/badge/Twitter-1DA1F2?style=for-the-badge&logo=x&logoColor=white)](https://x.com/Divya_Shah22)

</div>
