docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
en/docs/api/mcp-bundle/developers/known_issues/open.md
new file +17
ā0
1
+
# Open issues
2
+
3
+
Known bugs and inconsistencies in the current version of MCP Bundle (1.0.0): symptom, cause and workaround. Core issues are in the [JsonRpcBundle known issues](/docs/api/json-rpc-bundle/developers/known_issues/open). Fixed ones are on the [Fixed issues](/docs/api/mcp-bundle/developers/known_issues/fixed) page.
4
+
5
+
<include>(.issues/group-limits-not-validated.md)
6
+
7
+
---
8
+
9
+
<include>(.issues/oauth-not-supported.md)
10
+
11
+
---
12
+
13
+
<include>(.issues/xdebug-coverage-segfault.md)
14
+
15
+
---
16
+
17
+
<include>(.issues/bundle-docs-inconsistencies.md)
en/docs/api/mcp-bundle/developers/known_issues/.issues/group-limits-not-validated.md
new file +15
ā0
1
+
### Group limits are not validated by the configuration
2
+
3
+
:::warning subtitle="Open"
4
+
Affected versions: 1.0.0 (current). Verified against the code of tag 1.0.0.
5
+
:::
6
+
7
+
**Symptom.** The bundle-wide `max_body_bytes` and `session_ttl` must be integers >= 1, otherwise the container does not build. The same parameters under `groups.<group>` accept anything, and the error shows up only at request time:
8
+
9
+
* `max_body_bytes: 0` (or negative): every request to the group's endpoint fails with HTTP 500 (`maxBodyBytes must be at least 1.` from the SDK transport);
10
+
* `session_ttl: 0` or negative: a session expires right after it is created, and a session-based client gets 404 on every request after `initialize`;
11
+
* a string instead of a number: a `TypeError` when the bundle configuration is created, HTTP 500.
12
+
13
+
**Cause.** In `Configuration`, these group fields are `scalarNode` without `min(1)` (so that `~` is accepted as "inherit"), and `McpGroupConfig` assigns the values without a check.
14
+
15
+
**Workaround.** Set integers >= 1 for the group or leave the field out (then the bundle-wide value applies). For environment variables use `%env(int:...)%`.
en/docs/api/mcp-bundle/developers/known_issues/.issues/oauth-not-supported.md
new file +11
ā0
1
+
### OAuth-only clients cannot connect
2
+
3
+
:::warning subtitle="Open"
4
+
Affected versions: 1.0.0 (current). A limitation listed in the 1.0 release notes.
5
+
:::
6
+
7
+
**Symptom.** An MCP client that cannot send a custom header and expects OAuth authorization gets 401 and does not connect. For example, MCP Inspector without the token header starts its own OAuth flow, which fails.
8
+
9
+
**Cause.** OAuth is not implemented: there is no `/.well-known/oauth-protected-resource` and no `WWW-Authenticate` header in the 401 response. Access is only the core RPC token in a header (`Ufo-RPC-Token`).
10
+
11
+
**Workaround.** Use clients that support custom headers (Claude Code, Cursor, Gemini CLI, OpenAI Responses API) and the [manifests](/docs/api/mcp-bundle/discovery); in MCP Inspector pass `--header "Ufo-RPC-Token: ā¦"`.
en/docs/api/mcp-bundle/developers/known_issues/.issues/xdebug-coverage-segfault.md
new file +11
ā0
1
+
### Coverage under Xdebug ends in a segmentation fault
2
+
3
+
:::warning subtitle="Open"
4
+
Affected versions: 1.0.0 (current). Only affects development of the bundle, not how the application works.
5
+
:::
6
+
7
+
**Symptom.** Running the tests with coverage through Xdebug 3.4.2 (image `ufotech/php:8.4-fpm`) crashes with a segmentation fault on the tests that start the SDK server.
8
+
9
+
**Cause.** A crash of Xdebug 3.4.2 itself, not a bug in the bundle code (according to the 1.0 release notes); the exact cause is not established.
10
+
11
+
**Workaround.** Collect coverage with pcov; see [Testing](/docs/api/mcp-bundle/developers/testing).
en/docs/api/mcp-bundle/developers/known_issues/.issues/bundle-docs-inconsistencies.md
new file +8
ā0
1
+
### Inconsistencies in the bundle repository documentation
2
+
3
+
:::warning subtitle="Open"
4
+
Affected versions: 1.0.0 (current). A documentation inconsistency; does not affect how the bundle works.
5
+
:::
6
+
7
+
* The bundle's `README.md` and `README-UA.md` link to the documentation at `http://localhost/uk/docs/api/mcp-bundle`. The up-to-date documentation is on this site.
8
+
* The "In one minute" example in `docs/README.md` (and `-UA`) promises a `Catalog.search` tool for a `CatalogProcedure` class without `#[RPC\Info]`. Without the attribute the core uses the short class name, so the tool is named `CatalogProcedure.search`. To get `Catalog.search`, add `#[RPC\Info('Catalog')]`, as in the examples on this site.