Merge origin/main into feature/add-datasource-relevance-filter

Resolved conflict in src/tools/datasources.py by adapting the query
relevance filter to main's dict envelope convention:
- get_data_sources now returns {dataSources, hint} (from main) and
  additionally carries a `message` field when `query` is supplied
- Empty results use a query-specific hint (_DATASOURCES_EMPTY_QUERY_HINT)
  instead of the 'add a repository' hint when filtering yields nothing
- Tests updated from json.loads(JSON string) assertions to dict shape

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: sciapanCA

.github/workflows/ci.yml

@@ -94,7 +94,9 @@ jobs:
           password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Login to Docker Hub
+        id: dockerhub_login
         if: github.event_name == 'push'
+        continue-on-error: true
         uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # v4.0.0
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
@@ -111,17 +113,30 @@ jobs:
           tags: ${{ env.IMAGE_NAME }}:pr-${{ github.event.number }}
           cache-from: type=gha
 
-      # Push to main: build multi-platform and push with rolling tags
-      - name: Build and push Docker image
+      # Push to main: build multi-platform and push the production GHCR tag.
+      - name: Build and push Docker image (GHCR)
         if: github.event_name == 'push'
         uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294 # v7.0.0
         with:
           push: true
           platforms: linux/amd64,linux/arm64
           file: ./Dockerfile
-          tags: |
-            ${{ env.IMAGE_NAME }}:main
-            ${{ env.DOCKERHUB_IMAGE }}:mcp-dev
+          tags: ${{ env.IMAGE_NAME }}:main
+          labels: |
+            io.modelcontextprotocol.server.name=io.github.CodeAlive-AI/codealive-mcp
+          cache-from: type=gha
+          cache-to: type=gha
+
+      # Docker Hub is a secondary self-hosted distribution channel. Missing
+      # credentials must not block GHCR, because production pulls from GHCR.
+      - name: Build and push Docker image (Docker Hub)
+        if: github.event_name == 'push' && steps.dockerhub_login.outcome == 'success'
+        uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294 # v7.0.0
+        with:
+          push: true
+          platforms: linux/amd64,linux/arm64
+          file: ./Dockerfile
+          tags: ${{ env.DOCKERHUB_IMAGE }}:mcp-dev
           labels: |
             io.modelcontextprotocol.server.name=io.github.CodeAlive-AI/codealive-mcp
           cache-from: type=gha

.github/workflows/release.yml

@@ -148,13 +148,20 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
+      # Docker Hub publish is a secondary distribution channel for self-hosted
+      # customers. Treat it as best-effort: missing credentials must NOT block
+      # the primary release path (GHCR push, MCP Registry publish, git tag,
+      # GitHub Release). Configure DOCKERHUB_USERNAME / DOCKERHUB_TOKEN in the
+      # `release` environment to re-enable.
       - name: Login to Docker Hub (self-hosted distribution)
+        id: dockerhub_login
+        continue-on-error: true
         uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # v4.0.0
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
-      - name: Build and push Docker image
+      - name: Build and push Docker image (GHCR)
         uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294 # v7.0.0
         with:
           push: true
@@ -165,12 +172,25 @@ jobs:
             ${{ env.IMAGE_NAME }}:${{ steps.version.outputs.version }}
             ${{ env.IMAGE_NAME }}:v${{ steps.version.outputs.version }}
             ${{ env.IMAGE_NAME }}:latest
+          labels: |
+            io.modelcontextprotocol.server.name=io.github.CodeAlive-AI/codealive-mcp
+          cache-from: type=gha
+          cache-to: type=gha
+
+      - name: Build and push Docker image (Docker Hub)
+        if: steps.dockerhub_login.outcome == 'success'
+        uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294 # v7.0.0
+        with:
+          push: true
+          platforms: linux/amd64,linux/arm64
+          file: ./Dockerfile
+          build-args: VERSION=${{ steps.version.outputs.version }}
+          tags: |
             ${{ env.DOCKERHUB_IMAGE }}:mcp
             ${{ env.DOCKERHUB_IMAGE }}:mcp-v${{ steps.version.outputs.version }}
           labels: |
             io.modelcontextprotocol.server.name=io.github.CodeAlive-AI/codealive-mcp
           cache-from: type=gha
-          cache-to: type=gha
 
       # Git tag created AFTER Docker push succeeds — if Docker fails, no stale tag
       - name: Create and push git tag

