Reported issues for unblu

Pod holds 19 of 26 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to unblu.

Most discussed

Remove pypi-publish: false from release.yml (ci-components breaking change)

Context

The pypi-publish input is being removed from detailobsessed/ci-components's semantic-release-uv.yml reusable workflow because PyPI OIDC trusted publishing does not support reusable workflows (pypi/warehouse#11096).

The pypi-publish input was dead code for OIDC — it only worked with token-based auth. All projects that need PyPI publishing should use a separate pypi-publish job in their own release.yml (which this repo

Read the thread · 2026-02-12 · closed · 2 comments

chore: Research MCP registry discovery (pulsemcp.com, Smithery)

Research how to make the server discoverable by MCP registries:

• Research pulsemcp.com registry requirements
• Explore integration with Smithery CLI for easy installation
• Add appropriate metadata/tags for MCP server discovery

Read the thread · 2025-12-14 · closed · 2 comments

chore: Developer experience backlog

Overview

Low-priority improvements to track for future iterations. These should be addressed based on real-world usage feedback rather than speculatively.

Sub-Issues

This parent issue tracks the following sub-issues:

Read the thread · 2025-12-14 · open · 2 comments

feat: Support multiple Unblu API versions and spec updates

Problem

Unblu releases new versions regularly, and the swagger.json API spec changes with each release. In enterprise environments, it's common to have multiple Unblu versions deployed simultaneously:

This means the MCP serve

Read the thread · 2025-12-12 · open · 2 comments

Further improvements based on Anthropic's agent best practices

Background

This MCP server implements key techniques from Anthropic's Building Effective Agents guide. We've already applied:

• ✅ Progressive disclosure - 5 discovery tools instead of 300+ API definitions
• ✅ Clear tool interfaces - descriptive parameters with examples
• ✅ Helpful error messages - suggest alternatives when service/operation not found
• ✅ Server instructions - guide the model through the workf

Read the thread · 2025-12-12 · closed · 2 comments

Refactor: split server.py into domain sub-servers (exploring-step pattern)

Summary

The current server.py is a single monolithic file (~1850 lines) with all 13 curated tools, resources, and prompts. The exploring-step MCP server splits tools into domain-specific sub-servers mounted into a main server via mcp.mount(). Applying the same pattern to unblu-mcp would improve modularity and maintainability.

Proposed structure

src/unblu_mcp/_internal/
├── server.py              # create_server() factory + shared state init via lifespan
├── tools/
│   ├── __

[Read the thread](https://github.com/detailobsessed/unblu-mcp/issues/152) · 2026-03-03 · open · 1 comment

### Audit: is eunomia-mcp still needed after wise-mcp refactor?

## Context

When the server initially covered the full Unblu OpenAPI spec via `execute_operation`, `eunomia-mcp` was added to provide policy-based authorization (allow/deny rules per operation).

Since then the server has been significantly refactored per wise-mcp recommendations:
- The generic `execute_operation` tool is now complemented by purpose-built curated tools (`search_conversations`, `get_conversation`, `search_persons`, etc.)
- Each curated tool has intentional scope — only exposes sa

[Read the thread](https://github.com/detailobsessed/unblu-mcp/issues/139) · 2026-02-25 · open · 1 comment

### Test Eunomia integration end-to-end

## Problem

We have never actually tested the Eunomia integration with the `[safety]` extra installed. The existing tests in `TestEunomiaIntegration` only verify that:
- `create_server()` accepts a `policy_file` parameter
- `create_server()` raises `FileNotFoundError` for missing policy files
- `create_server()` works without a policy file

These tests are **skipped** when `eunomia-mcp` is not installed (which is always in CI currently).

## What's missing

1. **Installation test** - Verify `pip

[Read the thread](https://github.com/detailobsessed/unblu-mcp/issues/75) · 2025-12-17 · open · 1 comment

## Most recent

### feat: add runtimeHint to server.json

## Summary

Our `server.json` is missing the `runtimeHint` field, which tells MCP clients which runtime to use for the package. For our PyPI package, this should be `"uvx"`.

## Change

```diff
 {
   "registryType": "pypi",
   "identifier": "unblu-mcp",
   "version": "0.5.2",
+  "runtimeHint": "uvx",
   "transport": {
     "type": "stdio"
   },

Context

The 2025-12-11 schema added several new fields. See codereviewbuddy#23

Read the thread · 2026-02-07 · closed · 0 comments

Consider adopting mcp-client-capabilities for progressive enhancement

Context

Article: https://www.pulsemcp.com/posts/mcp-client-capabilities-gap

Apify created mcp-client-capabilities - a community-maintained database of MCP client capabilities that enables servers to adapt behavior based on what features each client supports.

Current State

Our server already uses a progressive disclosure pattern with 5 static tools:

• list_services, list_operations, search_operations, get_operation_schema for d

Read the thread · 2025-12-23 · open · 0 comments

feat: Consider adding RetryMiddleware for transient API failures

Summary

Consider adding FastMCP's RetryMiddleware to automatically retry transient API failures when calling the Unblu API.

Context

FastMCP provides RetryMiddleware that can automatically retry failed requests:

from fastmcp.server.middleware.error_handling import RetryMiddleware

mcp.add_middleware(RetryMiddleware(
    max_retries=3,
    retry_exceptions=(httpx.ConnectError, httpx.TimeoutException)
))

Current State

We already have good error handling:

• `ErrorHan

Read the thread · 2025-12-15 · open · 0 comments

bug: swagger.json bundled as LFS pointer instead of actual file

Description

The fix in #64 bundled swagger.json in the package, but it's the Git LFS pointer file (132 bytes) instead of the actual JSON content (~2.4MB).

$ cat .../site-packages/unblu_mcp/swagger.json
version https://git-lfs.github.com/spec/v1
oid sha256:1511a7e18239e29279e87de851fdd3a5cdfd4ea57b1758c148148e599f27f0b6
size 2470859

This causes a JSON parse error when starting the server:

json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)

Root Ca

Read the thread · 2025-12-15 · closed · 0 comments

bug: swagger.json not bundled in PyPI package

Description

When installing unblu-mcp from PyPI and running with uvx unblu-mcp, the server fails to start because swagger.json is not found:

FileNotFoundError: swagger.json not found. Please provide spec_path.

Steps to Reproduce

1. Install from PyPI: uvx unblu-mcp --provider k8s --environment dev
2. Server crashes with FileNotFoundError

Expected Behavior

The swagger.json file should be bundled with the package so users don't need to manually provide --spec.

Read the thread · 2025-12-15 · closed · 0 comments

feature: Add CLI support for K8s connection provider with automatic port-forwarding

Is your feature request related to a problem? Please describe.

The K8sConnectionProvider exists in the codebase (src/unblu_mcp/_internal/providers_k8s.py) but is not accessible via the CLI. Users who want to connect to Kubernetes-deployed Unblu instances with automatic port-forwarding must either:

1. Manually start kubectl port-forward before launching the MCP server
2. Configure environment variables (UNBLU_BASE_URL, UNBLU_TRUSTED_HEADERS) pointing to a manually-forwarded port

Read the thread · 2025-12-15 · closed · 1 comment

chore: Set up PyPI publishing infrastructure

Configure automated PyPI publishing:

• Verify pyproject.toml metadata is complete and accurate
• Set up GitHub Actions for automated PyPI publishing
• Configure semantic-release for version management
• Test installation from TestPyPI before production release

Read the thread · 2025-12-14 · closed · 0 comments

docs: Complete documentation for public release

Ensure documentation is ready for public consumption:

• Update README with clear installation instructions
• Add CONTRIBUTING.md for potential contributors
• Ensure LICENSE file is appropriate
• Add CHANGELOG.md
• Document the connection provider plugin system

Read the thread · 2025-12-14 · closed · 1 comment

chore: Code quality review for public release

Ensure code follows best practices for public consumption:

• Ensure code follows modern Python best practices (Python 3.10+)
• Review code structure and organization
• Check for DRY violations and refactor if needed
• Ensure consistent code style throughout
• Review docstrings and type hints for completeness
• Verify test coverage is adequate
• Check that all public APIs are well-documented

Read the thread · 2025-12-14 · closed · 1 comment

chore: Security review before public release

Thoroughly review all code to ensure no sensitive internals are exposed:

• Check for any hardcoded values, internal URLs, or company-specific configurations
• Review contrib/k8s/ wrapper for any assumptions that should be generalized
• Ensure environment variable names are generic (not company-specific)
• Review git history for any accidentally committed secrets

Priority: Critical - must complete before making repo public.

Read the thread · 2025-12-14 · closed · 1 comment

feat: Improve response filtering with exclude fields and nested filtering

Add support for excluding fields (not just including) and improve nested field filtering.

Priority: Low - Implement when real usage reveals pain points.

Read the thread · 2025-12-14 · open · 0 comments

The remaining reports are on the project's issue tracker.