XTend hosted MCP — development MVP

Standalone, Apache-2.0 licensed, read-only knowledge service for XTend agents. Implementation tracks XTend #113. This first development slice is not production-ready and has no deployed public endpoint.

Responsibilities

This repository owns HTTP hosting, synchronization, snapshots, limits and container operation. Canonical documentation and recipes remain in konnilabs/xtend. Requests use a local snapshot; only the background synchronizer contacts GitHub. Downloaded JavaScript and recipes are never executed. The upstream retrieval module is vendored unchanged with commit, hash and license in vendor/; upgrades are reviewed software changes, pending an upstream public library package boundary.

Related MCP server: mdbook-mcp-server

Run

Node.js 24.19.0; install with npm ci --ignore-scripts, then npm test and npm run check. Set XTEND_MCP_TOKENS to one or more comma-separated secrets (32–256 characters each), then run npm start. Supply secrets through the deployment environment; do not commit them.

For Docker: set the same variable, then docker compose up --build -d. The image binds internally to 0.0.0.0; Compose exposes only 127.0.0.1:31415 on the host. Put an HTTPS reverse proxy in front of it. Set XTEND_ALLOWED_HOSTS to the exact external hostname and internal health-check hostname; configure XTEND_ALLOWED_ORIGINS with exact scheme/host/port origins when browser access is needed. Missing Origin is allowed for machine clients. This slice ignores forwarded headers: clients behind a proxy share its IP budget. Dedicated per-client IP attribution through explicitly trusted proxies remains open. Bearer-header clients are supported; OAuth discovery is not implemented.

POST /mcp uses the official SDK's stateless Streamable HTTP transport and JSON responses. Use Authorization: Bearer <secret> and Accept: application/json, text/event-stream. GET /health is an unauthenticated process check; authenticated GET /ready reports readiness, commit, ref, snapshot inventory and synchronization status. Without a valid snapshot MCP returns 503. X-XTend-Snapshot selects a retained commit for a request; the response header reports the chosen commit. A retained snapshot can eventually be evicted; unavailable selections fail rather than silently switching.

Tools: xtend_knowledge_search, xtend_knowledge_context, xtend_recipe_list. Resources: paginated documentation listing and direct canonical documentation/kit URIs. Prompt: xtend_recipe, with stable recipe id; discover recipes with xtend_recipe_list or knowledge search. The prompt list includes paginated legacy xtendRmt_* aliases. Recipe discovery returns summaries, not source code, with locale/topic filters and optional exact XTend/adapter target versions. Missing compatibility metadata remains explicitly unknown. See the API proposal for cursor pinning, the additive metadata contract, error handling and validation evidence. Compiler, repair and workspace mutation tools are deliberately absent from this hosted profile.

Knowledge updates

XTEND_SOURCE_REPOSITORY defaults to konnilabs/xtend; XTEND_SOURCE_REF defaults to main (the development channel). Select a release tag for a release channel. GITHUB_TOKEN optionally provides read access and a larger API budget; never expose it to MCP clients.

Every sync resolves one commit, reads its Git tree, downloads the fixed artifact allowlist, checks schemas, counts, hashes, documentation coverage, canonical menu, kit files and declared kit source hashes, and prepares the upstream search index before atomic activation. Existing requests hold a snapshot lease. Failure leaves the last valid snapshot available. Startup revalidates cached artifacts. No independent productive recipe collection lives here.

Polling defaults to five minutes with jitter, ETag revalidation and bounded retries. Persist /data; XTEND_DATA_DIR overrides the local directory. XTEND_RETAIN_SNAPSHOTS defaults to three. XTEND_MAX_SNAPSHOT_BYTES defaults to 64 MiB (including source verification downloads); budget failure rejects the whole update, never truncates recipes. The filesystem/volume itself still needs an operator-enforced disk quota. Recipe counts and topic names have no fixed product maximum.

Request budgets

Defaults: 60 requests/minute/key, 120/minute/socket IP, 10 requests/second globally, eight concurrent MCP requests, 128 connections, 64 KiB body, 1 MiB response and ten-second timeout. All are configurable using the named XTEND_* variables in src/config.mjs. Limits protect application work; provider/proxy protection is needed for connection floods and network saturation. Never log access tokens. Shutdown aborts synchronization and closes HTTP connections.

XTEND_RECIPE_PAGE_BYTES defaults to 64 KiB per serialized recipe-tool result or prompt list. The effective limit also reserves 1 KiB below XTEND_MAX_RESPONSE_BYTES for the JSON-RPC envelope; the existing transport guard remains the final bound. Catalogue pages default to 25 items and allow at most 100 per request. These are response budgets, never limits on stored recipe counts.

Remaining acceptance work

• Run container build and SDK-client integration through a real TLS reverse proxy; benchmark target hardware.

• Populate optional locale/compatibility metadata in the canonical upstream recipe generator; the hosted catalogue and prompt handlers already accept and evaluate it without an image change.

• Prove generated kit freshness using a successful upstream release/drift gate (source hashes alone do not prove generator freshness).

• Add signed webhook triggering, stronger exponential backoff, rollback operations and exhaustive retention/crash tests.

• Expand timeout, response budget, rate, forged-header, secret-redaction and resource-exhaustion tests.

• Finish DE/EN operator documentation and review the shared retrieval package boundary.

• Pin CI action/image digests and establish dependency/security update policy before deployment.

The first tests cover real SDK server transport requests, knowledge retrieval and recipe ID 999, invalid access/origin/host/body, corrupt artifacts, 1,000-record growth, atomic update and pinning, restart recovery, and failed/single-flight synchronization. They use synthetic data, not a copied productive knowledge base. Docker verification belongs to CI and is not claimed as locally completed.

Deutsch

Dies ist der erste Entwicklungsstand, noch kein freigegebener Serverbetrieb. Die Wissensbasis bleibt im XTend-Hauptrepository; der Container übernimmt geprüfte Snapshots unabhängig vom Image. Zugangsschlüssel, HTTPS-Proxy und passende Host-/Origin-Freigaben sind für den Betrieb erforderlich. Die oben genannten offenen Abnahmen müssen vor einer öffentlichen Bereitstellung abgeschlossen sein.