CLAUDE.md

@@ -118,7 +118,7 @@ This is a Model Context Protocol (MCP) server that provides AI clients with acce
 2. Client calls tools (`get_data_sources` → `semantic_search` / `grep_search` → `fetch_artifacts` / `get_artifact_relationships` → `chat` only if synthesis is still needed)
 3. Middleware chain runs: N8N cleanup → ObservabilityMiddleware (OTel span + log correlation)
 4. Tool translates MCP call to CodeAlive API request (with `X-CodeAlive-*` headers)
-5. Response parsed, formatted as XML or text, returned to AI client
+5. Response parsed and returned to the AI client — as a `dict` for metadata/discovery tools, as an XML string for `fetch_artifacts`, or as plain text for `chat`
 
 ### Environment Variables
 
@@ -172,6 +172,17 @@ This project uses **loguru** for structured JSON logging. All logs go to **stder
 
 7. **Use `logger.configure(patcher=...)` for global context injection** (like OTel trace_id). Do NOT pass `patcher` to `logger.add()` — loguru 0.7.x does not support it there.
 
+8. **Tool-call failures are warnings with full structured arguments.** Do not log MCP
+   tool-call failures as `error` unless the whole server process is failing. A bad
+   tool call is recoverable input for the model loop, same as backend agent tools.
+   Log it as `logger.warning(..., tool_arguments={...})` or with `.bind(tool_arguments=...)`.
+   Do not redact `tool_arguments` in the logger path; the purpose is to recover the
+   exact failing invocation. Authorization headers remain masked via `log_api_request()`.
+
+9. **Tool-call lifecycle logs are debug.** The per-tool "started" and "completed"
+   messages from `ObservabilityMiddleware` must be `logger.debug`, not `logger.info`.
+   Info-level logs should not be emitted for every agent step/tool step.
+
 ### OTel Trace Correlation
 
 Every log record automatically gets `trace_id` and `span_id` injected by `_otel_patcher` (registered via `logger.configure`). The `ObservabilityMiddleware` also uses `logger.contextualize(trace_id=..., tool=...)` so all logs within a tool call carry the correlation ID. Do not duplicate this — it's automatic.
@@ -194,29 +205,79 @@ The `ObservabilityMiddleware` creates a span per tool call with these attributes
 
 On errors, the span gets `StatusCode.ERROR` + `record_exception()`. Do not add redundant span creation inside tool functions — the middleware handles it.
 
+#### Required MCP observability fix pattern
+
+When touching MCP tool observability, update both the generic middleware and the
+tool-specific body:
+
+- In `src/middleware/observability_middleware.py`, extract tool arguments from
+  the incoming `tools/call` message (FastMCP currently exposes this through the
+  message payload; keep the extraction defensive). Add them to the log context,
+  e.g. `with logger.contextualize(trace_id=trace_id, tool=tool_name,
+  tool_arguments=tool_arguments): ...`.
+- Change middleware lifecycle logs:
+  - `logger.info("Tool call started...")` -> `logger.debug(...)`
+  - `logger.info("Tool call completed...")` -> `logger.debug(...)`
+  - `logger.error("Tool call failed...")` -> `logger.warning(...,
+    tool_arguments=tool_arguments)`
+- Keep OTel span semantics unchanged: failed tool calls should still set
+  `StatusCode.ERROR` and `record_exception(exc)` because tracing represents the
+  tool invocation outcome, while logs use Warning to avoid misclassifying a
+  recoverable model/tool-call error as a server crash.
+- In each tool body, log in-band validation failures before raising `ToolError`.
+  Include all tool parameters in `tool_arguments`.
+
+Concrete example: `src/tools/artifact_relationships.py::get_artifact_relationships`
+must log these branches as Warning with full arguments:
+
+```python
+tool_arguments = {
+    "identifier": identifier,
+    "profile": profile,
+    "max_count_per_type": max_count_per_type,
+}
+```
+
+- missing/empty `identifier`
+- `max_count_per_type` outside `1..1000`
+- unsupported `profile` fallback branch
+- backend `HTTPStatusError` / unexpected exception before delegating to
+  `handle_api_error(...)`
+
+The API request/response helpers stay `Debug` and keep their existing masking
+rules. Do not put raw response bodies into warning logs.
+
 ### Adding New Tools — Observability Checklist
 
 When adding a new tool, ensure:
 1. The tool receives `ctx: Context` as its first argument (required for lifespan context and logging)
 2. API requests include all four `X-CodeAlive-*` headers: `Integration`, `Tool`, `Client`, plus `Authorization`
 3. Call `log_api_request()` before and `log_api_response()` after the HTTP call
