{
  "markdown": "# ScopeGate\n\n**Never hand an AI agent a full OAuth scope again.**\n\nScopeGate sits between your agents and the accounts they reach — yours or your\nclients'. You connect a service once, tick the exact actions an agent may call,\nand hand it an MCP endpoint that can do nothing else. Every call is logged; one\nclick kills the key without touching the connection.\n\n- **Per-action permissions** — `gmail:read_emails` yes, `gmail:send_email` no. Finer than any provider's OAuth scopes.\n- **Audit trail** — who, which tool, what outcome, how long. Per project, exportable.\n- **One-click revocation** — regenerate an endpoint key; the service connection stays.\n- **Tokens never leave** — AES-256-GCM at rest, refreshed automatically, agents only ever see `sg_…`.\n\nRun it yourself in one command:\n\n```bash\ndocker compose --profile local up\n```\n\nOpen [http://localhost:3000](http://localhost:3000) — the admin login is printed in\nthe container logs on first boot. Details in [Quick Start](#quick-start-self-hosted).\n\n## Tech Stack\n\n- **Framework**: Next.js 16 (App Router)\n- **Language**: TypeScript\n- **Database**: PostgreSQL + Prisma 7\n- **UI**: Tailwind CSS v4, shadcn/ui\n- **Auth**: Better Auth (database-backed sessions, Prisma adapter)\n- **MCP**: `@modelcontextprotocol/sdk` (Streamable HTTP)\n- **Package Manager**: pnpm\n\n## Quick Start (self-hosted)\n\nFull feature parity with the hosted cloud version — nothing is cut for self-host.\n\n```bash\ngit clone https://github.com/alifanov/scopegate.git\ncd scopegate\ndocker compose --profile local up\n```\n\nOpen [http://localhost:3000](http://localhost:3000). No `.env` file needed: a local\nPostgres and a fresh `BETTER_AUTH_SECRET` are provisioned automatically, and the\ngenerated admin login is printed once in the `app` container logs on first boot\n(look for `Generated admin login`) — search it with `docker compose logs app | grep -A4 \"First run\"`.\nThe password is also saved to the `app_data` volume so it survives restarts.\n\nTo connect real services (Gmail, LinkedIn, GitHub, …), copy `.env.example` to `.env`\nand fill in the OAuth client id/secret for the providers you want — every block is\nindependent and optional, a provider without credentials simply doesn't show up.\n\n## Development Setup\n\n### Prerequisites\n\n- Node.js 20.19+, 22.12+ or 24+ (required by Prisma 7)\n- pnpm\n- PostgreSQL\n\n### Setup\n\n1. Clone the repository and install dependencies:\n\n```bash\npnpm install\n```\n\n2. Copy the environment file and fill in your values:\n\n```bash\ncp .env.example .env\n```\n\n| Variable | Description |\n|---|---|\n| `DATABASE_URL` | PostgreSQL connection string |\n| `BETTER_AUTH_SECRET` | Secret key for session signing |\n| `BETTER_AUTH_URL` | App base URL (e.g. `http://localhost:3000`) |\n| `ADMIN_EMAIL` | Bootstrap admin email |\n| `ADMIN_PASSWORD` | Bootstrap admin password |\n\n3. Run database migrations:\n\n```bash\npnpm prisma migrate dev\n```\n\n4. Start the development server:\n\n```bash\npnpm dev\n```\n\nOpen [http://localhost:3000](http://localhost:3000).\n\n## Project Structure\n\n```\nsrc/\n├── app/\n│   ├── (auth)/              # Login & register pages\n│   ├── (dashboard)/         # Protected dashboard pages\n│   │   └── projects/        # Project management, endpoints, audit, settings\n│   ├── api/\n│   │   ├── auth/[...all]/    # Better Auth catch-all handler\n│   │   ├── projects/        # Projects CRUD, endpoints, services, audit\n│   │   └── mcp/[apiKey]/    # MCP Streamable HTTP handler\n│   ├── layout.tsx\n│   └── page.tsx             # Landing page\n├── components/\n│   ├── ui/                  # shadcn/ui components\n│   ├── layout/              # Sidebar, header\n│   └── shared/              # Reusable app components\n├── lib/\n│   ├── db.ts                # Prisma client singleton\n│   ├── auth.ts              # Better Auth server instance\n│   ├── auth-client.ts       # Better Auth client SDK\n│   ├── auth-middleware.ts   # getCurrentUser() helper\n│   ├── bootstrap.ts         # Admin user bootstrap on empty DB\n│   ├── provider-registry.ts # Every supported provider — the one file to edit\n│   └── mcp/\n│       ├── permissions.ts   # Permission groups (derived from the registry)\n│       ├── tools/           # One file per service, aggregated in index.ts\n│       ├── service-fetch.ts # Unified, SSRF-safe transport for all providers\n│       └── handler.ts       # MCP server factory + audit logging\n├── generated/prisma/        # Generated Prisma client\n└── middleware.ts             # Route protection\n```\n\n## Available Scripts\n\n```bash\npnpm dev              # Start development server\npnpm build            # Production build\npnpm start            # Start production server\npnpm lint             # Run ESLint\npnpm prisma generate  # Regenerate Prisma client\npnpm prisma migrate dev  # Create and apply migrations\npnpm prisma studio    # Open Prisma Studio (DB browser)\n```\n\n## How It Works\n\n1. **Login** — sign in with admin credentials (bootstrapped from env vars on first run)\n2. **Create a Project** — organize endpoints and services by project\n3. **Connect a Service** — add a service connection to the project\n4. **Create an MCP Endpoint** — select a service connection and pick specific permissions (e.g. `gmail:read_emails`, `calendar:create_event`)\n5. **Use the MCP URL** — plug the endpoint URL into any MCP-compatible AI agent; only the allowed actions are exposed\n6. **Monitor** — track every request in the audit log\n\n## Permissions\n\nA permission is a single action, not a service — `gmail:read_emails` can be granted\nwithout `gmail:send_email`. Groups are derived from `src/lib/provider-registry.ts`\n(27 providers: Google Workspace, Google Ads & Search Console, Meta, LinkedIn,\nTwitter, Slack, Notion, Jira, HubSpot, Salesforce, Stripe, Airtable, …) and listed\nin `src/lib/mcp/permissions.ts`. Adding a provider means editing the registry —\ntransport, token strategy and permission groups are all derived from it.\n\nA few Google examples:\n\n| Group | Actions |\n|---|---|\n| Gmail | `gmail:read_emails`, `gmail:send_email`, `gmail:list_labels`, `gmail:search_emails` |\n| Google Calendar | `calendar:list_events`, `calendar:create_event`, `calendar:update_event`, `calendar:delete_event` |\n| Google Drive | `drive:list_files`, `drive:read_file`, `drive:create_file`, `drive:delete_file` |\n\n## Database Schema\n\n- **User** — authentication, team membership\n- **Session** — database-backed auth sessions\n- **Account** — auth provider credentials (email/password)\n- **Project** — logical grouping for services and endpoints\n- **TeamMember** — user-project relationship with roles (owner/member)\n- **ServiceConnection** — OAuth tokens for connected services\n- **McpEndpoint** — MCP endpoint with API key, rate limit, active status\n- **EndpointPermission** — allowed actions per endpoint\n- **AuditLog** — request log with action, status, duration, errors\n\n## License\n\nSee [LICENSE](LICENSE).\n",
  "bytes": 6842,
  "sha": "8583ed58483216773c6922d62f7d6fe9828806147084e10e962d315aba4782d8",
  "repo_slug": "alifanov/scopegate",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_alifanov_scopegate_d49aaa1a/readme"
}