ChatGPT Local Agent MCP

https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp
Admin
ChatGPT Local Agent MCP is a local MCP server that gives ChatGPT controlled hands on your Windows...
Tokens:37,212
Snippets:547
Trust Score:6.4
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Development Lifecycle Commands

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/README2.md

Standard commands for installing dependencies, type checking, testing, building, and starting the application.

```powershell
npm ci
npm run type-check
npm test
npm run build
npm start
```

--------------------------------

### Launch the installer

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/README2.md

Execute the batch file from the source folder to initiate the installation process.

```powershell
.\install-chatgpt-local-agent-mcp.bat
```

--------------------------------

### Install Dependencies

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/README.md

Installs all necessary project dependencies.

```powershell
npm ci
```

--------------------------------

### Run Installer Script

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/INSTALL.md

Execute the main installation script from the extracted source folder. This script handles copying the application to the install folder and building it.

```powershell
.\install-chatgpt-local-agent-mcp.bat
```

--------------------------------

### Local MCP Server Setup

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/README.md

This text block outlines the local setup for the MCP server on a Windows PC, accessible via http://127.0.0.1:8789. It details the initial steps before connecting to ChatGPT.

```text
Windows PC
  -> http://127.0.0.1:8789
  -> local MCP server
  -> local dashboard / health checks
```

--------------------------------

### Run Server

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/README.md

Starts the built server for production use.

```powershell
npm start
```

--------------------------------

### Install Dependencies and Build Application

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/INSTALL.md

Install project dependencies using npm ci and build the application. This step is crucial for preparing the application for execution and can be re-run for updates or repairs.

```powershell
npm ci
npm run build
```

--------------------------------

### Install Playwright Browser Binaries

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/INSTALL.md

Install the necessary browser binaries for Playwright to enable browser automation. Ensure the server runs under the correct Windows account.

```powershell
npx playwright install
```

--------------------------------

### start_process

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Start a long-running process.

```APIDOC
## start_process

### Description
Start a long-running process.

### Inputs
- **command** (string) - Required
- **args** (string[]) - Optional
- **cwd** (string) - Optional
- **env** (Record<string, string>) - Optional

### Output
- **processId** (number)
- **command** (string)
- **started** (boolean)
```

--------------------------------

### Normal Install Root

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/README.md

Specifies the default directory where the chatgpt-local-agent-mcp is installed on Windows systems.

```text
%LOCALAPPDATA%\chatgpt-local-agent-mcp
```

--------------------------------

### Full Remote ChatGPT Connector Setup

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/README.md

This text block illustrates the architecture for a full remote ChatGPT connector setup. It shows the flow from ChatGPT to the local MCP server on a Windows PC, involving an HTTPS tunnel.

```text
ChatGPT
  -> your HTTPS hostname
  -> Cloudflare Tunnel or another HTTPS tunnel
  -> http://127.0.0.1:8789
  -> local MCP server
  -> your Windows PC
```

--------------------------------

### GET /authorize

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/auth.md

Initiates the authorization flow with optional PKCE support.

```APIDOC
## GET /authorize

### Description
Initiates the OAuth authorization process. Supports PKCE for public clients.

### Parameters
#### Query Parameters
- **code_challenge** (string) - Optional - Base64url-encoded SHA-256 hash of the verifier.
- **code_challenge_method** (string) - Optional - Must be 'S256'.
```

--------------------------------

### Initial remote request example

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/README2.md

A recommended read-only prompt to test the remote connection safely.

```text
Inspect only the configured test workspace. Show its top-level tree and Git status.
Do not modify files, start processes, open a browser, or use desktop controls.
```

--------------------------------

### Default Local Configuration

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/README.md

These are the full-power local defaults. Create a private .env file from .env.example and use these values for a local setup.

```env
GPT_FS_MCP_HOST=127.0.0.1
GPT_FS_MCP_PORT=8789
GPT_FS_MCP_MAX_POLICY_MODE=destructive
GPT_FS_MCP_ENFORCE_WORKSPACE_PROFILES=true
GPT_FS_MCP_SHELL_POLICY=full
GPT_FS_MCP_PROCESS_POLICY=full
AUTH_REQUIRED=true
NODE_ENV=development
```

--------------------------------

### Default runtime folder path

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/README2.md

The default location where the installer copies public application files.

```text
%LOCALAPPDATA%\chatgpt-local-agent-mcp
```

--------------------------------

### Configure Single and Multiple Workspaces

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/configuration.md

Examples of defining one or more workspace profiles to restrict filesystem access.

```json
[{
  "name": "chatgpt-agent",
  "label": "ChatGPT Local Agent Project",
  "rootPath": "C:\\projects\\chatgpt-local-agent-mcp",
  "allowedPolicyModes": ["observe", "diagnose", "edit", "operate"],
  "backupPolicy": "snapshot",
  "secretDenyGlobs": ["**/.env*", "**/.git/config", "**/node_modules"]
}]
```

```json
[
  {
    "name": "projects",
    "rootPath": "C:\\projects",
    "allowedPolicyModes": ["observe", "diagnose", "edit", "operate", "destructive"]
  },
  {
    "name": "documents",
    "rootPath": "C:\\Users\\me\\Documents",
    "allowedPolicyModes": ["observe", "diagnose"]
  }
]
```

--------------------------------

### Start Process Schema

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Defines the input and output structure for initiating a long-running process.

```typescript
{
  command: string;
  args?: string[];
  cwd?: string;
  env?: Record<string, string>;
}
```

```typescript
{
  processId: number;
  command: string;
  started: boolean;
}
```

--------------------------------

### Initiate OAuth Authorization Request

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/endpoints.md

Example request to the /authorize endpoint to begin the OAuth flow.

