# 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)
[](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
[](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
