# Oracle Fusion AR MCP Server 🚀

A **remote** Model Context Protocol (MCP) server built in Python that provides secure access to Oracle Fusion Cloud Accounts Receivable REST API. Deploy once, share with everyone!

## 🌟 Key Features

- **🌐 Remote MCP Server**: Deploy to cloud and share via URL
- **🔒 Secure**: No credential storage, per-request authentication
- **📊 Three MCP Tools**:
  - `oracle_ar_list_invoices` - List and filter invoices
  - `oracle_ar_get_invoice_details` - Get detailed invoice information
  - `oracle_ar_search_invoices` - Advanced search with statistics
- **📝 Dual Output**: Both JSON and human-readable Markdown
- **⚡ Fast**: Built with Python + uv + httpx (async)
- **☁️ Cloud-Ready**: One-click deploy to Railway, Render, Heroku

## 🚀 Quick Deploy

### Deploy to Railway (Recommended - Free Tier Available)

[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template)

1. Click the button above or go to [railway.app](https://railway.app)
2. Connect your GitHub repository
3. Set environment variable:
   - `ORACLE_BASE_URL`: `https://fa-euth-dev46-saasfademo1.ds-fa.oraclepdemos.com`
4. Deploy! 🎉

You'll get a URL like: `https://oracle-ar-mcp-server-production.up.railway.app`

### Deploy to Render

[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy)

1. Click the button or go to [render.com](https://render.com)
2. Connect your GitHub repository
3. Render auto-detects configuration from `render.yaml`
4. Deploy! 🎉

### Other Platforms

See [DEPLOYMENT.md](DEPLOYMENT.md) for detailed instructions for:
- Heroku
- Google Cloud Run
- AWS ECS/Fargate
- Azure Container Apps
- Docker deployment

## 📡 Connect to Your Deployed Server

Once deployed, anyone can connect using your server URL.

### For Claude Desktop

Add to `claude_desktop_config.json`:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "oracle-ar-remote": {
      "url": "https://YOUR-APP-URL.railway.app/sse",
      "transport": "sse"
    }
  }
}
```

### Test Your Deployment

```bash
# Health check
curl https://YOUR-APP-URL.railway.app/health

# Service info
curl https://YOUR-APP-URL.railway.app/

# Test SSE endpoint with MCP Inspector
npx @modelcontextprotocol/inspector --url https://YOUR-APP-URL.railway.app/sse
```

## 📚 API Documentation

### Endpoints

- `GET /` - Service information and available tools
- `GET /health` - Health check endpoint
- `GET /sse` - SSE endpoint for MCP connections
- `POST /messages` - MCP message endpoint

### MCP Tools

#### 1. oracle_ar_list_invoices

List invoices with optional filtering and pagination.

**Parameters:**
```json
{
  "username": "your-oracle-username",
  "password": "your-oracle-password",
  "customer_name": "Acme Corp",
  "date_from": "2024-01-01",
  "date_to": "2024-12-31",
  "status": "Open",
  "limit": 20,
  "offset": 0
}
```

#### 2. oracle_ar_get_invoice_details

Get detailed information about a specific invoice.

**Parameters:**
```json
{
  "username": "your-oracle-username",
  "password": "your-oracle-password",
  "invoice_id": "123456"
}
```

#### 3. oracle_ar_search_invoices

Advanced search with filters and statistics.

**Parameters:**
```json
{
  "username": "your-oracle-username",
  "password": "your-oracle-password",
  "filters": {
    "amountGreaterThan": 10000,
    "overdueDays": 30
  },
  "limit": 20
}
```

## 🛠️ Local Development

### Prerequisites

- Python 3.10+
- uv (recommended)
- Oracle Fusion Cloud credentials

### Setup

```bash
# Clone the repository
git clone https://github.com/YOUR_USERNAME/oracle-ar-mcp-server.git
cd oracle-ar-mcp-server

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

# Create environment file
cp .env.example .env
```

### Run Locally

```bash
# Run the server
uv run python -m src.server

# Server will start on http://localhost:3000
```

### Run Tests

```bash
# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=src

# Run linting
uv run ruff check src tests

