Add a tested Python MCP diagnostic example for the installed SDK
- Dominant language
- TypeScript
- Stars
- 22.5k
- Forks
- 3.1k
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 715
Description
## Problem
A Python diagnostic for a Streamable HTTP Model Context Protocol (MCP) endpoint attempted to create the client with this unsupported call:
```python
streamable_http_client(..., headers=...)
```
The installed `mcp` package rejected the call before it contacted the endpoint. That package version requires request headers on an `httpx.AsyncClient` supplied through `http_client=`:
```python
streamable_http_client(
...,
http_client=httpx.AsyncClient(headers={...}),
)
```
This local API mismatch can be mistaken for a remote MCP server, authentication, or transport failure. NemoClaw does not have a checked-in Python diagnostic example and test that own this SDK compatibility contract.
## Product decision required
Before implementation, decide whether NemoClaw will own this diagnostic as:
1. A checked-in troubleshooting tool or example.
2. A documented example with an exact compatible SDK range.
The selected surface must have a named source of truth for its SDK version and an automated compatibility test. This issue is not an installer defect.
## Acceptance criteria
- The accepted design identifies the owning repository surface and the exact SDK version source of truth.
- With the supported SDK, the diagnostic configures request headers through the supported HTTP-client API.
- Against a local test server, the diagnostic completes MCP `initialize` and `tools/list` requests.
- A client-construction or SDK-signature failure is reported as a local dependency compatibility error.
- The diagnostic does not classify a local dependency compatibility error as a remote server, authentication, authorization, or transport failure.
- Diagnostic output does not contain authorization headers, access tokens, or other credential values.
- A deterministic test uses the repository-installed dependency and fails when an incompatible SDK API replaces the supported API.
- The owned tool or documentation states how to run the diagnostic and how to interpret its result.
- Acceptance does not require a live external MCP service.
## Related work
- #10944 owns NemoClaw MCP verification behavior when connection or authentication fails. This issue owns the separate diagnostic-client SDK compatibility contract.
## Scope boundary
- Do not change a remote MCP server or OpenShell protocol behavior in this issue.
- Do not add support for an SDK range without an accepted compatibility and maintenance policy.
Contributor guide
Research direction
Start by resolving the product decision between a checked-in troubleshooting tool/example and documentation, then identify the owning surface and SDK version source of truth. Use the repository-installed dependency with a local test server to verify MCP initialize and tools/list, and ensure compatibility failures are distinguished from remote failures without exposing credentials. Done means the chosen surface documents usage and interpretation and includes a deterministic compatibility test.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- backend-api-design, testing, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100