# Reported issues for mcp-plesk-dev-docs

Pod holds 18 of 53 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 [mcp-plesk-dev-docs](/mcp/mcp-plesk-dev-docs).

## Most discussed

### Excise ghost profiles from settings and search

## Problem

Three ghost profile names exist in the codebase that don't match the actual profiles in `domain/models.py:_PROFILES`:

| Location | Reference | Actual profiles |
|---|---|---|
| `config/settings.py:27` | Default: `"pro"` | `light`, `medium`, `full`, `full-tq` |
| `search_service.py:195` | Checks `"local"` | `light`, `medium`, `full`, `full-tq` |
| `search_service.py:197` | Checks `"pro"` | `light`, `medium`, `full`, `full-tq` |

The default `"pro"` triggers a warning-and-fallback on 

[Read the thread](https://github.com/barateza/mcp-plesk-dev-docs/issues/72) · 2026-06-18 · closed · 1 comment

### Introduce repository Protocol interfaces

## Problem

`SearchService.__init__` takes 6 `Any`-typed dependencies; `IndexingService.__init__` takes 10. Every test constructs a full mock surface. Swapping a storage backend (e.g. LanceDB → another DB) means touching every consumer, not one seam.

## Solution

Define `Protocol` classes for the three real repository seams:
- **VectorRepository** — `search_vector()`, etc.
- **FtsRepository** — `search_fts()`, etc.
- **DocumentStore** — `persist_batch()`, `delete_stale_chunks()`, etc.

Wire con

[Read the thread](https://github.com/barateza/mcp-plesk-dev-docs/issues/69) · 2026-06-18 · closed · 1 comment

### Seal the benchmark seam — lightweight RetrievalContainer

## Problem

Benchmarks bootstrap the full production DI container (18 dependencies), mutate a process-global settings singleton at `benchmark_runner.py:172`, and duplicate TurboQuant index construction logic that already lives in `storage_runtime.build_tq_index_from_table()`.

If benchmarking ever ran concurrently with search queries, the profile would silently change mid-flight due to `global_settings.plesk_model_profile` mutation.

## Solution

Introduce a lightweight `RetrievalContainer` with

[Read the thread](https://github.com/barateza/mcp-plesk-dev-docs/issues/68) · 2026-06-18 · closed · 1 comment

### Progress notifications ctx.report_progress

Progress notifications via ctx.report_progress during long operations

---
_Imported from beads issue tracker_

[Read the thread](https://github.com/barateza/mcp-plesk-dev-docs/issues/66) · 2026-06-18 · closed · 1 comment

### LLM Sampling ctx.sample

LLM Sampling via ctx.sample (gated by PLESK_ENABLE_SAMPLING)

---
_Imported from beads issue tracker_

[Read the thread](https://github.com/barateza/mcp-plesk-dev-docs/issues/65) · 2026-06-18 · closed · 1 comment

### Search telemetry logging

Per-query search telemetry logged to OS logger

---
_Imported from beads issue tracker_

[Read the thread](https://github.com/barateza/mcp-plesk-dev-docs/issues/64) · 2026-06-18 · closed · 1 comment

### Rich markdown result cards

Rich markdown result cards instead of plain text output

---
_Imported from beads issue tracker_

[Read the thread](https://github.com/barateza/mcp-plesk-dev-docs/issues/63) · 2026-06-18 · closed · 1 comment

### VRAM auto-tuning

VRAM auto-tuning based on available GPU memory

---
_Imported from beads issue tracker_

[Read the thread](https://github.com/barateza/mcp-plesk-dev-docs/issues/62) · 2026-06-18 · closed · 1 comment

## Most recent

### Run full MCP 2026-07-28 compliance audit

## Parent

Spec: Full MCP 2026-07-28 compliance audit (#78)

## What to build

After all migrations are complete, run a systematic audit against the 13-point checklist from the spec to verify full compliance, update the research document, and file gaps.

## Acceptance criteria

- [ ] All 13 checklist items from the audit spec are verified against the current codebase:

| # | Check | Expected result |
|---|-------|----------------|
| 1 | Stateless protocol | FastMCP 4 serves sessionless protocol 

[Read the thread](https://github.com/barateza/mcp-plesk-dev-docs/issues/82) · 2026-07-31 · open · 0 comments

### Update Dockerfile for HTTP deployment and document remote usage

## Parent

Spec: Add Streamable HTTP transport for remote deployment (#77)

## What to build

Update the Dockerfile to default to HTTP transport and document how to deploy the server remotely.

## Acceptance criteria

- [ ] `Dockerfile` CMD defaults to `PLESK_TRANSPORT=http` with uvicorn
- [ ] Dockerfile exposes port 8000 (or configured port)
- [ ] `README.md` or a new `docs/deployment.md` covers:
  - Running locally with stdio (default)
  - Running locally with HTTP (`PLESK_TRANSPORT=http`)
  -

[Read the thread](https://github.com/barateza/mcp-plesk-dev-docs/issues/81) · 2026-07-31 · open · 0 comments

### Add PLESK_TRANSPORT config and branch main.py for HTTP mode

## Parent

Spec: Add Streamable HTTP transport for remote deployment (#77)

## What to build

Allow the server to run in Streamable HTTP mode in addition to the default stdio mode, controlled by the `PLESK_TRANSPORT` environment variable. The HTTP endpoint serves both modern 2026-07-28 and legacy handshake-era clients from the same URL via FastMCP 4's automatic protocol negotiation.

## Acceptance criteria

- [ ] `settings.py` gains `plesk_transport: str = "stdio"` field
- [ ] `main.py` branches

[Read the thread](https://github.com/barateza/mcp-plesk-dev-docs/issues/80) · 2026-07-31 · open · 0 comments

### Upgrade FastMCP to 4.x with cache defaults

## Parent

Spec: FastMCP 4.0 + Python SDK v2 upgrade (#76)

## What to build

Upgrade the MCP framework from FastMCP 3.2.4 (SDK 1.27.0) to FastMCP 4.x (SDK 2.x) and adopt the production defaults for cacheable list results.

## Acceptance criteria

- [ ] `pyproject.toml`: change `fastmcp>=3.2.4,<4` → `fastmcp>=4.0.0` (remove the upper bound pin)
- [ ] `uv sync` succeeds resolving all dependencies
- [ ] All 160 tests pass with no regressions
- [ ] `FastMCP` constructor gains `cache_ttl=300, cache_

[Read the thread](https://github.com/barateza/mcp-plesk-dev-docs/issues/79) · 2026-07-31 · open · 0 comments

### Spec: Full MCP 2026-07-28 compliance audit

## Problem Statement

After completing the sampling migration, FastMCP 4 upgrade, and Streamable HTTP addition, the project needs a systematic audit to verify full compliance with the MCP 2026-07-28 specification. The spec introduces multiple changes beyond the headline ones — new error codes, new field naming conventions, `server/discover` requirements, per-request metadata conventions, cache hint expectations, OpenTelemetry propagation conventions, and authorization hardening. An audit ensures

[Read the thread](https://github.com/barateza/mcp-plesk-dev-docs/issues/78) · 2026-07-31 · open · 0 comments

### Spec: Add Streamable HTTP transport for remote deployment

## Problem Statement

The MCP server currently runs on stdio transport only — it must be launched as a subprocess by an MCP client. This works well for local/desktop usage (Claude Desktop, IDE plugins) but prevents remote deployment scenarios: cloud-hosted servers, load-balanced fleets, serverless endpoints, and SaaS integrations. The MCP ecosystem increasingly expects Streamable HTTP as the transport for remote servers, and the 2026-07-28 spec requires `Mcp-Method`/`Mcp-Name` headers that are n

[Read the thread](https://github.com/barateza/mcp-plesk-dev-docs/issues/77) · 2026-07-31 · open · 0 comments

### Spec: FastMCP 4.0 + Python SDK v2 upgrade

## Problem Statement

After migrating away from `ctx.sample()` (ticket #75), the project still runs on FastMCP 3.2.4 and Python MCP SDK 1.27.0, which speak the pre-2026-07-28 protocol era. These versions are pinned (`fastmcp<4`, `mcp<2`) to prevent accidental upgrades that would break the sampling-dependent code. Once sampling is migrated, those pins can be removed and the project can upgrade to FastMCP 4.0 + SDK v2, gaining:

- Stateless protocol support (native `server/discover`, backward-comp

[Read the thread](https://github.com/barateza/mcp-plesk-dev-docs/issues/76) · 2026-07-31 · open · 0 comments

### Main migration: Replace ctx.sample() with AIClient.generate_answer_async() in search synthesis

## Parent

Spec: Migrate ctx.sample() to direct OpenRouter API calls (#73)

## What to build

Replace the deprecated `ctx.sample()` call in `_synthesize_answer()` with a direct call to `AIClient.generate_answer_async()` that talks to OpenRouter. This removes the server's dependency on the MCP Sampling protocol feature, which is deprecated in MCP 2026-07-28 and removed in FastMCP 4.0.

**Changes across these modules:**

### `mcp_plesk_dev_docs/server/tools/search_tools.py`
- `SearchTools.__init__

[Read the thread](https://github.com/barateza/mcp-plesk-dev-docs/issues/75) · 2026-07-31 · open · 0 comments

### Prefactor: Add AIClient.generate_answer_async() method for OpenRouter answer synthesis

## Parent

Spec: Migrate ctx.sample() to direct OpenRouter API calls (#73)

## What to build

Add a new async method `generate_answer_async()` to the existing `AIClient` class in `infrastructure/ai_client.py`. This method generates an answer from a query and context by calling the OpenRouter API with model fallback, and returns `Optional[str]` — it returns `None` when all models fail (graceful degradation).

This is a **pure prefactor**: the new method exists and is tested, but no caller uses it

[Read the thread](https://github.com/barateza/mcp-plesk-dev-docs/issues/74) · 2026-07-31 · open · 0 comments

### Spec: Migrate ctx.sample() to direct OpenRouter API calls (MCP 2026-07-28 compliance)

## Problem Statement

The MCP 2026-07-28 specification (finalized July 28, 2026) deprecates the Sampling protocol feature — `ctx.sample()` will be removed no earlier than 2027-07-28. FastMCP 4.0 already removes `ctx.sample()` entirely on all protocol eras, meaning upgrading from FastMCP 3.2.4 is blocked until this code is migrated.

Currently, `search_tools.py` uses `ctx.sample()` via `SamplingMessage`/`TextContent` to ask the MCP host's LLM to synthesize an answer from search results. This crea

[Read the thread](https://github.com/barateza/mcp-plesk-dev-docs/issues/73) · 2026-07-31 · open · 0 comments

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