# Run type checking
uv run mypy src
```

## 🔒 Security

### ✅ Secure Design

- **No Credential Storage**: Credentials are passed per-request only
- **Stateless**: No session state stored on server
- **No Logging**: Credentials are never logged
- **HTTPS Only**: All communication encrypted (via hosting platform)
- **Input Validation**: Full Pydantic validation on all inputs

### 🔑 Authentication Flow

1. User calls MCP tool with Oracle username/password
2. Server receives request (credentials in memory only)
3. Server authenticates request to Oracle API
4. Oracle returns data
5. Server formats and returns response
6. **Credentials discarded** (not stored anywhere)

## 📊 Technology Stack

- **Python 3.12** - Modern async Python
- **uv** - Fast, reliable package manager
- **MCP SDK** - Model Context Protocol support
- **httpx** - Async HTTP client
- **Pydantic** - Data validation and type safety
- **Starlette** - ASGI web framework
- **uvicorn** - ASGI server
- **pytest** - Testing framework

## 📁 Project Structure

```
.
├── src/
│   ├── server.py          # MCP server with SSE transport
│   ├── tools.py           # MCP tool implementations
│   ├── oracle_client.py   # Oracle API client (async)
│   ├── formatter.py       # Response formatters
│   ├── errors.py          # Error handling
│   ├── models.py          # Pydantic models
│   └── config.py          # Configuration
├── tests/                 # Test suite
├── .github/workflows/     # CI/CD pipelines
├── DEPLOYMENT.md          # Deployment guide
├── pyproject.toml         # Project configuration
└── README.md             # This file
```

## 🤝 Sharing Your Server

After deploying, share your server with others:

### 1. Share the SSE Endpoint URL

```
https://your-app.railway.app/sse
```

### 2. Provide Configuration Instructions

Users add this to their Claude Desktop config:

```json
{
  "mcpServers": {
    "oracle-ar": {
      "url": "https://your-app.railway.app/sse",
      "transport": "sse"
    }
  }
}
```

### 3. Users Provide Their Own Credentials

Each user must have their own Oracle Fusion credentials, which they provide when using the tools. The server never stores or shares credentials between users.

## 🧪 Testing

### Manual Testing

```bash
# Test health check
curl https://your-app.railway.app/health

# View available tools
curl https://your-app.railway.app/

# Test with MCP Inspector
npx @modelcontextprotocol/inspector --url https://your-app.railway.app/sse
```

### Automated Testing

```bash
# Run test suite
uv run pytest

# Run with coverage
uv run pytest --cov=src --cov-report=html

# View coverage report
open htmlcov/index.html
```

## 📈 Monitoring

### Health Check

```bash
curl https://your-app.railway.app/health
```

Response:
```json
{
  "status": "healthy",
  "service": "oracle-fusion-ar-mcp-server",
  "version": "1.0.0"
}
```

### Platform Logs

- **Railway**: Dashboard → Your App → Logs
- **Render**: Dashboard → Your Service → Logs
- **Heroku**: `heroku logs --tail`

## 💰 Cost

### Free Tier Options

- **Railway**: $5 credit/month (sufficient for light use)
- **Render**: 750 hours/month free
- **Heroku**: Free with credit card (1000 dyno hours/month)

### Paid Plans (Production)

- **Railway**: ~$5-10/month
- **Render**: ~$7/month
- **Heroku**: ~$7/month

## 🔄 Updates & CI/CD

### Automatic Deployments

Push to GitHub and your platform automatically deploys:

```bash
git add .
git commit -m "Add new feature"
git push origin main
```

### GitHub Actions

- ✅ Automatic testing on PRs
- ✅ Code quality checks (ruff, mypy)
- ✅ Coverage reports
- ✅ Build verification

## 🐛 Troubleshooting

### Server Won't Start

- Check platform logs for errors
- Verify environment variables are set
- Ensure `PORT` is not hardcoded (use platform's PORT)

### Oracle API Connection Failed

- Verify `ORACLE_BASE_URL` is correct
- Check Oracle API is accessible from your platform
- Test with health check endpoint

### Claude Desktop Can't Connect

- Verify SSE endpoint URL is correct
- Ensure HTTPS is enabled
- Check server is running (health check)
- Restart Claude Desktop after config change

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run tests (`uv run pytest`)
5. Commit changes (`git commit -m 'Add amazing feature'`)
6. Push to branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request

## 📄 License

MIT License - see [LICENSE](LICENSE) file

## 🙏 Acknowledgments

- Built with [Model Context Protocol](https://modelcontextprotocol.io)
- Uses [Oracle Fusion Cloud REST APIs](https://docs.oracle.com/en/cloud/saas/financials/24c/farfa/)
- Powered by [uv](https://github.com/astral-sh/uv)

## 📞 Support

- 📖 [Deployment Guide](DEPLOYMENT.md)
- 🐛 [Report Issues](https://github.com/YOUR_USERNAME/oracle-ar-mcp-server/issues)
- 💬 [Discussions](https://github.com/YOUR_USERNAME/oracle-ar-mcp-server/discussions)

---

**🚀 Deploy once, share with everyone!**

Made with ❤️ for the MCP community