Metadata-Version: 2.4
Name: mcp-json-soap-sql-queue-file-adapters
Version: 0.1.1
Summary: Model Context Protocol (MCP) server with four comprehensive adapters: JSON-to-SOAP XML transformation, JSON-to-SQL query generation, JSON-to-Kafka message queue integration, and JSON-to-File format conversion with SFTP support
Author-email: MCP Development Team <ramkumar.b@finastra.com>
License: MIT
Keywords: mcp,model-context-protocol,adapters,soap,xml,sql,database,kafka,message-queue,json,json-to-xml,json-to-sql,json-to-kafka,sftp,file-adapter,integration
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=0.1.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: click>=8.0.0
Provides-Extra: sql
Requires-Dist: pymysql>=1.1.0; extra == "sql"
Provides-Extra: queue
Requires-Dist: kafka-python>=2.0.0; extra == "queue"
Provides-Extra: file
Requires-Dist: paramiko>=3.0.0; extra == "file"
Provides-Extra: all
Requires-Dist: pymysql>=1.1.0; extra == "all"
Requires-Dist: kafka-python>=2.0.0; extra == "all"
Requires-Dist: paramiko>=3.0.0; extra == "all"
Dynamic: license-file

# mcp-json-soap-sql-queue-file-adapters

A **Model Context Protocol (MCP)** server that exposes four powerful tools for JSON transformation and integration workflows.

## How it works

```
JSON payload + parameters
        │
        ▼
   ┌─────────────────────────────┐
   │  Four Transformation Tools  │
   │  1. JSON → SOAP XML         │
   │  2. JSON → SQL Query        │
   │  3. JSON → Message Queue    │
   │  4. JSON → File Formats     │
   └─────────────────────────────┘
```

Give the server a JSON payload and parameters—it transforms it into your target format (SOAP XML, SQL queries via LLM, message queue messages, or file formats).

## Quickstart — run without installing (recommended)

```bash
uvx --from mcp-json-soap-sql-queue-file-adapters mcp-adapters
```

`uvx` downloads the package from PyPI into a temporary isolated environment and runs it immediately. No global install, no dependency conflicts.

## Plug into any MCP-compatible agent

```python
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain.agents import create_agent

client = MultiServerMCPClient(
   {
      "adapters": {
         "transport": "stdio",
         "command": "uvx",
         "args": [
            "--from",
            "mcp-json-soap-sql-queue-file-adapters",
            "mcp-adapters",
         ],
      }
   }
)
tools = await client.get_tools()

agent = create_agent(
   model=model,
   tools=tools,
)
```

## Tools

### 1. json_to_soap_xml

**What it does:** Converts a JSON object into a SOAP XML envelope with configurable namespaces and SOAP versions. Useful for integrating with legacy SOAP-based web services.

**Prerequisites:** None. Uses Python standard library only.

**Library dependencies:** None (built-in `xml.etree`)

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `operation_name` | ✅ | — | SOAP operation/method name |
| `payload` | ✅ | — | JSON dictionary to convert |
| `target_namespace` | ✅ | — | Target namespace URI |
| `namespace_prefix` | ❌ | `tns` | Namespace prefix |
| `soap_version` | ❌ | `1.1` | SOAP version (`1.1` or `1.2`) |
| `include_xml_declaration` | ❌ | `true` | Include XML declaration |

---

### 2. json_to_sql_query

**What it does:** Converts natural language questions into SQL SELECT queries. Uses an LLM to generate valid SQL, introspects your MySQL schema at runtime, validates the query (SELECT-only), and optionally executes it against your database.

**Prerequisites:** 
- ✅ An LLM API key (OpenAI, Azure OpenAI, or Anthropic)
- ✅ MySQL database server running (optional: only needed if executing queries, not for dry-run)

**Library dependencies:** 
- `pymysql>=1.1.0` — Install with: `pip install "mcp-json-soap-sql-queue-file-adapters[sql]"`

