DollhouseMCP

Instructions

Implementation Reference

• src/server/tools/PortfolioTools.ts:76-102 (registration)

  MCP tool registration for 'init_portfolio' including full input schema, description, and handler function that delegates to server.initPortfolio method.
  tool: { name: "init_portfolio", description: "Initialize a new GitHub portfolio repository for storing your DollhouseMCP elements. Creates the repository structure with proper directories and README.", inputSchema: { type: "object", properties: { repository_name: { type: "string", description: "Name for the portfolio repository. Defaults to 'dollhouse-portfolio' if not specified.", }, private: { type: "boolean", description: "Whether to create a private repository. Defaults to false (public).", }, description: { type: "string", description: "Repository description. Defaults to 'My DollhouseMCP element portfolio'.", }, }, }, }, handler: (args: InitPortfolioArgs) => server.initPortfolio({ repositoryName: args?.repository_name, private: args?.private, description: args?.description }) },
• src/server/tools/PortfolioTools.ts:13-17 (schema)

  TypeScript interface defining the input arguments for the init_portfolio tool.
  interface InitPortfolioArgs { repository_name?: string; private?: boolean; description?: string; }
• src/portfolio/PortfolioRepoManager.ts:215-292 (handler)

  Core implementation logic for creating the GitHub portfolio repository. Handles consent validation, existence checks, API calls to GitHub, error handling with specific codes, and initializes repository structure with README.md and element directories. This is the primary execution logic called by init_portfolio.
  async createPortfolio(username: string, consent: boolean | undefined): Promise<string> { // MEDIUM FIX: Normalize username to prevent Unicode attacks (DMCP-SEC-004) const normalizedUsername = UnicodeValidator.normalize(username).normalizedContent; // CRITICAL: Validate consent is explicitly provided if (consent === undefined) { throw new Error('Consent is required for portfolio creation'); } if (!consent) { logger.info(`User declined portfolio creation for ${username}`); throw new Error('User declined portfolio creation'); } // Log consent for audit trail logger.info(`User consented to portfolio creation for ${normalizedUsername}`); // LOW FIX: Add security audit logging (DMCP-SEC-006) SecurityMonitor.logSecurityEvent({ type: 'PORTFOLIO_INITIALIZATION', severity: 'LOW', source: 'PortfolioRepoManager.createPortfolio', details: `User ${normalizedUsername} consented to portfolio creation`, metadata: { username: normalizedUsername } }); // Check if portfolio already exists const existingRepo = await this.githubRequest( `/repos/${normalizedUsername}/${this.repositoryName}` ); if (existingRepo && existingRepo.html_url) { logger.info(`Portfolio already exists for ${normalizedUsername}`); return existingRepo.html_url; } // Create the portfolio repository try { const repo = await this.githubRequest( '/user/repos', 'POST', { name: this.repositoryName, description: PortfolioRepoManager.DEFAULT_DESCRIPTION, private: false, auto_init: true } ); // Initialize portfolio structure await this.generatePortfolioStructure(normalizedUsername); return repo.html_url; } catch (error: any) { // Handle race condition: if repository was created between our check and creation attempt if (error.message && error.message.includes('name already exists')) { logger.info(`Portfolio repository already exists for ${normalizedUsername} (race condition handled)`); // Re-check for the existing repository and return its URL try { const existingRepo = await this.githubRequest( `/repos/${normalizedUsername}/${this.repositoryName}` ); if (existingRepo && existingRepo.html_url) { return existingRepo.html_url; } } catch (recheckError) { ErrorHandler.logError('PortfolioRepoManager.recheckExistingRepo', recheckError, { username: normalizedUsername }); } // If we can't get the existing repo, throw a more specific error throw new Error(`Portfolio repository already exists for ${normalizedUsername}. Please check your GitHub account.`); } ErrorHandler.logError('PortfolioRepoManager.createPortfolioRepo', error, { username: normalizedUsername }); throw ErrorHandler.wrapError(error, `Failed to create portfolio repository for ${normalizedUsername}. ${error.message || 'Unknown error occurred.'}`, ErrorCategory.NETWORK_ERROR); } }
• src/server/types.ts:68-68 (schema)

  IToolHandler interface defining the server.initPortfolio method signature used by the tool handler.
  initPortfolio(options: {repositoryName?: string; private?: boolean; description?: string}): Promise<any>;
• src/portfolio/PortfolioRepoManager.ts:94-189 (helper)

  Helper method for making authenticated GitHub API requests, used by createPortfolio for repo creation and structure initialization.
  public async githubRequest( path: string, method: string = 'GET', body?: any ): Promise<any> { const token = await this.getTokenAndValidate(); const url = `${PortfolioRepoManager.GITHUB_API_BASE}${path}`; const options: RequestInit = { method, headers: { 'Authorization': `Bearer ${token}`, 'Accept': 'application/vnd.github.v3+json', 'Content-Type': 'application/json', 'User-Agent': 'DollhouseMCP/1.0' } }; if (body) { options.body = JSON.stringify(body); } const response = await fetch(url, options); // Check if response exists before accessing properties if (!response) { const error: any = new Error('No response received from GitHub API'); error.status = 0; error.code = 'PORTFOLIO_SYNC_005'; throw error; } if (response.status === 404) { return null; // Not found is often expected } // Check if response is ok BEFORE trying to parse JSON if (!response.ok) { // Try to parse error details if response is JSON let data: any = {}; // HTTP headers are case-insensitive, check both cases for robustness const contentType = response.headers.get('content-type') || response.headers.get('Content-Type'); if (contentType && contentType.toLowerCase().includes('application/json')) { try { data = await response.json(); } catch (jsonError) { // JSON parsing failed for error response - continue with empty data // This can happen if GitHub returns malformed JSON or content-type mismatch if (process.env.DEBUG) { console.debug('Failed to parse JSON error response:', jsonError); } } } // Create error with status code attached for better classification let errorMessage = data.message || `GitHub API error: ${response.status}`; let errorCode = 'PORTFOLIO_SYNC_005'; // Default switch (response.status) { case 401: errorMessage = 'GitHub authentication failed. Please check your token.'; errorCode = 'PORTFOLIO_SYNC_001'; break; case 403: if (data.message?.includes('rate limit')) { errorMessage = `GitHub API rate limit exceeded: ${data.message}`; errorCode = 'PORTFOLIO_SYNC_006'; } else { errorMessage = `GitHub API access forbidden: ${data.message || 'insufficient permissions'}`; errorCode = 'PORTFOLIO_SYNC_001'; // Treat as auth issue } break; case 422: // Validation failed - often means repository already exists errorMessage = `Repository validation failed: ${data.message || 'name already exists on this account'}`; errorCode = 'PORTFOLIO_SYNC_003'; break; case 500: errorMessage = 'GitHub API server error. Please try again later.'; errorCode = 'PORTFOLIO_SYNC_005'; break; default: errorMessage = `GitHub API error (${response.status}): ${data.message || 'Unknown error'}`; } const error: any = new Error(errorMessage); error.status = response.status; error.code = errorCode; throw error; } // Parse JSON only after we know response is ok const data = await response.json(); return data; }