Update README with API, CLI, and MCP documentation
This commit is contained in:
waffle2k
@@ -1,307 +1,164 @@
|
|||||||
# Finger Web Flask Application
|
# finger-web
|
||||||
|
|
||||||
A simple, modern Flask web application demonstrating basic web development concepts with clean code structure, responsive design, and best practices.
|
A Flask web application that fronts a finger daemon, with a JSON API, a CLI client, and an MCP server for Claude integration.
|
||||||
|
|
||||||
## 🚀 Features
|
## Components
|
||||||
|
|
||||||
- **Multiple Routes**: Home, About, Contact pages with clean navigation
|
| Path | Description |
|
||||||
- **Contact Form**: Functional contact form with validation and flash messages
|
|------|-------------|
|
||||||
- **JSON API**: RESTful API endpoints for data exchange
|
| `app.py` | Flask web app and JSON API |
|
||||||
- **Responsive Design**: Mobile-first design using Bootstrap 5
|
| `cli/finger.py` | Command-line client |
|
||||||
- **Error Handling**: Custom 404 and 500 error pages
|
| `mcp/server.py` | MCP server for Claude |
|
||||||
- **Modern UI**: Clean, professional interface with animations
|
|
||||||
- **Form Validation**: Client-side and server-side validation
|
|
||||||
- **Configuration Management**: Environment-based configuration
|
|
||||||
|
|
||||||
## 📁 Project Structure
|
---
|
||||||
|
|
||||||
```
|
## Web App
|
||||||
finger-web/
|
|
||||||
├── app.py # Main Flask application
|
|
||||||
├── config.py # Configuration settings
|
|
||||||
├── requirements.txt # Python dependencies
|
|
||||||
├── README.md # Project documentation
|
|
||||||
├── .gitignore # Git ignore file
|
|
||||||
├── Dockerfile # Docker container configuration
|
|
||||||
├── .dockerignore # Docker ignore file
|
|
||||||
├── docker-compose.yml # Docker Compose configuration
|
|
||||||
├── templates/ # HTML templates
|
|
||||||
│ ├── base.html # Base template with navigation
|
|
||||||
│ ├── index.html # Home page
|
|
||||||
│ ├── about.html # About page
|
|
||||||
│ ├── contact.html # Contact form
|
|
||||||
│ ├── 404.html # 404 error page
|
|
||||||
│ └── 500.html # 500 error page
|
|
||||||
└── static/ # Static assets
|
|
||||||
├── css/
|
|
||||||
│ └── style.css # Custom styles
|
|
||||||
└── js/
|
|
||||||
└── main.js # JavaScript functionality
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🛠️ Technologies Used
|
### Requirements
|
||||||
|
|
||||||
### Backend
|
- Python 3.9+
|
||||||
- **Python 3.x** - Programming language
|
- A `finger` binary available on the server's PATH
|
||||||
- **Flask 2.3.3** - Web framework
|
|
||||||
- **Jinja2** - Template engine
|
|
||||||
- **Werkzeug** - WSGI toolkit
|
|
||||||
|
|
||||||
### Frontend
|
### Installation
|
||||||
- **HTML5** - Markup language
|
|
||||||
- **CSS3** - Styling with custom animations
|
|
||||||
- **JavaScript (ES6+)** - Interactive functionality
|
|
||||||
- **Bootstrap 5.3** - CSS framework for responsive design
|
|
||||||
|
|
||||||
## 📋 Prerequisites
|
|
||||||
|
|
||||||
- Python 3.7 or higher
|
|
||||||
- pip (Python package installer)
|
|
||||||
- Virtual environment (recommended)
|
|
||||||
|
|
||||||
## 🚀 Installation & Setup
|
|
||||||
|
|
||||||
### 1. Clone or Download the Project
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# If using git
|
|
||||||
git clone <repository-url>
|
|
||||||
cd finger-web
|
|
||||||
|
|
||||||
# Or download and extract the project files
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. Create Virtual Environment (Recommended)
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Create virtual environment
|
|
||||||
python -m venv venv
|
|
||||||
|
|
||||||
# Activate virtual environment
|
|
||||||
# On Windows:
|
|
||||||
venv\Scripts\activate
|
|
||||||
# On macOS/Linux:
|
|
||||||
source venv/bin/activate
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. Install Dependencies
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
pip install -r requirements.txt
|
pip install -r requirements.txt
|
||||||
```
|
```
|
||||||
|
|
||||||
### 4. Run the Application
|
### Configuration
|
||||||
|
|
||||||
|
All settings are read from environment variables.
|
||||||
|
|
||||||
|
| Variable | Description | Default |
|
||||||
|
|----------|-------------|---------|
|
||||||
|
| `SECRET_KEY` | Flask secret key | `dev-secret-key-change-in-production` |
|
||||||
|
| `FLASK_DEBUG` | Enable debug mode | `True` |
|
||||||
|
| `BASIC_AUTH_USERS` | Comma-separated `user:pass` pairs for upload auth | _(none — upload disabled)_ |
|
||||||
|
| `SCP_ENABLED` | Enable SCP transfer of uploaded plan files | `false` |
|
||||||
|
| `REMOTE_HOST` | Remote host for SCP | — |
|
||||||
|
| `REMOTE_USER` | Remote user for SCP | — |
|
||||||
|
| `REMOTE_PATH` | Remote path for SCP destination | — |
|
||||||
|
| `REMOTE_PORT` | Remote SSH port | `22` |
|
||||||
|
| `REMOTE_PRIVATE_KEY` | Path to SSH private key | — |
|
||||||
|
|
||||||
|
### Running
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
python app.py
|
python app.py
|
||||||
```
|
# or with gunicorn
|
||||||
|
|
||||||
The application will start on `http://localhost:5000`
|
|
||||||
|
|
||||||
## 🌐 Available Routes
|
|
||||||
|
|
||||||
| Route | Method | Description |
|
|
||||||
|-------|--------|-------------|
|
|
||||||
| `/` | GET | Home page |
|
|
||||||
| `/about` | GET | About page |
|
|
||||||
| `/contact` | GET, POST | Contact form |
|
|
||||||
| `/api/hello` | GET | Simple JSON API endpoint |
|
|
||||||
| `/api/info` | GET | Application information API |
|
|
||||||
|
|
||||||
## 🔧 Configuration
|
|
||||||
|
|
||||||
The application uses environment variables for configuration. You can set these in your environment or create a `.env` file:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Flask Configuration
|
|
||||||
FLASK_DEBUG=True
|
|
||||||
SECRET_KEY=your-secret-key-here
|
|
||||||
|
|
||||||
# Database (for future use)
|
|
||||||
DATABASE_URL=sqlite:///app.db
|
|
||||||
|
|
||||||
# Mail Configuration (for future use)
|
|
||||||
MAIL_SERVER=smtp.gmail.com
|
|
||||||
MAIL_PORT=587
|
|
||||||
MAIL_USE_TLS=True
|
|
||||||
MAIL_USERNAME=[email protected]
|
|
||||||
MAIL_PASSWORD=your-app-password
|
|
||||||
```
|
|
||||||
|
|
||||||
## 📱 API Endpoints
|
|
||||||
|
|
||||||
### GET /api/hello
|
|
||||||
Returns a simple greeting message.
|
|
||||||
|
|
||||||
**Response:**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"message": "Hello from Flask API!",
|
|
||||||
"status": "success",
|
|
||||||
"version": "1.0"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### GET /api/info
|
|
||||||
Returns application information and available routes.
|
|
||||||
|
|
||||||
**Response:**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"app_name": "Finger Web Flask App",
|
|
||||||
"routes": ["/", "/about", "/contact", "/api/hello", "/api/info"],
|
|
||||||
"framework": "Flask"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🎨 Customization
|
|
||||||
|
|
||||||
### Styling
|
|
||||||
- Edit `static/css/style.css` to customize the appearance
|
|
||||||
- The app uses Bootstrap 5 classes for responsive design
|
|
||||||
- Custom CSS variables and animations are included
|
|
||||||
|
|
||||||
### JavaScript
|
|
||||||
- Modify `static/js/main.js` for additional functionality
|
|
||||||
- Includes form validation, animations, and keyboard shortcuts
|
|
||||||
- API helper functions are available
|
|
||||||
|
|
||||||
### Templates
|
|
||||||
- All HTML templates extend `templates/base.html`
|
|
||||||
- Use Jinja2 template syntax for dynamic content
|
|
||||||
- Bootstrap components are readily available
|
|
||||||
|
|
||||||
## 🔍 Features in Detail
|
|
||||||
|
|
||||||
### Contact Form
|
|
||||||
- Client-side validation with real-time feedback
|
|
||||||
- Server-side validation and sanitization
|
|
||||||
- Flash messages for user feedback
|
|
||||||
- Form submission with loading states
|
|
||||||
|
|
||||||
### Responsive Design
|
|
||||||
- Mobile-first approach
|
|
||||||
- Bootstrap grid system
|
|
||||||
- Custom breakpoints and animations
|
|
||||||
- Touch-friendly interface
|
|
||||||
|
|
||||||
### Error Handling
|
|
||||||
- Custom 404 and 500 error pages
|
|
||||||
- Graceful error handling in routes
|
|
||||||
- User-friendly error messages
|
|
||||||
|
|
||||||
### JavaScript Features
|
|
||||||
- Form validation and enhancement
|
|
||||||
- Smooth scrolling navigation
|
|
||||||
- Card animations on scroll
|
|
||||||
- Keyboard shortcuts (Alt+H, Alt+A, Alt+C)
|
|
||||||
- API interaction helpers
|
|
||||||
|
|
||||||
## 🚀 Deployment
|
|
||||||
|
|
||||||
### Development
|
|
||||||
```bash
|
|
||||||
python app.py
|
|
||||||
```
|
|
||||||
|
|
||||||
### Docker Deployment
|
|
||||||
|
|
||||||
#### Option 1: Using Docker directly
|
|
||||||
```bash
|
|
||||||
# Build the Docker image
|
|
||||||
docker build -t finger-web .
|
|
||||||
|
|
||||||
# Run the container
|
|
||||||
docker run -d -p 5000:5000 --name finger-web-app finger-web
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Option 2: Using Docker Compose (Recommended)
|
|
||||||
```bash
|
|
||||||
# Build and start the application
|
|
||||||
docker-compose up -d
|
|
||||||
|
|
||||||
# View logs
|
|
||||||
docker-compose logs -f
|
|
||||||
|
|
||||||
# Stop the application
|
|
||||||
docker-compose down
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Docker Commands
|
|
||||||
```bash
|
|
||||||
# Build image
|
|
||||||
docker build -t finger-web .
|
|
||||||
|
|
||||||
# Run container with environment variables
|
|
||||||
docker run -d \
|
|
||||||
-p 5000:5000 \
|
|
||||||
-e FLASK_ENV=production \
|
|
||||||
-e SECRET_KEY=your-secret-key \
|
|
||||||
--name finger-web-app \
|
|
||||||
finger-web
|
|
||||||
|
|
||||||
# View container logs
|
|
||||||
docker logs finger-web-app
|
|
||||||
|
|
||||||
# Stop and remove container
|
|
||||||
docker stop finger-web-app
|
|
||||||
docker rm finger-web-app
|
|
||||||
```
|
|
||||||
|
|
||||||
### Production
|
|
||||||
For production deployment, consider using:
|
|
||||||
- **Docker** for containerization (included)
|
|
||||||
- **Docker Compose** for orchestration (included)
|
|
||||||
- **Gunicorn** as WSGI server
|
|
||||||
- **Nginx** as reverse proxy
|
|
||||||
- **Heroku**, **DigitalOcean**, or **AWS** for hosting
|
|
||||||
|
|
||||||
Example with Gunicorn:
|
|
||||||
```bash
|
|
||||||
pip install gunicorn
|
|
||||||
gunicorn -w 4 -b 0.0.0.0:5000 app:app
|
gunicorn -w 4 -b 0.0.0.0:5000 app:app
|
||||||
```
|
```
|
||||||
|
|
||||||
## 🔒 Security Considerations
|
### Docker
|
||||||
|
|
||||||
- Change the `SECRET_KEY` in production
|
```bash
|
||||||
- Use environment variables for sensitive data
|
docker-compose up -d
|
||||||
- Enable HTTPS in production
|
```
|
||||||
- Implement rate limiting for forms
|
|
||||||
- Validate and sanitize all user inputs
|
|
||||||
|
|
||||||
## 🤝 Contributing
|
|
||||||
|
|
||||||
1. Fork the project
|
|
||||||
2. Create a feature branch
|
|
||||||
3. Make your changes
|
|
||||||
4. Test thoroughly
|
|
||||||
5. Submit a pull request
|
|
||||||
|
|
||||||
## 📝 License
|
|
||||||
|
|
||||||
This project is open source and available under the [MIT License](LICENSE).
|
|
||||||
|
|
||||||
## 📞 Support
|
|
||||||
|
|
||||||
If you encounter any issues or have questions:
|
|
||||||
1. Check the existing documentation
|
|
||||||
2. Review the code comments
|
|
||||||
3. Test in a clean virtual environment
|
|
||||||
4. Create an issue with detailed information
|
|
||||||
|
|
||||||
## 🎯 Future Enhancements
|
|
||||||
|
|
||||||
- Database integration with SQLAlchemy
|
|
||||||
- User authentication and sessions
|
|
||||||
- Email functionality for contact form
|
|
||||||
- Admin dashboard
|
|
||||||
- API rate limiting
|
|
||||||
- Unit tests
|
|
||||||
- CI/CD pipeline
|
|
||||||
- Kubernetes deployment manifests
|
|
||||||
- Monitoring and logging integration
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
**Built with ❤️ using Flask and Bootstrap**
|
## API
|
||||||
|
|
||||||
|
| Endpoint | Method | Auth | Description |
|
||||||
|
|----------|--------|------|-------------|
|
||||||
|
| `/finger` | GET/POST | — | Web UI finger query |
|
||||||
|
| `/finger/<username>` | GET | — | Web UI finger query (URL form) |
|
||||||
|
| `/api/finger` | GET | — | JSON: list logged-in users |
|
||||||
|
| `/api/finger/<username>` | GET | — | JSON: finger a specific user |
|
||||||
|
| `/api/upload` | POST | Basic | Upload a plan file |
|
||||||
|
| `/api/info` | GET | — | API metadata |
|
||||||
|
|
||||||
|
### Example
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl http://localhost:5000/api/finger/[email protected]
|
||||||
|
```
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "success",
|
||||||
|
"username": "[email protected]",
|
||||||
|
"result": "Login: pete\t\t\tName: Pete Blair\n..."
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## CLI
|
||||||
|
|
||||||
|
### Installation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pip install -r cli/requirements.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
### Configuration
|
||||||
|
|
||||||
|
```bash
|
||||||
|
export FINGER_WEB_URL=http://localhost:5000
|
||||||
|
export FINGER_USER=youruser # only needed for plan uploads
|
||||||
|
export FINGER_PASS=yourpassword # only needed for plan uploads
|
||||||
|
```
|
||||||
|
|
||||||
|
### Usage
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Finger a user
|
||||||
|
python cli/finger.py query [email protected]
|
||||||
|
|
||||||
|
# Upload your plan file
|
||||||
|
python cli/finger.py plan ~/.plan
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## MCP Server
|
||||||
|
|
||||||
|
Exposes finger query and plan upload as tools for Claude.
|
||||||
|
|
||||||
|
### Installation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pip install -r mcp/requirements.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
### Configuration
|
||||||
|
|
||||||
|
```bash
|
||||||
|
export FINGER_WEB_URL=http://localhost:5000
|
||||||
|
export FINGER_USER=youruser # only needed for upload_plan tool
|
||||||
|
export FINGER_PASS=yourpassword # only needed for upload_plan tool
|
||||||
|
```
|
||||||
|
|
||||||
|
### Running
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python mcp/server.py
|
||||||
|
```
|
||||||
|
|
||||||
|
### Claude Desktop configuration
|
||||||
|
|
||||||
|
Add to your `claude_desktop_config.json`:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"finger": {
|
||||||
|
"command": "python",
|
||||||
|
"args": ["/path/to/finger-web/mcp/server.py"],
|
||||||
|
"env": {
|
||||||
|
"FINGER_WEB_URL": "http://localhost:5000",
|
||||||
|
"FINGER_USER": "youruser",
|
||||||
|
"FINGER_PASS": "yourpassword"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Available tools
|
||||||
|
|
||||||
|
| Tool | Description |
|
||||||
|
|------|-------------|
|
||||||
|
| `finger_user(username)` | Query finger info for a user, or leave empty to list logged-in users |
|
||||||
|
| `upload_plan(filename, content)` | Upload or update a plan file |
|
||||||
|
|||||||
Reference in New Issue
Block a user