v0.2.2

Overview

v0.2.2 strengthens MCP request accounting and upstream stream integrity, makes the administration panel more reliable under pagination and partial runtime-configuration failures, and introduces automated Linux release archives alongside the versioned Docker image.

Reliability and security

• Ambiguous MCP routing fields are rejected. Duplicate or case-colliding JSON-RPC method, params, and tool-name fields can no longer bypass RPM, concurrency, quota, or usage accounting.
• Prematurely terminated upstream streams now fail explicitly. Chat Completions and Anthropic streams must reach their protocol terminal events; truncated answers are rejected and reserved successful-call quota is rolled back.
• Quota rollback preserves the original reservation period. Delayed failures after a monthly rollover can no longer decrement another period, and each reservation is released at most once across normal and panic cleanup paths.
• Panel rendering paths are hardened. Browser HTML sinks are centralized behind sanitization, API errors expose stable codes, and authentication handlers are split into clearer registration and session boundaries.

Administration panel

• Dashboard health reflects the real upstream state. The panel distinguishes healthy, degraded, unhealthy, and unknown states instead of presenting an unsupported availability claim.
• Overview loading is independent from health probes. Upstream checks are cached and coalesced, local dashboard data can load without waiting for them, and settings updates invalidate stale health results.
• Saved-but-not-applied settings remain visible. Durable and live settings revisions are tracked separately across storage, APIs, health checks, and the UI so partial runtime application failures are not mistaken for successful activation.
• Tier assignments are preserved across cursor pages. The user editor loads all tier pages and blocks stale references, preventing unrelated edits from silently changing assignments.
• Invite redemption history is bounded with stable pagination. Storage, API responses, modal state, and controls now use keyset pagination for large histories.

Release and documentation

• Publishing a GitHub Release now runs the full Go test suite, builds Linux amd64 and arm64 archives, uploads SHA-256 checksums, and publishes the matching multi-architecture Docker image.
• Runtime, proxy, persisted-settings, panel-route, credential-recovery, Docker, and release-workflow documentation has been aligned with current behavior.
• The default build version and documented Docker image tag are updated to v0.2.2.

Upgrade notes

• v0.2.2 is intended as an upgrade from v0.2.1.
• Database migrations, including persisted settings revision tracking, are applied automatically at startup; no manual migration is required.
• No new mandatory environment variables are introduced.
• As with previous project releases, v0.2.2 is published as a prerelease.

Included commits

• e95ac9c docs(readme): refresh setup and runtime guidance
• 3733699 fix(grok): reject prematurely terminated streams
• cf6d211 refactor(panel): harden rendering and split auth handlers
• 33854f2 feat(release): automate GitHub release assets
• c5b9801 fix(usage): reject ambiguous MCP routing fields
• 771e8cc fix(panel): report real overview health status
• 6761770 docs(readme): align runtime and deployment contracts
• e2188a4 fix(quota): preserve reservation period on rollback
• 94960ac chore(gitignore): exclude local agent metadata
• ca4ea77 fix(panel): preserve tier assignments across cursor pages
• e95425f fix(panel): decouple dashboard loading from health probes
• 5a2d2a4 fix(settings): preserve saved-not-applied runtime state
• fc1080f fix(invites): bound redemption history with pagination
• 564197f chore(release): prepare v0.2.2

Full changelog: v0.2.1...v0.2.2

v0.2.1

Overview

v0.2.1 expands registration security and auditability while reducing memory pressure and SQLite write contention under load. It also adds opt-in operational metrics for administrators and aligns the Go module path with the canonical GitHub repository.

Security and registration

• Proof of work is now required for registration. The server issues signed, single-use registration challenges that are bound to the submitted registration data. The browser solves the SHA-256 challenge in a Web Worker before password hashing and account creation begin.
• Challenge issuance is rate-limited. This reduces the cost of automated registration abuse before expensive bcrypt work reaches the server.
• Registration mode is enforced atomically. The authoritative registration policy is read and validated inside the same SQLite transaction as user creation, preventing a concurrent mode change from bypassing disabled or invite-only registration.
• Invite registration no longer leaks username availability. Invite-code existence is checked before username lookup and bcrypt work, while final invite validation and consumption remain authoritative inside the registration transaction.
• Forwarded client IP handling is hardened. Forwarded headers are parsed with bounded work and client addresses are canonicalized, limiting memory amplification from malicious X-Forwarded-For input.