```http
GET /authorize?client_id=my-client&redirect_uri=https://example.com/callback&response_type=code&scope=mcp:read+mcp:write&state=abc123&code_challenge=E9Mrozoa2owUzRrSnm3wzYItLodyqiiHXEnMgOjSDdA&code_challenge_method=S256
```

--------------------------------

### Monitor Operations via Journal

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/README.md

Command-line examples for tailing and filtering the JSONL journal file.

```bash
# Tail journal
tail -f data/journal.jsonl | jq .

# Find errors
cat data/journal.jsonl | jq 'select(.outcome == "error")'

# Find specific tool
cat data/journal.jsonl | jq 'select(.tool == "write_file")'
```

--------------------------------

### browser_console

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Get console logs and errors.

```APIDOC
## browser_console

### Description
Get console logs and errors.

### Inputs
- **sessionId** (string) - Required
- **clear** (boolean) - Optional

### Output
- **sessionId** (string)
- **logs** (Array)
```

--------------------------------

### workspace_info

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Get information about available workspaces and their constraints.

```APIDOC
## workspace_info

### Description
Get information about available workspaces and their constraints.

### Inputs
None

### Output
- **workspaces** (Array) - List of available workspace profiles and their allowed operations.
```

--------------------------------

### MCP Error Response Example

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/endpoints.md

Example of an error response returned by the MCP endpoint.

```json
{
  "error": "policy_denied",
  "max_policy_mode": "operate",
  "policy_mode": "destructive",
  "tool": "delete"
}
```

--------------------------------

### Run in Watch Mode

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/README.md

Starts the server in development mode with automatic reloading on file changes.

```powershell
npm run dev
```

--------------------------------

### Initial Test Configuration

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/README.md

This text block lists the components that are NOT required for the initial local-only smoke test. It helps in understanding the minimal setup for verifying the local server.

```text
No Cloudflare.
No public URL.
No GitHub OAuth App.
No ChatGPT connector OAuth.
No remote connector yet.
```

--------------------------------

### browser_snapshot

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Get the DOM snapshot (HTML).

```APIDOC
## browser_snapshot

### Description
Get the DOM snapshot (HTML).

### Inputs
- **sessionId** (string) - Required

### Output
- **sessionId** (string)
- **html** (string)
- **title** (string)
- **url** (string)
```

--------------------------------

### GET /authorize

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/endpoints.md

Initiates the OAuth authorization flow by redirecting the user to GitHub.

```APIDOC
## GET /authorize

### Description
Begin OAuth authorization flow. Redirects user to GitHub.

### Method
GET

### Endpoint
/authorize

### Parameters
#### Query Parameters
- **client_id** (string) - Required - OAuth client ID
- **redirect_uri** (string) - Required - Callback URI (must match config)
- **response_type** (string) - Required - Must be code
- **scope** (space-separated string) - Required - Requested scopes (e.g., mcp:read mcp:write mcp:browser)
- **state** (string) - Required - Opaque state string for CSRF protection
- **code_challenge** (string) - Optional - PKCE challenge (if AUTH_REQUIRE_PKCE=true, required)
- **code_challenge_method** (string) - Optional - PKCE method (S256 or plain). If provided, must be S256.
```

--------------------------------

### GET /callback

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/endpoints.md

Handles the OAuth callback from GitHub after the user has logged in.

```APIDOC
## GET /callback

### Description
OAuth callback from GitHub. User is redirected here after GitHub login.

### Method
GET

### Endpoint
/callback

### Parameters
#### Query Parameters
- **code** (string) - Required - GitHub authorization code
- **state** (string) - Required - State string from /authorize
```

--------------------------------

### Set Safer Workspace Policies

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/INSTALL.md

Configure file system and process policies to 'workspace_guarded' for a safer initial setup. Use full policies only when explicit control is desired.

```env
GPT_FS_MCP_SHELL_POLICY=workspace_guarded
GPT_FS_MCP_PROCESS_POLICY=workspace_guarded
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/README.md

Environment configurations for local development, remote Cloudflare tunnel setups, and restrictive policy modes.

```env
AUTH_REQUIRED=false
NODE_ENV=development
PUBLIC_BASE_URL=http://127.0.0.1:8789
CLOUDFLARE_TUNNEL_ENABLED=false
GPT_FS_MCP_HOST=127.0.0.1
```

```env
AUTH_REQUIRED=true
PUBLIC_BASE_URL=https://mcp.your-domain.com
CLOUDFLARE_TUNNEL_ENABLED=true
CLOUDFLARED_CONFIG=C:\Users\you\.cloudflared\config.yml
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
OAUTH_CLIENT_ID=...
OAUTH_CLIENT_SECRET=...
OAUTH_REDIRECT_URIS=https://mcp.your-domain.com/oauth/callback
ALLOWED_GITHUB_LOGINS=you
```

```env
GPT_FS_MCP_MAX_POLICY_MODE=operate
GPT_FS_MCP_SHELL_POLICY=workspace_guarded
GPT_FS_MCP_PROCESS_POLICY=workspace_guarded
GPT_FS_MCP_WORKSPACE_PROFILES_JSON=[{
  "name": "work",
  "rootPath": "C:\\projects",
  "allowedPolicyModes": ["observe", "diagnose", "edit", "operate"],
  "backupPolicy": "snapshot"
}]
```

--------------------------------

### Safer Workspace Profile Configuration

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/README2.md

Example of a restricted workspace profile configuration using JSON.

```env
GPT_FS_MCP_MAX_POLICY_MODE=edit
GPT_FS_MCP_SHELL_POLICY=workspace_guarded
GPT_FS_MCP_PROCESS_POLICY=workspace_guarded
GPT_FS_MCP_WORKSPACE_PROFILES_JSON=[{"name":"test-repo","label":"Disposable test repo","rootPath":"C:\\Users\\you\\Documents\\GitHub\\test-repo","allowedPolicyModes":["observe","diagnose","edit"],"backupPolicy":"snapshot","secretDenyGlobs":["**/.env","**/*secret*","**/*token*","**/*credential*"]}]
```

--------------------------------

### Exchange Authorization Code for Token

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/endpoints.md

Example POST request to exchange an authorization code for an access token.

```bash
POST /token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=abc123&
client_id=my-client&
client_secret=secret&
code_verifier=verifier123
```

--------------------------------

### Get DOM Snapshot

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Retrieves the current HTML content of the page.

```typescript
{
  sessionId: string;
}
```

```typescript
{
  sessionId: string;
  html: string;
  title: string;
  url: string;
}
```

--------------------------------

### Secret Redaction JSON Example

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/auth.md

Demonstrates the expected output format for redacted sensitive keys in logs.

```json
{
  "token": "***REDACTED***",
  "client_secret": "***REDACTED***"
}
```

--------------------------------

### GET /.well-known/oauth-authorization-server

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/endpoints.md

Retrieves OAuth authorization server metadata per RFC 8414.

```APIDOC
## GET /.well-known/oauth-authorization-server

