v0.2.0: users, realms, status, syslog tools by Miggets7 · Pull Request #1 · openremote/mcp-server

Miggets7 · 2026-05-20T09:39:30Z

Summary

Extends the MCP server beyond the v0.1.0 asset/attribute surface:

Users (Keycloak-backed) — CRUD (query_users, get_user, create_user, update_user, delete_user), role management, self-service profile/locale, and the password-reset email flow.
Realms — full CRUD (list_realms, list_accessible_realms, get_realm, create_realm, update_realm, delete_realm).
System status — get_health_status, get_system_info + matching resources.
Syslog — event query/clear and config read/replace.

Tool surface: 13 → 43 tools, 4 → 6 resources. Additive only — no v0.1.x breaking changes.

fixes #2

…t_current_user Remove tool families that are either security liabilities or low-value for an LLM-driven workflow: - users-sessions.ts (both tools): disconnect_user_session uses HTTP GET to mutate state, easy for an LLM to fire by accident and log real users out. get_user_sessions had marginal debug value on its own. - update_password / update_current_password: plaintext password flows through the LLM context (transcripts, provider logs, cache). Email-only reset flow (request_password_reset, request_current_password_reset) stays. - reset_user_secret: regenerating a service user's OAuth secret can lock out integrations and, worst case, the MCP server's own auth. - get_current_user: returns the service-user identity that the server already runs as; marginal value to downstream prompts. Net: 24 -> 17 user tools. PUT-replace semantics on update_user and the update_*_roles tools kept as-is (description warnings already present).

Drop the users-sessions import and registerUserSessionTools() call, and remove the trimmed tool names from the LLM-facing instructions block.

README capability table: tool count 49 -> 43; rows for get_current_user, update_password, update_current_password, reset_user_secret, get_user_sessions, disconnect_user_session removed. CLAUDE.md: add project guidance file; scope-boundaries paragraph documents that sessions and direct-credential mutation are deferred (footgun + LLM-context credential leakage); conventions paragraph lists the active users-* split sub-files.

Copilot

Pull request overview

This PR bumps the MCP server to v0.2.0 and expands the tool/resource surface from asset/attribute management to include Keycloak-backed user management, realm CRUD, system status, and syslog operations—aligning the implementation with the scope described in issue #2.

Changes:

