omiderfanmanesh/MCP-server

🔐 Session-Based Authenticated MCP Server

A Model Context Protocol (MCP) server with session-based authentication that provides secure access to books database and currency conversion tools. Designed specifically for AI assistants to use authentication seamlessly.

✨ Key Features

🔐 Session-Based Authentication

• Simple authentication with username only
• Automatic session management (1-hour expiration)
• No token parameters required in tool calls
• Perfect for AI assistant integration

📚 Books Database

• Search books by title, author, genre, year
• Paginated results with limit/offset
• Individual book lookup by ID
• CSV-based storage with Excel conversion

💱 Currency Exchange

• Convert between 10+ major currencies
• Real-time synthetic exchange rates
• Precise decimal calculations
• Error handling for invalid currencies

🤖 AI Assistant Optimized

• Seamless integration with GitHub Copilot, Claude Desktop, Cursor IDE
• No complex token passing required
• Simple authenticate-then-use workflow
• Comprehensive error messages and hints

🚀 Quick Start

1. Installation

# Clone the repository
git clone https://github.com/omiderfanmanesh/MCP-server.git
cd MCP-server

# Install dependencies
pip install -r requirements.txt

2. Run the Server

# Start the MCP server
python -m mcp_server.server

3. Basic Usage

# First, authenticate
"Please authenticate me as 'developer'"

# Then use any protected tools
"Find me some science fiction books"
"Convert 100 USD to EUR"
"Check my session status"
"Log me out when done"

🔧 Integration Examples

Cursor IDE Configuration

Add to your MCP settings:

{
  "mcpServers": {
    "authenticated-books": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "/path/to/MCP-server"
    }
  }
}

Claude Desktop Configuration

{
  "mcpServers": {
    "authenticated-books": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "/path/to/MCP-server"
    }
  }
}

📋 Available Tools

🧪 Testing

This project includes a comprehensive test suite with 30 test cases covering all functionality:

# Run all tests
python -m pytest tests/ -v

# Run specific test categories
python -m pytest tests/test_mcp_server.py::TestSessionAuthentication -v
python -m pytest tests/test_mcp_server.py::TestBooksRepository -v
python -m pytest tests/test_mcp_server.py::TestExchangeRates -v

Test Coverage

• ✅ JWT token generation and validation
• ✅ Session authentication flow
• ✅ Protected operations security
• ✅ Books database queries and filtering
• ✅ Currency conversion with all supported currencies
• ✅ Error handling and edge cases
• ✅ Integration workflows
• ✅ Session expiration and cleanup

🐳 Docker Deployment

Local Development

# Build and run with Docker Compose
docker-compose up --build

# The server will be available on localhost:8000

Production Deployment

# Build production image
docker build -t mcp-auth-server .

# Run container
docker run -p 8000:8000 mcp-auth-server

📚 Documentation

🏗️ Architecture Overview

graph TB
    A[AI Assistant] -->|authenticate| B[MCP Server]
    B -->|session_id| C[Session Storage]
    A -->|books_query| B
    B -->|check session| C
    C -->|valid| D[Books Database]
    A -->|exchange_convert| B
    B -->|check session| C
    C -->|valid| E[Exchange Service]

Core Components

• Session Manager: Handles authentication and session lifecycle
• Books Repository: CSV-based database with search capabilities
• Exchange Service: Multi-currency conversion with synthetic rates
• Security Layer: JWT-based session validation
• Error Handler: Comprehensive error messages and recovery hints

🔄 Authentication Flow

1. Authenticate: authenticate(username="your_name")

   • Generates JWT token
   • Creates session with 1-hour expiration
   • Returns session details

2. Use Tools: Call any protected operation

   • Automatic session validation
   • No token parameters needed
   • Clear error messages if session expired

3. Logout: logout()

   • Cleans up session data
   • Clears authentication state

🌟 Why Session-Based?

Unlike traditional JWT implementations that require token parameters in every API call, this server uses session-based authentication specifically designed for AI assistants:

Problems with Token Parameters

• AI assistants can't easily pass tokens to tool calls
• Complex parameter management
• Poor user experience

Session-Based Solution

• ✅ Authenticate once, use forever (until expiration)
• ✅ No token parameters in tool schemas
• ✅ Perfect for AI assistant workflows
• ✅ Automatic session management

🛠️ Development

Project Structure

MCP-server/
├── mcp_server/           # Main server code
│   ├── server.py         # MCP server with authentication
│   ├── books.py          # Books database repository
│   └── exchange.py       # Currency exchange service
├── tests/                # Comprehensive test suite
│   └── test_mcp_server.py
├── docs/                 # Complete documentation
│   ├── ARCHITECTURE.md   # System design
│   ├── API.md           # Tool reference
│   ├── DEPLOYMENT.md    # Production guide
│   ├── EXAMPLES.md      # Usage scenarios
│   └── GETTING_STARTED.md
├── data/                 # Books database
│   └── books.csv
├── docker-compose.yml    # Docker deployment
├── Dockerfile           # Container definition
└── requirements.txt     # Dependencies

Development Setup

# Install in development mode
pip install -e .

# Run tests with coverage
python -m pytest tests/ --cov=mcp_server

# Run server with debug logging
python -m mcp_server.server --debug

📄 License

This project is licensed under the MIT License - see the file for details.

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

See for detailed guidelines.

🔗 Links

• Model Context Protocol Specification
• MCP Python SDK
• Claude Desktop Integration
• Cursor IDE

📞 Support

• 📧 Email: [Your Email]
• 🐛 Issues: GitHub Issues
• 📖 Docs:
• 💬 Discussions: GitHub Discussions

Ready to authenticate your MCP server? 🚀 Start with the !