### Description
OAuth authorization server metadata (per RFC 8414).

### Method
GET

### Endpoint
/.well-known/oauth-authorization-server

### Response
#### Success Response (200)
- **JSON** (object) - Metadata containing issuer, authorization_endpoint, token_endpoint, scopes_supported, response_types_supported, grant_types_supported, token_endpoint_auth_methods_supported, and code_challenge_methods_supported.
```

--------------------------------

### Configure Remote Deployment with Cloudflare

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/configuration.md

Configures a secure remote setup using Cloudflare Tunnel, GitHub OAuth, and restricted access.

```env
AUTH_REQUIRED=true
PUBLIC_BASE_URL=https://mcp.example.com
CLOUDFLARE_TUNNEL_ENABLED=true
CLOUDFLARED_CONFIG=C:\Users\you\.cloudflared\config.yml
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
OAUTH_CLIENT_ID=...
OAUTH_CLIENT_SECRET=...
OAUTH_REDIRECT_URIS=https://mcp.example.com/oauth/callback
ALLOWED_GITHUB_LOGINS=you
```

--------------------------------

### Build Project

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/README.md

Compiles the project for production deployment.

```powershell
npm run build
```

--------------------------------

### browser_network

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Get network requests.

```APIDOC
## browser_network

### Description
Get network requests.

### Inputs
- **sessionId** (string) - Required
- **clear** (boolean) - Optional

### Output
- **sessionId** (string)
- **requests** (Array)
```

--------------------------------

### Configure Local Development Environment

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/configuration.md

Sets up a local-only development instance without authentication and with a local host binding.

```env
AUTH_REQUIRED=false
PUBLIC_BASE_URL=http://127.0.0.1:8789
CLOUDFLARE_TUNNEL_ENABLED=false
NODE_ENV=development
GPT_FS_MCP_HOST=127.0.0.1
GPT_FS_MCP_PORT=8789
```

--------------------------------

### git_diff

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Get git diff (changes).

```APIDOC
## git_diff

### Description
Get git diff (changes).

### Inputs
- **cwd** (string) - Required
- **cached** (boolean) - Optional
- **maxBytes** (number) - Optional

### Output
- **cwd** (string)
- **diff** (string)
- **truncated** (boolean)
```

--------------------------------

### git_status

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Get git repository status.

```APIDOC
## git_status

### Description
Get git repository status.

### Inputs
- **cwd** (string) - Required - Current working directory

### Output
- **cwd** (string)
- **branch** (string)
- **status** (string)
- **untracked** (string[])
- **modified** (string[])
- **staged** (string[])
```

--------------------------------

### stat_many

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Get metadata for multiple paths.

```APIDOC
## stat_many

### Description
Get metadata for multiple paths (Max 200 paths).

### Inputs
- **paths** (Array) - Required - List of paths.
- **cwd** (string) - Optional - Current working directory.

### Output
- **stats** (Array) - List of metadata for each path.
```

--------------------------------

### stat

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Get file/directory metadata (size, timestamps, type).

```APIDOC
## stat

### Description
Get file/directory metadata (size, timestamps, type).

### Inputs
- **path** (string) - Required - The path to the file or directory.
- **cwd** (string) - Optional - Current working directory.

### Output
- **path** (string) - The path of the file/directory.
- **exists** (boolean) - Whether the path exists.
- **kind** (string) - The type of the path (file, directory, symlink, other, missing).
- **size** (number) - Optional - File size.
- **modifiedAt** (string) - Optional - Last modification timestamp.
- **createdAt** (string) - Optional - Creation timestamp.
- **isSymlink** (boolean) - Optional - Whether it is a symlink.
```

--------------------------------

### Project File Structure

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/README.md

Overview of the source directory layout for the MCP server.

```text
src/
  index.ts                    # Express app & route registration
  config.ts                   # Configuration loading
  runtime.ts                  # ExecutionContext
  mcp.ts                      # MCP server creation
  policy.ts                   # Policy modes
  scopes.ts                   # Scope definitions
  journal.ts                  # Audit logging
  
  auth/
    routes.ts                 # OAuth routes
    store.ts                  # Token/code storage
  
  tools/
    registry.ts               # Tool definitions
    workspace.ts              # workspace_info
    files.ts                  # Filesystem tools
    ops.ts                    # Git, patch, copy, move, delete
    process.ts                # Process tools
    shell.ts                  # Shell tool
    browser.ts                # Browser tools
    screen.ts                 # Screen tools
    desktop.ts                # Desktop tools
  
  dashboard/
    index.ts                  # Web dashboard
