vikingowl
5e81185df3
This commit completes the Phase 10 migration to MCP-only architecture by removing all legacy mode code paths and configuration options. **Breaking Changes:** - Removed `McpMode` enum from configuration system - Removed `mode` setting from `[mcp]` config section - MCP architecture is now always enabled (no option to disable) **Code Changes:** - Simplified `McpSettings` struct (now a placeholder for future options) - Updated `McpClientFactory` to remove legacy mode branching - Always use MCP architecture with automatic fallback to local client - Added test infrastructure: `MockProvider` and `MockMcpClient` in test_utils **Documentation:** - Created comprehensive v0.x → v1.0 migration guide - Added CHANGELOG_v1.0.md with detailed technical changes - Documented common issues (cloud model 404s, timeouts, API key setup) - Included rollback procedures and troubleshooting steps **Testing:** - All 29 tests passing - Fixed agent tests to use new mock implementations - Updated factory test to reflect new behavior This completes the 10-phase migration plan documented in .agents/new_phases.md, establishing Owlen as a production-ready MCP-only TUI application. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
189 lines
5.6 KiB
Markdown
189 lines
5.6 KiB
Markdown
# Migration Guide
|
|
|
|
This guide documents breaking changes between versions of Owlen and provides instructions on how to migrate your configuration or usage.
|
|
|
|
As Owlen is currently in its alpha phase (pre-v1.0), breaking changes may occur more frequently. We will do our best to document them here.
|
|
|
|
---
|
|
|
|
## Migrating from v0.x to v1.0 (MCP-Only Architecture)
|
|
|
|
**Version 1.0** marks a major milestone: Owlen has completed its transition to a **MCP-only architecture** (Model Context Protocol). This brings significant improvements in modularity, extensibility, and performance, but requires configuration updates.
|
|
|
|
### Breaking Changes
|
|
|
|
#### 1. MCP Mode is Now Always Enabled
|
|
|
|
The `[mcp]` section in `config.toml` previously had a `mode` setting that could be set to `"legacy"` or `"enabled"`. In v1.0+, MCP architecture is **always enabled** and the `mode` setting has been removed.
|
|
|
|
**Old configuration (v0.x):**
|
|
```toml
|
|
[mcp]
|
|
mode = "legacy" # or "enabled"
|
|
```
|
|
|
|
**New configuration (v1.0+):**
|
|
```toml
|
|
[mcp]
|
|
# MCP is now always enabled - no mode setting needed
|
|
# This section is kept for future MCP-specific configuration options
|
|
```
|
|
|
|
#### 2. Direct Provider Access Removed
|
|
|
|
In v0.x, Owlen could make direct HTTP calls to Ollama and other providers when in "legacy" mode. In v1.0+, **all LLM interactions go through MCP servers**.
|
|
|
|
### What Changed Under the Hood
|
|
|
|
The v1.0 architecture implements the full 10-phase migration plan:
|
|
|
|
- **Phase 1-2**: File operations via MCP servers
|
|
- **Phase 3**: LLM inference via MCP servers (Ollama wrapped)
|
|
- **Phase 4**: Agent loop with ReAct pattern
|
|
- **Phase 5**: Mode system (chat/code) with tool availability
|
|
- **Phase 6**: Web search integration
|
|
- **Phase 7**: Code execution with Docker sandboxing
|
|
- **Phase 8**: Prompt server for versioned prompts
|
|
- **Phase 9**: Remote MCP server support (HTTP/WebSocket)
|
|
- **Phase 10**: Legacy mode removal and production polish
|
|
|
|
### Migration Steps
|
|
|
|
#### Step 1: Update Your Configuration
|
|
|
|
Edit `~/.config/owlen/config.toml`:
|
|
|
|
**Remove the `mode` line:**
|
|
```diff
|
|
[mcp]
|
|
-mode = "legacy"
|
|
```
|
|
|
|
The `[mcp]` section can now be empty or contain future MCP-specific settings.
|
|
|
|
#### Step 2: Verify Provider Configuration
|
|
|
|
Ensure your provider configuration is correct. For Ollama:
|
|
|
|
```toml
|
|
[general]
|
|
default_provider = "ollama"
|
|
default_model = "llama3.2:latest" # or your preferred model
|
|
|
|
[providers.ollama]
|
|
provider_type = "ollama"
|
|
base_url = "http://localhost:11434"
|
|
|
|
[providers.ollama-cloud]
|
|
provider_type = "ollama-cloud"
|
|
base_url = "https://ollama.com"
|
|
api_key = "$OLLAMA_API_KEY" # Optional: for Ollama Cloud
|
|
```
|
|
|
|
#### Step 3: Understanding MCP Server Configuration
|
|
|
|
While not required for basic usage (Owlen will use the built-in local MCP client), you can optionally configure external MCP servers:
|
|
|
|
```toml
|
|
[[mcp_servers]]
|
|
name = "llm"
|
|
command = "owlen-mcp-llm-server"
|
|
transport = "stdio"
|
|
|
|
[[mcp_servers]]
|
|
name = "filesystem"
|
|
command = "/path/to/filesystem-server"
|
|
transport = "stdio"
|
|
```
|
|
|
|
**Note**: If no `mcp_servers` are configured, Owlen automatically falls back to its built-in local MCP client, which provides the same functionality.
|
|
|
|
#### Step 4: Verify Installation
|
|
|
|
After updating your config:
|
|
|
|
1. **Check Ollama is running**:
|
|
```bash
|
|
curl http://localhost:11434/api/version
|
|
```
|
|
|
|
2. **List available models**:
|
|
```bash
|
|
ollama list
|
|
```
|
|
|
|
3. **Test Owlen**:
|
|
```bash
|
|
owlen
|
|
```
|
|
|
|
### Common Issues After Migration
|
|
|
|
#### Issue: "Warning: No MCP servers defined in config. Using local client."
|
|
|
|
**This is normal!** In v1.0+, if you don't configure external MCP servers, Owlen uses its built-in local MCP client. This provides the same functionality without needing separate server processes.
|
|
|
|
**No action required** unless you specifically want to use external MCP servers.
|
|
|
|
#### Issue: Timeouts on First Message
|
|
|
|
**Cause**: Ollama loads models into memory on first use, which can take 10-60 seconds for large models.
|
|
|
|
**Solution**:
|
|
- Be patient on first inference after model selection
|
|
- Use smaller models for faster loading (e.g., `llama3.2:latest` instead of `qwen3-coder:latest`)
|
|
- Pre-load models with: `ollama run <model-name>`
|
|
|
|
#### Issue: Cloud Models Return 404 Errors
|
|
|
|
**Cause**: Ollama Cloud model names may differ from local model names.
|
|
|
|
**Solution**:
|
|
- Verify model availability on https://ollama.com/models
|
|
- Remove the `-cloud` suffix from model names when using cloud provider
|
|
- Ensure `api_key` is set in `[providers.ollama-cloud]` config
|
|
|
|
### Rollback to v0.x
|
|
|
|
If you encounter issues and need to rollback:
|
|
|
|
1. **Reinstall v0.x**:
|
|
```bash
|
|
# Using AUR (if applicable)
|
|
yay -S owlen-git
|
|
|
|
# Or from source
|
|
git checkout <v0.x-tag>
|
|
cargo install --path crates/owlen-tui
|
|
```
|
|
|
|
2. **Restore configuration**:
|
|
```toml
|
|
[mcp]
|
|
mode = "legacy"
|
|
```
|
|
|
|
3. **Report issues**: https://github.com/Owlibou/owlen/issues
|
|
|
|
### Benefits of v1.0 MCP Architecture
|
|
|
|
- **Modularity**: LLM, file operations, and tools are isolated in MCP servers
|
|
- **Extensibility**: Easy to add new tools and capabilities via MCP protocol
|
|
- **Multi-Provider**: Support for multiple LLM providers through standard interface
|
|
- **Remote Execution**: Can connect to remote MCP servers over HTTP/WebSocket
|
|
- **Better Error Handling**: Structured error responses from MCP servers
|
|
- **Agentic Capabilities**: ReAct pattern for autonomous task completion
|
|
|
|
### Getting Help
|
|
|
|
- **Documentation**: See `docs/` directory for detailed guides
|
|
- **Issues**: https://github.com/Owlibou/owlen/issues
|
|
- **Configuration Reference**: `docs/configuration.md`
|
|
- **Troubleshooting**: `docs/troubleshooting.md`
|
|
|
|
---
|
|
|
|
## Future Migrations
|
|
|
|
We will continue to document breaking changes here as Owlen evolves. Always check this guide when upgrading to a new major version.
|