Owlibou/owlen
2
1
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

67
docs/CHANGELOG_v1.0.md
View File

@@ -6,35 +6,39 @@ Version 1.0.0 marks the completion of the MCP-only architecture migration, remov
## Breaking Changes
### 1. Removed Legacy MCP Mode
### 1. MCP mode defaults to remote-preferred (legacy retained)
**What changed:**
- The `[mcp]` section in `config.toml` no longer accepts a `mode` setting
- The `McpMode` enum has been removed from the configuration system
- MCP architecture is now always enabled - no option to disable it
- 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:**
```diff
# old config.toml
```toml
[mcp]
-mode = "legacy" # or "enabled"
mode = "remote_preferred"
allow_fallback = true
warn_on_legacy = true
```
# new config.toml
To opt out of remote MCP servers temporarily:
```toml
[mcp]
# MCP is always enabled - no mode setting needed
mode = "local_only" # or "legacy" for backwards compatibility
```
**Code changes:**
- `crates/owlen-core/src/config.rs`: Removed `McpMode` enum, simplified `McpSettings`
- `crates/owlen-core/src/mcp/factory.rs`: Removed legacy mode handling from `McpClientFactory`
- All provider calls now go through MCP clients exclusively
- `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()` no longer checks for legacy mode
- Automatically falls back to `LocalMcpClient` when no external MCP servers are configured
- Improved error messages for server connection failures
- `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:**
```rust
@@ -46,11 +50,11 @@ match self.config.mcp.mode {
**After:**
```rust
// Always use MCP architecture
if let Some(server_cfg) = self.config.mcp_servers.first() {
// Try remote server, fallback to local on error
} else {
// Use local client
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"),
}
```
@@ -79,8 +83,8 @@ Added comprehensive mock implementations for testing:
- Rollback procedures if needed
2. **Updated Configuration Reference**
- Removed references to legacy mode
- Clarified MCP server configuration
- 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
@@ -92,9 +96,9 @@ Added comprehensive mock implementations for testing:
### Configuration System
- `McpSettings` struct now only serves as a placeholder for future MCP-specific settings
- Removed `McpMode` enum entirely
- Default configuration no longer includes mode setting
- `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
@@ -113,16 +117,15 @@ No performance regressions expected. The MCP architecture may actually improve p
### Backwards Compatibility
**Breaking:** Configuration files with `mode = "legacy"` will need to be updated:
- The setting is ignored (logs a warning in future versions)
- User config has been automatically updated if using standard path
- 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 is kept for future expansion:
- Can add MCP-specific timeouts
- Can add connection pooling settings
- Can add server selection strategies
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

13
docs/configuration.md
View File

@@ -4,9 +4,15 @@ Owlen uses a TOML file for configuration, allowing you to customize its behavior
## File Location
By default, Owlen looks for its configuration file at `~/.config/owlen/config.toml`.
Owlen resolves the configuration path using the platform-specific config directory:
A default configuration file is created on the first run if one doesn't exist.
| Platform | Location |
|----------|----------|
| Linux | `~/.config/owlen/config.toml` |
| macOS | `~/Library/Application Support/owlen/config.toml` |
| Windows | `%APPDATA%\owlen\config.toml` |
Run `owlen config path` to print the exact location on your machine. A default configuration file is created on the first run if one doesn't exist, and `owlen config doctor` can migrate/repair legacy files automatically.
## Configuration Precedence
@@ -16,6 +22,8 @@ Configuration values are resolved in the following order:
2. **Configuration File**: Any values set in `config.toml` will override the defaults.
3. **Command-Line Arguments / In-App Changes**: Any settings changed during runtime (e.g., via the `:theme` or `:model` commands) will override the configuration file for the current session. Some of these changes (like theme and model) are automatically saved back to the configuration file.
Validation runs whenever the configuration is loaded or saved. Expect descriptive `Configuration error` messages if, for example, `remote_only` mode is set without any `[[mcp_servers]]` entries.
---
## General Settings (`[general]`)
@@ -118,6 +126,7 @@ base_url = "https://ollama.com"
- `api_key` (string, optional)
The API key to use for authentication, if required.
**Note:** `ollama-cloud` now requires an API key; Owlen will refuse to start the provider without one and will hint at the missing configuration.
- `extra` (table, optional)
Any additional, provider-specific parameters can be added here.

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

