@basicbit/vrchat-mcp 0.1.0

package/docs/vrcx.md

@@ -0,0 +1,69 @@
+# VRCX Integration Notes
+
+This repo includes optional read-only tooling to pull _local_ context from the VRCX SQLite database.
+
+The goal is to expose information that VRChat's public API does not provide (e.g. local memos, your join/leave history, and time-spent estimates), while avoiding sensitive material (cookies, stored credentials).
+
+## Default locations
+
+VRCX stores its primary database under the user's application data directory.
+
+- Windows: `%APPDATA%\\VRCX\\VRCX.sqlite3`
+- macOS (common): `~/Library/Application Support/VRCX/VRCX.sqlite3`
+- Linux (common): `~/.config/VRCX/VRCX.sqlite3` (some builds use `~/.local/share/VRCX`)
+
+VRCX also stores a small JSON settings file:
+
+- Windows: `%APPDATA%\\VRCX\\VRCX.json`
+
+The `VRCX.json` key `VRCX_DatabaseLocation` can override the DB path.
+
+VRCX may also create `VRCX-WorldData.db` in the same directory.
+
+## Key tables (high-level)
+
+Useful (non-secret) tables commonly present:
+
+- `memos`, `world_memos`, `avatar_memos` (your local notes)
+- `gamelog_location` (your recent world/instance visits)
+- `gamelog_join_leave` (player join/leave events; used by VRCX to estimate time spent)
+- `favorite_world`, `favorite_avatar`, `cache_world`, `cache_avatar`
+
+Sensitive / do-not-expose tables:
+
+- `cookies` (session cookies)
+- `configs` contains keys like `config:savedcredentials` (may include credentials/cookies)
+  - Only a small allowlist of safe keys should be read (e.g. `config:lastuserloggedin`, `config:vrcx_databaseversion`).
+
+Per-user tables (prefixed):
+
+VRCX creates user-specific tables using a prefix derived from the logged-in VRChat userId.
+The prefix is roughly `userId` with `-` and `_` removed.
+
+Examples:
+
+- `<prefix>_notes`
+- `<prefix>_friend_log_current`
+- `<prefix>_friend_log_history`
+- `<prefix>_feed_*`
+
+## “Time spent with someone” (how VRCX derives it)
+
+VRCX uses `gamelog_join_leave` entries.
+
+- `type = 'OnPlayerLeft'` rows often include a `time` column representing how long that player was present before leaving.
+- `created_at` is the leave timestamp.
+- Join timestamp can be approximated as: `joinTime = created_at - time`.
+
+This enables tools to provide:
+
+- relationship summary: total time spent, last seen, count of distinct instances
+- relationship sessions: recent per-session breakdown (bounded by limit)
+
+## Tooling philosophy
+
+- Read-only by default.
+- Small, curated outputs.
+- No raw SQL passthrough.
+- Never return `cookies` or sensitive `configs` keys.
+- History-heavy tools are separate or explicitly bounded by limits.

package/package.json

@@ -0,0 +1,109 @@
+{
+  "name": "@basicbit/vrchat-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for VRChat friends, worlds, groups, events, notifications, and VRCX history.",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "vrchat-mcp": "dist/bin/cli.js"
+  },
+  "files": [
+    "dist",
+    "assets/logo.svg",
+    "docs/architecture.md",
+    "docs/curated-tools.md",
+    "docs/design-notes.md",
+    "docs/evals.md",
+    "docs/tools-guide.md",
+    "docs/tools.md",
+    "docs/vrcx.md",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "dev": "tsx src/index.ts",
+    "lint": "eslint . --ext .ts,.tsx,.mts --max-warnings=0",
+    "lint:fix": "npm run lint -- --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "vitest run test/e2e",
+    "test:e2e:live": "vitest run test/e2e/live.test.ts",
+    "test:evals": "vitest run test/evals",
+    "smoke:live": "tsx scripts/live-smoke.ts",
+    "check": "npm run lint && npm run typecheck && npm test",
+    "mcp:login": "tsx scripts/mcp-client.ts login",
+    "mcp:status": "tsx scripts/mcp-client.ts status",
+    "mcp:logout": "tsx scripts/mcp-client.ts logout",
+    "mcp:list-tools": "tsx scripts/mcp-client.ts list-tools",
+    "mcp:call": "tsx scripts/mcp-client.ts call",
+    "generate:schemas": "openapi-zod-client specs/vrchat-openapi.yaml -o src/generated/vrchat-schemas.ts -t scripts/templates/openapi-schemas.hbs --export-schemas -p .prettierrc.json && tsx scripts/postprocess-schemas.ts src/generated/vrchat-schemas.ts",
+    "generate:test-schemas": "openapi-zod-client test/fixtures/spec.yaml -o test/generated/mock-schemas.ts -t scripts/templates/openapi-schemas.hbs --export-schemas -p .prettierrc.json && tsx scripts/postprocess-schemas.ts test/generated/mock-schemas.ts",
+    "generate:tools-docs": "tsx scripts/generate-tools-docs.ts",
+    "mcpo": "uvx mcpo --port 8000 --api-key \"top-secret\" -- npx tsx src/index.ts",
+    "start": "node dist/bin/cli.js",
+    "metrics:scc": "tsx scripts/metrics/scc.ts",
+    "metrics:lizard": "tsx scripts/metrics/lizard.ts",
+    "metrics": "npm run metrics:scc && npm run metrics:lizard"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "keywords": [
+    "vrchat",
+    "mcp",
+    "modelcontextprotocol",
+    "model-context-protocol",
+    "claude",
+    "opencode",
+    "vrchat-api",
+    "vrcx"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BASIC-BIT/vrchat-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/BASIC-BIT/vrchat-mcp/issues"
+  },
+  "homepage": "https://github.com/BASIC-BIT/vrchat-mcp#readme",
+  "license": "MIT",
+  "devDependencies": {
+    "@apidevtools/json-schema-ref-parser": "^15.3.5",
+    "@eslint/js": "^10.0.1",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^25.0.3",
+    "@typescript-eslint/eslint-plugin": "^8.50.0",
+    "@typescript-eslint/parser": "^8.50.0",
+    "@vitest/coverage-v8": "^4.0.16",
+    "ajv-formats": "^3.0.1",
+    "eslint": "^10.3.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-sonarjs": "^4.0.3",
+    "globals": "^17.6.0",
+    "mock-json-schema": "^1.1.2",
+    "openapi-backend": "^5.15.0",
+    "openapi-zod-client": "^1.18.3",
+    "prettier": "^3.7.4",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.0.16"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "better-sqlite3": "^12.6.2",
+    "keytar": "^7.9.0",
+    "tough-cookie": "^6.0.0",
+    "undici": "^8.2.0",
+    "yaml": "^2.8.4",
+    "zod": "^4.2.1"
+  }
+}