# Serverpod Overview

> Serverpod Overview is an Agent Skill for development published in the serverpod/serverpod repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Serverpod overview — what it is, project structure, how to work with. Always use at least once when working with projects that use Serverpod.

- Skill name: `serverpod-overview`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/serverpod/serverpod/blob/HEAD/packages/serverpod/skills/serverpod-overview/SKILL.md
- Repository: serverpod/serverpod (3,224 GitHub stars when collected)

## SKILL.md

# Serverpod Overview

Serverpod is an open-source backend framework for Flutter written in Dart. A Serverpod project consists of usually three packages:

`my_project_server` - the server code.
`my_project_client` - generated client code.
`my_project_flutter` - a Flutter app (imports the client).

There can also be packages that share code, e.g., `my_project_shared`.

The server exposes endpoint classes that the client calls via generated RPC client. Add methods to the endpoints, the code generation will recreate them on the client side. Models are defined in YAML and generate Dart classes for both server and client.

Serverpod projects use a Postgres database for persistence and include an ORM, caching, real-time streaming (using Dart streams), file uploads, scheduling (called future calls), logging, and a built-in web server (Relic). Each of these features have specific skills that you can use to get more details.

## Running the server

Most likely the server is already running with hot reload and `serverpod generate --watch`. NEVER attempt to start the server. The user is running the server with the `serverpod start` command (as an agent do NOT run this command, instead prompt the user to run `serverpod start`, if neccessary). Hot reload will update the generated code and quickly restart the server when files are changed.

ALWAYS use the MCP server instead of the command line. Use the MCP server to:

- `create_migration` and `apply_migrations` for database (after you change data models).
- `tail_server_logs` to read logs from the server.
- `tail_flutter_logs` to read raw stdout/stderr from the Flutter app.
- `hot_restart` will reload the server and the Flutter app. ALWAYS call it after doing changes in the Flutter app that may not work with normal hot reload (which is automatically applied).

## Working on the project with no running instance

- NEVER use the CLI unless you have already attempted to use the MCP.
- ONLY if you cannot connect to the MCP server, the code can be generated by calling `serverpod generate`.
- NEVER edit the generated code, as it will be overwritten by the next generation.

After generating the code, database migrations can be created by calling `serverpod create-migration`. Use ONLY if you cannot use the MCP.

```bash
# Use `--force` to create migrations with destructive changes
# Use the `--tag` flag to name the migration
serverpod create-migration [--force] [--tag <tag>]
```

See the [Serverpod Migrations](../serverpod-migrations/SKILL.md) skill for more details.

Checklist after doing changes:

1. `dart analyze` (`dart` MCP server)
2. `dart format` (`dart` MCP server)
3. Do `serverpod` MCP `hot_restart` if required (hot reload is done automatically). Will also hot restart Flutter app
4. Check `serverpod` MCP `tails_logs` for any issues

---

Source: https://www.openparable.com/skill/development/serverpod-overview (OpenParable). Cite the canonical URL above.