24
docs/platform-support.md Normal file
View File

@@ -0,0 +1,24 @@
# Platform Support
Owlen targets all major desktop platforms; the table below summarises the current level of coverage and how to verify builds locally.
| Platform | Status | Notes |
|----------|--------|-------|
| Linux | ✅ Primary | CI and local development happen on Linux. `owlen config doctor` and provider health checks are exercised every run. |
| macOS | ✅ Supported | Tested via local builds. Uses the macOS application support directory for configuration and session data. |
| Windows | ⚠️ Preview | Uses platform-specific paths and compiles via `scripts/check-windows.sh`. Runtime testing is limited—feedback welcome. |
### Verifying Windows compatibility from Linux/macOS
```bash
./scripts/check-windows.sh
```
The script installs the `x86_64-pc-windows-gnu` target if necessary and runs `cargo check` against it. Run it before submitting PRs that may impact cross-platform support.
### Troubleshooting
- Provider startup failures now surface clear hints (e.g. "Ensure Ollama is running").
- The TUI warns when the active terminal lacks 256-colour capability; consider switching to a true-colour terminal for the best experience.
Refer to `docs/troubleshooting.md` for additional guidance.

20
docs/troubleshooting.md
View File

@@ -9,10 +9,17 @@ If you are unable to connect to a local Ollama instance, here are a few things t
1. **Is Ollama running?** Make sure the Ollama service is active. You can usually check this with `ollama list`.
2. **Is the address correct?** By default, Owlen tries to connect to `http://localhost:11434`. If your Ollama instance is running on a different address or port, you will need to configure it in your `config.toml` file.
3. **Firewall issues:** Ensure that your firewall is not blocking the connection.
4. **Health check warnings:** Owlen now performs a provider health check on startup. If it fails, the error message will include a hint (either "start owlen-mcp-llm-server" or "ensure Ollama is running"). Resolve the hint and restart.
## Model Not Found Errors
If you get a "model not found" error, it means that the model you are trying to use is not available. For local providers like Ollama, you can use `ollama list` to see the models you have downloaded. Make sure the model name in your Owlen configuration matches one of the available models.
Owlen surfaces this as `InvalidInput: Model '<name>' was not found`.
1. **Local models:** Run `ollama list` to confirm the model name (e.g., `llama3:8b`). Use `ollama pull <model>` if it is missing.
2. **Ollama Cloud:** Names may differ from local installs. Double-check https://ollama.com/models and remove `-cloud` suffixes.
3. **Fallback:** Switch to `mode = "local_only"` temporarily in `[mcp]` if the remote server is slow to update.
Fix the name in your configuration file or choose a model from the UI (`:model`).
## Terminal Compatibility Issues
@@ -26,9 +33,18 @@ Owlen is built with `ratatui`, which supports most modern terminals. However, if
If Owlen is not behaving as you expect, there might be an issue with your configuration file.
- **Location:** The configuration file is typically located at `~/.config/owlen/config.toml`.
- **Location:** Run `owlen config path` to print the exact location (Linux, macOS, or Windows). Owlen now follows platform defaults instead of hard-coding `~/.config`.
- **Syntax:** The configuration file is in TOML format. Make sure the syntax is correct.
- **Values:** Check that the values for your models, providers, and other settings are correct.
- **Automation:** Run `owlen config doctor` to migrate legacy settings (`mode = "legacy"`, missing providers) and validate the file before launching the TUI.
## Ollama Cloud Authentication Errors
If you see `Auth` errors when using the `ollama-cloud` provider:
1. Ensure `providers.ollama-cloud.api_key` is set **or** export `OLLAMA_API_KEY` / `OLLAMA_CLOUD_API_KEY` before launching Owlen.
2. Confirm the key has access to the requested models.
3. Avoid pasting extra quotes or whitespace into the config file—`owlen config doctor` will normalise the entry for you.
## Performance Tuning