@basicbit/vrchat-mcp 0.1.0

package/docs/curated-tools.md

@@ -0,0 +1,132 @@
+# Curated Tool Charter
+
+This document defines the curated tool surface. The goal is to keep the
+default toolset small, explicit, and task-oriented so MCP clients can choose the next call
+without wading through hundreds of low-level endpoints.
+
+## Principles
+
+- Small and explicit: each tool has a single, obvious purpose.
+- Human-input friendly: accept names or natural inputs where reasonable.
+- Composable: outputs include IDs and metadata for follow-ups.
+- Safe by default: write tools are opt-in via `writes.allow`, with group allowlists for group-scoped writes.
+
+## Write controls
+
+- Read-only tools are always enabled.
+- Write tools require `writes.allow = true`.
+- Group-scoped writes additionally honor `groups.allowlist`.
+
+## Current curated tools (implemented)
+
+Friends and social (read):
+
+- `vrchat_friends_search`
+- `vrchat_friend_details`
+- `vrchat_friends_list`
+- `vrchat_friends_overview`
+
+Users and groups (read):
+
+- `vrchat_me`
+- `vrchat_user_profile`
+- `vrchat_user_groups`
+
+Avatars (read):
+
+- `vrchat_avatar_profile`
+
+Groups and updates (read):
+
+- `vrchat_groups_search`
+- `vrchat_group_profile`
+- `vrchat_group_members`
+- `vrchat_group_posts_recent`
+- `vrchat_group_events_list`
+- `vrchat_group_event_get`
+- `vrchat_group_events_upcoming`
+- `vrchat_group_instances_overview`
+
+Worlds (read):
+
+- `vrchat_worlds_search`
+- `vrchat_worlds_favorites`
+- `vrchat_world_profile`
+- `vrchat_world_instances_overview`
+
+Status and presence:
+
+- `vrchat_status_get` (read)
+- `vrchat_status_set` (low-risk write)
+- `vrchat_profile_update` (profile write; status preserved automatically)
+
+Status page (read):
+
+- `vrchat_status_page_overview`
+
+Notifications (read):
+
+- `vrchat_notifications_recent`
+
+Local VRCX (read, optional):
+
+- `vrcx_db_status`
+- `vrcx_memos_user_get`
+- `vrcx_memos_world_get`
+- `vrcx_memos_avatar_get`
+- `vrcx_gamelog_world_visits_recent`
+- `vrcx_instances_recent`
+- `vrcx_user_relationship_summary`
+- `vrcx_user_relationship_sessions`
+
+Events and calendar (read):
+
+- `vrchat_events_upcoming`
+- `vrchat_events_search`
+
+Events and calendar (write):
+
+- `vrchat_event_create`
+- `vrchat_event_update`
+- `vrchat_event_delete`
+
+Instances and invites (write):
+
+- `vrchat_instance_create`
+- `vrchat_invite_user`
+
+Invites (write, low-risk):
+
+- `vrchat_invite_self`
+
+## Next up (near-term)
+
+Groups (read):
+
+- `vrchat_group_members_summary`
+- `vrchat_groups_overview`
+
+Notifications (read):
+
+- `vrchat_notifications_unread`
+
+## Later (optional)
+
+Invites:
+
+- `vrchat_invites_pending`
+- `vrchat_invite_accept` (medium-risk)
+
+Automation hooks:
+
+- `vrchat_status_guard` (periodic check + corrective update)
+
+## Toolset toggles (planned)
+
+Auto-generated read tools are enabled by default (`vrchat_read_<operationId>`).
+Auto-generated write tools are enabled by default (`vrchat_write_<operationId>`, gated by `writes.allow`).
+The raw tool (`vrchat_call`) is disabled by default and can be enabled via config/environment flags.
+
+## Group allowlist guard
+
+Use `groups.allowlist` in the config file to limit group write operations to specific group IDs.

package/docs/design-notes.md

