Skip to content

feat: prepare RatelDesk API, MCP, and release tooling - #62

Draft
Proxicon wants to merge 32 commits into
mainfrom
feat/api-docs-mcp-cli-release-readiness
Draft

Proxicon wants to merge 32 commits into
mainfrom
feat/api-docs-mcp-cli-release-readiness

Conversation

@Proxicon

@Proxicon Proxicon commented Sep 17, 2026

Copy link
Copy Markdown
Contributor

Closes #61

Delivered

  • Caller-bound local HTTP MCP gateway pairing and delegation: opaque rdk_ MCP credentials are purpose- and resource-bound, exchanged only for short-lived request-scoped API execution credentials, and never forwarded to business APIs. Explicit authentik mode remains available separately.
  • Credential lifecycle and account management: interactive management-session policy, CSRF-protected account UI, one-time secret reveal, expiry/revocation, organization-and-permission tuples, current membership/RBAC evaluation, SQLite-safe chronological ordering, and forward identity migrations.
  • OpenAPI and Scalar: deterministic Release-mode catalog/taxonomy, accurate anonymous/local-cookie/opaque-credential/machine security descriptions, product version, Web-proxy Try It route, and a rendered Scalar browser check with an attached screenshot artifact.
  • Compose and release readiness: validated local/Authentik MCP examples with an origin allowlist and non-root config handoff; exact validated release payload transfer, draft-only upload/completeness/conflict safeguards, and extracted archive execution on Linux and Windows matching runners.
  • CLI/stdio: integration-credential identity diagnostics, caller-derived assignment identity, and cache partitioning without secret-bearing cache keys.

Supported executable archives

Releases deliberately support only Linux x64, Linux ARM64, and Windows x64 for self-contained rateldesk CLI and rateldesk-mcp stdio archives. macOS archives and macOS runner jobs were retired at 1430eb1; they are not packaged, checksummed, uploaded, or advertised as supported artifacts. The payload expectation is enforced in package, manifest, upload, and extracted-archive validation scripts.

Requirement-to-test mapping

Review area Primary automated coverage
A1, A7: local/external MCP, delegation, purpose separation, concurrency, CLI/stdio McpGatewayDelegationEndpointTests, McpHttpHostTests, HelpdeskToolsMutationTests, HelpdeskCliTests
A2, B3: payload transfer, draft upload safety, archive execution tools/release/test-publish-release-assets.sh, tools/release/test-executable-archives.sh, release rehearsal and Linux/Windows archive-runtime CI jobs
A3, A4, B1: credential management, provider migrations, RBAC tuples IntegrationCredentialManagementAuthorizationTests, IntegrationCredentialSqliteTests, CurrentUserAccessServiceTests, LocalAuthenticationEndpointsTests, and the rendered account journey
A5, A6: OpenAPI security/taxonomy/version and Scalar proxy OpenApiAndVersionEndpointsTests, WebAuthRoutesTests, and Playwright setup.spec.ts
B2: documented MCP Compose modes/origins/non-root access tools/ci/test-mcp-compose-config.sh, AuthentikMcpOptionsValidatorTests, McpHttpHostTests, Compose CI jobs

Validation

Current head: 6449cdb62eaf7301229db5973d37789daa4a1499.

  • Pull-request validation run #352 passed public disclosure, .NET, Playwright, Docker, Compose (SQLite and PostgreSQL), release rehearsal, layout/reference, and extracted-archive execution on Linux x64, Linux ARM64, and Windows x64.
  • Managed PostgreSQL validation passed.
  • The stale macOS-queued run was cancelled after the platform policy changed; macOS is intentionally outside the release payload and CI matrix.
  • tools/release/test-publish-release-assets.sh passed locally, including missing files, partial uploads, reruns, conflicts, complete payload checks, and the supported-RID manifest.
  • Focused local credential regression: dotnet test tests/Helpdesk.Tests/Helpdesk.Tests.csproj --no-build --filter 'FullyQualifiedName~IntegrationCredentialSqliteTests|FullyQualifiedName~IntegrationCredentialManagementAuthorizationTests' -v:minimal — 15 passed.

Owner smoke journey (disposable data)

  1. Start a fresh local stack, complete setup, and sign in as an administrator.
  2. Open Account → Integration credentials, create an organization-scoped API/MCP credential, and copy its one-time secret.
  3. Use the API credential with the CLI or stdio server for helpdesk_auth, health, and a permitted business read.
  4. Configure an HTTP MCP client with manual Authorization: Bearer rdk_... and the documented canonical resource; initialize, read, perform a confirmed permitted mutation, then verify a forbidden write/cross-organization read.
  5. Revoke the credential in Account and confirm the next API/MCP request is denied.

Draft status

This remains a draft for owner review. No merge, tag, release, image/package publication, or deployment has been performed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Release readiness: API reference, local credentials, MCP and downloadable tooling

1 participant