**Workflow:**
```
question + MySQL creds
        │
        ▼
  schema introspection  ──►  LLM  ──►  SQL validator  ──►  (execute)
```

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `question` | ✅ | — | Natural language question about your data |
| `host` | ✅ | — | MySQL server hostname or IP |
| `username` | ✅ | — | MySQL username |
| `password` | ✅ | — | MySQL password |
| `database_name` | ✅ | — | Target database name |
| `port` | ❌ | `3306` | MySQL port |
| `table` | ❌ | `all` | Restrict to single table or `all` for full schema |
| `max_retries` | ❌ | `0` | LLM retry attempts if SQL validation fails |
| `debug` | ❌ | `false` | Include internal workflow logs in response |

---

### 3. json_to_msgqueue

**What it does:** Serializes a JSON payload into a message-queue message and publishes it to Kafka. Internally converts JSON to XML with correlation IDs and timestamps for traceability.

**Prerequisites:**
- ✅ **Kafka broker** running and accessible on your network
- ✅ **Broker address and credentials** (host and port)

**Library dependencies:**
- `kafka-python>=2.0.0` — Install with: `pip install "mcp-json-soap-sql-queue-file-adapters[queue]"`

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `payload` | ✅ | — | JSON object to serialize into the message body |
| `queue_type` | ❌ | `kafka` | Target queue type (currently only `kafka` supported) |
| `topic` | ❌ | `default` | Target Kafka topic name |
| `correlation_id` | ❌ | Auto-generated | Request tracking ID |
| `kafka_headers` | ❌ | `null` | Optional Kafka message headers (dict) |

**Kafka Broker Setup**

You must set up a Kafka broker before using this tool. For local development, the easiest approach is using Docker Compose:

1. **Create a `docker-compose.yml` in your project root:**
   ```yaml
   version: '3.8'
   services:
     kafka:
       image: confluentinc/cp-kafka:7.5.0
       container_name: kafka-local
       environment:
         KAFKA_BROKER_ID: 1
         KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
         KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092
         KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
       depends_on:
         - zookeeper
       ports:
         - "9092:9092"

     zookeeper:
       image: confluentinc/cp-zookeeper:7.5.0
       container_name: zookeeper-local
       environment:
         ZOOKEEPER_CLIENT_PORT: 2181
       ports:
         - "2181:2181"
   ```

2. **Start Kafka and Zookeeper:**
   ```bash
   docker-compose up -d
   ```

3. **Verify Kafka is running:**
   ```bash
   docker ps | grep kafka
   ```

4. **Configure environment variables:**
   Create or update your `.env` file with:
   ```bash
   KAFKA_BROKERS=localhost:19092
   KAFKA_CLIENT_ID=tool-queue-adapter
   KAFKA_RETRY_ATTEMPTS=3
   KAFKA_TIMEOUT_MS=30000
   ```

5. **Stop Kafka when done:**
   ```bash
   docker-compose down
   ```

---

### 4. json_to_other_files

**What it does:** Generates files in different formats (CSV, delimited text, or Markdown) from JSON data and uploads them to an SFTP server. Useful for exporting data to various formats for downstream systems.

**Prerequisites:**
- ✅ **SFTP server** running and accessible on your network
- ✅ **SFTP credentials** (host, port, username, password, remote directory path)
- ✅ **Writable remote directory** on the SFTP server

**Library dependencies:**
- `paramiko>=3.0.0` — Install with: `pip install "mcp-json-soap-sql-queue-file-adapters[file]"`

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `tenant_id` | ✅ | — | Tenant identifier used in output file naming |
| `user_id` | ✅ | — | Caller identifier for request logging |
| `file_type` | ✅ | — | Output format (`csv`, `delimited`, or `markdown`) |
| `data` | ✅ | — | JSON object to convert |
| `delim_char` | ❌ | `null` | Delimiter character when `file_type` is `delimited` |

**Supported formats:**
- **CSV** — Standard comma-separated values with headers
- **Delimited** — Custom-delimited format (e.g., pipe `|`, tab `\t`, semicolon `;`)
- **Markdown** — Markdown table format for documentation

