Owlibou/owlen
2
0
Fork 0
Code Issues 20 Pull Requests Actions Packages Projects Releases 5 Activity

fix: restore mcp flexibility and improve cli tooling

Browse Source
This commit is contained in:
vikingowl
2025-10-11 06:11:22 +02:00
parent 40c44470e8
commit 5ac0d152cb
19 changed files with 998 additions and 162 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
docs/migration-guide.md
View File

@@ -12,26 +12,32 @@ As Owlen is currently in its alpha phase (pre-v1.0), breaking changes may occur
### Breaking Changes
#### 1. MCP Mode is Now Always Enabled
#### 1. MCP Mode now defaults to `remote_preferred`
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.
The `[mcp]` section in `config.toml` still accepts a `mode` setting, but the default behaviour has changed. If you previously relied on `mode = "legacy"`, you can keep that line – the value now maps to the `local_only` runtime with a compatibility warning instead of breaking outright. New installs default to the safer `remote_preferred` mode, which attempts to use any configured external MCP server and automatically falls back to the local in-process tooling when permitted.
**Supported values (v1.0+):**
| Value | Behaviour |
|--------------------|-----------|
| `remote_preferred` | Default. Use the first configured `[[mcp_servers]]`, fall back to local if `allow_fallback = true`.
| `remote_only` | Require a configured server; the CLI will error if it cannot start.
| `local_only` | Force the built-in MCP client and the direct Ollama provider.
| `legacy` | Alias for `local_only` kept for compatibility (emits a warning).
| `disabled` | Not supported by the TUI; intended for headless tooling.
You can additionally control the automatic fallback behaviour:
**Old configuration (v0.x):**
```toml
[mcp]
mode = "legacy" # or "enabled"
mode = "remote_preferred"
allow_fallback = true
warn_on_legacy = true
```
**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 (with opt-in compatibility)
#### 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**.
In v0.x, Owlen could make direct HTTP calls to Ollama when in "legacy" mode. The default v1.0 behaviour keeps all LLM interactions behind MCP, but choosing `mode = "local_only"` or `mode = "legacy"` now reinstates the direct Ollama provider while still keeping the MCP tooling stack available locally.
### What Changed Under the Hood
@@ -49,17 +55,26 @@ The v1.0 architecture implements the full 10-phase migration plan:
### Migration Steps
#### Step 1: Update Your Configuration
#### Step 1: Review Your MCP Configuration
Edit `~/.config/owlen/config.toml`:
Edit `~/.config/owlen/config.toml` and ensure the `[mcp]` section reflects how you want to run Owlen:
**Remove the `mode` line:**
```diff
```toml
[mcp]
-mode = "legacy"
mode = "remote_preferred"
allow_fallback = true
```
The `[mcp]` section can now be empty or contain future MCP-specific settings.
If you encounter issues with remote servers, you can temporarily switch to:
```toml
[mcp]
mode = "local_only" # or "legacy" for backwards compatibility
```
You will see a warning on startup when `legacy` is used so you remember to migrate later.
**Quick fix:** run `owlen config doctor` to apply these defaults automatically and validate your configuration file.
#### Step 2: Verify Provider Configuration