@basicbit/vrchat-mcp 0.1.7 → 0.1.9

package/dist/src/transports/http.js

@@ -0,0 +1,343 @@
+import { createHash, randomUUID, timingSafeEqual } from 'node:crypto';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { localhostHostValidation } from '@modelcontextprotocol/sdk/server/middleware/hostHeaderValidation.js';
+import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
+import express from 'express';
+import { logger } from '../infra/logger.js';
+const HTTP_HOST = '127.0.0.1';
+const MIN_BEARER_TOKEN_LENGTH = 32;
+const DEFAULT_SESSION_IDLE_TIMEOUT_MS = 30 * 60_000;
+function jsonRpcError(res, status, message) {
+    res.status(status).json({
+        jsonrpc: '2.0',
+        error: { code: -32000, message },
+        id: null,
+    });
+}
+function validateOptions(options) {
+    if (!Number.isInteger(options.port) || options.port < 0 || options.port > 65535) {
+        throw new Error('HTTP port must be an integer from 0 to 65535.');
+    }
+    if (options.path.length < 2 ||
+        options.path.length > 128 ||
+        !/^\/[A-Za-z0-9._~/-]*$/.test(options.path) ||
+        /^\/healthz\/?$/i.test(options.path)) {
+        throw new Error('HTTP path must be a non-reserved URL path using safe characters.');
+    }
+    if (options.bearerToken.length < MIN_BEARER_TOKEN_LENGTH) {
+        throw new Error(`VRCHAT_MCP_HTTP_BEARER_TOKEN must be at least ${MIN_BEARER_TOKEN_LENGTH} characters.`);
+    }
+    if (!Number.isInteger(options.maxSessions) || options.maxSessions < 1) {
+        throw new Error('HTTP maxSessions must be a positive integer.');
+    }
+    if (!Number.isInteger(options.rateLimitPerMinute) || options.rateLimitPerMinute < 1) {
+        throw new Error('HTTP rateLimitPerMinute must be a positive integer.');
+    }
+    if (options.sessionIdleTimeoutMs !== undefined &&
+        (!Number.isInteger(options.sessionIdleTimeoutMs) || options.sessionIdleTimeoutMs < 1)) {
+        throw new Error('HTTP sessionIdleTimeoutMs must be a positive integer.');
+    }
+}
+function tokenDigest(value) {
+    return createHash('sha256').update(value, 'utf8').digest();
+}
+function bearerTokenMatches(header, expectedDigest) {
+    if (!header?.startsWith('Bearer '))
+        return false;
+    const candidate = header.slice('Bearer '.length);
+    return timingSafeEqual(tokenDigest(candidate), expectedDigest);
+}
+function headerValue(value) {
+    return Array.isArray(value) ? value[0] : value;
+}
+function isRequestTooLarge(error) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    return error.status === 413;
+}
+function createRateLimiter(limit) {
+    const windows = new Map();
+    const windowMs = 60_000;
+    return (req, res, next) => {
+        const now = Date.now();
+        const key = req.ip ?? 'loopback';
+        const current = windows.get(key);
+        if (!current || now - current.startedAt >= windowMs) {
+            windows.set(key, { startedAt: now, count: 1 });
+            next();
+            return;
+        }
+        current.count += 1;
+        if (current.count > limit) {
+            res.setHeader('Retry-After', '60');
+            jsonRpcError(res, 429, 'Too many requests');
+            return;
+        }
+        next();
+    };
+}
+async function listen(app, port) {
+    return await new Promise((resolve, reject) => {
+        const server = app.listen(port, HTTP_HOST);
+        const onError = (error) => {
+            server.off('listening', onListening);
+            reject(error);
+        };
+        const onListening = () => {
+            server.off('error', onError);
+            resolve(server);
+        };
+        server.once('error', onError);
+        server.once('listening', onListening);
+    });
+}
+export async function startHttpTransport(options) {
+    validateOptions(options);
+    const expectedTokenDigest = tokenDigest(options.bearerToken);
+    const sessions = new Map();
+    const app = express();
+    let boundPort = options.port;
+    let closing = false;
+    let pendingInitializations = 0;
+    const sessionIdleTimeoutMs = options.sessionIdleTimeoutMs ?? DEFAULT_SESSION_IDLE_TIMEOUT_MS;
+    app.disable('x-powered-by');
+    app.use(localhostHostValidation());
+    app.use((req, res, next) => {
+        res.setHeader('Cache-Control', 'no-store');
+        res.setHeader('X-Content-Type-Options', 'nosniff');
+        res.setHeader('Referrer-Policy', 'no-referrer');
+        const origin = req.headers.origin;
+        if (!origin) {
+            next();
+            return;
+        }
+        try {
+            const parsed = new URL(origin);
+            const allowedHostname = parsed.hostname === '127.0.0.1' ||
+                parsed.hostname === 'localhost' ||
+                parsed.hostname === '[::1]';
+            const allowedPort = Number(parsed.port || '80') === boundPort;
+            if (parsed.protocol === 'http:' && allowedHostname && allowedPort) {
+                next();
+                return;
+            }
+        }
+        catch {
+            // Rejected below.
+        }
+        jsonRpcError(res, 403, 'Invalid Origin header');
+    });
+    app.get('/healthz', (_req, res) => {
+        res.json({ status: closing ? 'stopping' : 'ok' });
+    });
+    app.use(options.path, createRateLimiter(options.rateLimitPerMinute));
+    app.use(options.path, (req, res, next) => {
+        if (!bearerTokenMatches(req.headers.authorization, expectedTokenDigest)) {
+            res.setHeader('WWW-Authenticate', 'Bearer');
+            jsonRpcError(res, 401, 'Unauthorized');
+            return;
+        }
+        next();
+    });
+    app.use(options.path, express.json({ limit: '256kb', strict: true }));
+    const releaseSession = (sessionId, session) => {
+        if (sessions.get(sessionId) !== session)
+            return;
+        sessions.delete(sessionId);
+        if (session.idleTimer) {
+            clearTimeout(session.idleTimer);
+            session.idleTimer = undefined;
+        }
+        options.releaseServer?.(session.server);
+    };
+    const scheduleSessionExpiry = (sessionId, session) => {
+        if (sessions.get(sessionId) !== session || session.activeResponses > 0)
+            return;
+        if (session.idleTimer)
+            clearTimeout(session.idleTimer);
+        session.idleTimer = setTimeout(() => {
+            if (sessions.get(sessionId) !== session || session.activeResponses > 0)
+                return;
+            releaseSession(sessionId, session);
+            void session.transport.close().catch((error) => {
+                logger.warn('Failed to close an expired MCP HTTP session.', {
+                    message: error instanceof Error ? error.message : String(error),
+                });
+            });
+        }, sessionIdleTimeoutMs);
+        session.idleTimer.unref();
+    };
+    const trackSessionResponse = (sessionId, session, res) => {
+        if (session.idleTimer) {
+            clearTimeout(session.idleTimer);
+            session.idleTimer = undefined;
+        }
+        session.activeResponses += 1;
+        let settled = false;
+        const settle = () => {
+            if (settled)
+                return;
+            settled = true;
+            session.activeResponses = Math.max(0, session.activeResponses - 1);
+            scheduleSessionExpiry(sessionId, session);
+        };
+        res.once('finish', settle);
+        res.once('close', settle);
+    };
+    const handleSessionRequest = async (sessionId, session, req, res, parsedBody) => {
+        trackSessionResponse(sessionId, session, res);
+        try {
+            await session.transport.handleRequest(req, res, parsedBody);
+        }
+        catch (error) {
+            logger.warn('Failed to handle an established MCP HTTP session.', {
+                message: error instanceof Error ? error.message : String(error),
+            });
+            if (!res.headersSent)
+                jsonRpcError(res, 500, 'Internal server error');
+        }
+    };
+    const initializeSession = async (req, res) => {
+        let server;
+        let session;
+        let initializedSessionId;
+        pendingInitializations += 1;
+        try {
+            server = await options.serverFactory();
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => randomUUID(),
+                onsessioninitialized: (sessionId) => {
+                    initializedSessionId = sessionId;
+                    if (session) {
+                        sessions.set(sessionId, session);
+                        scheduleSessionExpiry(sessionId, session);
+                    }
+                },
+                onsessionclosed: (sessionId) => {
+                    if (session)
+                        releaseSession(sessionId, session);
+                },
+            });
+            session = { server, transport, activeResponses: 0 };
+            transport.onclose = () => {
+                const sessionId = transport.sessionId ?? initializedSessionId;
+                if (sessionId && session)
+                    releaseSession(sessionId, session);
+            };
+            await server.connect(transport);
+            await transport.handleRequest(req, res, req.body);
+            const sessionId = transport.sessionId ?? initializedSessionId;
+            if (sessionId)
+                scheduleSessionExpiry(sessionId, session);
+        }
+        catch (error) {
+            if (session) {
+                const sessionId = session.transport.sessionId ?? initializedSessionId;
+                if (sessionId)
+                    releaseSession(sessionId, session);
+                else
+                    options.releaseServer?.(session.server);
+                await session.transport.close().catch(() => undefined);
+            }
+            else if (server) {
+                options.releaseServer?.(server);
+            }
+            logger.error('Failed to handle MCP HTTP initialization.', {
+                message: error instanceof Error ? error.message : String(error),
+            });
+            if (!res.headersSent)
+                jsonRpcError(res, 500, 'Internal server error');
+        }
+        finally {
+            pendingInitializations -= 1;
+        }
+    };
+    app.post(options.path, async (req, res) => {
+        if (closing) {
+            jsonRpcError(res, 503, 'Server is shutting down');
+            return;
+        }
+        const requestedSessionId = headerValue(req.headers['mcp-session-id']);
+        const existing = requestedSessionId ? sessions.get(requestedSessionId) : undefined;
+        if (requestedSessionId && existing) {
+            await handleSessionRequest(requestedSessionId, existing, req, res, req.body);
+            return;
+        }
+        if (requestedSessionId) {
+            jsonRpcError(res, 404, 'MCP session not found');
+            return;
+        }
+        if (!isInitializeRequest(req.body)) {
+            jsonRpcError(res, 400, 'Invalid or missing MCP session');
+            return;
+        }
+        if (sessions.size + pendingInitializations >= options.maxSessions) {
+            jsonRpcError(res, 429, 'Maximum MCP session count reached');
+            return;
+        }
+        await initializeSession(req, res);
+    });
+    const handleEstablishedSession = async (req, res) => {
+        const sessionId = headerValue(req.headers['mcp-session-id']);
+        const session = sessionId ? sessions.get(sessionId) : undefined;
+        if (!sessionId || !session) {
+            jsonRpcError(res, sessionId ? 404 : 400, sessionId ? 'MCP session not found' : 'Missing MCP session');
+            return;
+        }
+        await handleSessionRequest(sessionId, session, req, res);
+    };
+    app.get(options.path, handleEstablishedSession);
+    app.delete(options.path, handleEstablishedSession);
+    const jsonErrorHandler = (error, _req, res, _next) => {
+        void _next;
+        const requestError = error;
+        logger.warn('Rejected an invalid MCP HTTP request body.', {
+            message: requestError instanceof Error ? requestError.message : String(requestError),
+        });
+        const status = isRequestTooLarge(requestError) ? 413 : 400;
+        if (!res.headersSent) {
+            jsonRpcError(res, status, status === 413 ? 'Request body too large' : 'Invalid JSON request body');
+        }
+    };
+    app.use(jsonErrorHandler);
+    const httpServer = await listen(app, options.port);
+    const address = httpServer.address();
+    if (!address || typeof address === 'string') {
+        await new Promise((resolve) => httpServer.close(() => resolve()));
+        throw new Error('Unable to determine HTTP listening port.');
+    }
+    boundPort = address.port;
+    httpServer.headersTimeout = 10_000;
+    httpServer.requestTimeout = 30_000;
+    httpServer.keepAliveTimeout = 5_000;
+    const close = async () => {
+        if (closing)
+            return;
+        closing = true;
+        for (const [sessionId, session] of [...sessions]) {
+            releaseSession(sessionId, session);
+            await session.transport.close().catch((error) => {
+                logger.warn('Failed to close an MCP HTTP session.', {
+                    message: error instanceof Error ? error.message : String(error),
+                });
+            });
+        }
+        await new Promise((resolve, reject) => {
+            httpServer.close((error) => {
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            });
+        });
+    };
+    return {
+        host: HTTP_HOST,
+        port: boundPort,
+        path: options.path,
+        url: `http://${HTTP_HOST}:${boundPort}${options.path}`,
+        sessionCount: () => sessions.size,
+        close,
+    };
+}
+//# sourceMappingURL=http.js.map

