# 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](/mcp/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](https://github.com/pypi/warehouse/issues/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](https://github.com/detailobsessed/unblu-mcp/issues/125) · 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](https://pulsemcp.com) registry requirements
- [ ] Explore integration with [Smithery CLI](https://smithery.ai/) for easy installation
- [ ] Add appropriate metadata/tags for MCP server discovery

[Read the thread](https://github.com/detailobsessed/unblu-mcp/issues/40) · 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:

| Issue | Category | Status |
|-------|----------|--------|
| #35 | Observability | Track which operations are most frequently used |
| #36 | Poka-yoke | Add validation for common parameter mistakes |
| #37 | Documentation | Improve tool docstrings with examples and ed

[Read the thread](https://github.com/detailobsessed/unblu-mcp/issues/33) · 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**:

| Environment | Typical Version | Notes |
|-------------|-----------------|-------|
| test1 | Latest | First to get updates |
| dev | Varies | Development testing |
| staging | Older | Pre-production validation |
| production | Oldest | Updated last, most stable |

This means the MCP serve

[Read the thread](https://github.com/detailobsessed/unblu-mcp/issues/22) · 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](https://www.anthropic.com/engineering/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](https://github.com/detailobsessed/unblu-mcp/issues/15) · 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](https://github.com/detailobsessed/codereviewbuddy/issues/23) 

[Read the thread](https://github.com/detailobsessed/unblu-mcp/issues/124) · 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](https://github.com/apify/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](https://github.com/detailobsessed/unblu-mcp/issues/82) · 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:

```python
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](https://github.com/detailobsessed/unblu-mcp/issues/71) · 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](https://github.com/detailobsessed/unblu-mcp/issues/65) · 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](https://github.com/detailobsessed/unblu-mcp/issues/63) · 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](https://github.com/detailobsessed/unblu-mcp/issues/51) · 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](https://github.com/detailobsessed/unblu-mcp/issues/44) · 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](https://github.com/detailobsessed/unblu-mcp/issues/43) · 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](https://github.com/detailobsessed/unblu-mcp/issues/42) · 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](https://github.com/detailobsessed/unblu-mcp/issues/41) · 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](https://github.com/detailobsessed/unblu-mcp/issues/39) · 2025-12-14 · open · 0 comments

The remaining reports are on [the project's issue tracker](https://github.com/detailobsessed/unblu-mcp/issues).