# Product Requirements Document: Oracle Fusion AR MCP Server
## Executive Summary
Build a production-ready MCP (Model Context Protocol) server that wraps the Oracle Fusion Cloud Accounts Receivable REST API, enabling secure, multi-tenant access for AI agents and clients to query AR data through credential-per-request authentication.
---
## 1. Project Overview
### 1.1 Purpose
Create an MCP server that acts as a secure intermediary between MCP clients (like Claude) and the Oracle Fusion AR REST API, allowing multiple users to authenticate with their own Oracle credentials and access AR invoice data programmatically.
### 1.2 Target API
- **Base URL**: `https://fa-euth-dev46-saasfademo1.ds-fa.oraclepdemos.com`
- **Primary Endpoint**: `/fscmRestApi/resources/11.13.18.05/receivablesInvoices`
- **Authentication**: Basic Auth (username/password)
- **Response Format**: JSON
### 1.3 Success Criteria
- Users can connect to the MCP server from any MCP client
- Each request is authenticated independently with user-provided credentials
- Server returns structured AR invoice data in both JSON and human-readable formats
- Server is deployable to cloud platforms (Railway, etc.)
- Server supports pagination for large result sets
- Error messages are actionable and guide users toward solutions
---
## 2. Technical Architecture
### 2.1 Technology Stack
- **Language**: TypeScript (recommended for MCP compatibility)
- **Framework**: MCP TypeScript SDK
- **Transport**: Streamable HTTP (for remote access)
- **Runtime**: Node.js
- **Deployment**: Railway (or similar cloud platform)
### 2.2 Architecture Pattern
```
MCP Client (Claude/Desktop App)
↓ (connects to)
MCP Server (your code)
↓ (authenticates & proxies to)
Oracle Fusion AR REST API
↓ (returns)
JSON response → formatted for client
```
### 2.3 Authentication Flow
1. Client calls MCP tool with `username` and `password` as parameters
2. Server receives request with credentials
3. Server constructs Basic Auth header from credentials
4. Server makes authenticated request to Oracle Fusion API
5. Server receives JSON response
6. Server formats and returns response to client
7. **No credentials are stored** - stateless design
---
## 3. Functional Requirements
### 3.1 Core Tools
#### Tool 1: `oracle_ar_list_invoices`
**Purpose**: Retrieve a list of receivables invoices with optional filtering
**Input Parameters**:
- `username` (required, string): Oracle Fusion username
- `password` (required, string): Oracle Fusion password
- `limit` (optional, number, default: 20): Number of invoices to return
- `offset` (optional, number, default: 0): Pagination offset
- `customer_name` (optional, string): Filter by customer name
- `invoice_number` (optional, string): Filter by specific invoice number
- `date_from` (optional, string, ISO date): Filter invoices from date
- `date_to` (optional, string, ISO date): Filter invoices to date
- `status` (optional, string): Filter by invoice status (e.g., "Open", "Closed")
**Output**:
- Structured JSON with invoice data
- Human-readable summary with key metrics
- Pagination information (total count, next offset)
**Example Response Structure**:
```json
{
"items": [
{
"InvoiceNumber": "INV-12345",
"CustomerName": "Acme Corp",
"InvoiceAmount": 10000.00,
"InvoiceDate": "2024-01-15",
"DueDate": "2024-02-15",
"Status": "Open",
"OutstandingAmount": 10000.00
}
],
"count": 1,
"hasMore": false,
"totalCount": 1,
"offset": 0,
"limit": 20
}
```
**Annotations**:
- `readOnlyHint`: true
- `destructiveHint`: false
- `idempotentHint`: true
#### Tool 2: `oracle_ar_get_invoice_details`
**Purpose**: Retrieve detailed information about a specific invoice
**Input Parameters**:
- `username` (required, string): Oracle Fusion username
- `password` (required, string): Oracle Fusion password
- `invoice_id` (required, string): The unique invoice identifier
**Output**:
- Complete invoice details including line items
- Payment history
- Customer information
- Formatted for readability
**Annotations**:
- `readOnlyHint`: true
- `destructiveHint`: false
- `idempotentHint`: true
#### Tool 3: `oracle_ar_search_invoices`
**Purpose**: Advanced search with multiple filter combinations
**Input Parameters**:
- `username` (required, string): Oracle Fusion username
- `password` (required, string): Oracle Fusion password
- `q` (optional, string): Full-text search query
- `filters` (optional, object): Advanced filter criteria
- `amountGreaterThan` (number)
- `amountLessThan` (number)
- `overdueDays` (number)
- `customerId` (string)
**Output**:
- Filtered invoice list with relevance scoring
- Aggregated statistics (total amount, average, etc.)
**Annotations**:
- `readOnlyHint`: true
- `destructiveHint`: false
- `idempotentHint`: true
### 3.2 Error Handling
**Authentication Errors** (401 Unauthorized):
```
"Authentication failed. Please verify your Oracle Fusion username and password are correct.
If you're using the demo environment, ensure your account has active access."
```
**Network Errors**:
```
"Unable to connect to Oracle Fusion API at [URL]. Please check:
1. Network connectivity
2. API endpoint availability
3. Firewall settings if deployed on restricted network"
```
**Rate Limiting** (429 Too Many Requests):
```
"Oracle Fusion API rate limit exceeded. Please wait [X] seconds before retrying."
```
**Invalid Parameters**:
```
"Invalid parameter: [parameter_name]. Expected [type/format]. Example: [example_value]"
```
**Empty Results**:
```
"No invoices found matching your criteria. Try:
- Broadening date range
- Removing specific filters
- Checking spelling of customer names"
```
### 3.3 Response Formatting
**Dual Format Strategy**:
1. **Structured JSON** (for programmatic access)
2. **Markdown Summary** (for human readability)
**Example Markdown Output**:
```markdown
## Invoice Summary
**Total Invoices**: 15
**Total Amount**: $125,450.00
**Outstanding**: $42,300.00
### Recent Invoices
1. **INV-12345** - Acme Corp - $10,000.00 (Open)
- Due: Feb 15, 2024
- Overdue: 5 days
2. **INV-12346** - TechCo Inc - $25,500.00 (Paid)
- Paid: Jan 30, 2024
```
---
## 4. Non-Functional Requirements
### 4.1 Security
- **No credential storage**: Credentials passed per-request only
- **No logging of credentials**: Sanitize logs to remove sensitive data
- **HTTPS only**: All communication encrypted in transit
- **Input validation**: Sanitize all user inputs to prevent injection attacks
- **Rate limiting**: Implement client-side rate limiting to respect Oracle API limits
### 4.2 Performance
- **Response time**: < 3 seconds for standard invoice list queries
- **Pagination**: Support up to 100 items per request
- **Concurrent requests**: Handle at least 10 concurrent user requests
- **Timeout**: 30 second timeout for Oracle API calls
### 4.3 Scalability
- **Stateless design**: No session state - scales horizontally
- **Multi-tenant**: Support unlimited concurrent users
- **Cloud-ready**: Deployable to Railway, Heroku, AWS, etc.
### 4.4 Reliability
- **Error recovery**: Graceful handling of API failures
- **Retry logic**: Exponential backoff for transient failures (up to 3 retries)
- **Circuit breaker**: Stop retrying if Oracle API is consistently failing
- **Health check endpoint**: `/health` for monitoring
---
## 5. Implementation Phases
### Phase 1: Core Infrastructure (Week 1)
- [ ] Set up TypeScript project structure
- [ ] Configure MCP TypeScript SDK
- [ ] Implement Oracle Fusion API client with Basic Auth
- [ ] Create error handling utilities
- [ ] Implement response formatting (JSON + Markdown)
### Phase 2: Tool Implementation (Week 1-2)
- [ ] Implement `oracle_ar_list_invoices` tool
- [ ] Implement `oracle_ar_get_invoice_details` tool
- [ ] Implement `oracle_ar_search_invoices` tool
- [ ] Add input validation with Zod schemas
- [ ] Add pagination support
### Phase 3: Testing & Refinement (Week 2)
- [ ] Test with MCP Inspector
- [ ] Test with Claude Desktop
- [ ] Create evaluation questions (10 complex scenarios)
- [ ] Fix edge cases and improve error messages
- [ ] Optimize response formatting
### Phase 4: Deployment (Week 2-3)
- [ ] Configure for Railway deployment
- [ ] Set up environment variables
- [ ] Deploy to Railway
- [ ] Test remote connectivity
- [ ] Document connection instructions
### Phase 5: Documentation (Week 3)
- [ ] Write README with setup instructions
- [ ] Create user guide with examples
- [ ] Document API mapping (Oracle -> MCP tools)
- [ ] Create troubleshooting guide
---
## 6. Oracle Fusion AR API Details
### 6.1 Known Endpoints
Based on Oracle Fusion REST API standards:
**Base Path**: `/fscmRestApi/resources/11.13.18.05/receivablesInvoices`
**Common Operations**:
- `GET /receivablesInvoices` - List invoices
- `GET /receivablesInvoices/{InvoiceId}` - Get specific invoice
- Query parameters:
- `q` - Search query
- `finder` - Predefined finder (e.g., `findByCustomer`)
- `limit` - Results per page
- `offset` - Pagination offset
- `orderBy` - Sort field
- `fields` - Field selection
### 6.2 Authentication Details
- **Type**: Basic Authentication
- **Header**: `Authorization: Basic base64(username:password)`
- **Credentials**: User-specific Oracle Fusion credentials
- **Session**: None required - stateless requests
### 6.3 Response Format
Standard Oracle REST response:
```json
{
"items": [...],
"count": 10,
"hasMore": false,
"limit": 25,
"offset": 0,
"links": [...]
}
```
### 6.4 Common Query Examples
```
# List all invoices
GET /receivablesInvoices?limit=10
# Search by customer
GET /receivablesInvoices?q=CustomerName='Acme Corp'
# Filter by date range
GET /receivablesInvoices?q=InvoiceDate>=2024-01-01;InvoiceDate<=2024-12-31
# Get specific fields only
GET /receivablesInvoices?fields=InvoiceNumber,CustomerName,InvoiceAmount
# Sort by date descending
GET /receivablesInvoices?orderBy=-InvoiceDate
```
---
## 7. Deployment Configuration
### 7.1 Railway Deployment
**Environment Variables**:
- `PORT` - Assigned by Railway
- `NODE_ENV` - `production`
- `ORACLE_BASE_URL` - Oracle Fusion API base URL (for easy updates)
**Procfile**:
```
web: node dist/index.js
```
**Build Command**:
```bash
npm install && npm run build
```
**Start Command**:
```bash
node dist/index.js
```
### 7.2 MCP Configuration (for users)
Users will add to their MCP client config:
**For Claude Desktop** (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"oracle-ar": {
"url": "https://your-app.railway.app/sse",
"type": "sse"
}
}
}
```
**For Programmatic Access**:
```typescript
const client = new McpClient({
url: "https://your-app.railway.app/sse",
type: "sse"
});
```
---
## 8. Testing Strategy
### 8.1 Unit Tests
- Test API client authentication
- Test parameter validation
- Test response formatting
- Test error handling
### 8.2 Integration Tests
- Test actual Oracle API calls (with test credentials)
- Test pagination
- Test filtering
- Test concurrent requests
### 8.3 MCP Evaluation Questions
Create 10 realistic scenarios:
1. "Find all invoices for customer 'Acme Corp' that are overdue by more than 30 days"
2. "What's the total outstanding amount across all open invoices?"
3. "List the top 5 customers by total invoice amount in 2024"
4. "Find invoices issued in January 2024 with amounts greater than $50,000"
5. "How many invoices are currently in 'Disputed' status?"
6. "What's the average payment cycle (invoice date to payment date) for closed invoices?"
7. "Find all invoices for customer ID X and calculate the total paid vs outstanding"
8. "Which month in 2024 had the highest invoice volume?"
9. "List all invoices that have partial payments"
10. "Find invoices with specific line items matching a product code"
### 8.4 Manual Testing Checklist
- [ ] Test with valid credentials
- [ ] Test with invalid credentials
- [ ] Test with empty results
- [ ] Test with large result sets (pagination)
- [ ] Test filtering combinations
- [ ] Test concurrent requests from multiple users
- [ ] Test from Claude Desktop
- [ ] Test from MCP Inspector
- [ ] Test remote deployment connectivity
---
## 9. Success Metrics
### 9.1 Technical Metrics
- Server uptime: > 99%
- Average response time: < 3 seconds
- Error rate: < 1% of requests
- Successful authentication rate: > 95%
### 9.2 Usability Metrics
- Users can connect on first attempt
- Clear error messages lead to resolution
- Evaluation questions pass at > 80% rate
- Documentation is sufficient for self-service setup
### 9.3 Evaluation Criteria
- All 10 evaluation questions return correct answers
- MCP Inspector shows proper tool registration
- Response formats are both machine and human readable
- Deployed server accessible from public internet
---
## 10. Future Enhancements (Out of Scope for V1)
### 10.1 Additional AR Operations
- Create invoice
- Update invoice
- Apply payment
- Create credit memo
- Send invoice reminders
### 10.2 Advanced Features
- Caching layer for frequently accessed data
- Webhook support for real-time updates
- Analytics dashboard
- Batch operations
- Export to CSV/Excel
### 10.3 Additional Oracle Modules
- Accounts Payable (AP)
- General Ledger (GL)
- Fixed Assets (FA)
- Cash Management
---
## 11. Risks and Mitigations
### 11.1 Risks
| Risk | Impact | Probability | Mitigation |
|------|--------|-------------|------------|
| Oracle API changes | High | Medium | Version API endpoint, document fallbacks |
| Credential security | Critical | Low | Never store credentials, use HTTPS only |
| Rate limiting | Medium | Medium | Implement client-side throttling |
| Oracle demo env downtime | Medium | Medium | Clear error messages, retry logic |
| MCP protocol changes | Medium | Low | Use stable SDK version, monitor updates |
### 11.2 Dependencies
- Oracle Fusion API availability
- Railway platform stability
- MCP protocol stability
- Node.js/TypeScript ecosystem
---
## 12. Delivery Artifacts
### 12.1 Code
- [ ] Complete TypeScript MCP server
- [ ] Package.json with dependencies
- [ ] TypeScript configuration
- [ ] Build scripts
### 12.2 Documentation
- [ ] README.md with setup instructions
- [ ] API_MAPPING.md (Oracle API → MCP tools)
- [ ] DEPLOYMENT.md (Railway deployment guide)
- [ ] TROUBLESHOOTING.md
- [ ] Example queries and responses
### 12.3 Testing
- [ ] 10 evaluation questions (XML format)
- [ ] Test credentials (if available)
- [ ] Manual testing checklist (completed)
### 12.4 Deployment
- [ ] Deployed server URL
- [ ] Health check endpoint
- [ ] Sample MCP client configuration
---
## 13. Acceptance Criteria
The Oracle Fusion AR MCP Server is considered complete when:
1. ✅ All three core tools are implemented and functional
2. ✅ Server successfully authenticates with Oracle Fusion API using user-provided credentials
3. ✅ Responses include both structured JSON and human-readable Markdown
4. ✅ Error messages are clear and actionable
5. ✅ Server is deployed to Railway and accessible via public URL
6. ✅ MCP Inspector can connect and list all tools
7. ✅ Claude Desktop can connect and execute queries
8. ✅ At least 8 of 10 evaluation questions pass
9. ✅ Documentation is complete and enables self-service setup
10. ✅ No credentials are logged or stored anywhere
---
## 14. Timeline
**Total Duration**: 2-3 weeks
- **Week 1**: Core implementation and basic tools
- **Week 2**: Testing, refinement, and deployment
- **Week 3**: Documentation and polish
---
## Appendix A: Oracle Fusion AR Data Model
### Invoice Object (Sample Fields)
```json
{
"InvoiceId": 123456,
"InvoiceNumber": "INV-2024-001",
"CustomerName": "Acme Corporation",
"CustomerId": 789,
"InvoiceDate": "2024-01-15T00:00:00Z",
"DueDate": "2024-02-15T00:00:00Z",
"InvoiceCurrencyCode": "USD",
"InvoiceAmount": 25000.00,
"OutstandingAmount": 15000.00,
"PaidAmount": 10000.00,
"InvoiceStatus": "Open",
"PaymentTerms": "Net 30",
"BillToCustomerName": "Acme Corporation",
"BillToAddress": "123 Main St, New York, NY 10001",
"CreationDate": "2024-01-14T10:30:00Z",
"LastUpdateDate": "2024-01-20T15:45:00Z"
}
```
---
## Appendix B: MCP Tool Schema Examples
### Tool Schema: oracle_ar_list_invoices
```typescript
{
name: "oracle_ar_list_invoices",
description: "Retrieve a list of Oracle Fusion Accounts Receivable invoices with optional filtering and pagination. Returns both structured data and a human-readable summary.",
inputSchema: {
type: "object",
properties: {
username: {
type: "string",
description: "Oracle Fusion username for authentication"
},
password: {
type: "string",
description: "Oracle Fusion password for authentication"
},
limit: {
type: "number",
description: "Maximum number of invoices to return (1-100, default: 20)",
default: 20,
minimum: 1,
maximum: 100
},
offset: {
type: "number",
description: "Number of invoices to skip for pagination (default: 0)",
default: 0,
minimum: 0
},
customer_name: {
type: "string",
description: "Filter by customer name (partial match supported)"
},
invoice_number: {
type: "string",
description: "Filter by specific invoice number"
},
date_from: {
type: "string",
description: "Filter invoices from this date (ISO format: YYYY-MM-DD)",
pattern: "^\\d{4}-\\d{2}-\\d{2}$"
},
date_to: {
type: "string",
description: "Filter invoices to this date (ISO format: YYYY-MM-DD)",
pattern: "^\\d{4}-\\d{2}-\\d{2}$"
},
status: {
type: "string",
description: "Filter by invoice status",
enum: ["Open", "Closed", "Disputed", "Pending", "Cancelled"]
}
},
required: ["username", "password"]
},
annotations: {
readOnlyHint: true,
destructiveHint: false,
idempotentHint: true
}
}
```
---
## Document Control
- **Version**: 1.0
- **Created**: January 2026
- **Author**: Claude (AI Assistant)
- **Status**: Draft for Review
- **Next Review**: Upon implementation completion