package/dist/src/transports/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../../src/transports/http.ts"],"names":[],"mappings":"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"}

package/docs/architecture.md

@@ -4,7 +4,10 @@ This server is organized by responsibility so each file stays small and focused.
 
 ## Entry point
 
-- `src/index.ts` boots the MCP server, initializes auth, registers tools/resources, wires pipeline handlers, and connects the stdio transport.
+- `src/index.ts` selects stdio (default) or loopback Streamable HTTP and owns process shutdown.
+- `src/server.ts` initializes the process-wide VRChat runtime and creates transport-independent `McpServer` instances.
+- `src/transports/http.ts` owns bearer authentication, Origin/Host protection, rate limits, stateful HTTP sessions, SSE routing, and graceful session cleanup.
+- STDIO uses one `McpServer`. HTTP creates one `McpServer` per client session while sharing process-wide VRChat auth, cache, and pipeline state.
 
 ## Core API plumbing (`src/core/`)
 
@@ -34,6 +37,7 @@ This server is organized by responsibility so each file stays small and focused.
 ## Resources (`src/resources/`)
 
 - MCP resources backed by pipeline/cache (e.g., friend change delta feed).
+- Subscription state is tracked per `McpServer`; pipeline updates fan out only to subscribed live sessions.
 
 ## Infra + utils
 

