Oracle Fusion AR 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

1. Click the button above or go to 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

1. Click the button or go to render.com
2. Connect your GitHub repository
3. Render auto-detects configuration from render.yaml
4. Deploy! 🎉

Other Platforms

See 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

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

Test Your Deployment

# 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:

{
  "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:

{
  "username": "your-oracle-username",
  "password": "your-oracle-password",
  "invoice_id": "123456"
}

3. oracle_ar_search_invoices

Advanced search with filters and statistics.

Parameters:

{
  "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

# 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

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

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

Run Tests

# 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:

{
  "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

# 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

# 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

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

Response:

{
  "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:

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 file

🙏 Acknowledgments

• Built with Model Context Protocol
• Uses Oracle Fusion Cloud REST APIs
• Powered by uv

📞 Support

• 📖 Deployment Guide
• 🐛 Report Issues
• 💬 Discussions

---

🚀 Deploy once, share with everyone!

Made with ❤️ for the MCP community