-4. Errors go through `handle_api_error(ctx, e, "description", method=_TOOL_NAME)` — this ensures the `[tool_name]` prefix in error messages
+4. Errors are logged as Warning with full `tool_arguments` before they go through `handle_api_error(ctx, e, "description", method=_TOOL_NAME)` — this ensures the `[tool_name]` prefix in error messages and preserves the exact failed call in logs
 5. The middleware automatically wraps the tool in an OTel span — no manual span creation needed
 
 ## Tool Response Conventions
 
-### Response format: dict for metadata, XML for content
-
-Tools that return **search metadata** (identifiers, match counts, line numbers)
-return a `dict`. FastMCP serializes it automatically via `pydantic_core.to_json`,
-which preserves Unicode — no manual `json.dumps()` needed. Examples:
-`semantic_search`, `grep_search`, `codebase_search`.
-
-Tools that return **source code content** return an **XML string**. XML tags give
-the LLM clear structural boundaries between artifacts, content blocks, and
-relationships — this is critical for accurate reasoning over multi-artifact
-responses. **Do not convert `fetch_artifacts` or `get_artifact_relationships`
-to dict/JSON** — the XML structure is intentional.
+### Response format: dict for metadata/discovery, XML only for source code
+
+Tools that return **structured metadata** (identifiers, match counts, line
+numbers, relationship groups, data source listings) return a `dict` (or list of
+dicts). FastMCP serializes it automatically via `pydantic_core.to_json`, which
+preserves Unicode — no manual `json.dumps()` needed. Examples:
+`semantic_search`, `grep_search`, `codebase_search`, `get_data_sources`,
+`get_artifact_relationships`.
+
+**Never call `json.dumps(...)` from a tool's return path.** Python's `json.dumps`
+defaults to `ensure_ascii=True` and escapes Cyrillic/CJK/etc. to `\uXXXX`.
+Returning a `dict` lets FastMCP route through `pydantic_core.to_json`, which
+emits UTF-8. If you must serialize manually for some reason, pass
+`ensure_ascii=False` explicitly.
+
+Only `fetch_artifacts` returns an **XML string**. XML tags give the LLM clear
+structural boundaries between artifacts, content blocks, and inline
+relationships when streaming source code — this is critical for accurate
+reasoning over multi-artifact responses. **Do not convert `fetch_artifacts` to
+dict/JSON** — the XML structure is intentional.
 
 ### Hint other MCP tools when the response implies a follow-up call
 

README.md

@@ -140,8 +140,8 @@ Replace `YOUR_API_KEY_HERE` with your actual API key.
 **Option 1: Remote HTTP (Recommended)**
 
 1. Open Cursor → Settings (`Cmd+,` or `Ctrl+,`)
-2. Navigate to **"MCP"** in the left panel
-3. Click **"Add new MCP server"**
+2. Navigate to **"Tools & MCP"** in the left panel (older builds called this **"Tools & Integrations"**)
+3. Click **"New MCP Server"**
 4. Paste this configuration:
 
 ```json
@@ -157,7 +157,9 @@ Replace `YOUR_API_KEY_HERE` with your actual API key.
 }
 ```
 
-5. Save and restart Cursor
+5. Save — Cursor reloads the server automatically. The entry is stored in `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global).
+
+> **Tip:** Cursor also supports a one-click install deeplink — `cursor://anysphere.cursor-deeplink/mcp/install?name=codealive&config=BASE64_CONFIG`. Only follow deeplinks from trusted sources.
 
 **Option 2: Docker (STDIO)**
 
@@ -179,29 +181,64 @@ Replace `YOUR_API_KEY_HERE` with your actual API key.
 </details>
 
 <details>
-<summary><b>Codex</b></summary>
+<summary><b>Codex (CLI, App, IDE Extension)</b></summary>
+
+OpenAI Codex ships in three form-factors that **share the same configuration**: the **Codex CLI**, the **Codex App** (macOS / Windows), and the **Codex IDE Extension** (VS Code `openai.chatgpt` and JetBrains 2025.3+). All three read `~/.codex/config.toml`, so one snippet covers every Codex surface. A project-level `.codex/config.toml` in the repo root is also supported for trusted projects.
 