@@ -0,0 +1,48 @@
+# Design Notes (Archived)
+
+These notes capture ideas and decisions from early planning docs. Items here are
+either future-facing or contextual and are not required to run the MCP today.
+
+## Tool ergonomics
+
+- Prefer curated tools with clear, single-purpose effects.
+- Favor name-based inputs for human-friendly lookup; return IDs for follow-ups.
+- Automatically unroll pagination for “get all” domains (friends, groups) unless
+  the user explicitly wants page-based browsing (e.g., world search).
+- Keep outputs compact and task-oriented; avoid dumping large, low-signal fields.
+
+## Safety + scope (future-facing)
+
+- Hard deny: account deletion should never be exposed.
+- Dangerous actions (world/group deletion, moderation actions) should remain
+  off by default; if ever enabled, require explicit opt-in and strong warnings.
+- Optional “read-only vs power-user” profiles may be useful later (not implemented).
+
+## Realtime + caching
+
+- Pipeline websocket should update caches and drive MCP resources.
+- Prefer resources + subscriptions over custom notifications for live updates.
+- Stale-while-revalidate for heavy list endpoints (friends, groups) is desired.
+
+## Friends overview (location-centric)
+
+- Group online friends by instance/location to mirror VRChat’s social tab.
+- Include instance details per location (summary by default, full optional).
+- Use deduped instance/group/world lookups to keep output compact.
+- Support optional filters like status + minimum instance user count.
+
+## Groups + notifications
+
+- Prefer group posts as the primary “updates” feed; announcements are singular.
+- Use upcoming-window semantics for group events (e.g., next 7 days).
+- Keep group profile separate from heavy lists (members/posts/instances).
+
+## Evals (opt-in)
+
+- LLM-as-judge evals for curated tool outputs are valuable but optional.
+- Mock mode should be deterministic; live mode should be opt-in with real creds.
+- Sources to revisit if needed:
+  - https://platform.openai.com/docs/guides/graders
+  - https://platform.openai.com/docs/guides/structured-outputs
+  - https://www.promptfoo.dev/docs/intro/
+  - https://docs.ragas.io/

package/docs/evals.md

