From 06dfbf99653d523f72036f2bd890e1f5415a5fce Mon Sep 17 00:00:00 2001
From: Peter Wood <peter@peterwood.dev>
Date: Fri, 2 May 2025 23:51:18 -0400
Subject: [PATCH] feat: add initial implementation of Finance MCP server with
 REST API and setup instructions (ref #16)

---
 mcp/README.md        | 141 ++++++++++++++++++++++++++
 mcp/mcp-issues.md    | 230 +++++++++++++++++++++++++++++++++++++++++++
 mcp/mcp_server.py    |  37 +++++++
 mcp/requirements.txt |   3 +
 mcp/start_server.sh  |   2 +
 5 files changed, 413 insertions(+)
 create mode 100644 mcp/README.md
 create mode 100644 mcp/mcp-issues.md
 create mode 100644 mcp/mcp_server.py
 create mode 100644 mcp/requirements.txt
 create mode 100644 mcp/start_server.sh

diff --git a/mcp/README.md b/mcp/README.md
new file mode 100644
index 0000000..9bc3b5d
--- /dev/null
+++ b/mcp/README.md
@@ -0,0 +1,141 @@
+# Finance MCP Server
+
+A Model Control Protocol (MCP) server implementation for financial transaction management.
+
+## Current Implementation
+
+The server currently provides a basic REST API for managing financial transactions with the following features:
+
+- FastAPI-based REST API
+- In-memory transaction storage
+- Basic CRUD operations for transactions
+- Data validation using Pydantic models
+- Auto-generated API documentation (Swagger UI)
+
+### Project Structure
+
+```
+mcp/
+├── mcp_server.py      # Main server implementation
+├── requirements.txt   # Python dependencies
+└── start_server.sh   # Server startup script
+```
+
+## Setup Instructions
+
+1. Install Python dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+2. Make the start script executable:
+   ```bash
+   chmod +x start_server.sh
+   ```
+
+3. Start the server:
+   ```bash
+   ./start_server.sh
+   ```
+
+The server will start on `http://localhost:8000` with the following endpoints:
+- `/` - Health check endpoint
+- `/docs` - Auto-generated API documentation (Swagger UI)
+- `/transactions` - Transaction management endpoints
+  - GET /transactions - List all transactions
+  - POST /transactions - Create a new transaction
+  - GET /transactions/{id} - Get a specific transaction
+
+## API Usage
+
+### Create a Transaction
+```bash
+curl -X POST "http://localhost:8000/transactions" \
+     -H "Content-Type: application/json" \
+     -d '{
+           "amount": 100.00,
+           "description": "Grocery shopping",
+           "category": "expenses"
+         }'
+```
+
+### List All Transactions
+```bash
+curl "http://localhost:8000/transactions"
+```
+
+## Recommended Next Steps
+
+1. **Database Integration**
+   - Implement PostgreSQL integration using SQLAlchemy
+   - Add database migrations
+   - Create proper data models
+   - Add transaction persistence
+
+2. **Authentication & Authorization**
+   - Implement JWT-based authentication
+   - Add user management
+   - Role-based access control
+   - API key authentication for machine-to-machine communication
+
+3. **Enhanced Features**
+   - Add transaction categories management
+   - Implement transaction search and filtering
+   - Add date range queries
+   - Support for different currencies
+   - Transaction metadata support
+
+4. **Security Enhancements**
+   - Input validation and sanitization
+   - Rate limiting
+   - CORS configuration
+   - Request logging and monitoring
+   - SSL/TLS configuration
+
+5. **Testing**
+   - Unit tests for models and endpoints
+   - Integration tests
+   - Load testing
+   - API documentation tests
+
+6. **Monitoring & Logging**
+   - Structured logging
+   - Prometheus metrics
+   - Health check endpoints
+   - Error tracking
+   - Performance monitoring
+
+7. **DevOps**
+   - Docker containerization
+   - CI/CD pipeline
+   - Environment configuration
+   - Backup strategy
+   - Deployment documentation
+
+8. **API Enhancements**
+   - Pagination
+   - Sorting options
+   - Bulk operations
+   - Webhook support
+   - Event streaming
+
+9. **Documentation**
+   - API documentation
+   - Development guide
+   - Deployment guide
+   - Contributing guidelines
+
+10. **Compliance & Standards**
+    - GDPR compliance
+    - Financial regulations compliance
+    - API versioning
+    - Error handling standards
+    - Audit logging
+
+## Contributing
+
+Please read our contributing guidelines before submitting pull requests.
+
+## License
+
+[Add your chosen license here]
\ No newline at end of file
diff --git a/mcp/mcp-issues.md b/mcp/mcp-issues.md
new file mode 100644
index 0000000..dd8964d
--- /dev/null
+++ b/mcp/mcp-issues.md
@@ -0,0 +1,230 @@
+# MCP Server Enhancement Issues
+
+## Priority 1: Core Infrastructure
+
+### Issue 1: Database Integration with Existing PostgreSQL Setup
+**Labels**: `enhancement`, `database`, `priority-high`
+
+#### Description
+Currently, the MCP server uses in-memory storage for transactions. We need to integrate it with the existing PostgreSQL database.
+
+#### Tasks
+- [ ] Add SQLAlchemy to requirements.txt
+- [ ] Create database models that align with existing Prisma schema
+- [ ] Implement database connection handling
+- [ ] Convert in-memory operations to database operations
+- [ ] Add database migration system
+- [ ] Add connection error handling
+- [ ] Add database connection pooling
+
+#### Technical Details
+- Use existing PostgreSQL setup from docker-compose.yml
+- Align with existing Prisma schema structure
+- Implement proper connection closing and resource cleanup
+
+#### Dependencies
+- SQLAlchemy
+- alembic (for migrations)
+- psycopg2-binary
+
+**Estimated time**: 3-4 days
+
+---
+
+### Issue 2: Authentication System Implementation
+**Labels**: `enhancement`, `security`, `priority-high`
+
+#### Description
+Implement secure authentication system for the MCP server endpoints.
+
+#### Tasks
+- [ ] Add JWT authentication
+- [ ] Create authentication middleware
+- [ ] Implement user session management
+- [ ] Add API key authentication for machine-to-machine communication
+- [ ] Integrate with existing user system from the main application
+- [ ] Add rate limiting for authentication attempts
+- [ ] Implement secure password handling
+
+#### Technical Details
+- Use Python-JWT for token handling
+- Integrate with existing user schema from Prisma
+- Implement token refresh mechanism
+- Add proper error handling for auth failures
+
+#### Dependencies
+- python-jose[cryptography]
+- passlib[bcrypt]
+- python-multipart
+
+#### Security Considerations
+- Token expiration
+- Secure password hashing
+- Protection against brute force attacks
+
+**Estimated time**: 2-3 days
+
+---
+
+## Priority 2: Feature Enhancements
+
+### Issue 3: Enhanced Transaction Features
+**Labels**: `enhancement`, `feature`, `priority-medium`
+
+#### Description
+Add enhanced features for transaction management and querying.
+
+#### Tasks
+- [ ] Implement transaction categories management
+- [ ] Add transaction search functionality
+  - [ ] Date range filtering
+  - [ ] Amount range filtering
+  - [ ] Category filtering
+  - [ ] Description search
+- [ ] Add pagination for transaction listings
+- [ ] Implement sorting options
+- [ ] Add support for different currencies
+- [ ] Implement transaction metadata support
+
+#### Technical Details
+- Add proper indexing for search operations
+- Implement efficient pagination
+- Add currency conversion support
+- Add proper validation for all new fields
+
+#### API Endpoints to Add
+- GET /transactions/search
+- GET /categories
+- POST /categories
+- PUT /transactions/{id}/metadata
+
+**Estimated time**: 3-4 days
+
+---
+
+## Priority 3: Observability & Quality
+
+### Issue 4: Monitoring and Logging Setup
+**Labels**: `enhancement`, `observability`, `priority-medium`
+
+#### Description
+Implement monitoring and logging systems for better observability.
+
+#### Tasks
+- [ ] Set up structured logging
+  - [ ] Request logging
+  - [ ] Error logging
+  - [ ] Performance metrics
+- [ ] Add Prometheus metrics
+  - [ ] Request counts
+  - [ ] Response times
+  - [ ] Error rates
+- [ ] Implement detailed health check endpoints
+- [ ] Add performance monitoring
+- [ ] Set up error tracking
+
+#### Technical Details
+- Use Python logging module with JSON formatter
+- Implement OpenTelemetry integration
+- Add proper error context collection
+- Implement custom metrics for financial operations
+
+#### Dependencies
+- prometheus-client
+- opentelemetry-api
+- opentelemetry-sdk
+- python-json-logger
+
+**Estimated time**: 2-3 days
+
+---
+
+### Issue 5: Testing Infrastructure
+**Labels**: `enhancement`, `testing`, `priority-medium`
+
+#### Description
+Set up complete testing infrastructure for the MCP server.
+
+#### Tasks
+- [ ] Set up unit testing framework
+- [ ] Implement integration tests
+- [ ] Add API documentation tests
+- [ ] Create load testing suite
+- [ ] Set up test data fixtures
+- [ ] Implement CI pipeline for tests
+
+#### Test Coverage Areas
+- [ ] Transaction operations
+- [ ] Authentication
+- [ ] Database operations
+- [ ] Error handling
+- [ ] API endpoints
+- [ ] Data validation
+
+#### Technical Details
+- Use pytest for testing
+- Implement proper test database handling
+- Add mock services for external dependencies
+- Set up GitHub Actions for CI
+
+#### Dependencies
+- pytest
+- pytest-cov
+- pytest-asyncio
+- locust (for load testing)
+
+**Estimated time**: 4-5 days
+
+---
+
+## Priority 4: DevOps & Documentation
+
+### Issue 6: Docker & Deployment Setup
+**Labels**: `enhancement`, `devops`, `priority-low`
+
+#### Description
+Containerize the MCP server and set up deployment infrastructure.
+
+#### Tasks
+- [ ] Create Dockerfile for MCP server
+- [ ] Update docker-compose.yml to include MCP service
+- [ ] Set up environment configuration
+- [ ] Create deployment scripts
+- [ ] Implement backup strategy
+- [ ] Add health checks for container orchestration
+
+#### Technical Details
+- Multi-stage Docker build
+- Environment variable configuration
+- Volume management for persistent data
+- Container health monitoring
+
+**Estimated time**: 2-3 days
+
+---
+
+### Issue 7: Documentation Enhancement
+**Labels**: `documentation`, `priority-low`
+
+#### Description
+Create comprehensive documentation for the MCP server.
+
+#### Tasks
+- [ ] Create API documentation
+- [ ] Write development guide
+- [ ] Create deployment guide
+- [ ] Add contributing guidelines
+- [ ] Document security practices
+- [ ] Add troubleshooting guide
+
+#### Areas to Cover
+- Setup instructions
+- API endpoints and usage
+- Authentication flows
+- Database schema
+- Configuration options
+- Deployment procedures
+- Contributing workflow
+- Security best practices
+
+**Estimated time**: 2-3 days
\ No newline at end of file
diff --git a/mcp/mcp_server.py b/mcp/mcp_server.py
new file mode 100644
index 0000000..63ca23f
--- /dev/null
+++ b/mcp/mcp_server.py
@@ -0,0 +1,37 @@
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+from datetime import datetime
+from typing import List, Optional
+
+app = FastAPI(title="Finance MCP Server")
+
+class Transaction(BaseModel):
+    id: Optional[int]
+    amount: float
+    description: str
+    timestamp: datetime = datetime.now()
+    category: str
+
+# In-memory storage (replace with database in production)
+transactions: List[Transaction] = []
+
+@app.get("/")
+async def root():
+    return {"status": "running", "service": "Finance MCP Server"}
+
+@app.get("/transactions")
+async def get_transactions():
+    return transactions
+
+@app.post("/transactions")
+async def create_transaction(transaction: Transaction):
+    transaction.id = len(transactions) + 1
+    transactions.append(transaction)
+    return transaction
+
+@app.get("/transactions/{transaction_id}")
+async def get_transaction(transaction_id: int):
+    for tx in transactions:
+        if tx.id == transaction_id:
+            return tx
+    raise HTTPException(status_code=404, detail="Transaction not found")
\ No newline at end of file
diff --git a/mcp/requirements.txt b/mcp/requirements.txt
new file mode 100644
index 0000000..34d56f8
--- /dev/null
+++ b/mcp/requirements.txt
@@ -0,0 +1,3 @@
+fastapi==0.68.0
+uvicorn==0.15.0
+pydantic==1.8.2
\ No newline at end of file
diff --git a/mcp/start_server.sh b/mcp/start_server.sh
new file mode 100644
index 0000000..394c27e
--- /dev/null
+++ b/mcp/start_server.sh
@@ -0,0 +1,2 @@
+#!/bin/bash
+uvicorn mcp_server:app --reload --port 8000
\ No newline at end of file