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.

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:

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

Read the thread · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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:

Read the thread · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 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 · 2026-07-31 · open · 0 comments

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