Overleaf MCP Server

Instructions

Implementation Reference

• src/git-manager.ts:23-53 (handler)

  Core handler function that performs the git clone of an Overleaf project, handling authentication and directory setup.
  async cloneProject(projectId: string, localPath: string, email?: string, token?: string) { // Ensure parent directory exists await fs.ensureDir(path.dirname(localPath)); let gitUrl = ''; // Try to get credentials if not provided if (!email || !token) { const creds = await this.authManager.getCredentials(); if (creds) { gitUrl = this.getGitUrl(projectId, creds.email, creds.token); } else { // Fallback to no-auth URL (will likely fail or prompt if interactive, but MCP is non-interactive) // Ideally we should error here if no auth is available for a private repo, // but let's try to construct it. gitUrl = this.getGitUrl(projectId); } } else { gitUrl = this.getGitUrl(projectId, email, token); } const git: SimpleGit = simpleGit(); try { await git.clone(gitUrl, localPath); console.error(`Successfully cloned project ${projectId} to ${localPath}`); return { success: true, message: `Cloned to ${localPath}` }; } catch (error: any) { console.error('Clone failed:', error); throw new Error(`Failed to clone project: ${error.message}`); } }
• src/index.ts:35-56 (schema)

  Input schema defining parameters for the clone_project tool: projectId (required), localPath (required), email (optional), token (optional).
  inputSchema: { type: 'object', properties: { projectId: { type: 'string', description: 'The ID of the Overleaf project', }, localPath: { type: 'string', description: 'The local path to clone the project to (absolute path)', }, email: { type: 'string', description: 'Overleaf account email (optional if configured globally)', }, token: { type: 'string', description: 'Overleaf git token (optional if configured globally)', }, }, required: ['projectId', 'localPath'], },
• src/index.ts:32-57 (registration)

  Registration of the clone_project tool in the list of tools returned by ListToolsRequestHandler, including name, description, and schema.
  { name: 'clone_project', description: 'Clone an Overleaf project to a local directory', inputSchema: { type: 'object', properties: { projectId: { type: 'string', description: 'The ID of the Overleaf project', }, localPath: { type: 'string', description: 'The local path to clone the project to (absolute path)', }, email: { type: 'string', description: 'Overleaf account email (optional if configured globally)', }, token: { type: 'string', description: 'Overleaf git token (optional if configured globally)', }, }, required: ['projectId', 'localPath'], }, },
• src/index.ts:129-135 (handler)

  Dispatcher handler in CallToolRequestHandler that extracts arguments and calls gitManager.cloneProject.
  case 'clone_project': { const { projectId, localPath, email, token } = request.params.arguments as any; const result = await gitManager.cloneProject(projectId, localPath, email, token); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], }; }
• src/git-manager.ts:13-21 (helper)

  Helper function to construct the git clone URL with embedded credentials if provided.
  private getGitUrl(projectId: string, email?: string, token?: string): string { // If credentials are provided directly, use them if (email && token) { // Encode email to handle special characters like '@' const encodedEmail = encodeURIComponent(email); return `https://${encodedEmail}:${token}@git.overleaf.com/${projectId}`; } return `https://git.overleaf.com/${projectId}`; }