```

--------------------------------

### desktop_hotkey

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Simulates a hotkey combination press.

```APIDOC
## desktop_hotkey

### Description
Press a hotkey combination.

### Inputs
- **modifiers** (string[]) - Required - Modifier keys
- **key** (string) - Required - Key to press

### Output
- **pressed** (boolean) - Success status
```

--------------------------------

### Throw AuthStoreCapacityError

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/errors.md

Usage example for throwing an AuthStoreCapacityError when a limit is reached.

```typescript
throw new AuthStoreCapacityError("access tokens");
// Message: "Auth store capacity reached for access tokens"
```

--------------------------------

### Initialize and Run MCP Server

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/README.md

Standard pattern for configuring the Express application, registering routes, and handling MCP requests.

```typescript
// 1. Load configuration from environment
const config = loadConfig();

// 2. Create Express app with middleware
const app = express();
app.use(hostHeaderValidation(config.allowedHosts));

// 3. Register auth routes (GitHub + MCP OAuth)
registerAuthRoutes(app, config, authStore);

// 4. Register dashboard
registerDashboardRoutes(app, { config, journal });

// 5. POST /mcp handler creates MCP server per request
app.post("/mcp", authenticateMcpRequestMiddleware, (req, res) => {
  // Extract execution context from token
  const context = authenticateMcpRequest(req, res);
  
  // Validate tool access (policy, workspace, scope)
  if (rejectToolPreflight(req, res, context)) return;
  
  // Create MCP server and process request
  const server = createMcpServer({ config, context, journal });
  const transport = new StreamableHTTPServerTransport();
  server.connect(transport);
  transport.handleRequest(req, res, req.body);
});

// 6. Start Express server
app.listen(config.port, config.host);
```

--------------------------------

### GET /healthz Response

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/endpoints.md

Standard health check response format.

```json
{
  "authRequired": boolean,
  "name": "chatgpt-local-agent-mcp",
  "ok": true,
  "transport": "streamable-http",
  "version": "0.1.0"
}
```

--------------------------------

### Throw InvalidScopeError

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/errors.md

Usage example for throwing an InvalidScopeError with specific scope strings.

```typescript
throw new InvalidScopeError(["mcp:invalid", "mcp:badscope"]);
// Message: "Invalid scope: mcp:invalid mcp:badscope"
```

--------------------------------

### mkdir

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Creates a new directory at the specified path.

```APIDOC
## mkdir

### Description
Create a directory.

### Inputs
- **path** (string) - Required
- **cwd** (string) - Optional
- **createParents** (boolean) - Optional

### Output
- **path** (string)
- **created** (boolean)
- **alreadyExists** (boolean)
```

--------------------------------

### Get Network Requests

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Retrieves a list of network requests made during the session.

```typescript
{
  sessionId: string;
  clear?: boolean;
}
```

```typescript
{
  sessionId: string;
  requests: Array<{
    url: string;
    method: string;
    status: number;
    timing: number;
  }>;
}
```

--------------------------------

### Get Console Logs

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Retrieves console logs and errors from the browser session.

```typescript
{
  sessionId: string;
  clear?: boolean;
}
```

```typescript
{
  sessionId: string;
  logs: Array<{
    type: "log" | "error" | "warn" | "info";
    message: string;
    timestamp: number;
  }>;
}
```

--------------------------------

### browser_session_create

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Create a new browser session.

```APIDOC
## browser_session_create

### Description
Create a new browser session.

### Inputs
- **headless** (boolean) - Optional
- **profile** (string) - Optional

### Output
- **sessionId** (string)
- **browser** (string)
- **headless** (boolean)
```

--------------------------------

### desktop_key_press

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Simulates a single key press on the keyboard.

```APIDOC
## desktop_key_press

### Description
Press a keyboard key.

### Inputs
- **key** (string) - Required - Key to press

### Output
- **key** (string) - Key pressed
- **pressed** (boolean) - Success status
```

--------------------------------

### Get Mouse Position Output Schema

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Defines the return structure for the desktop_mouse_position tool.

```typescript
{
  x: number;
  y: number;
}
```

--------------------------------

### Press Hotkey Input and Output Schemas

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Defines the input parameters and output structure for the desktop_hotkey tool.

```typescript
{
  modifiers: string[];
  key: string;
}
```

```typescript
{
  pressed: boolean;
}
```

--------------------------------

### window_list

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

List all currently open windows.

```APIDOC
## window_list

### Description
List open windows.

### Output
- **windows** (Array) - List of open windows containing hwnd, title, processName, and visibility status.
```

--------------------------------

### Create Browser Session

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Initializes a new browser session with optional headless and profile settings.

```typescript
{
  headless?: boolean;
  profile?: string;
}
```

```typescript
{
  sessionId: string;
  browser: string;
  headless: boolean;
}
```

--------------------------------

### GET /.well-known/oauth-protected-resource

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/endpoints.md

Retrieves OAuth protected resource metadata per RFC 8414.

```APIDOC
## GET /.well-known/oauth-protected-resource

### Description
OAuth protected resource metadata endpoint (per RFC 8414).

### Method
GET

### Endpoint
/.well-known/oauth-protected-resource

### Response
#### Success Response (200)
- **JSON** (object) - Metadata containing issuer, resource, authorization_endpoint, token_endpoint, and scopes_supported.
```

--------------------------------

### browser_navigate

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Navigate to a URL.

```APIDOC
## browser_navigate

### Description
Navigate to a URL.

### Inputs
- **sessionId** (string) - Required
- **url** (string) - Required
- **timeout** (number) - Optional

### Output
- **url** (string)
- **title** (string)
- **status** (number)
```

--------------------------------

### GET /healthz

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/endpoints.md

Public health check endpoint used for monitoring and uptime checks.

```APIDOC
## GET /healthz

### Description
Public health check endpoint for load balancers and monitoring.

### Method
GET

### Endpoint
/healthz

### Response
#### Success Response (200)
- **authRequired** (boolean) - Indicates if authentication is required
- **name** (string) - Server name
- **ok** (boolean) - Status indicator
- **transport** (string) - Transport type
- **version** (string) - Server version
```

--------------------------------

### Localhost-only configuration

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/README2.md

Environment variables for the initial smoke test. AUTH_REQUIRED=false is only permitted for local loopback development.

```env
PUBLIC_BASE_URL=http://127.0.0.1:8789
CLOUDFLARE_TUNNEL_ENABLED=false
AUTH_REQUIRED=false
```

--------------------------------

### GET /debug/healthz Response

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/endpoints.md

Extended health check response containing runtime information.

```json
{
  "authRequired": boolean,
  "defaultCwd": string,
  "journalPath": string,
  "name": "chatgpt-local-agent-mcp",
  "ok": true,
  "pid": number,
  "publicBaseUrl": string,
  "resourceUri": string,
  "transport": "streamable-http",
  "version": "0.1.0"
}
```

--------------------------------

### Run Tests

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/README.md

Executes the project's test suite.

```powershell
npm test
```

--------------------------------

### mkdir tool schema

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Defines the input and output structure for creating a directory.

```typescript
{
  path: string;
  cwd?: string;
  createParents?: boolean;
}
```

```typescript
{
  path: string;
  created: boolean;
  alreadyExists: boolean;
}
```

--------------------------------

### browser_page_select

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Switch to a specific tab/page.

```APIDOC
## browser_page_select

### Description
Switch to a specific tab/page.

### Inputs
- **sessionId** (string) - Required
- **pageId** (string) - Required

### Output
- **pageId** (string)
- **selected** (boolean)
```

--------------------------------

### Command Execution Policies

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/README2.md

Available policies for shell and process execution.

```text
disabled
workspace_guarded
full
```

--------------------------------

### browser_cdp_connect

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Connect to an existing browser instance using the Chrome DevTools Protocol.

```APIDOC
## browser_cdp_connect

### Description
Connect to existing browser via Chrome DevTools Protocol.

### Inputs
- **wsUrl** (string) - Required - The WebSocket URL for the CDP connection.
- **profilePath** (string) - Optional - The path to the browser profile.

### Output
- **connected** (boolean) - Connection status.
- **browser** (string) - Browser identifier.
```

--------------------------------

### process_list

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

List running processes.

```APIDOC
## process_list

### Description
List running processes.

### Inputs
- **filter** (string) - Optional

### Output
- **processes** (Array<{pid: number, name: string, memory: number}>)
```

--------------------------------

### GET /debug/healthz

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/endpoints.md

Extended health check providing runtime information, only available when EXPOSE_RUNTIME_DEBUG is enabled.

```APIDOC
## GET /debug/healthz

### Description
Extended health check with runtime information. Only available when EXPOSE_RUNTIME_DEBUG=true.

### Method
GET

### Endpoint
/debug/healthz

### Response
#### Success Response (200)
- **authRequired** (boolean) - Indicates if authentication is required
- **defaultCwd** (string) - Default current working directory
- **journalPath** (string) - Path to journal
- **name** (string) - Server name
- **ok** (boolean) - Status indicator
- **pid** (number) - Process ID
- **publicBaseUrl** (string) - Public base URL
- **resourceUri** (string) - Resource URI
- **transport** (string) - Transport type
- **version** (string) - Server version
```

--------------------------------

### Journal Entry JSON Structure

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/errors.md

Example of a JSON object representing an error recorded in the operation journal.

```json
{
  "id": "uuid",
  "timestamp": "2026-01-15T10:30:00Z",
  "tool": "write_file",
  "outcome": "error",
  "phase": "outcome",
  "error": "Permission denied: /root/protected.txt",
  "durationMs": 45,
  "argsRedacted": { "path": "/root/protected.txt" }
}
```

--------------------------------

### System Architecture Structure

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/api-index.md

Visual representation of the project's file structure and request handling flow.

```text
index.ts
  ├─ Express app setup with middleware
  ├─ Authentication middleware (OAuth + MCP authorization)
  ├─ Auth routes (/authorize, /callback, /token)
  ├─ Dashboard routes (/dashboard)
  └─ MCP endpoint POST /mcp
      ├─ Policy validation (tool access, workspace profiles)
      ├─ MCP server creation
      └─ Tool registration (40+ tools)
```

--------------------------------

### Runtime Defaults

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/README.md

Displays the default URLs for the server, MCP endpoint, and dashboard. These are essential for accessing the system's functionalities.

```text
Server:     http://127.0.0.1:8789
MCP:        http://127.0.0.1:8789/mcp
Dashboard: http://127.0.0.1:8789/dashboard
```

--------------------------------

### Dashboard and health check URLs

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/README2.md

Endpoints to verify the server status after starting the local control surface.

```text
Dashboard: http://127.0.0.1:8789/dashboard
Health:    http://127.0.0.1:8789/healthz
```

--------------------------------

### OAuth Configuration Mapping

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/README2.md

Reference values for configuring GitHub callbacks and ChatGPT connector endpoints.

```text
GitHub callback:      https://your-public-host.example/callback
ChatGPT connector:   https://your-public-host.example/mcp
ChatGPT redirect:    OAUTH_REDIRECT_URIS
```

--------------------------------

### GET /dashboard

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/endpoints.md

Retrieves the web-based dashboard for monitoring operations, managing browser sessions, and viewing the journal.

```APIDOC
## GET /dashboard

### Description
Web-based dashboard for monitoring operations, managing browser sessions, and viewing journal.

### Method
GET

### Endpoint
/dashboard

### Response
#### Success Response (200)
- **HTML** (text/html) - Dashboard HTML served

#### Error Response (401)
- **Unauthorized** - If AUTH_REQUIRED=true and no token is provided.
```

--------------------------------

### Provide Custom Workspace Profiles

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/README.md

Configure custom workspace profiles by setting the GPT_FS_MCP_WORKSPACE_PROFILES_JSON environment variable. This allows for defining root paths, allowed policy modes, backup policies, and secret deny globs to restrict assistant access.

```env
GPT_FS_MCP_WORKSPACE_PROFILES_JSON=
```

--------------------------------

### Click Mouse Input and Output Schemas

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Defines the input parameters and output structure for the desktop_mouse_click tool.

```typescript
{
  button?: "left" | "right" | "middle";
  x?: number;
  y?: number;
  clickCount?: number;
}
```

```typescript
{
  button: string;
  clicked: boolean;
}
```

--------------------------------

### Press Key Input and Output Schemas

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Defines the input parameters and output structure for the desktop_key_press tool.

```typescript
{
  key: string;
}
```

```typescript
{
  key: string;
  pressed: boolean;
}
```

--------------------------------

### Cloudflare Tunnel Forwarding URL

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/README.md

This URL shows how a typical setup uses Cloudflare Tunnel to forward a public hostname to your local server.

```text
http://127.0.0.1:8789
```

--------------------------------

### list_dir Input and Output Schemas

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Defines the input for listing directory contents and the resulting entry list.

```typescript
{
  path: string;
  cwd?: string;
  maxEntries?: number;
}
```

```typescript
{
  path: string;
  entries: Array<{
    name: string;
    kind: "file" | "directory" | "symlink" | "other";
    size?: number;
    modifiedAt?: string;
  }>;
  warnings?: Array<{
    message: string;
    severity: "info" | "warning";
  }>;
}
```

--------------------------------

### Move Mouse Input and Output Schemas

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Defines the input parameters and output structure for the desktop_mouse_move tool.

```typescript
{
  x: number;
  y: number;
  duration?: number;
}
```

```typescript
{
  x: number;
  y: number;
  moved: boolean;
}
```

--------------------------------

### Access All Tool Definitions

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Provides an ordered list of all available tool definitions.

```typescript
export const TOOL_DEFINITIONS: ReadonlyArray<ToolDefinition>
```

--------------------------------

### Handle access_denied redirect

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/errors.md

The redirect format used when a user denies authorization on GitHub.

```text
{redirect_uri}?error=access_denied&error_description=User+denied+access&state={state}
```

--------------------------------

### ChatGPT Connector OAuth Configuration

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/README2.md

Environment variables for the ChatGPT connector OAuth client.

```env
OAUTH_CLIENT_ID=
OAUTH_CLIENT_SECRET=
OAUTH_REDIRECT_URIS=
```

--------------------------------

### port_list

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

List listening ports.

```APIDOC
## port_list

### Description
List listening ports.

### Output
- **ports** (Array<{port: number, state: string, protocol: string}>)
```

--------------------------------

### createAccessToken Method

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/auth.md

Issues a new access token and stores it.

```typescript
function createAccessToken(record: AccessTokenRecord): void
```

```typescript
{
  audience: string;
  expiresAt: string;
  issuedAt: string;
  login: string;
  scopes: string[];
  subject: string;
  tokenHash: string;
}
```

--------------------------------

### Define Base URL

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/endpoints.md

The default base URL for the server.

```text
http://{GPT_FS_MCP_HOST}:{GPT_FS_MCP_PORT}
```

--------------------------------

### desktop_text_type

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Types the provided text string using the keyboard.

```APIDOC
## desktop_text_type

### Description
Type text on the keyboard.

### Inputs
- **text** (string) - Required - Text to type
- **delay** (number) - Optional - Delay between keystrokes

### Output
- **typed** (boolean) - Success status
- **characters** (number) - Number of characters typed
```

--------------------------------

### browser_screenshot

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Take a screenshot of the page.

```APIDOC
## browser_screenshot

### Description
Take a screenshot of the page.

### Inputs
- **sessionId** (string) - Required
- **fullPage** (boolean) - Optional
- **maxBytes** (number) - Optional

### Output
- **sessionId** (string)
- **screenshotPath** (string)
- **size** (number)
- **width** (number)
- **height** (number)
```

--------------------------------

### Define AppConfig

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/types.md

Represents the complete application configuration loaded from environment variables, covering server, auth, and security settings.

```typescript
export type AppConfig = {
  // Server binding
  host: string;
  port: number;
  publicBaseUrl: string;
  allowedHosts: string[];
  
  // Authentication
  authRequired: boolean;
  authRequirePkce: boolean;
  githubClientId?: string;
  githubClientSecret?: string;
  oauthClientId?: string;
  oauthClientSecret?: string;
  oauthRedirectUris: string[];
  allowedGithubLogins: string[];
  
  // Rate limiting
  authRateLimitMax: number;
  authRateLimitMaxBuckets: number;
  authRateLimitWindowMs: number;
  
  // Auth store (tokens/codes)
  authStoreMaxTokens: number;
  authStoreMaxAuthCodes: number;
  authStoreMaxPending: number;
  authStoreCleanupIntervalMs: number;
  
  // Policies & security
  maxPolicyMode: PolicyMode;
  shellPolicy: CommandPolicy;
  processPolicy: CommandPolicy;
  enforceWorkspaceProfiles: boolean;
  workspaceProfiles: WorkspaceProfile[];
  
  // Workspace
  defaultCwd: string;
  
  // Output limits
  maxOutputBytes: number;
  maxBodyBytes: number;
  
  // Browser
  maxBrowserSessions: number;
  browserSessionIdleMs: number;
  maxBrowserLogEntries: number;
  maxBrowserScreenshotFiles: number;
  maxBrowserScreenshotBytes: number;
  
  // Screen capture
  maxScreenshotAreaPixels: number;
  maxScreenshotBytes: number;
  maxScreenshotDimension: number;
  maxScreenshotFiles: number;
  
  // Backup & journal
  backupDir: string;
  maxBackupBytes: number;
  journalPath: string;
  
  // Command execution
  shellTimeoutMs: number;
  
  // Cloudflare
  cloudflareTunnelEnabled: boolean;
  
  // Development
  devIdentityLogin: string;
  exposeRuntimeDebug: boolean;
  trustProxyHeaders: boolean;
  
  // Computed URLs
  resourceUri: string;
  protectedResourceMetadataUrl: string;
  defaultOauthScopes: string[];
};
```

--------------------------------

### MCP Tools

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/README.md

Summary of the 40 available MCP tools categorized by functionality.

```APIDOC
The system exposes 40 MCP tools across the following categories:
- **Workspace**: workspace_info
- **Filesystem**: read, write, search, patch, backup
- **Git**: status, diff, commit
- **Process**: start, stop, kill, list, port, wait, tail
- **Browser**: navigate, click, fill, screenshot, console, network
- **Screen**: screenshot, window_list, OCR
- **Desktop**: mouse and keyboard control
- **Shell**: arbitrary command execution
```

--------------------------------

### browser_wait

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Wait for element or navigation.

```APIDOC
## browser_wait

### Description
Wait for element or navigation.

### Inputs
- **sessionId** (string) - Required
- **selector** (string) - Optional
- **timeout** (number) - Optional

### Output
- **found** (boolean)
- **timedOut** (boolean)
- **elapsed** (number)
```

--------------------------------

### Localhost Testing Environment Variables

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/README2.md

Configuration for testing on localhost with authentication disabled.

```env
PUBLIC_BASE_URL=http://127.0.0.1:8789
CLOUDFLARE_TUNNEL_ENABLED=false
AUTH_REQUIRED=false
NODE_ENV=development
```

--------------------------------

### Navigate Browser

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Navigates the browser to a specified URL with an optional timeout.

```typescript
{
  sessionId: string;
  url: string;
  timeout?: number;
}
```

```typescript
{
  url: string;
  title: string;
  status: number;
}
```

--------------------------------

### browser_cdp_connect Input and Output Schemas

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Defines the connection parameters for Chrome DevTools Protocol and the connection status output.

```typescript
{
  wsUrl: string;
  profilePath?: string;
}
```

```typescript
{
  connected: boolean;
  browser: string;
}
```

--------------------------------

### Configure GitHub OAuth for User Login

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/INSTALL.md

Set up GitHub as the identity provider by providing your GitHub OAuth App credentials and specifying allowed GitHub logins.

```env
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
ALLOWED_GITHUB_LOGINS=your-github-login
```

--------------------------------

### Authenticated Remote Connector Configuration

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/README2.md

Environment variables for remote access with authentication enabled.

```env
GPT_FS_MCP_HOST=127.0.0.1
GPT_FS_MCP_PORT=8789
AUTH_REQUIRED=true
AUTH_REQUIRE_PKCE=true
PUBLIC_BASE_URL=https://your-public-host.example
CLOUDFLARE_TUNNEL_ENABLED=true
CLOUDFLARED_CONFIG=C:\Users\you\.cloudflared\config.yml

GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
ALLOWED_GITHUB_LOGINS=your-github-login

OAUTH_CLIENT_ID=
OAUTH_CLIENT_SECRET=
OAUTH_REDIRECT_URIS=
```

--------------------------------

### stat Input and Output Schemas

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Defines the input path and the resulting file metadata.

```typescript
{
  path: string;
  cwd?: string;
}
```

```typescript
{
  path: string;
  exists: boolean;
  kind: "file" | "directory" | "symlink" | "other" | "missing";
  size?: number;
  modifiedAt?: string;
  createdAt?: string;
  isSymlink?: boolean;
}
```

--------------------------------

### Process List Schema

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Defines the input and output structure for listing active processes.

```typescript
{
  filter?: string;
}
```

```typescript
{
  processes: Array<{
    pid: number;
    name: string;
    memory: number;
  }>;
}
```

--------------------------------

### Default Workspace Profiles on Windows

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/README.md

When GPT_FS_MCP_WORKSPACE_PROFILES_JSON is empty, the server defaults to creating workspace profiles for each detected filesystem root. On Windows, this includes drive roots like C:\ and D:\, granting full-machine access.

```text
C:\
D:\
```

--------------------------------

### Type Text Input and Output Schemas

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Defines the input parameters and output structure for the desktop_text_type tool.

```typescript
{
  text: string;
  delay?: number;
}
```

```typescript
{
  typed: boolean;
  characters: number;
}
```

--------------------------------

### Select Browser Page

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Switches the active focus to a specific tab or page.

```typescript
{
  sessionId: string;
  pageId: string;
}
```

```typescript
{
  pageId: string;
  selected: boolean;
}
```

--------------------------------

### screen_screenshot

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Capture a screenshot of the desktop or a specific region.

```APIDOC
## screen_screenshot

### Description
Take a screenshot of the screen/desktop.

### Inputs
- **region** (object) - Optional - The region to capture (x, y, width, height).
- **maxBytes** (number) - Optional - Maximum size in bytes.

### Output
- **screenshotPath** (string) - Path to the saved screenshot.
- **size** (number) - File size.
- **width** (number) - Image width.
- **height** (number) - Image height.
```

--------------------------------

### browser_press_key

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Press a keyboard key.

```APIDOC
## browser_press_key

### Description
Press a keyboard key.

### Inputs
- **sessionId** (string) - Required
- **key** (string) - Required

### Output
- **key** (string)
- **pressed** (boolean)
```

--------------------------------

### rollback_backup tool schema

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Defines the input and output structure for restoring files from backups.

```typescript
{
  backupId: string;
}
```

```typescript
{
  backupId: string;
  path: string;
  restored: boolean;
  restoredSize: number;
}
```

--------------------------------

### createPendingAuthorize Method

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/auth.md

Initiates a pending GitHub authorization process.

```typescript
function createPendingAuthorize(record: Omit<PendingAuthorizeRecord, "createdAt">): string
```

```typescript
{
  clientId: string;
  redirectUri: string;
  resource: string;
  scope: string[];
  state: string;
  codeChallenge?: string;
  codeChallengeMethod?: "S256";
}
```

--------------------------------

### Verification success criteria

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/README2.md

Expected output indicating the server is running correctly.

```text
server starts
health endpoint responds
dashboard opens
build output exists
local controls are usable
```

--------------------------------

### Configure Public Base URL and Tunnel

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/INSTALL.md

Set the public base URL for your MCP server and enable Cloudflare Tunnel. Ensure the Cloudflared configuration path is correctly specified.

```env
PUBLIC_BASE_URL=https://mcp.your-domain.example
CLOUDFLARE_TUNNEL_ENABLED=true
CLOUDFLARED_CONFIG=C:\Users\you\.cloudflared\config.yml
```

--------------------------------

### Define Application Configuration Types

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/configuration.md

TypeScript type definitions for the application configuration, workspace profiles, and security policies.

```typescript
// From src/config.ts

export type AppConfig = {
  allowedHosts: string[];
  allowedGithubLogins: string[];
  authRateLimitMaxBuckets: number;
  authRateLimitMax: number;
  authRateLimitWindowMs: number;
  authRequired: boolean;
  authRequirePkce: boolean;
  authStoreMaxAuthCodes: number;
  authStoreMaxPending: number;
  authStoreMaxTokens: number;
  authStoreCleanupIntervalMs: number;
  backupDir: string;
  browserSessionIdleMs: number;
  maxBrowserLogEntries: number;
  maxBrowserScreenshotFiles: number;
  maxBrowserScreenshotBytes: number;
  maxBrowserSessions: number;
  cloudflareTunnelEnabled: boolean;
  defaultCwd: string;
  defaultOauthScopes: string[];
  devIdentityLogin: string;
  exposeRuntimeDebug: boolean;
  enforceWorkspaceProfiles: boolean;
  githubClientId?: string;
  githubClientSecret?: string;
  host: string;
  journalPath: string;
  maxBodyBytes: number;
  maxBackupBytes: number;
  maxOutputBytes: number;
  maxPolicyMode: PolicyMode;
  maxScreenshotAreaPixels: number;
  maxScreenshotBytes: number;
  maxScreenshotDimension: number;
  maxScreenshotFiles: number;
  oauthClientId?: string;
  oauthClientSecret?: string;
  oauthRedirectUris: string[];
  port: number;
  protectedResourceMetadataUrl: string;
  publicBaseUrl: string;
  resourceUri: string;
  processPolicy: CommandPolicy;
  shellTimeoutMs: number;
  shellPolicy: CommandPolicy;
  trustProxyHeaders: boolean;
  workspaceProfiles: WorkspaceProfile[];
};

export type WorkspaceProfile = {
  allowedPolicyModes: PolicyMode[];
  backupPolicy: "none" | "manual" | "snapshot";
  label: string;
  name: string;
  rootPath: string;
  secretDenyGlobs: string[];
};

export type CommandPolicy = "disabled" | "workspace_guarded" | "full";
export type PolicyMode = "observe" | "diagnose" | "edit" | "operate" | "destructive";
```

--------------------------------

### GitHub OAuth Configuration

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/README.md

Environment variables required for GitHub OAuth integration. Ensure these are set in your .env file.

```env
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
ALLOWED_GITHUB_LOGINS=
```

--------------------------------

### Port List Schema

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Defines the output structure for listing listening network ports.

```typescript
{
  ports: Array<{
    port: number;
    state: string;
    protocol: string;
  }>;
}
```

--------------------------------

### browser_type

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Type text into an element.

```APIDOC
## browser_type

### Description
Type text into an element.

### Inputs
- **sessionId** (string) - Required
- **selector** (string) - Required
- **text** (string) - Required
- **delay** (number) - Optional

### Output
- **selector** (string)
- **typed** (boolean)
```

--------------------------------

### Configure .env for Localhost-Only Smoke Testing

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/INSTALL.md

Set environment variables for a local-only smoke test. Ensure Auth is off, Tunnel is off, and Public base URL points to localhost. This configuration is only for local development and should not be used with public URLs or tunnels.

```env
PUBLIC_BASE_URL=http://127.0.0.1:8789
CLOUDFLARE_TUNNEL_ENABLED=false
AUTH_REQUIRED=false
```

--------------------------------

### move tool schema

Source: https://github.com/xxyoudeadpunkxx/chatgpt-local-agent-mcp/blob/main/_autodocs/mcp-tools.md

Defines the input and output structure for moving or renaming files and directories.

```typescript
{
  from: string;
  to: string;
  cwd?: string;
  overwrite?: boolean;
}
```

```typescript
{
  from: string;
  to: string;
  kind: "file" | "directory";
}
```
Tokens:
Raw