Performance and reliability

• SQLite usage writes are batched asynchronously. Usage persistence now reduces write-path contention without increasing the number of concurrent SQLite writers.
• Search capacity is released before quota rollback. Failed operations no longer hold scarce search capacity while compensating quota state.
• Rate limiter state is sharded and reclaimed incrementally. This lowers lock contention and reduces retained memory after temporary high-cardinality traffic spikes.
• SSE parsing performs fewer allocations. Event processing is byte-oriented, and the per-event limit is separated from the total response budget so complete raw responses are preserved without unnecessary temporary strings.
• Upstream error bodies are bounded. Non-2xx responses can no longer trigger excessive allocation or garbage-collection pressure through oversized response bodies.

Administration and auditability

• Invite-code redemption history is persisted atomically with registration. Audit records retain the redeemed invite code, the created user, and the redemption time.
• Administrators can inspect invite registration history in the panel. The release includes the supporting panel endpoints, pagination, and database migration.
• Invite pagination refreshes after create and delete operations. The panel no longer displays stale or inconsistent pages after invite-code changes.
• Unexpected registration storage failures return server errors. Internal failures are no longer misreported to clients as HTTP 400 validation errors.
• Operational metrics are opt-in. Database and asynchronous usage-writer metrics remain disabled by default and are exposed only after an administrator enables the persisted runtime setting.

Project and release changes

• The Go module path, internal imports, and documented linker flags now use the canonical repository path: github.com/MapleMapleCat/Grok_Search_Mcp.
• The default build version and documented Docker image tag have been updated to v0.2.1.

Upgrade and compatibility notes

• v0.2.1 is intended as an upgrade from v0.2.0.
• The application automatically applies the new invite-code redemption-history migration on startup; no manual database migration is required.
• Browser-based registration handles proof-of-work challenges automatically. Custom clients that call the registration API directly must request, solve, and submit a registration challenge before creating an account.
• Operational metrics remain disabled after upgrade until explicitly enabled by an administrator.
• Go consumers using the previous module path must update imports to github.com/MapleMapleCat/Grok_Search_Mcp.
• The Docker image is published as maplemaplecat/grok-search-mcp:v0.2.1.

Included commits

• 2e1dddc feat(store): improve SQLite write-path throughput and expose contention metrics.
• bab25c1 refactor(grok): reduce SSE parsing allocations while preserving raw responses.
• 7bfd571 fix(grok): limit upstream error response bodies.
• 9a193e0 fix(ratelimit): harden forwarded IP parsing and reduce limiter contention.
• cd72d68 feat(panel): gate operational metrics behind an administrator setting.
• 50673a0 refactor(project): align the Go module path with the GitHub repository.
• 9286570 fix(auth): prevent username disclosure during invite registration.
• e2d62bd fix(auth): enforce registration mode atomically.
• b0044b3 feat(auth): require signed, single-use proof of work for registration.
• 4fc8bc1 feat(invites): add invite redemption audit visibility and panel consistency fixes.
• 1e3abc0 chore(release): prepare version and image references for v0.2.1.

Assets

• grok-search-mcp_0.2.1_linux_amd64.tar.gz: statically linked Linux amd64 binary, README, and license.
• grok-search-mcp_0.2.1_linux_arm64.tar.gz: statically linked Linux arm64 binary, README, and license.
• checksums.txt: SHA-256 checksums for both archives.

Verify downloaded assets with:

sha256sum -c checksums.txt

Full changelog

v0.2.0...v0.2.1

v0.2.0

Database incompatibility / 数据库不兼容

Warning

v0.2.0 is not database-compatible with v0.1.0. Do not start v0.2.0 with an existing v0.1.0 SQLite database.

v0.2.0 与 v0.1.0 的数据库不兼容。请勿让 v0.2.0 直接使用现有的 v0.1.0 SQLite 数据库。