-OpenAI Codex CLI supports MCP via `~/.codex/config.toml`.
+**Option 1: One-line add (Recommended)**
+
+```bash
+codex mcp add codealive --url https://mcp.codealive.ai/api
+```
+
+Then open `~/.codex/config.toml` and add the bearer-token reference plus the Streamable HTTP feature flag:
 
-**`~/.codex/config.toml` (Docker stdio – recommended)**
 ```toml
+[features]
+rmcp_client = true
+
 [mcp_servers.codealive]
-command = "docker"
-args = ["run", "--rm", "-i",
-        "-e", "CODEALIVE_API_KEY=YOUR_API_KEY_HERE",
-        "ghcr.io/codealive-ai/codealive-mcp:main"]
+url = "https://mcp.codealive.ai/api"
+bearer_token_env_var = "CODEALIVE_API_KEY"
+```
+
+Finally, export the key:
+```bash
+export CODEALIVE_API_KEY="YOUR_API_KEY_HERE"
 ```
 
-**Experimental: Streamable HTTP (requires `[features].rmcp_client = true`)**
+Verify with `codex mcp list`.
 
-> **Note:** Streamable HTTP support requires `rmcp_client = true` under a `[features]` section in your Codex configuration.
+> **Note:** Streamable HTTP requires `[features].rmcp_client = true`. The old top-level `experimental_use_rmcp_client = true` flag is deprecated. `bearer_token_env_var` is preferred over inline `headers = { Authorization = "Bearer …" }` because it keeps secrets out of the config file.
+
+**Option 2: Inline header (HTTP)**
 
 ```toml
+[features]
+rmcp_client = true
+
 [mcp_servers.codealive]
 url = "https://mcp.codealive.ai/api"
 headers = { Authorization = "Bearer YOUR_API_KEY_HERE" }
 ```
 
+**Option 3: Docker (STDIO)**
+
+```toml
+[mcp_servers.codealive]
+command = "docker"
+args = ["run", "--rm", "-i", "ghcr.io/codealive-ai/codealive-mcp:main"]
+env_vars = ["CODEALIVE_API_KEY"]
+```
+
+```bash
+export CODEALIVE_API_KEY="YOUR_API_KEY_HERE"
+```
+
+No `[features]` flag is needed for stdio. `env_vars` forwards values from the parent shell — safer than embedding the key in `args`.
+
+**Codex App UI:** Settings → MCP Servers → Add Server. The UI writes the same `~/.codex/config.toml` entry. The CLI and IDE extension pick it up automatically.
+
 </details>
 
 <details>

manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": "0.4",
   "name": "codealive-mcp",
   "display_name": "CodeAlive",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "description": "Semantic code search and codebase Q&A for Claude Desktop using your CodeAlive account or self-hosted deployment.",
   "long_description": "CodeAlive gives Claude Desktop access to semantic code search, artifact fetch, repository discovery, and architecture-aware codebase Q&A. This extension runs locally via MCP and supports both CodeAlive Cloud and self-hosted deployments.",
   "author": {

pyproject.toml

@@ -37,7 +37,7 @@ packages = ["src"]
 package-dir = {"" = "."}
 
 [tool.setuptools_scm]
-fallback_version = "2.0.3"
+fallback_version = "2.0.4"
 
 [tool.uv]
 # Relative dates in exclude-newer (e.g. "7 days") require uv ≥ 0.11.

server.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.CodeAlive-AI/codealive-mcp",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "description": "Semantic code search and analysis from CodeAlive for AI assistants and agents.",
   "keywords": [
     "context-engineering",

src/codealive_mcp_server.py

@@ -80,6 +80,9 @@
     - Use specific function/class names or file path scopes when looking for particular implementations
     - Treat `semantic_search` and `grep_search` as the default discovery tools
     - Prefer `semantic_search` over the deprecated `codebase_search` legacy alias
+    - Use `get_artifact_relationships` only with exact artifact identifiers from prior search/fetch results.
+      It expands a known artifact's relationship graph; it does not search by path, class name, or guessed symbol.
+      For exact source code, call `fetch_artifacts` on identifiers returned by search or relationships.
     - Remember that context from previous messages is maintained in the same conversation
 
     Flexible data source usage: