feat: Add streamable-http transport, .env configuration, and enhanced logging

[muTeREdO]

Summary

This PR adds several key enhancements to the NetBox MCP Server to improve usability, configuration flexibility, and debugging capabilities.

Features Added

🌐 Dual Transport Support

• stdio transport: For local/CLI usage (existing functionality)
• streamable-http transport: For web services and remote access
• Unified configuration-driven approach using FastMCP's built-in capabilities

⚙️ Flexible Configuration System

• .env file support: Easy configuration management with env.sample template
• CLI arguments: Override any configuration option via command line
• Environment variables: Traditional environment variable support
• Configuration precedence: CLI args > .env file > environment variables

🔍 Enhanced Logging & Debugging

• Comprehensive debug logging: Request/response details, configuration info, error traces
• NetBox client logging: Detailed HTTP request/response logging
• Host header fix: Prevents "No Host Supplied" errors
• JSON filter parsing: Automatic handling of JSON string filters in MCP tools

📚 Documentation Updates

• Complete README overhaul: Configuration examples, transport setup, troubleshooting
• Usage examples: Both stdio and streamable-http configurations
• Debug guide: Common issues and solutions

Configuration Options

# .env file example
NETBOX_URL=https://netbox.example.com/
NETBOX_TOKEN=your-token
MCP_TRANSPORT=stdio                    # or streamable-http
MCP_SERVER_HOST=localhost              # for HTTP transport
MCP_SERVER_PORT=8000                   # for HTTP transport
LOG_LEVEL=INFO                         # DEBUG, INFO, WARNING, ERROR
VERIFY_SSL=true                        # SSL verification

CLI Usage Examples

# stdio transport (default)
python3 server.py

# streamable-http transport
python3 server.py --transport streamable-http --host 0.0.0.0 --port 8080

# Debug mode
python3 server.py --log-level DEBUG

Breaking Changes

• Server now supports explicit configuration (backward compatible with environment variables)
• Enhanced error handling may change some error message formats
• Added new dependencies: python-dotenv

Testing

• stdio transport functionality verified
• streamable-http transport functionality verified
• .env file configuration tested
• CLI argument overrides tested
• Debug logging verified
• NetBox API connectivity tested

Files Changed

• server.py: Major enhancements with transport support, configuration, and logging
• README.md: Comprehensive documentation update
• netbox_client.py: Enhanced debugging and error handling
• .gitignore: Added to ignore .env, __pycache__, etc.
• env.sample: Configuration template
• requirements.txt & pyproject.toml: Updated dependencies

Statistics: 7 files changed, 604 additions, 46 deletions

Related Issues

This addresses common user requests for:

• HTTP transport support for web services
• Better configuration management
• Enhanced debugging capabilities
• Improved documentation

---

Note: This maintains full backward compatibility while adding significant new functionality.

[ltucker]

Thanks for this! I see several ideas and fixes in here -- I think it may be worth breaking it up a bit to look at some of these independently if you're up for it.

I would agree there is a fundamental need to establish a reasonable configuration system to address some of these issues and that might be a good place to start (and then address some of the things it enables in follow ups)

The support for .env and letting environment drive configuration of fastmcp makes sense to me -- I'm slightly less sold on introducing argparse as the driver of the expected app configuration structure / getting too far into trying to expose the whole configuration with command line args at this point. Possibly we could put in an explicit pydantic definition of the configuration structure instead of stating it as argparse?