@@ -0,0 +1,129 @@
+# Evals
+
+This project uses three evaluation loops, from cheapest to most realistic.
+
+## 1. Mock LLM Evals
+
+Use this when changing tool outputs, schemas, or response wording.
+
+```bash
+npm run test:evals
+```
+
+These tests run against the mock VRChat server and grade expected facts with an LLM. They are deterministic enough for CI-style regression checks, but they do not prove live VRChat behavior.
+
+## 2. Read-Only Live Smoke
+
+Use this after login changes, curated tool changes, or OpenAPI/spec parameter changes.
+
+```bash
+npm run build
+npm run smoke:live
+```
+
+The smoke script starts the built MCP server, uses file cookie storage by default, and calls representative read tools across auth, profile, friends, worlds, groups, events, notifications, status page, and VRCX.
+
+Useful optional targets:
+
+```bash
+VRCHAT_MCP_SMOKE_FRIEND_NAME="Display Name" npm run smoke:live
+VRCHAT_MCP_SMOKE_WORLD_QUERY="club" npm run smoke:live
+VRCHAT_MCP_SMOKE_GROUP_ID="grp_..." npm run smoke:live
+```
+
+Expected result shape:
+
+```json
+{
+  "passed": 29,
+  "warned": 0,
+  "failed": 0,
+  "results": []
+}
+```
+
+Warnings are acceptable for optional VRCX or private group data. Failures need investigation before shipping.
+
+## 3. Manual Agent Evals
+
+Use this for the checks that catch tool-routing problems: connect Claude/OpenCode to the MCP server and ask for real VRChat lookups. Watch whether the client chooses the right tools, follows IDs from prior results, handles empty results, and asks for confirmation before writes.
+
+Good read-only prompts:
+
+```text
+Who is online right now, grouped by world, and where are the largest clusters of my friends?
+```
+
+```text
+Find a friend named <name>, tell me where they are, and include the world/group IDs I would need for follow-up actions.
+```
+
+```text
+Find upcoming events for group <group name or ID> this week. Pick the next one and show the event details.
+```
+
+```text
+Search for worlds matching "club" and summarize three good candidates without dumping tags unless useful.
+```
+
+```text
+Show recent notifications and tell me which ones look actionable.
+```
+
+Good write-flow prompts, only with `writes.allow=true` and disposable targets:
+
+```text
+Create a private instance in <world name> for me, then invite only me to it.
+```
+
+```text
+Invite <friend name> to my current instance, but ask me for confirmation before sending anything.
+```
+
+```text
+Set my VRChat status description to a test value, confirm it changed, then set it back.
+```
+
+Manual pass criteria:
+
+- The client uses curated tools before raw/generated tools when a curated tool exists.
+- The client handles names first, then carries IDs forward for follow-up calls.
+- The client treats empty or missing results as a real outcome, not a failure.
+- The client does not expose excessive friend/profile data unless needed for the task.
+- The client asks before medium-risk or externally visible writes.
+- The client explains any VRChat API errors in user terms and suggests the next useful tool.
+
+## Live LLM Evals
+
+Live LLM evals are opt-in because they call real VRChat APIs and an LLM grader.
+
+Create a live config outside the repository, then point `VRCHAT_MCP_LIVE_CONFIG_FILE` at it. If `cookieFile` is omitted, tests use a per-user config directory such as `%APPDATA%\\vrchat-mcp\\cookies.json` on Windows or `~/.config/vrchat-mcp/cookies.json` on Linux.
+
+```json
+{
+  "loginTimeoutSec": 120,
+  "debug": false,
+  "writeTests": { "enabled": false }
+}
+```
+
+Create an eval config outside the repository, set `OPENAI_API_KEY` in your shell or secret manager, then point `VRCHAT_MCP_EVAL_CONFIG_FILE` at the eval config. Do not put API keys directly in JSON files.
+
+You can copy `test/fixtures/evals.live.example.json`; it references `OPENAI_API_KEY` by environment variable name only.
+
+Run live evals from PowerShell with:
+
+```powershell
+$env:VRCHAT_MCP_LIVE_CONFIG_FILE = Join-Path $env:APPDATA 'vrchat-mcp\e2e.live.json'
+$env:VRCHAT_MCP_EVAL_CONFIG_FILE = Join-Path $env:APPDATA 'vrchat-mcp\evals.live.json'
+$env:VRCHAT_MCP_ENABLE_LIVE_EVALS = '1'
+npm test -- test/evals/live-llm.test.ts
+```
+
+Run live evals from bash with:
+
+```bash
+VRCHAT_MCP_LIVE_CONFIG_FILE="$HOME/.config/vrchat-mcp/e2e.live.json" VRCHAT_MCP_EVAL_CONFIG_FILE="$HOME/.config/vrchat-mcp/evals.live.json" VRCHAT_MCP_ENABLE_LIVE_EVALS=1 npm test -- test/evals/live-llm.test.ts
+```
+
+If this fails before running test cases with a login error, run `npm run smoke:live` first. Smoke is the cheaper auth/session diagnostic.

package/docs/tools-guide.md

@@ -0,0 +1,27 @@
+# Tools Guide
+
+This is the human-oriented overview for how to use the tool surface. The full, generated catalog of exposed tools (with schemas) is in `docs/tools.md`.
+
+## 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 opt-in**. Set `writes.allow = true` (or `VRCHAT_MCP_ALLOW_WRITES=true`) to enable any non-GET operation.
+- Group write actions are restricted by `groups.allowlist` when set.
+
+## MCP resources
+
+- `vrchat://friends/changes{?after,limit}` - delta feed for friend updates.
+- `vrchat://friends/snapshot{?includeOffline,pageSize,maxPages}` - friends snapshot.
+
+## Swagger UI (mcpo)
+
+- Run `npm run mcpo` to spin up an OpenAPI proxy with Swagger UI.
+- `npm run mcpo` requires `uvx` (from Astral’s `uv`) to be installed.
+- Open `http://localhost:8000/docs` to browse and try tool calls.
+- For config-based setup (Claude Desktop config + hot reload), see `README.md`.
+
+## Where the truth lives
+
+- `docs/tools.md` is generated from code + the OpenAPI spec and reflects the actual exposed tools.
+- `docs/curated-tools.md` describes the curated tool charter and risk tiers.