@basicbit/vrchat-mcp 0.1.9 → 0.1.11

package/dist/src/tools/raw.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { callOperation, CallError } from '../core/client.js';
-import { getBlockedOperationReason } from '../core/operationPolicy.js';
+import { getBlockedOperationReason, getCuratedOnlyReason } from '../core/operationPolicy.js';
 import { CallInputSchema } from '../schemas/call.js';
 import { writeToolAnnotations } from '../utils/toolAnnotations.js';
 import { toolName } from '../utils/toolNames.js';
@@ -22,6 +22,10 @@ export function registerRawTools(server) {
         if (blockedReason) {
             return toolError(`Operation ${args.operationId} is disabled: ${blockedReason}`);
         }
+        const curatedOnlyReason = getCuratedOnlyReason(args.operationId);
+        if (curatedOnlyReason) {
+            return toolError(curatedOnlyReason);
+        }
         try {
             const result = await callOperation(args);
             return {

package/dist/src/tools/raw.js.map

@@ -1 +1 @@
-{"version":3,"file":"raw.js","sourceRoot":"","sources":["../../../src/tools/raw.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,SAAS,EAAkB,MAAM,mBAAmB,CAAC;AAC7E,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAEtD,MAAM,UAAU,gBAAgB,CAAC,MAAiB;IAChD,MAAM,CAAC,YAAY,CACjB,QAAQ,CAAC,aAAa,CAAC,EACvB;QACE,WAAW,EAAE,iDAAiD;QAC9D,WAAW,EAAE,eAAe;QAC5B,YAAY,EAAE,CAAC,CAAC,MAAM,CAAC;YACrB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;YACf,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;YAC7B,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;YACpD,IAAI,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;YACxB,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;SAC/B,CAAC;QACF,WAAW,EAAE,oBAAoB;KAClC,EACD,KAAK,EAAE,IAAe,EAAE,EAAE;QACxB,MAAM,aAAa,GAAG,yBAAyB,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAClE,IAAI,aAAa,EAAE,CAAC;YAClB,OAAO,SAAS,CACd,aAAa,IAAI,CAAC,WAAW,iBAAiB,aAAa,EAAE,CAC9D,CAAC;QACJ,CAAC;QAED,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,CAAC;YACzC,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;qBACtC;iBACF;gBACD,iBAAiB,EAAE,MAA4C;aAChE,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,SAAS,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;gBAC5C,OAAO,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;YAC7C,CAAC;YACD,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;YACrE,OAAO,SAAS,CAAC,OAAO,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"raw.js","sourceRoot":"","sources":["../../../src/tools/raw.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,SAAS,EAAkB,MAAM,mBAAmB,CAAC;AAC7E,OAAO,EAAE,yBAAyB,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAC7F,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAEtD,MAAM,UAAU,gBAAgB,CAAC,MAAiB;IAChD,MAAM,CAAC,YAAY,CACjB,QAAQ,CAAC,aAAa,CAAC,EACvB;QACE,WAAW,EAAE,iDAAiD;QAC9D,WAAW,EAAE,eAAe;QAC5B,YAAY,EAAE,CAAC,CAAC,MAAM,CAAC;YACrB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;YACf,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;YAC7B,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;YACpD,IAAI,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;YACxB,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;SAC/B,CAAC;QACF,WAAW,EAAE,oBAAoB;KAClC,EACD,KAAK,EAAE,IAAe,EAAE,EAAE;QACxB,MAAM,aAAa,GAAG,yBAAyB,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAClE,IAAI,aAAa,EAAE,CAAC;YAClB,OAAO,SAAS,CACd,aAAa,IAAI,CAAC,WAAW,iBAAiB,aAAa,EAAE,CAC9D,CAAC;QACJ,CAAC;QAED,MAAM,iBAAiB,GAAG,oBAAoB,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACjE,IAAI,iBAAiB,EAAE,CAAC;YACtB,OAAO,SAAS,CAAC,iBAAiB,CAAC,CAAC;QACtC,CAAC;QAED,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,CAAC;YACzC,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;qBACtC;iBACF;gBACD,iBAAiB,EAAE,MAA4C;aAChE,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,SAAS,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;gBAC5C,OAAO,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;YAC7C,CAAC;YACD,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;YACrE,OAAO,SAAS,CAAC,OAAO,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/docs/curated-tools.md

@@ -94,10 +94,24 @@ Events and calendar (write):
 Instances and invites (write):
 
 - `vrchat_instance_create`
+- `vrchat_instance_link_event`
 - `vrchat_invite`
 - `vrchat_invite_user`
 - `vrchat_invite_user_to_me`
 
+`vrchat_instance_link_event` accepts an explicit group, event, world, and instance ID. It first
+checks `groups.allowlist`, then freshly reads both objects and requires the event and group-type
+instance to have that same group owner. It refuses to replace a different existing event link.
+Calls targeting one instance are serialized within the MCP process so concurrent requests cannot
+replace one another after both read an unlinked instance. Re-linking the same event is an
+idempotent no-op that still invalidates the relevant caches. The result includes the group and
+event IDs plus readable event and instance names for safe follow-up calls. The tool can only set
+`calendarEntryId`; it cannot unlink an event or change any other instance field, and it does not
+send invitations or notifications. A conflicting existing link is rejected after invalidating the
+same caches so later reads see that fresh state. VRChat accepts the link only when the event starts
+within six hours or ended within the previous six hours. Like other account-changing tools,
+approval belongs at the MCP client or agent-harness boundary.
+
 Groups and social writes:
 
 - `vrchat_group_invite`

package/docs/robust-notes.md

@@ -26,4 +26,12 @@ The separate unresolved policy-sensitive boundary remains VRChat authentication:
 
 ## API Content Upload Boundary
 
-VRChat Creator Guidelines (API Usage / Bots, checked 2026-05-26) say not to create or use software, scripts, or applications that upload content such as worlds, avatars, or similar asset types on a user's behalf. Treat generated operations for uploading or managing uploaded asset content as policy-sensitive, not merely high-risk writes. Default policy blocks explicit avatar/world content-management operations (`createAvatar`, `updateAvatar`, `deleteAvatar`, `createWorld`, `updateWorld`, `deleteWorld`, `publishWorld`, `unpublishWorld`) in central operation validation and hides their generated write tools. Do not assume all image-like uploads are prohibited: icons, prints, gallery images, file upload pipeline operations, and similar user image/file operations remain separate policy decisions. Selecting or viewing avatars is a different class from uploading avatar content; do not over-block ordinary user account actions without mapping them to the guideline text.
+VRChat Creator Guidelines (API Usage / Bots, checked 2026-05-26) say not to create or use software, scripts, or applications that upload content such as worlds, avatars, or similar asset types on a user's behalf. Treat generated operations for uploading or managing uploaded asset content as policy-sensitive, not merely high-risk writes. Default policy blocks explicit avatar/world content-management operations (`createAvatar`, `deleteAvatar`, `createWorld`, `updateWorld`, `deleteWorld`, `publishWorld`, `unpublishWorld`) in central operation validation and hides their generated write tools.
+
+`updateAvatar` is the one exception, and the boundary moved rather than disappeared. It is no longer in central operation validation, because the curated `vrchat_avatar_update` tool has to reach it; it is listed as curated-only instead, so the raw call tool and the generated write registry both still refuse it. That tool writes `name`, `description`, `releaseStatus` and content tags, and never `assetUrl`, `unityPackageUrl`, `unityVersion` or `version`. The reasoning: editing metadata on already-uploaded content is a different act from uploading content on a user's behalf, which is what the guideline text addresses.
+
+**Avatar `releaseStatus` is deliberately allowed** (decided 2026-08-03). It looks like the avatar analogue of `publishWorld` / `unpublishWorld`, but those are blocked for a reason avatars do not share: unpublishing a world sends it back through Community Labs, so toggling world publication has a real and costly consequence an agent should not be able to trigger. Avatars have no equivalent gate. The avatar act this reasoning permits is metadata editing and nothing more: `createAvatar` and `deleteAvatar` both remain hard-blocked, creation because it is upload and deletion because it is destructive and irreversible. Changing an existing avatar's publication state is metadata management, not upload or republication.
+
+This does not make `releaseStatus` casual — it can still expose a creator's work against their terms, leak an avatar meant to stay private, or breach content policy depending on what the avatar contains, which is why the tool description tells callers to confirm intent first.
+
+Do not assume all image-like uploads are prohibited: icons, prints, gallery images, file upload pipeline operations, and similar user image/file operations remain separate policy decisions. Selecting or viewing avatars is a different class from uploading avatar content; do not over-block ordinary user account actions without mapping them to the guideline text.

package/docs/spec-drift.md

@@ -0,0 +1,104 @@
+# Spec Drift
+
+`specs/vrchat-openapi.yaml` is the **community** OpenAPI description
+([vrchatapi/specification](https://github.com/vrchatapi/specification)), not one VRChat
+publishes. It is reverse-engineered and maintained by volunteers, so it drifts from the live API
+continuously and permanently. That is expected, not a bug in the spec.
+
+**The live API is the source of truth — not the spec, and not this file.** This is a log of
+divergences we have actually observed, with dates and evidence, so nobody re-investigates the same
+thing from scratch.
+
+Every entry is a point-in-time observation and can go stale. VRChat may change behavior, the
+community spec may catch up, and a workaround recorded here may become unnecessary or actively
+wrong. **Before making a substantive change that depends on an entry, re-verify it against the
+live API and update the entry with what you found.** An old date is a reason for suspicion, not
+confidence.
+
+Add an entry whenever you find a new divergence, including ones you decide not to work around.
+Where a fix is needed, prefer `scripts/postprocess-schemas.ts` over editing the spec:
+`specs/vrchat-openapi.yaml` is gitignored, so spec edits are local-only and vanish on a fresh
+clone.
+
+---
+
+## Confirmed divergences
+
+### `GroupPermissions` enum is incomplete
+*Observed 2026-08-02, not re-verified since · patched in `postprocess-schemas.ts`*
+
+Spec lists 25 values. `GET /groups/{groupId}/permissions` returns **27**, the extras being
+`group-instance-announcement-create` and `group-instance-bypass-avatar-performance`. Any role
+update using them failed zod validation before reaching VRChat.
+
+### `Group.transferTargetId` is nullable
+*Observed 2026-08-02, not re-verified since · patched in `postprocess-schemas.ts`*
+
+Spec types it as a non-null `UserID`. Groups with no pending ownership transfer return `null`,
+which failed the whole `getGroup` parse and took `vrchat_group_profile` down with it.
+
+### `InviteRequest.instanceId` needs the worldId prefix
+*Observed 2026-08-02, not re-verified since · handled in `services/invites/curated.ts`*
+
+The spec describes `InstanceID` as the bare instance part
+(`12345~hidden(usr_…)~region(eu)`). `POST /invite/{userId}` rejects that form with
+`400: Invalid location` and requires the **full** `worldId:instanceId~…` string.
+
+Verified live: full string → `200`, worldId stripped → `400`.
+
+### `CreateInstanceRequest.canRequestInvite` is restricted to private instances
+*Observed 2026-09-01 · handled in `services/instances/curated.ts`*
+
+The community schema permits `canRequestInvite` for every instance type. The live API accepts
+`true` only when `type` is `private`; a group instance returns
+`400: Cannot add canRequestInvite to non-private instances.` The same group instance succeeds
+when the field is omitted or set to `false`.
+
+### Single calendar events report `occurrenceKind: "single"`
+*Observed 2026-09-01 · handled in `services/events/curated.ts`*
+
+The generated `CalendarEvent` schema does not declare `occurrenceKind`. The live group calendar
+event endpoint reports `"single"` for a confirmed non-recurring event, while the curated delete
+tool deliberately exposes the more explicit `targetKind: "single_event"` safety value.
+
+### Role permissions have undocumented prerequisites
+*Observed 2026-08-02, not re-verified since*
+
+Not a schema issue — the API enforces dependencies the spec never mentions.
+`group-members-remove` and `group-bans-manage` both require `group-members-manage` on the same
+role, otherwise `PUT /groups/{groupId}/roles/{roleId}` returns
+`400: Role missing required permissions: group-members-manage`.
+
+### `UserStatus` has no color mapping
+*Observed 2026-08-02, not re-verified since*
+
+The spec defines the enum but says nothing about colors, because they are a client-UI concept.
+For reference: **Join Me = blue, Active = green, Ask Me = orange, Busy = red.**
+
+### Existing instances can be linked to calendar events with an undocumented `PUT`
+*Observed and re-verified 2026-08-31 · handled by the curated instance linker*
+
+The community spec has no update operation for an existing instance. The live API accepts
+`PUT /instances/{worldId}:{instanceId}` with `{"calendarEntryId":"cal_..."}` and returns the
+updated `Instance`. `PATCH` on the same path returned `405`.
+
+VRChat returned `400` when the event was outside its link window, with the rule that an event
+must start within six hours or have ended within the previous six hours. Moving the test event
+inside that window made the same `PUT` return `200`. Sending `{"calendarEntryId":null}` also
+returned `200` and removed the link, but the curated tool intentionally exposes linking only.
+
+Verified live with an owned disposable test group, event, and group-only instance. No invitation
+or announcement was sent. Because the endpoint is missing from the spec, `core/client.ts` carries
+a narrow operation fallback until the community spec catches up. Raw access is blocked and the
+curated tool sends only `calendarEntryId` after checking the configured group allowlist and both
+objects' ownership.
+
+---
+
+## Suspected, not yet verified
+
+### `UpdateAvatarRequest.description` minLength
+Spec declares `minLength: 1`, which would make an empty description an invalid request and leave
+no way to clear one. BASIC reports descriptions are effectively optional in practice, so
+`vrchat_avatar_update` deliberately does **not** enforce a minimum and lets VRChat decide. If a
+`description: ""` write is ever seen failing, record the result here and add the constraint.