@basicbit/vrchat-mcp 0.1.5 → 0.1.6

package/docs/privacy.md

@@ -0,0 +1,23 @@
+# Privacy
+
+VRChat MCP runs locally on your machine as a stdio MCP server. The project does not operate a hosted service for your VRChat session.
+
+## Data Access
+
+Depending on which tools you call, VRChat MCP can retrieve VRChat account, friend, world, group, event, notification, invite, avatar, status, and local VRCX history data. Tool results are returned to the MCP client that launched the server.
+
+## Authentication Storage
+
+By default, VRChat auth cookies are stored in the operating system keychain. If keychain storage is unavailable, the server falls back to a local cookie file on your machine. You can opt into file storage explicitly with `VRCHAT_MCP_COOKIE_STORE=file`.
+
+VRChat's Creator Guidelines caution third-party API applications not to request or store login credentials, auth tokens, or session data. This project currently relies on local user-managed cookies because VRChat does not provide OAuth for this use case. Treat that as a policy-sensitive personal-use boundary: do not collect anyone else's login information, do not host this service for other users, and clear cookies with `vrchat_auth_logout` when you no longer need the session.
+
+## Network Requests
+
+The server makes requests to VRChat APIs, VRChat pipeline services, and VRChat status endpoints as needed for the tools you call. VRCX features read local VRCX database files on your machine when VRCX data is present.
+
+Curated write tools, generated write tools for API gaps, generated read tools, and read-only VRCX local-history tools are enabled by default for local full-capability use. Use your MCP client or agent harness to control account-changing tool calls, or set `VRCHAT_MCP_ALLOW_WRITES=false` for read-only mode. VRCX tools stay read-only and avoid known cookie/credential storage.
+
+## Hosted Integrations
+
+Do not send VRChat MCP cookies or session tokens to hosted third-party services. Public HTTP or hosted connector variants should only be used if a future VRChat OAuth or public-data-only design exists.

package/docs/robust-notes.md

@@ -0,0 +1,29 @@
+# Robust Notes
+
+Durable product and security-review notes for future agents.
+
+## Security Review Product Boundary
+
+VRChat MCP is intended to be a local, full-capability MCP server. Do not reduce the default tool surface to read-only as a security-review reflex. The expected permission boundary for account-changing actions is the user's MCP client or agent harness, which should decide whether to allow, deny, or ask before executing tool calls.
+
+Default posture:
+
+- Curated write tools are enabled by default through `writes.allow = true`.
+- VRCX local-history tools are enabled by default and remain read-only, bounded, and curated.
+- Generated read tools are enabled by default for API exploration, excluding hard-skipped operations and operations with curated replacements.
+- Generated write tools are enabled by default for usable API-gap coverage, excluding hard-skipped operations and operations with curated replacements.
+- Read-only mode remains available with `writes.allow = false` or `VRCHAT_MCP_ALLOW_WRITES=false` for test, demo, or constrained deployments.
+
+Generated tool `operationIds` lists are narrowing controls, not required allowlists, and they do not re-enable generated operations covered by curated tools. Keep generated tools default-on for broad VRChat API capability and rely on the local MCP client or agent harness to approve or deny account-changing tool calls. Do not propose disabling generated read/write/delete routers by default as a context-budget optimization unless the user explicitly reopens that product boundary. Prefer solving context cost with schema deduplication, smaller repeated metadata, on-demand operation details, and curated consolidation of common multi-endpoint workflows. If a generated write becomes common or needs better ergonomics, add a curated write tool with clear inputs, bounded behavior, IDs in outputs, rate/backoff behavior where appropriate, and tests; the generated duplicate should then disappear from the default surface.
+
+Do not omit generated `outputSchema` only to save context: some MCP clients may use output schemas for validation or UX, and the field is optional context for clients rather than guaranteed model prompt text. Treat output schema removal as a client-compatibility decision, not a default budget trick.
+
+When consolidating tools, preserve harness permission granularity. Avoid combining read-only and write operations in one curated tool, and avoid combining destructive and non-destructive writes unless the resulting tool is correctly annotated/described as the highest-risk operation it can perform. Prefer explicit `action` enums over natural-language routing, and keep code focused on validation/execution rather than fuzzy intent inference.
+
+When future audits flag write/VRCX/generated-tool exposure, treat the preferred remediation as better docs, curated coverage, tool annotations, tests, and harness guidance, not disabling the feature by default.
+
+The separate unresolved policy-sensitive boundary remains VRChat authentication: this project uses local user-managed cookies because there is no OAuth flow for this use case. Do not host this service for other users or collect other users' credentials/session data.
+
+## 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.

package/docs/tools-guide.md

@@ -5,9 +5,15 @@ This is the human-oriented overview for how to use the tool surface. The full, g
 ## How to use tools
 
 - Prefer **curated tools** first. They include search and summary flows for common VRChat tasks.
-- Use **auto-generated tools** (`vrchat_read_<operationId>`, `vrchat_write_<operationId>`) only when a curated tool does not exist.
-- **Writes are enabled by default**. Set `writes.allow = false` (or `VRCHAT_MCP_ALLOW_WRITES=false`) for read-only mode.
+- Auto-generated API-gap coverage is exposed through `vrchat_read`, `vrchat_write`, and `vrchat_delete`. Pass an OpenAPI `operationId`; use `vrchat_operations` to list available operation IDs and `vrchat_operation_details` for exact params/body schemas. Generated routers omit hard-skipped operations and operations already covered by curated tools. Use `generatedReadTools.operationIds` or `generatedWriteTools.operationIds` only when you want to narrow the remaining generated surface.
+- Curated write tools are enabled by default for local full-capability use. Set `writes.allow = false` (or `VRCHAT_MCP_ALLOW_WRITES=false`) for read-only mode.
+- The MCP client or agent harness is expected to control approval/denial for account-changing tool calls.
 - Group write actions are restricted by `groups.allowlist` when set.
+- Do not expose this server as a hosted/public MCP service with VRChat cookies. Keep it local and user-controlled.
+
+## Metadata budget
+
+Tool names, tool descriptions, argument names, argument descriptions, and schema structure consume model context. Run `npm run metrics:tool-budget` to report the estimated default tool metadata token budget, category breakdown, initial tool-list cost, full schema cost, repeated argument-description hotspots, blank tool-description coverage, argument-description coverage, and the largest tools by metadata size. CI includes this in `npm run metrics`; keep the budget from drifting upward unless the extra guidance is worth the context cost.
 
 ## MCP resources
 
@@ -23,5 +29,5 @@ This is the human-oriented overview for how to use the tool surface. The full, g
 
 ## Where the truth lives
 
-- `docs/tools.md` is generated from code + the OpenAPI spec and reflects the actual exposed tools.
+- `docs/tools.md` is generated from code + the OpenAPI spec and includes curated tools plus the generated catalog.
 - `docs/curated-tools.md` describes the curated tool charter and risk tiers.