From 83280f68cc9e377eec30aedb876096cb32bc1e47 Mon Sep 17 00:00:00 2001 From: vikingowl Date: Sat, 25 Oct 2025 03:08:34 +0200 Subject: [PATCH] docs(mcp): align tool docs with codex parity - Document web_search as the canonical MCP tool name and retain the legacy web.search alias across README, changelog, and mode docs. - Explain how to mirror Codex CLI MCP installs with codex mcp add and note the common server bundle. - Point the configuration guide at spec-compliant naming and runtime toggles for Codex users. Acceptance Criteria: - Documentation stops advertising dotted tool names as canonical and references Codex-compatible installs. Test Notes: - docs-only change; no automated tests run. --- CHANGELOG.md | 4 ++-- README.md | 16 ++++++++++++++-- docs/configuration.md | 4 ++-- docs/phase5-mode-system.md | 7 ++++--- 4 files changed, 22 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c06ee17..d97f9a4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -39,7 +39,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `McpMode` support was restored with explicit validation; `remote_only`, `remote_preferred`, and `local_only` now behave predictably. - Configuration loading performs structural validation and fails fast on missing default providers or invalid MCP definitions. - Ollama provider error handling now distinguishes timeouts, missing models, and authentication failures. -- The `web.search` tool now proxies through Ollama Cloud’s `/api/web_search` endpoint and is hidden whenever the active provider cannot reach the cloud. +- The `web_search` tool now proxies through Ollama Cloud’s `/api/web_search` endpoint and is hidden whenever the active provider cannot reach the cloud. The legacy `web.search` alias stays enabled for older sessions. - `owlen` warns when the active terminal likely lacks 256-color support. - `config.toml` now carries a schema version (`1.2.0`) and is migrated automatically; deprecated keys such as `agent.max_tool_calls` trigger warnings instead of hard failures. - Model selector navigation (Tab/Shift-Tab) now switches between local and cloud tabs while preserving selection state. @@ -52,7 +52,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - Cloud usage tracker now persists hourly and weekly token totals, exposes a `:limits` command, and renders live gradient gauges in the header with 80 %/95 % toast notifications. -- Web search tooling is available whenever Ollama Cloud is configured, giving the assistant automatic access to the `web.search` function with runtime toggles via `:web on|off`. +- Web search tooling is available whenever Ollama Cloud is configured, giving the assistant automatic access to the `web_search` function with runtime toggles via `:web on|off`. Legacy dotted references continue to resolve through the alias layer. - Provider registry aggregates local and cloud Ollama models, including health checks, scope badges, and graceful fallback between providers. - Release documentation covers the migration from v0.1, including the new config schema defaults, cloud setup guide, and troubleshooting steps for common errors. diff --git a/README.md b/README.md index 32ced6a..e5901c2 100644 --- a/README.md +++ b/README.md @@ -43,9 +43,21 @@ The refreshed chrome introduces a cockpit-style header with live gradient gauges - **Local + Cloud resiliency**: Owlen now distinguishes the on-device daemon from Ollama Cloud and gracefully falls back to local if the hosted key is missing or unauthorized. Cloud requests include `Authorization: Bearer ` and reuse the canonical `https://ollama.com` base URL so you no longer hit 401 loops. - **Context + quota cockpit**: The header shows `context used / window (percentage)` and a second gauge for hourly/weekly cloud token usage. Configure soft limits via `providers.ollama_cloud.hourly_quota_tokens` and `weekly_quota_tokens`; Owlen tracks consumption locally even when the provider omits token counters. -- **Web search tooling**: When cloud is enabled, models can call the `web.search` tool automatically. Toggle availability at runtime with `:web on` / `:web off` if you need a local-only session. +- **Web search tooling**: When cloud is enabled, models can call the spec-compliant `web_search` tool automatically (the legacy `web.search` alias remains for backward compatibility). Toggle availability at runtime with `:web on` / `:web off` if you need a local-only session. - **Docs & config parity**: Ship-ready config templates now include per-provider `list_ttl_secs` and `default_context_window` values, plus explicit `OLLAMA_API_KEY` guidance. Run `owlen config doctor` after upgrading from v0.1 to normalize legacy keys and receive deprecation warnings for `OLLAMA_CLOUD_API_KEY` and `OWLEN_OLLAMA_CLOUD_API_KEY`. -- **Runtime toggles**: Use `:web on` / `:web off` in the TUI or `owlen providers web --enable/--disable` from the CLI to expose or hide the `web.search` tool without editing `config.toml`. +- **Runtime toggles**: Use `:web on` / `:web off` in the TUI or `owlen providers web --enable/--disable` from the CLI to expose or hide the `web_search` tool without editing `config.toml`. + +## MCP Naming & Codex Compatibility + +To stay interoperable with Codex and the broader Model Context Protocol (MCP) ecosystem, Owlen now documents the underscore form (`web_search`) as the canonical tool identifier. This matches Codex’s own configuration flags (`tools.web_search`) and avoids dotted names that fall outside MCP’s identifier rules.citeturn6view0 + +When you need Codex parity, mirror the CLI workflow Codex documents: + +- List or install servers with `codex mcp add -- ` (e.g., Context7, Figma local/remote, Playwright, Chrome DevTools, Sentry, GitHub).citeturn4view0 +- Keep legacy `web.search` in Owlen as an alias so older transcripts still replay, but prefer `web_search` in configs, prompts, and tests. +- Use Owlen’s tooling registry to pair those servers with the same identifier Codex emits (for example `context7__search` once names are qualified during Codex handshakes). + +The documentation set below explains how to register those servers, how to export Codex’s MCP configuration if you want to share the exact JSON with Owlen, and how to toggle `web_search` at runtime. ## Security & Privacy diff --git a/docs/configuration.md b/docs/configuration.md index 1888484..3420fb4 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -202,9 +202,9 @@ Requests target the same `/api/chat` endpoint documented by Ollama and automatic The quota fields are optional and purely informational—they are never sent to the provider. Owlen uses them to display hourly/weekly token usage in the chat header, emit pre-limit toasts at 80% and 95%, and power the `:limits` command. Adjust the numbers to reflect the soft limits on your account or remove the keys altogether if you do not want usage tracking. -If your deployment exposes the web search endpoint under a different path, set `web_search_endpoint` in the same table. The default (`/api/web_search`) matches the Ollama Cloud REST API documented in the web retrieval guide. +If your deployment exposes the web search endpoint under a different path, set `web_search_endpoint` in the same table. The default (`/api/web_search`) matches the Ollama Cloud REST API documented in the web retrieval guide. Tools should be registered as `web_search` to stay within MCP’s identifier rules; Owlen keeps `web.search` as a backward-compatible alias but treats the underscored form as canonical.citeturn6view0 -Toggle the feature at runtime with `:web on` / `:web off` from the TUI or `owlen providers web --enable/--disable` on the CLI; both commands persist the change back to `config.toml`. +Toggle the feature at runtime with `:web on` / `:web off` from the TUI or `owlen providers web --enable/--disable` on the CLI; both commands persist the change back to `config.toml`. Codex users can mirror this setup by running `codex mcp add` for each server (Context7, Figma, Playwright, Chrome DevTools, Sentry, GitHub, etc.) and then binding the exposed tool identifiers to Owlen’s registry.citeturn4view0turn6view0 > **Tip:** If the official `ollama signin` flow fails on Linux v0.12.3, follow the [Linux Ollama sign-in workaround](#linux-ollama-sign-in-workaround-v0123) in the troubleshooting guide to copy keys from a working machine or register them manually. diff --git a/docs/phase5-mode-system.md b/docs/phase5-mode-system.md index c1b2576..36a5b62 100644 --- a/docs/phase5-mode-system.md +++ b/docs/phase5-mode-system.md @@ -14,7 +14,7 @@ Phase 5 has been fully implemented according to the specification in `.agents/ne - `ModeConfig` for configuring tool availability per mode - `ModeToolConfig` with wildcard (`*`) support for allowing all tools - Default configuration: - - Chat mode: only `web_search` allowed + - Chat mode: only `web_search` allowed (legacy `web.search` alias still resolves) - Code mode: all tools allowed (`*`) ### 2. Configuration Integration (✅ Complete) @@ -27,7 +27,7 @@ Phase 5 has been fully implemented according to the specification in `.agents/ne ```toml [modes.chat] -allowed_tools = ["web_search"] +allowed_tools = ["web_search"] # Legacy `web.search` alias still accepted [modes.code] allowed_tools = ["*"] # All tools allowed @@ -132,6 +132,7 @@ default_model = "llama3.2:latest" [modes.chat] # In chat mode, only web search is allowed +# When migrating older configs you can still list `web.search`, but Owlen rewrites it internally. allowed_tools = ["web_search"] [modes.code] @@ -166,7 +167,7 @@ owlen -c ### Tool Filtering Behavior **In Chat Mode:** -- ✅ `web_search` - Allowed +- ✅ `web_search` - Allowed (legacy `web.search` alias also resolves) - ❌ `code_exec` - Blocked (suggests switching to code mode) - ❌ `file_write` - Blocked - ❌ `file_delete` - Blocked