octocode-mcp
Version:
Model Context Protocol (MCP) server for advanced GitHub repository analysis and code discovery. Provides AI assistants with powerful tools to search, analyze, and understand codebases across GitHub.
174 lines (173 loc) • 8.39 kB
TypeScript
/**
* GitHub API Error Constants
* Centralized error definitions with keys, messages, and explanations
*/
/**
* Error codes for internal tracking and testing
*/
export declare const ERROR_CODES: {
readonly AUTH_REQUIRED: "AUTH_REQUIRED";
readonly RATE_LIMIT_PRIMARY: "RATE_LIMIT_PRIMARY";
readonly RATE_LIMIT_SECONDARY: "RATE_LIMIT_SECONDARY";
readonly FORBIDDEN_PERMISSIONS: "FORBIDDEN_PERMISSIONS";
readonly NOT_FOUND: "NOT_FOUND";
readonly INVALID_REQUEST: "INVALID_REQUEST";
readonly SERVER_UNAVAILABLE: "SERVER_UNAVAILABLE";
readonly NETWORK_CONNECTION_FAILED: "NETWORK_CONNECTION_FAILED";
readonly REQUEST_TIMEOUT: "REQUEST_TIMEOUT";
readonly UNKNOWN: "UNKNOWN";
};
export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
/**
* Error message templates with explanations
*/
export declare const ERROR_MESSAGES: {
/**
* 401 - Authentication Required
* When: No token provided or token is invalid
* Cause: Missing/invalid GITHUB_TOKEN or GH_TOKEN
* Fix: Set valid GitHub personal access token
*/
readonly AUTH_REQUIRED: {
readonly message: "GitHub authentication required";
readonly suggestion: "TELL THE USER: Refresh your GitHub token! Run 'gh auth login' OR 'gh auth refresh' OR set a new GITHUB_TOKEN/GH_TOKEN environment variable";
readonly explanation: "API request requires authentication. GitHub APIs have different rate limits for authenticated (5000/hour) vs unauthenticated (60/hour) requests.";
};
/**
* 403 - Primary Rate Limit Exceeded
* When: Used all API quota for current hour (REST or GraphQL)
* Cause: Too many requests within rate limit window
* Fix: Wait until rate limit resets, or use authenticated requests for higher limits
* Docs: https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting
*/
readonly RATE_LIMIT_PRIMARY: {
readonly message: "GitHub API rate limit exceeded";
readonly messageWithTime: (resetTime: Date, seconds: number) => string;
readonly messageWithoutTime: "GitHub API rate limit exceeded. Reset time unavailable - check GitHub status or try again later";
readonly suggestion: "Set GITHUB_TOKEN for higher rate limits (5000/hour vs 60/hour)";
readonly explanation: "Primary rate limit tracks total API calls per hour. Authenticated users get 5000 requests/hour, unauthenticated get 60 requests/hour.";
};
/**
* 403 - Secondary Rate Limit (Abuse Detection)
* When: Making requests too quickly (abuse detection)
* Cause: High frequency of requests triggering anti-abuse mechanisms
* Fix: Slow down request rate, add delays between requests
* Docs: https://docs.github.com/en/rest/overview/resources-in-the-rest-api#secondary-rate-limits
*/
readonly RATE_LIMIT_SECONDARY: {
readonly message: (retryAfter: number) => string;
readonly suggestion: "Reduce request frequency to avoid abuse detection";
readonly explanation: "Secondary rate limits prevent API abuse by limiting request frequency. Triggered by making too many requests too quickly, regardless of remaining quota.";
readonly fallbackRetryAfter: 60;
};
/**
* 403 - Forbidden (Insufficient Permissions)
* When: Token lacks required scopes for the operation
* Cause: GitHub token missing necessary OAuth scopes
* Fix: Refresh token with required scopes using gh CLI
*/
readonly FORBIDDEN_PERMISSIONS: {
readonly message: "Access forbidden - insufficient permissions";
readonly suggestion: "Check repository permissions or authentication";
readonly suggestionWithScopes: (missing: string[]) => string;
readonly fallbackSuggestion: "Token may not have sufficient permissions for this operation";
readonly explanation: "GitHub tokens require specific OAuth scopes for different operations. Common scopes: repo (full repository access), read:org (organization access), gist (gist access).";
};
/**
* 404 - Not Found
* When: Repository, file, or resource does not exist or is inaccessible
* Cause: Wrong path, deleted resource, or private repo without access
* Fix: Verify resource exists, check spelling, ensure token has access to private repos
*/
readonly NOT_FOUND: {
readonly message: "Repository, resource, or path not found";
readonly explanation: "Resource not found or not accessible. Could be: incorrect path, deleted resource, private repository without access, wrong branch name.";
};
/**
* 422 - Unprocessable Entity (Validation Error)
* When: Request parameters are invalid or malformed
* Cause: Invalid search query syntax, invalid parameter values
* Fix: Check API documentation for correct parameter format
* Docs: https://docs.github.com/en/rest/overview/resources-in-the-rest-api#client-errors
*/
readonly INVALID_REQUEST: {
readonly message: "Invalid search query or request parameters";
readonly suggestion: "Check search syntax and parameter values";
readonly explanation: "Request was well-formed but contains invalid parameters. Common causes: invalid search syntax, parameters out of range, invalid filter combinations.";
};
/**
* 502/503/504 - Server Errors
* When: GitHub API is temporarily unavailable
* Cause: GitHub server issues, maintenance, or overload
* Fix: Retry after a short delay, check GitHub status page
*/
readonly SERVER_UNAVAILABLE: {
readonly message: "GitHub API temporarily unavailable";
readonly suggestion: "Retry the request after a short delay";
readonly explanation: "GitHub servers are temporarily unavailable. Usually resolves quickly. Check https://www.githubstatus.com for service status.";
};
/**
* Network Error - Connection Failed
* When: Cannot reach GitHub API servers
* Cause: No internet connection, DNS failure, firewall blocking
* Fix: Check internet connection, verify DNS resolution, check firewall settings
*/
readonly NETWORK_CONNECTION_FAILED: {
readonly message: "Network connection failed";
readonly suggestion: "Check internet connection and GitHub API status";
readonly explanation: "Cannot establish connection to GitHub API. Check internet connectivity, DNS settings, and firewall/proxy configuration.";
};
/**
* Network Error - Request Timeout
* When: Request takes too long to complete
* Cause: Slow network, large response, GitHub server delay
* Fix: Retry request, check network speed, consider pagination for large requests
*/
readonly REQUEST_TIMEOUT: {
readonly message: "Request timeout";
readonly suggestion: "Retry the request or check network connectivity";
readonly explanation: "Request exceeded timeout limit. Could be slow network, large response size, or GitHub server delay.";
};
/**
* Unknown Error
* When: Unrecognized error occurred
* Cause: Unexpected error not matching known patterns
* Fix: Check error message for details, report if persistent
*/
readonly UNKNOWN: {
readonly message: "Unknown error occurred";
readonly explanation: "An unexpected error occurred that does not match known error patterns.";
};
};
/**
* HTTP status code to error code mapping
*/
export declare const STATUS_TO_ERROR_CODE: Record<number, ErrorCode>;
/**
* Network error patterns
*/
export declare const NETWORK_ERROR_PATTERNS: {
readonly CONNECTION_FAILED: readonly ["ENOTFOUND", "ECONNREFUSED"];
readonly TIMEOUT: readonly ["timeout"];
};
/**
* Rate limit detection patterns
*/
export declare const RATE_LIMIT_PATTERNS: {
readonly SECONDARY: RegExp;
readonly GRAPHQL_TYPE: "RATE_LIMITED";
};
/**
* Rate limit configuration
*/
export declare const RATE_LIMIT_CONFIG: {
/**
* Add 1 second buffer to rate limit reset time per GitHub best practices
* Docs: https://docs.github.com/en/rest/overview/resources-in-the-rest-api#exceeding-the-rate-limit
*/
readonly RESET_BUFFER_SECONDS: 1;
/**
* Default secondary rate limit retry delay when no retry-after header present
*/
readonly SECONDARY_FALLBACK_SECONDS: 60;
};