Added new tool modules for users (CRUD, roles, self-service, password reset), realms, status, and syslog, and registered them in src/server.ts.
Added status resources (openremote://status/health, openremote://status/info) plus Vitest coverage for the new tools/resources.
Updated docs and versioning (README.md, CLAUDE.md, package.json, server version string).

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/tools/users-self.test.ts	Adds coverage for self-service user profile + locale update tools.
tests/tools/users-roles.test.ts	Adds coverage for role catalog + user role assignment tools.
tests/tools/users-passwords.test.ts	Adds coverage for password reset email flow tools, including error path.
tests/tools/users-crud.test.ts	Adds coverage for user CRUD/query tools, including error path.
tests/tools/syslog.test.ts	Adds coverage for syslog event query/clear + config read/replace tools.
tests/tools/status.test.ts	Adds coverage for system health/info tools.
tests/tools/realms.test.ts	Adds coverage for realm CRUD/list tools.
tests/resources/status.test.ts	Adds coverage for new status MCP resources.
src/tools/users-self.ts	Implements current-user profile/locale tools.
src/tools/users-roles.ts	Implements role catalog and user role assignment tools.
src/tools/users-passwords.ts	Implements password reset email flow tools.
src/tools/users-crud.ts	Implements user query + CRUD tools.
src/tools/syslog.ts	Implements syslog query/clear and config read/replace tools.
src/tools/status.ts	Implements health and system info tools.
src/tools/realms.ts	Implements realm CRUD and realm listing tools.
src/server.ts	Registers the new tools/resources, updates version and instructions text.
src/resources/status.ts	Adds `openremote://status/health` and `openremote://status/info` resources.
README.md	Updates published tool/resource list and adds roadmap section.
package.json	Bumps package version to 0.2.0.
CLAUDE.md	Adds repo guidance, conventions, and scope boundaries for v0.2.0+.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Miggets7 · 2026-05-21T13:10:21Z

+      inputSchema: {
+        level: syslogLevelSchema.optional().describe("Minimum level filter"),
+        per_page: z.number().int().min(1).max(1000).optional(),
+        page: z.number().int().min(0).optional(),
+        from: z.number().int().optional().describe("Lower bound timestamp (epoch ms)"),
+        to: z.number().int().optional().describe("Upper bound timestamp (epoch ms)"),
+        category: z.array(syslogCategorySchema).optional(),
+        subCategory: z.array(z.string()).optional(),


Correction to my earlier reply: keeping per_page as-is. The backend SyslogResource.getEvents query param is literally per_page (snake_case), and we intentionally mirror the OpenRemote wire shape for this tool rather than introducing a camelCase rename plus an internal mapping layer. Not changing this.

Miggets7 · 2026-05-21T11:59:01Z

+    "get_health_status",
+    {
+      description:
+        "Get the OpenRemote system health status (database, gateway, etc.). Requires `read:admin`. Returns a map keyed by component.",


Not changing this one. getHealthStatus() is typed RestResponse<{ [index: string]: any }> (a flat indexed map), and OpenRemote's /health endpoint returns a map keyed by each HealthStatusProvider name. There is no top-level status field or nested components map — that is the Spring Boot Actuator shape, which OpenRemote does not use. The current wording "Returns a map keyed by component" matches the actual payload. Happy to revisit if you have a live-deployment response showing a different shape.

Miggets7 · 2026-05-21T11:58:53Z

+- get_client_roles / update_client_roles / update_realm_roles / get_user_realm_roles / update_user_realm_roles / get_user_client_roles / update_user_client_roles / get_current_user_realm_roles / get_current_user_client_roles
+- update_current_user / update_current_user_locale
+
+Tools — realms (admin):


Renamed the heading to "Tools — realms". list_accessible_realms is the non-admin variant, so the (admin) qualifier was misleading (server.ts:45).

list_accessible_realms is the non-admin variant, so the "(admin)" qualifier on the realms instructions heading was inaccurate.

…sthrough Review findings (PR #1): - update_realm: the backend requires the realm id in the body and 500s without it. Extract a shared base schema, add a required id to the update variant, and document that a get_realm-first read is mandatory for every update, not only partial ones. - update_user_client_roles: document that roles are name strings, not the role objects get_client_roles returns. - request_password_reset / request_current_password_reset: note that a configured mail server is required; the backend returns a 500 otherwise. - Remove update_current_user and update_current_user_locale: both are dead under service-account auth (405 and no-op). Drops registration, the users-self files, and updates README and scope notes. Cleanup: - Replace deprecated ZodObject.passthrough() with z.looseObject() / .loose() (Zod 4.4.3); behavior unchanged.

Miggets7 · 2026-06-02T09:22:24Z

All five findings addressed in b57872c (release/v0.2.0).

Request shape

update_user_client_roles: kept the string[] shape since it mirrors the backend updateUserClientRoles. Clarified in the tool description and on the roles field that these are role name strings, to be sourced from get_user_client_roles (which already returns names) or the name field of get_client_roles objects.
update_realm missing id: extracted a shared base schema. update_realm now uses a variant with a required id: z.string().min(1), and the description states id is always required (the backend returns a 500 without it) and that a get_realm-first read is mandatory for every update, not only partial ones. create_realm keeps the id-less schema since the backend generates the id.

Self-service tools removed (update_current_user, update_current_user_locale). Confirmed against ManagerKeycloakIdentityProvider.createUpdateUser: the 405 fires because the request body's isServiceAccount defaults to false while the stored record is a service account, so the tool can never succeed under service-account auth; locale is a no-op. Dropped the registration, deleted the users-self files and test, and updated the README and scope notes.

OpenRemote backend issues (id required in the realm body, password-reset 500 on missing SMTP): these are upstream backend behaviors, not fixable in the MCP layer. Documented both in the tool descriptions instead. update_realm states the id is required, and both request_password_reset / request_current_password_reset now warn that a configured mail server is required (otherwise a 500 IllegalStateException that cannot be distinguished from an invalid user id).

Unrelated cleanup in the same commit: migrated the deprecated ZodObject.passthrough() to z.looseObject() / .loose() (Zod 4.4.3); behavior unchanged.

Ekhorn

Went through it with the same settings. It looks good now. I will approve after these last threads.

Remove request_current_password_reset: like the other self-service endpoints it is useless under service-account auth (it emails the service account's nonexistent inbox). Inline the remaining request_password_reset into users-crud.ts and delete the now single-tool users-passwords.ts; absorb its tests. Note the exclusion in the scope boundaries. Fix syslog enum drift against @openremote/model: drop the invalid DEBUG level and MANAGER category, add the missing ALARM category. The model ships these as ambient const enums, so deriving them via Object.values hits TS2475 under tsc; keep corrected literals in sync on model bumps instead.

Ekhorn

Nice!

Miggets7 added 13 commits May 15, 2026 20:31

feat(users): add user CRUD tools (query/get/create/update/delete)

2d561ed

feat(users): add password/secret tools

d0913fb

feat(users): add role management tools

a392d5e

feat(users): add session tools

d220663

feat(users): add self-service tools (profile + locale)

f5ae80d

feat(realms): add realm CRUD tools

b94bcdd

feat(status): add health + info tools and resources

e3b3367

feat(syslog): add event + config tools

ba83a99

feat(server): register v0.2.0 tools and resources

c3bd836

chore: bump to 0.2.0; update README capability tables

3034f48

refactor(server): unregister trimmed user tools

bb7f8e9

Drop the users-sessions import and registerUserSessionTools() call, and remove the trimmed tool names from the LLM-facing instructions block.

Miggets7 self-assigned this May 20, 2026

Miggets7 added the Enhancement Improvement of an existing feature label May 20, 2026

Miggets7 requested a review from a team May 20, 2026 10:05

wborn requested a review from Copilot May 21, 2026 07:42

Copilot started reviewing on behalf of wborn May 21, 2026 07:42 View session

Copilot AI reviewed May 21, 2026

View reviewed changes

docs(server): drop misleading (admin) qualifier from realms tool heading

1aa947f

list_accessible_realms is the non-admin variant, so the "(admin)" qualifier on the realms instructions heading was inaccurate.

Ekhorn assigned Ekhorn and unassigned Ekhorn May 28, 2026

Ekhorn requested review from Ekhorn and removed request for a team May 28, 2026 08:14

This comment was marked as resolved.

Sign in to view

Miggets7 requested a review from Ekhorn June 2, 2026 09:24

Ekhorn reviewed Jun 4, 2026

View reviewed changes

Comment thread src/tools/users-passwords.ts Outdated

Comment thread src/tools/syslog.ts

Miggets7 requested a review from Ekhorn June 4, 2026 11:09

Ekhorn approved these changes Jun 4, 2026

View reviewed changes

Miggets7 merged commit 7545893 into main Jun 4, 2026
1 check passed

Miggets7 deleted the release/v0.2.0 branch June 4, 2026 12:00

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

v0.2.0: users, realms, status, syslog tools#1

v0.2.0: users, realms, status, syslog tools#1
Miggets7 merged 16 commits into
mainfrom
release/v0.2.0

Miggets7 commented May 20, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Miggets7 May 21, 2026

Uh oh!

Miggets7 May 21, 2026

Uh oh!

Miggets7 May 21, 2026

Uh oh!

This comment was marked as resolved.

Uh oh!

Miggets7 commented Jun 2, 2026

Uh oh!

Ekhorn left a comment

Uh oh!

Uh oh!

Uh oh!

Ekhorn left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Miggets7 commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Miggets7 May 21, 2026

Choose a reason for hiding this comment

Uh oh!

Miggets7 May 21, 2026

Choose a reason for hiding this comment

Uh oh!

Miggets7 May 21, 2026

Choose a reason for hiding this comment

Uh oh!

This comment was marked as resolved.

Uh oh!

Miggets7 commented Jun 2, 2026

Uh oh!

Ekhorn left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Ekhorn left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Miggets7 commented May 20, 2026 •

edited

Loading