package/docs/curated-tools.md

@@ -104,6 +104,24 @@ Groups and social writes:
 - `vrchat_friend_request`
 - `vrchat_boop`
 
+Group posts (write):
+
+- `vrchat_group_post_create`
+- `vrchat_group_post_update`
+- `vrchat_group_post_delete`
+
+Neither create nor update notifies group members unless `sendNotification` is explicitly set, because a single post can ping the whole group.
+
+All three accept `groupId` or `shortCode`, and the `groups.allowlist` guard always runs against the resolved ID so a short code cannot route around it.
+
+VRChat replaces the entire post on edit, and its API has no single-post read. `vrchat_group_post_update` therefore always looks the post up first, scanning the most recent 300 posts fresh from the API rather than from the cached list, and fills in whatever fields the caller omitted. Omitting `roleIds` keeps the current role restrictions; pass `roleIds: []` to clear them. Omitting `imageId` keeps the current image; pass `imageId: null` to remove it. An update whose supplied values all match the post is rejected, since re-sending identical content only bumps the timestamp and can re-notify members.
+
+If the post is older than that lookup window, supplying `title`, `text`, and `visibility` together still lets the edit land as an outright replace. That path cannot recover `roleIds` or `imageId`, so it clears them and reports `mergedFromExisting: false`. Skipping the lookup is deliberately not offered as an optimization: a replace that silently drops `roleIds` would widen a role-restricted post to the whole group.
+
+Creates and updates report success even when the write lands but VRChat's response cannot be parsed, returning `post: null`. Neither call is idempotent, so reporting a failure there would invite a retry that posts twice and, with `sendNotification`, notifies twice.
+
+All three tools invalidate cached group reads after the write, including when the response fails to parse. One gap worth knowing: a `vrchat_group_posts_recent` load already in flight when the write happens can still store its pre-write result afterwards, because `invalidateByTag` cannot see a request whose entry has not been written yet. Reads can then serve the old list for the remainder of the group cache TTL. This affects every cached area equally, not just posts, and fixing it needs generation-checking in `CacheManager` rather than anything post-specific.
+
 Invites (write, low-risk):
 
 - `vrchat_invite_self`

package/docs/privacy.md

@@ -1,6 +1,6 @@
 # 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.
+VRChat MCP runs locally on your machine as a stdio MCP server by default. It also provides an opt-in Streamable HTTP listener that is hard-bound to `127.0.0.1` and protected by a required bearer token. The project does not operate a hosted service for your VRChat session.
 
 ## Data Access
 
@@ -20,4 +20,4 @@ Curated write tools, generated write tools for API gaps, generated read tools, a
 
 ## 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.
+The local HTTP bearer token protects access to the MCP listener; it is not a VRChat credential and does not make the server suitable for public hosting. Do not place the bearer token in URLs or logs, and 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/tools-guide.md

@@ -23,6 +23,7 @@ Tool names, tool descriptions, argument names, argument descriptions, and schema
 ## Swagger UI (mcpo)
 
 - Run `npm run mcpo` to spin up an OpenAPI proxy with Swagger UI.
+- This development proxy is separate from the native MCP Streamable HTTP transport (`--transport http`).
 - `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`.