**SFTP Server Setup**

You must set up an SFTP server before using this tool. For local development, follow these steps using WSL with `openssh-server`:

1. **Install and start SSH server in WSL:**
   ```bash
   sudo apt install openssh-server
   sudo service ssh start
   ```

2. **Create the target remote directory:**
   ```bash
   mkdir -p /home/your_username/sftp
   ```

3. **Test SFTP connectivity:**
   ```bash
   sftp your_username@localhost
   ```
   When prompted, enter your WSL password. If login succeeds, you'll enter an SFTP prompt.

4. **Verify directory access:**
   ```bash
   cd /home/your_username/sftp
   ls
   ```
   If you can change into the directory and list files, the setup is complete.

5. **Configure environment variables:**
   Create or update your `.env` file with:
   ```bash
   SFTP_HOST=localhost
   SFTP_PORT=22
   SFTP_USERNAME=your_username
   SFTP_PASSWORD=your_password
   SFTP_REMOTE_DIRECTORY=/home/your_username/sftp
   ```
   Replace `your_username` with your actual WSL username and set `SFTP_PASSWORD` to your WSL password.

## Required environment variables

Set these before starting the server (in your shell or a `.env` file in the working directory):

### For json_to_sql_query (SQL Query Adapter)

Set one of these LLM API keys:

```bash
# OpenAI
OPENAI_API_KEY=sk-...

# Azure OpenAI
AZURE_OPENAI_API_KEY=your-key
AZURE_OPENAI_ENDPOINT=https://<resource>.openai.azure.com/
AZURE_DEPLOYMENT=your-deployment-name
AZURE_OPENAI_API_VERSION=2024-02-15-preview

# Anthropic (Claude)
ANTHROPIC_API_KEY=sk-ant-...
```

### For json_to_msgqueue (Message Queue Adapter)

```bash
KAFKA_BROKERS=localhost:19092
KAFKA_CLIENT_ID=tool-queue-adapter
KAFKA_RETRY_ATTEMPTS=3
KAFKA_TIMEOUT_MS=30000
```

### For json_to_other_files (File Export Adapter)

```bash
SFTP_HOST=sftp.example.com
SFTP_PORT=22
SFTP_USERNAME=user
SFTP_PASSWORD=pass
SFTP_REMOTE_DIRECTORY=/uploads/
```



## Prerequisites

Each tool requires different infrastructure to be available:

### For json_to_soap_xml
✅ **No prerequisites** — Uses Python standard library only.

### For json_to_sql_query
✅ **MySQL database server** running (optional: only for query execution, not for dry-run)
- Host, port, username, password with SELECT privileges on target database

✅ **LLM API** from OpenAI, Azure OpenAI, or Anthropic (set environment variables above)

### For json_to_msgqueue
✅ **Kafka broker** running and accessible
- Setup required before using this tool
- Use Docker Compose for local development (see Kafka Broker Setup under `json_to_msgqueue` tool section)
- Broker address and port
- Credentials set via environment variables (see Required environment variables section)

### For json_to_other_files
✅ **SFTP server** running and accessible
- Setup required before using this tool
- Use WSL with `openssh-server` for local development (see SFTP Server Setup under `json_to_other_files` tool section)
- SFTP host, port, username, password, and remote directory path
- Remote directory must be writable by the SFTP user
- Credentials set via environment variables (see Required environment variables section)

---


## Project structure

```
mcp_server/
  ├── mcp_server.py              ← MCP server entry point + 4 tools
  ├── mcp_tools_soap_adapter/    ← SOAP XML conversion
  ├── mcp_tools_sql_adapter/     ← SQL generation + validation + execution
  ├── mcp_tools_queue_adapter/   ← Message queue serialization
  └── mcp_tools_file_adapter/    ← File format conversion
pyproject.toml                    ← Package metadata + dependencies
LICENSE                           ← MIT License
README.md                         ← This file
```

## License

MIT — see [LICENSE](LICENSE) for details.
