mirror of
https://github.com/acedanger/finance.git
synced 2025-12-05 22:50:12 -08:00
feat: add initial implementation of Finance MCP server with REST API and setup instructions (ref #16)
This commit is contained in:
Peter Wood
141
mcp/README.md
Normal file
141
mcp/README.md
Normal file
@@ -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]
|
||||
230
mcp/mcp-issues.md
Normal file
230
mcp/mcp-issues.md
Normal file
@@ -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
|
||||
37
mcp/mcp_server.py
Normal file
37
mcp/mcp_server.py
Normal file
@@ -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")
|
||||
3
mcp/requirements.txt
Normal file
3
mcp/requirements.txt
Normal file
@@ -0,0 +1,3 @@
|
||||
fastapi==0.68.0
|
||||
uvicorn==0.15.0
|
||||
pydantic==1.8.2
|
||||
2
mcp/start_server.sh
Normal file
2
mcp/start_server.sh
Normal file
@@ -0,0 +1,2 @@
|
||||
#!/bin/bash
|
||||
uvicorn mcp_server:app --reload --port 8000
|
||||
Reference in New Issue
Block a user