MCP SQL Server Chat - Refactored Architecture

This project has been refactored from a monolithic script into a modular, maintainable multi-file structure following Python best practices.

File Structure

├── config.py              # Configuration and constants
├── mcp_integration.py     # MCP protocol utilities and tool conversion
├── openai_integration.py  # OpenAI client utilities and response handling
├── chat.py               # Core chat orchestration logic
├── chat_session.py       # Session state and message history management
├── streamlit_app.py      # Main Streamlit UI application
└── README.md             # This file

Module Descriptions

config.py

Centralized configuration and constants:

• MODEL: OpenAI model to use
• MCP_SERVER_COMMAND, MCP_SERVER_SCRIPT: MCP server configuration
• UI settings (page title, icon, layout)
• System prompt and default messages

Best Practice: Keeps all magic strings and configuration in one place for easy maintenance.

mcp_integration.py

MCP (Model Context Protocol) utilities:

• mcp_tool_to_openai_function(): Converts MCP tools to OpenAI function format
• create_server_params(): Creates MCP server configuration
• get_mcp_tools(): Fetches and converts available tools

Best Practice: Separates MCP-specific logic from business logic.

openai_integration.py

OpenAI client and response handling:

• initialize_openai_client(): Sets up OpenAI client with API key validation
• extract_function_calls(): Parses function calls from OpenAI responses
• format_tool_output(): Formats tool execution results

Best Practice: Encapsulates OpenAI-specific operations in a dedicated module.

chat.py

Core chat turn orchestration:

• run_chat_turn(): Main async function coordinating MCP + OpenAI interaction
• Handles tool discovery, function calling, and result feeding

Best Practice: Clean separation of business logic from UI and client initialization.

chat_session.py

Session state management:

• initialize_session_state(): Sets up Streamlit session state
• get_messages(), add_user_message(), add_assistant_message(): Session accessors
• get_display_messages(): Filters out system messages for display

Best Practice: Centralized state management for easier testing and maintenance.

streamlit_app.py

Main Streamlit UI application:

• configure_page(): Page configuration
• render_sidebar(): Settings panel
• render_message_history(): Chat display
• handle_user_input(): User input processing
• main(): Application entry point

Best Practice: UI logic is clean and focused on presentation.

Running the Application

streamlit run streamlit_app.py

Environment Setup

# Set your OpenAI API key
export OPENAI_API_KEY="your-api-key-here"

# Ensure mcp_mssql_server.py is in the same directory or update config.py

Key Benefits of This Refactoring

1. Modularity: Each module has a single responsibility
2. Testability: Isolated functions can be unit tested independently
3. Reusability: Modules can be imported and used in other projects
4. Maintainability: Changes to one concern don't affect others
5. Scalability: Easy to add new features without cluttering the codebase
6. Documentation: Docstrings and clear code organization
7. Configuration Management: All settings in one place
8. Error Handling: Better separation for targeted error management
9. Async Management: Proper asyncio handling with fallbacks

Extending the Architecture

Adding a New MCP Tool Handler

1. Add utility function to mcp_integration.py
2. Import and use in chat.py

Adding UI Features

1. Create new functions in streamlit_app.py or a new ui_components.py
2. Import utilities as needed

Adding New Configuration

1. Add constants to config.py
2. Import in relevant modules

Type Hints

All modules use Python type hints for better IDE support and code clarity.

Error Handling

• openai_integration.py validates API key on client initialization
• streamlit_app.py handles async event loop edge cases
• chat.py coordinates error handling across MCP and OpenAI

Testing Recommendations

The modular structure makes it easy to test individual components:

# Example: test mcp_integration.py
from mcp_integration import mcp_tool_to_openai_function

# Example: test openai_integration.py
from openai_integration import extract_function_calls

Each function is isolated and can be tested independently with mock objects.