owlen/docs/CHANGELOG_v1.0.md

Changelog for v1.0.0 - MCP-Only Architecture

Summary

Version 1.0.0 marks the completion of the MCP-only architecture migration, removing all legacy code paths and fully embracing the Model Context Protocol for all LLM interactions and tool executions.

Breaking Changes

1. MCP mode defaults to remote-preferred (legacy retained)

What changed:

• The [mcp] section in config.toml keeps a mode setting but now defaults to remote_preferred.
• Legacy values such as "legacy" map to the local_only runtime and emit a warning instead of failing.
• New toggles (allow_fallback, warn_on_legacy) give administrators explicit control over graceful degradation.

Migration:

[mcp]
mode = "remote_preferred"
allow_fallback = true
warn_on_legacy = true

To opt out of remote MCP servers temporarily:

[mcp]
mode = "local_only"  # or "legacy" for backwards compatibility

Code changes:

• crates/owlen-core/src/config.rs: Reintroduced McpMode with compatibility aliases and new settings.
• crates/owlen-core/src/mcp/factory.rs: Respects the configured mode, including strict remote-only and local-only paths.
• crates/owlen-cli/src/main.rs: Chooses between remote MCP providers and the direct Ollama provider based on the mode.

2. Updated MCP Client Factory

What changed:

• McpClientFactory::create() now enforces the configured mode (remote_only, remote_preferred, local_only, or legacy).
• Helpful configuration errors are surfaced when remote-only mode lacks servers or fallback is disabled.
• CLI users in local_only/legacy mode receive the direct Ollama provider instead of a failing MCP stub.

Before:

match self.config.mcp.mode {
    McpMode::Legacy => { /* use local */ },
    McpMode::Enabled => { /* use remote or fallback */ },
}

After:

match self.config.mcp.mode {
    McpMode::RemoteOnly => start_remote()?,
    McpMode::RemotePreferred => try_remote_or_fallback()?,
    McpMode::LocalOnly | McpMode::Legacy => use_local(),
    McpMode::Disabled => bail!("unsupported"),
}

New Features

Test Infrastructure

Added comprehensive mock implementations for testing:

1. MockProvider (crates/owlen-core/src/provider.rs)

   • Located in provider::test_utils module
   • Provides a simple provider for unit tests
   • Implements all required Provider trait methods

2. MockMcpClient (crates/owlen-core/src/mcp.rs)

   • Located in mcp::test_utils module
   • Provides a simple MCP client for unit tests
   • Returns mock tool descriptors and responses

Documentation

1. Migration Guide (docs/migration-guide.md)

   • Comprehensive guide for migrating from v0.x to v1.0
   • Step-by-step configuration update instructions
   • Common issues and troubleshooting
   • Rollback procedures if needed

2. Updated Configuration Reference

   • Documented the new remote_preferred default and fallback controls
   • Clarified MCP server configuration with remote-only expectations
   • Added examples for local and cloud Ollama usage

Bug Fixes

• Fixed test compilation errors due to missing mock implementations
• Resolved ambiguous glob re-export warnings (non-critical, test-only)

Internal Changes

Configuration System

• McpSettings gained mode, allow_fallback, and warn_on_legacy knobs.
• McpMode enum restored with explicit aliases for historical values.
• Default configuration now prefers remote servers but still works out-of-the-box with local tooling.

MCP Factory

• Simplified factory logic by removing mode branching
• Improved fallback behavior with better error messages
• Test renamed to reflect new behavior: test_factory_creates_local_client_when_no_servers_configured

Performance

No performance regressions expected. The MCP architecture may actually improve performance by:

• Removing unnecessary mode checks
• Streamlining the client creation process
• Better error handling reduces retry overhead

Compatibility

Backwards Compatibility

• Existing mode = "legacy" configs keep working (now mapped to local_only) but trigger a startup warning.
• Users who relied on remote-only behaviour should set mode = "remote_only" explicitly.

Forward Compatibility

The McpSettings struct now provides a stable surface to grow additional MCP-specific options such as:

• Connection pooling strategies
• Remote health-check cadence
• Adaptive retry controls

Testing

All tests passing:

test result: ok. 29 passed; 0 failed; 0 ignored

Key test areas:

• Agent ReAct pattern parsing
• MCP client factory creation
• Configuration loading and validation
• Mode-based tool filtering
• Permission and consent handling

Upgrade Instructions

See Migration Guide for detailed instructions.

Quick upgrade:

1. Update your ~/.config/owlen/config.toml:

   # Remove the 'mode' line from [mcp] section
   sed -i '/^mode = /d' ~/.config/owlen/config.toml
   

2. Rebuild Owlen:

   cargo build --release
   

3. Test with a simple query:

   owlen
   

Known Issues

1. Warning about ambiguous glob re-exports - Non-critical, only affects test builds
2. First inference may be slow - Ollama loads models on first use (expected behavior)
3. Cloud model 404 errors - Ensure model names match Ollama Cloud's naming (remove -cloud suffix from model names)

Contributors

This release completes the Phase 10 migration plan documented in .agents/new_phases.md.

Related Issues

• Closes: Legacy mode removal
• Implements: Phase 10 cleanup and production polish
• References: MCP architecture migration phases 1-10