Before upgrading, stop v0.1.0 and back up its database file or Docker volume. Start v0.2.0 with a new database path or volume, then recreate or manually migrate the required users, tiers, API keys, invite codes, and runtime settings. In-place upgrades and downgrades using the same database are not supported.

升级前请先停止 v0.1.0，并备份数据库文件或 Docker 数据卷。请为 v0.2.0 使用新的数据库路径或数据卷，再按需重新创建或手动迁移用户、等级、API Key、邀请码及运行时设置。不支持在同一个数据库上直接升级或降级。

Project naming

• Unified the project, executable, MCP implementation, panel, Docker Compose service, and documentation under the grok-search-mcp name.
• Renamed release archives and their contained executable from grok-mcp to grok-search-mcp.
• Published the multi-platform Docker image as maplemaplecat/grok-search-mcp:v0.2.0.
• Renamed the default database file to grok-search-mcp.db and the Compose volume to grok-search-mcp-data.
• Added GROK_SEARCH_MCP_* environment variables while retaining the former GROK_MCP_* names as compatibility aliases.

Highlights

• Added bounded keyset pagination throughout the user and administration panels, configurable usage page sizes, lazy debug-body loading, and cancellation of obsolete requests so large histories no longer cause unbounded database or DOM work.
• Added live global and per-user search concurrency controls, persisted runtime settings, and limiter reuse to reduce contention while allowing administrators to tune active search capacity without restarting the service.
• Improved long-running search reliability with incremental SSE parsing, bounded stream resources, phase-specific connection and TLS timeouts, larger reusable connection pools, and safe transport replacement.
• Reworked SQLite persistence with separate read/write pools, indexed ownership and usage queries, asynchronous usage accounting, retention rollups, maintenance operations, bounded debug capture storage, and clearer responsibility-based modules.
• Improved authentication scalability with complete cached snapshots and a sharded, bounded LRU resolver cache.
• Improved panel performance and maintainability through batched tier loading, domain-specific handlers and event controllers, semantic stylesheet modules, and shared pagination/runtime-settings helpers.
• Tightened data integrity for invite-code creator references and removed obsolete full-list and legacy compatibility paths.
• Added release-triggered multi-platform Docker publishing and pinned patched Go toolchain and runtime images.

Deployment notes

• Search concurrency and other supported runtime settings can be updated from the administration panel without restarting.
• The listen address, database path, JWT secret, and source-IP RPM settings remain startup-only configuration.
• Internet-facing deployments should continue to place the plain-HTTP service behind a trusted HTTPS reverse proxy or load balancer.
• Docker image: maplemaplecat/grok-search-mcp:v0.2.0.

Assets

• grok-search-mcp_0.2.0_linux_amd64.tar.gz: statically linked Linux amd64 binary, README, and license.
• grok-search-mcp_0.2.0_linux_arm64.tar.gz: statically linked Linux arm64 binary, README, and license.
• checksums.txt: SHA-256 checksums for both archives.

Verify downloaded assets from the same directory with:

sha256sum -c checksums.txt

Full changelog

v0.1.0...v0.2.0

v0.1.0

Highlights

• Exposes Grok real-time web search, X/Twitter search, and model discovery through a Streamable HTTP MCP endpoint.
• Supports CPA upstream integrations through OpenAI Responses, OpenAI Chat Completions, and Anthropic Messages protocols.
• Includes per-user MCP API keys, tier-based rate limits and monthly quotas, usage tracking, invite-based registration, and an embedded administration panel.
• Persists service data and runtime settings in SQLite and includes a non-root Docker Compose deployment.

Deployment requirements

• Streamable HTTP only; stdio transport is not supported.
• The service listens on plain HTTP and does not terminate TLS. Internet-facing deployments should use a trusted HTTPS reverse proxy or load balancer.
• This is a prerelease. Validate configuration and backup SQLite data before production deployment.

Assets

• grok-mcp_0.1.0_linux_amd64.tar.gz: statically linked Linux amd64 binary, README, and license.
• grok-mcp_0.1.0_linux_arm64.tar.gz: statically linked Linux arm64 binary, README, and license.
• checksums.txt: SHA-256 checksums for both archives.

Verify downloaded assets with:

sha256sum -c checksums.txt