Local development
This page explains how to build, test and change the code of email-mcp on your
own computer. It names the make targets, the Go version, the checks of CI
(continuous integration: the checks that GitHub runs on each pull request and
on each push to main), the rules of the code, the steps to add a tool, a
command, a migration or a package, and which page of the docs to update. Read
it before your first change.
The make targets
Make is a tool that runs the build steps of a project. The steps are in the
Makefile. These four commands build the program, run the tests,
run the linters (tools that find mistakes in code without running it) and look
for known vulnerabilities. The comment after each command says what it makes or
runs:
make build # bin/email-mcp
make test # go test -race ./..., then two packages again without -race
make lint # go vet, staticcheck and golangci-lint
make vuln # govulncheck
If your shell sets GOROOT to another Go install, run make as
env -u GOROOT make test. GOROOT is the variable that names the folder of a
Go install. env -u GOROOT runs the command without that variable (-u:
unset), so go and golangci-lint (a program that runs many linters at once)
both use the same Go.
| Target | What it runs |
|---|---|
build |
CGO_ENABLED=0 go build -trimpath -o bin/email-mcp ./cmd/email-mcp. CGO_ENABLED=0 means no C compiler, so the binary is static: it needs no system library to run. -trimpath removes the file paths of your computer from the binary. The build sets no version, so email-mcp version prints email-mcp dev. |
test |
Every test that needs no build tag, in two runs. The first runs every package with -race, the race detector (a check that finds two goroutines, functions that run at the same time, that use the same memory without a lock). The second runs the packages of NORACE_PKGS again without it, for their heavy tests and their time limits. See The race detector. |
lint |
go vet and staticcheck (a linter for Go) with the build tags interop, screenshots and sitebuild, then golangci-lint run. The tags make the linters read the files that go test ./... leaves out. Install golangci-lint v2 first. |
vuln |
govulncheck, which checks the code and the dependencies for known vulnerabilities. |
screenshots |
The images of the user manual. See The docs site. |
site |
The images, then the docs site and its checks. |
site-serve |
The images, then a preview of the site that rebuilds when a file changes. |
social-card |
site/assets/social-card.png, the preview picture of the landing page, from its SVG file (Scalable Vector Graphics: a picture made of shapes). Run it only after a change of the SVG. |
No target runs the interop test, because it needs Docker (a tool that runs programs in containers). See The interop test.
The Makefile runs staticcheck and govulncheck with go run tool@version, so
there is nothing to install: Go downloads and builds that version of the tool
the first time. The versions are the variables STATICCHECK_VERSION and
GOVULNCHECK_VERSION of the Makefile. The workflows pin (fix to one exact
version) the same versions, and a comment in each file says to keep them in
step.
The settings of golangci-lint are in .golangci.yml. It runs the
standard set of linters (errcheck, govet, ineffassign, staticcheck and unused)
and gosec, a linter for security mistakes, and it checks the format with gofmt.
It reads the same three build tags. It skips internal/thirdparty, the copied
HTML (HyperText Markup Language) parser (see
Map of packages).
The Go version
The go line of go.mod (go 1.26.0) is the oldest Go that can
build the module. .go-version holds the Go version of the
project, for tools that choose the Go version of a folder, such as goenv. The
workflows do not read it: they install the newest stable Go
(go-version: stable of actions/setup-go). The Dockerfile pins its Go image
by digest (a hash of the exact image), and its comment says to use the latest
stable release.
What CI runs
.github/workflows/ci.yml runs on every pull request and on every
push to main. It has five jobs:
| Job | What it runs |
|---|---|
vet and test |
go vet with the three build tags, then make test |
lint |
staticcheck with the three build tags, then golangci-lint, which the job builds with its own Go |
goreleaser check |
goreleaser check, which reads .goreleaser.yaml, the settings of GoReleaser (the tool that builds the release). A bad key then fails the pull request, and not the release after the tag exists. |
govulncheck |
govulncheck |
build site |
make site, then it uploads the images as a workflow artifact (files that a run keeps for download) for 7 days, also when make site failed |
The workflows of the repository follow these rules. Keep them when you add or change a workflow:
- Set
permissions: contents: readat the top, so the token that GitHub gives the run (GITHUB_TOKEN) may only read the repository by default. Give a job that needs more its own block, with only what it needs, as the jobreleaseofrelease.ymland the jobdeployofpages.ymlhave. - Pin each action by its full commit SHA (Secure Hash Algorithm: here, the hash that names one commit), with the release tag in a comment after it.
- Set
persist-credentials: falseon the checkout, so it does not keep the token in its git settings. - Put no
${{ }}value into arun:script. Pass a value throughenv:, and use it as a shell variable in quotes.
The interop test runs in its own workflow. The page Testing lists what each workflow runs. The docs check also runs in its own workflow (see Which page do I update?).
Dependabot
Dependabot is the GitHub service that opens pull requests to update
dependencies. Its settings are in .github/dependabot.yml:
- It looks once a week, and it opens one pull request for each ecosystem (a kind of dependency): the Go modules, the actions, the images of the Dockerfiles, and the image of the interop compose file.
- A version must be 7 days old before Dependabot offers it (the cooldown,
default-days: 7). Security updates do not wait. - The pull requests of the Go modules start with
fix(deps):. The Go modules are inside the released program, and release-please (the tool that proposes each release) counts afixas a change that needs a patch release. So a security fix in a module leads to a proposed release, which a maintainer then merges. Without the prefix, Dependabot would writebuild(deps):, which makes no release. - It does not update
go-imap/v2, which is pinned to one beta version on purpose, or chromedp andgo-json-experiment/json, which only the tests use. With thefixprefix, each update of a test module would propose a release of a program that did not change. A fix in a pinned module does not arrive by itself: watch the releases of that module, and read the result of govulncheck.
The comment at the top of the file lists what Dependabot does not see, so a
person updates it by hand: the images of BuildKit (the build engine of Docker)
and of the Syft scanner (it lists the modules inside an image) of the release,
the tool versions that go run uses, the version of Hugo (the program that
builds the docs site) in .hugo-version, the versions of cosign (a tool that
signs files) and Syft that release.yml gives to two installer actions, the
golangci-lint version of ci.yml, chromedp, and the release-please version in
the $schema address of release-please-config.json.
Rules of the code
The rules come from .github/copilot-instructions.md and from the
code:
- Format the code with
gofmt. The lint fails when a file is not formatted. - Return errors, and do not panic. Wrap an error with
fmt.Errorf("...: %w", err), so the caller can still find the cause. - Give each exported name a comment that starts with the name. Make a comment say why, because the code already says what.
- Write table-driven tests (one test runs the same check over a table of
cases), with
github.com/stretchr/testify/require. - A message in the tool API (application programming interface: here, the tools and their arguments) is named by a ref, never by a sequence number (the position of a message, which changes). The agent passes a ref back unchanged (see Refs, folders and tags). Address messages with UID (unique id) sets in each IMAP (Internet Message Access Protocol) command, never with sequence sets.
- Fetch with
BODY.PEEK(a fetch that does not mark the message as read), unless the purpose is to mark it as read. - Log no mail content and no secret. The page Activity log and program log has the rules for a log line.
The design documents under docs/superpowers/specs/ are history. The page
Architecture overview says
how to read them. One part is kept current (see The landing page truth
table).
Commit and pull request titles
Each commit message and each pull request title is a Conventional Commit
(a format for commit messages: type(scope): description), such as
fix(mcpserver): point agents to html_body in the create_draft description.
A squash merge makes the title of the pull request the commit message on
main. release-please reads these messages to choose the next version and to
write the changelog (the list of changes of each release). So a fix: or a
feat: makes a release, and a docs:, ci: or test: alone does not. The
page Making a release says which type raises which number.
Add code
The page Map of packages says which package gets which kind of code. The sections below name the files and the tests to change, or link to the page that does.
Add a tool
A tool is one action that an agent can call, such as get_message. The agent
is the AI (artificial intelligence) program that calls the tools.
- The use case. Add a method to
service.Service. It checks the permission first, with thepolicy.Actionthat it needs. See One tool call, step by step. - The input. Add an input struct in
mcpserver. Thejsontag of a field is the name of the argument, and thejsonschematag is its description. The SDK (software development kit: the Go library for MCP, Model Context Protocol) builds the schema of the tool from the struct. - The handler. Add it in
registerReadToolsininternal/mcpserver/read_tools.goorregisterWriteToolsininternal/mcpserver/write_tools.go, withaddTool. Give it a description that names the level it needs, and its annotations (hints for the client):readOnly(), orwriteHints(destructive, idempotent, openWorld).addToolininternal/mcpserver/server.gois the only way to add a tool, because it wraps the handler withsafe, which finds the caller first.TestEveryToolRunsThroughSafefails for a tool that was added another way. - The activity log. Each argument name goes in
omittedArgumentsininternal/mcpserver/capture.go(the log never keeps it: the content of a message) or inkeptArgumentsininternal/mcpserver/capture_test.go. Decide on purpose.TestEveryArgumentOfEveryToolIsKeptOrOmittedfails for an argument that is in neither. Add the name of the tool toauditToolsininternal/service/accounts.go, with a name constant as the other tools have, so the Activity page can filter by it. - The lists of the tests. These tests fail for a tool that the server
lists and they do not know:
wantToolsand the number of tools inTestToolsListFullSet, ininternal/mcpserver/write_tools_test.go;- for a read tool, the list
wantofTestToolsListStableAndAnnotated, ininternal/mcpserver/read_tools_test.go; - the number of tools in the serve test of
cmd/email-mcp/serve_test.go; requiredLevel, and the mapargsinsideTestEveryWriteToolRefusedBelowItsLevel, ininternal/e2e/security_test.go;- a call of the tool in
TestEveryToolCallIsInTheActivityLog, ininternal/e2e/capture_test.go.
- Only for the person? A use case that only the person may call gets no
tool. Add it to
userOnlyCallsininternal/mcpserver/useronly_test.go, and the test fails when the code ofmcpservercalls it. A test of the same file also checks the name of each tool: see Tests that check every item of a list.
Then update the manual page What the agent can do.
Add a command
See Add a command.
Add a migration
A migration is a numbered SQL (Structured Query Language) file in
internal/store/migrations/ that changes the structure of the
database. Add the file with the next number, and its methods in a file of the
package store. The page
Storage and secrets
has the rules. Read them first: a migration that rebuilds a table can delete
the stored passwords.
Add a package
- Put it in the layer that its imports allow, and add its row to Map of packages and to the maps of Which page do I update?.
- Write or change the tech docs page that explains it, and add its path to the
code_areasof that page (the list of the code that a page covers). - A file with a build tag that is not one of
interop,screenshotsandsitebuildneeds that tag ingo vetand staticcheck in the Makefile and inci.yml, and inbuild-tagsof.golangci.yml. Otherwise no linter reads the file. A file with one of the three tags needs no change, because each linter reads every package with them.
Which page do I update?
A change of the code can make a page of the docs wrong. The site has two kinds of docs: the user manual, for the person who uses email-mcp, and the tech docs, for the people who change the code. The two maps below say which pages to read for each part of the code. The docs check, a check on each pull request, fails when a change of the program leaves out one of the two kinds.
The docs check
The workflow .github/workflows/docs-check.yml (a workflow is a
file of steps that GitHub runs) has the job docs check. The job runs when a
pull request is opened or reopened, when a commit is pushed to it, and when a
label is added or removed. A label is a short name that a person attaches to a
pull request. The job gives the list of the files that the pull request
changes to test/docscheck/main.go. A moved file counts with its
old path and its new path, so a file that moves out of internal/ still
counts.
First, the check looks for a change of behaviour (of what the program does). A change counts as behaviour when it touches:
- a Go file in
cmd/orinternal/that is not a test file (a file whose name ends in_test.go); - any file in
internal/web/templates/,internal/web/static/orinternal/store/migrations/. The program embeds files of these folders (builds them into the binary). The check counts every file in them, whatever its type.
Files in internal/testutil/, internal/e2e/ and internal/thirdparty/ do
not count. No other file counts either, such as the Makefile, a workflow or a
page of the site.
Then, if behaviour changed, the pull request must do both of these:
- change a file under
site/content/manual/, or carry the labelno-manual-change; - change a file under
site/content/tech/, or carry the labelno-tech-docs-change.
The landing page (site/content/_index.md) is in neither folder, so it does
not count as docs. When a part is missing, the job fails. Its message names the
missing part and the label that would clear it.
The check sees folders, not pages: a change of any file under
site/content/manual/ clears the manual part. So the check cannot tell you
which page to change. The maps below do that.
The check also fails when it cannot check, with a message that starts with
docscheck:. This happens, for example, when it reads no changed file. The job
fails too when gh (the GitHub command line tool) cannot read the pull request
from GitHub. It also happens when the pull request changes more than 3000
files, because the GitHub API (here, the web service that lists the files)
lists no more. In that case, check the docs by hand.
The job reads the labels from GitHub when it runs, not from the event that started it. So “Re-run jobs” on an old run uses the labels that the pull request has when the job runs again.
You can run the check on your own computer, from the root of the repository.
origin/main is your copy of the branch main of GitHub, so run
git fetch origin first to bring it up to date. The command sees only commits,
so commit your change first. With no commit, the check reads no file and
cannot run. The command lists the files that your commits change since your
branch left origin/main. The | (a
pipe) gives that list to the check as its standard input (the text that a
program reads). --name-only prints only the paths. --no-renames lists a
moved file as two paths, the old one and the new one, as the job does.
origin/main... (three dots) compares your last commit with the commit where
your branch left origin/main. go run ./test/docscheck builds the check and
runs it:
git diff --name-only --no-renames origin/main... | go run ./test/docscheck
It prints nothing and exits with 0 (the code that means success) when nothing
is missing. A missing part ends with the line exit status 1, and a check that
could not run ends with exit status 2. In both cases the go run command
itself exits with 1, so read the message.
The check reads the labels from the variable PR_LABELS, a JSON (JavaScript
Object Notation) array of names. This command runs the same check as if the
pull request had the label no-manual-change. The variable is set for go run
only, so it comes after the |:
git diff --name-only --no-renames origin/main... |
PR_LABELS='["no-manual-change"]' go run ./test/docscheck
The two labels
Add a label only after you read the pages of the maps below, and none of them needs a change:
no-manual-change: the person who uses email-mcp sees no change in what it does, and no step of the manual changes. A change that alters only the look of a web page can carry it too:make sitemakes the images of the manual again when the code changed, so the images show the changed look.no-tech-docs-change: no sentence of a tech docs page becomes wrong.
There are two labels, not one. One label would clear both parts. Then a pull request that updated the tech docs could skip the manual with it.
In this repository, only people with write access can add a label. If you have no write access, say in the pull request why a label fits, and a maintainer adds it.
The pull request template .github/pull_request_template.md adds
two checkboxes, one for each kind of docs, and a link to this section. GitHub
fills it in when you open a pull request on github.com. A pull request that a
tool opens with its own text does not get it. The docs check runs in both
cases. When a change alters what the landing page states, also read its truth
notes again (see The landing page truth
table).
Map of the tech docs
Each row names a code area, its main page, and other pages that may need a
change. Each tech docs page also lists the code that it covers, at its end,
under “Code covered by this page”. The docs check does not count
internal/e2e, internal/testutil and internal/thirdparty, but they are in
the map so that you can find their page. Two pages are named Local HTTP mode,
one in each part of the docs. HTTP (HyperText Transfer Protocol: the protocol
of web servers) is one of the two ways that an AI app talks to the server.
internal/service is large, so several pages explain it. Choose the page by
the file:
send.go,write.go,queue.goandapprovals.go: The send flow;service.go,read.goandprincipal.go: One tool call, step by step;calls.go: Activity log and program log;tokens.go: Local HTTP mode;accounts.go: Permissions for the settings and the risk acceptance, and Connecting an account for connecting an account;reconnect.go: Connecting an account;backends.go: The mail backend;links.go: Permissions.
internal/mime has two pages. Choose the page by the file:
build.go,body.go,recipients.go,draft.goandaddress.go: Building mail;- the other files: Mail content.
These files and folders are not Go packages. The docs check counts the files of the first three rows. It does not count the other rows.
| File or folder | Main tech page | Also check |
|---|---|---|
internal/store/migrations/ |
Storage and secrets | this page |
internal/web/templates/, internal/web/static/ |
The web portal | |
internal/web/templates/approval.html |
The web portal | The send flow |
Makefile |
this page | Testing |
.golangci.yml, .go-version, .github/copilot-instructions.md |
this page | |
go.mod, .github/dependabot.yml |
this page | Map of packages |
.github/workflows/ci.yml |
this page | Testing |
.github/workflows/docs-check.yml, test/docscheck/, .github/pull_request_template.md |
this page | Testing |
test/sitecheck/ |
this page | Testing |
test/socialcard/ |
this page | Testing |
.hugo-version, site/hugo.toml, site/config/, site/layouts/, site/assets/ |
this page | |
.github/workflows/interop.yml, test/interop/ |
Testing | |
.github/workflows/release-please.yml, .github/workflows/pages.yml |
Making a release | |
.github/workflows/release.yml |
Making a release | Testing |
.goreleaser.yaml, release-please-config.json, .release-please-manifest.json, server.json, CHANGELOG.md |
Making a release | |
Dockerfile |
Making a release | this page |
.dockerignore |
this page | |
DESIGN.md, PRODUCT.md |
The web portal |
The landing page of the site has a drawing of the approval page, in
site/layouts/_partials/approval-picture.html. A change of
internal/web/templates/approval.html may need the same change in the drawing.
The test TestLandingPictureLabelsMatchPortal in
internal/web/landing_labels_test.go compares a fixed list of labels of the
approval page and of the drawing, and fails until both say the same.
A new package gets a row in this map in the same pull request, and a row in
Map of packages. It also gets a
row in the map of the user manual below, or a place in its list of areas with
no manual page. A new file in internal/service or internal/mime gets a line
in the list of its package above.
The site check (test/sitecheck/maps.go) fails when a Go package
of cmd/ or internal/ has no row in one of the two maps, and when the first
column of a map names a path that does not exist. It does not check the lists
of internal/service and internal/mime, or the pages that a row names.
Map of the user manual
Each row names a part of the code and the manual pages that may need a change.
The manual pages also list their code in code_areas, but they do not show the
list.
| Code | Manual pages |
|---|---|
cmd/email-mcp/main.go (the list of commands, the help) |
Commands, Install email-mcp, Update email-mcp |
cmd/email-mcp/serve.go |
Commands, Local HTTP mode, Containers, Connect an AI app and its five app pages |
cmd/email-mcp/setup.go |
Connect your first account, The web pages, Commands |
cmd/email-mcp/account.go, connect.go |
Connect your first account, Manage accounts, Commands |
cmd/email-mcp/reconnect.go |
Connect your first account, Manage accounts, Commands, Known limitations |
cmd/email-mcp/token.go |
Local HTTP mode, Commands |
cmd/email-mcp/outbox.go |
Activity and undo, Commands, Update email-mcp |
cmd/email-mcp/importenv.go |
Moving from the old email-mcp, Commands |
cmd/email-mcp/key.go |
The master key, Commands |
cmd/email-mcp/doctor.go |
Your first use, Troubleshooting, The master key, Commands, Update email-mcp |
cmd/email-mcp/console.go (the flags that all commands share) |
Commands, Where the data lives |
internal/mcpserver/read_tools.go, write_tools.go |
What the agent can do, Permission levels |
internal/mcpserver/shape.go |
What the agent can do, Known limitations |
internal/mcpserver/server.go (Instructions, the text that the server sends to the agent) |
What the agent can do |
internal/mcpserver/elicit.go |
Confirmations, How each AI app confirms, Your first use, Connect an AI app and its five app pages |
internal/mcpserver/errors.go |
Troubleshooting |
internal/mcpserver/capture.go |
Activity and undo |
internal/policy/policy.go |
Permission levels, Local HTTP mode |
internal/policy/limiter.go |
Full autonomy, limits and settings |
internal/domain/account |
Permission levels, Full autonomy, limits and settings, Your first use |
internal/tokens |
Local HTTP mode |
internal/httpserve |
Local HTTP mode, How each AI app confirms |
internal/confirm |
Confirmations, How each AI app confirms |
internal/outbox |
Full autonomy, limits and settings, Activity and undo, Known limitations |
internal/audit (the activity log) |
Activity and undo |
internal/web/server.go (the routes), templates/layout.html (the menu) |
The web pages |
internal/web/session.go, guard.go, links.go |
Connect your first account, The web pages, Security |
internal/web/accounts.go |
Connect your first account, The web pages |
internal/web/templates/connect.html |
Connect your first account |
internal/web/templates/accounts.html |
Manage accounts, The web pages, Connect your first account, Permission levels |
internal/web/settings.go, templates/settings.html |
Permission levels, Full autonomy, limits and settings, Manage accounts; settings.go also Your first use |
internal/web/reconnect.go, templates/reconnect.html |
Manage accounts |
internal/web/approvals.go, templates/approval.html, templates/approvals.html |
Confirmations, The web pages; approvals.go and approval.html also Your first use |
internal/web/activity.go, templates/activity.html |
Activity and undo |
internal/web/connections.go, templates/connections.html |
Local HTTP mode, The web pages |
internal/web/templates/message.html (the notice page, such as “It is too late to cancel this send”) |
Activity and undo |
internal/web/static/ (the styles, the script and the icon of the web pages) |
The web pages. make site makes the images of the manual again, so a change of the look alone needs no text change. |
internal/web/templates/no_session.html, use_name.html |
Connect your first account, Troubleshooting, The web pages |
internal/mime |
What the agent can do, Security, Known limitations |
internal/provider/imapsmtp |
What the agent can do, Connect your first account, Troubleshooting |
internal/discovery |
Connect your first account, Manage accounts |
internal/connect |
Connect your first account, Manage accounts, Troubleshooting |
internal/secrets |
The master key, Where the data lives, Recommended Claude Code deny rules, Troubleshooting |
internal/app/kek.go |
The master key, Where the data lives, Containers |
internal/app/app.go |
Where the data lives, Activity and undo, Recommended Claude Code deny rules, Update email-mcp |
internal/store |
Where the data lives, Troubleshooting, Update email-mcp |
internal/version |
Install email-mcp, Update email-mcp |
.goreleaser.yaml |
Install email-mcp, Update email-mcp, Verifying a release |
.github/workflows/release.yml |
Verifying a release |
Dockerfile |
Containers, Update email-mcp |
| The code of the behaviour that the landing page states: the levels, the defaults of a new account, the approval page, the Trash rules, the activity log | Not a manual page: read again the words with the truth notes (T1, T2 and so on) in site/content/_index.md |
The landing page is not a page of the manual, but the person reads it first. Its claims have truth notes (see The landing page truth table).
These areas have no manual page: internal/service, internal/domain/mail,
internal/signing, internal/inflight, internal/errtype,
internal/thirdparty, internal/e2e and internal/testutil. A change in
internal/service reaches the person through a tool or a web page, so use the
row of that tool or page. Some files of a mapped package have no row, such as
internal/app/sender.go, because no manual page describes them. If a change of
such a file is something that a person can see, find the page that shows it,
and add a row here.
The landing page truth table
The truth table is the list of the claims of the landing page, each with the
code that proves it. It is in the design document of the landing page,
docs/superpowers/specs/2026-11-05-landing-page-design.md. The
other design documents are history, but this table is kept current, because
site/content/_index.md and test/sitecheck/landing_test.go point to it.
Each claim on the landing page has a truth note, such as T13: a comment in
the front matter (the block of settings at the top of the file), or the
shortcode truth in the body. The note names the row of the claim in the
table. When a change touches the code that a row names, read the words with
that note again. These rows cover the levels, the defaults of a new account,
the approval page, the Trash rules and the activity log.
Find the pages that name a path
The maps name the pages to read first. A search finds the pages that contain a
path, in their code_areas (the list of code in the front matter, the block of
settings at the top of the file) or in their text. Run it from the root of the
repository. grep -rl prints the name of each file that holds the text (-r:
in every folder below, -l: only the names of the files).
--exclude=local-development.md leaves out this page, because its maps name
most paths:
grep -rl --exclude=local-development.md 'internal/outbox/' site/content
A page may name a file by its short name only, such as outbox.go, so search
for the short name too.
The docs site
The docs site is built with Hugo, a program that makes web pages from Markdown
files. Its files are under site/. Three targets build it:
make screenshotsmakes the images of the user manual insite/assets/screenshots/. The images are not in git.make sitemakes the images, builds the site intosite/public/, and checks it.make site-servemakes the images and shows the site onhttp://localhost:1313/. It builds the pages again when a file changes.
make site runs these steps:
- Hugo builds the site.
--panicOnWarningturns a Hugo warning into an error, so a warning cannot reach the published site. - The site check
test/sitecheck/main.goreads the built pages and the Markdown files. It fails on each rule that the comment at its top lists, for example a broken link or anchor, an image with no alt text, a path incode_areasthat does not exist, or a line of more than 80 characters outside a code block and a table. - Hugo builds the site again with the test pages of the table hook (the template that turns a Markdown table into HTML). The check reads that build too, and a test checks each test table.
- A test opens every page in Chrome at the width of a phone, and fails when a page scrolls sideways.
The links to the code on a page that you build go to the branch main. On a
tag, the publish workflow points them at the tag, and on any other run at the
commit (see Making a release).
make screenshots needs Chrome, and so does the last step of make site. The
images come from TestScreenshots in
internal/e2e/screenshots_test.go: it starts the whole program
with sample data, and a headless Chrome (Chrome with no window) opens each page
and saves it in light and in dark. Find in
internal/testutil/chrometest/chrometest.go finds Chrome: the
program that CHROME_PATH names when it is set, or else the first of a list of
the usual places on Linux and macOS. One Chrome may run for at most 2 minutes
(timeLimit), so a page that never loads fails the test.
Make runs the tests when the stamp file site/assets/screenshots/.done is
missing, or when a file in cmd/ or internal/, go.mod or go.sum is newer
than it. So a change of the text of the site does not make the images again.
The last step of make site still opens Chrome. This command makes the images
again even when nothing changed (-B: treat every target as out of date):
make -B screenshots
Add or change a shot
A shot is one screen of the program, saved as <name>-light.png and
<name>-dark.png.
- In
TestScreenshots, bring the program to the state that the screen needs through the real paths: connect the sample account (h.connect), and call tools with the MCP client. Use only addresses onexample.com. - Open the page with
s.open(link, want...), or click to it withs.click(selector, ready, want...).wantare texts that the page must show, so a renamed button fails the test. Choose the height of the window withs.viewport:shotHeight(800 pixels) orshotHeightShort(420). The width isshotWidth(1280). - Call
s.shot("name"). It fails when the page shows an access token or one of the values inforbidden, such as the password and the sign-in link. - Take no shot while a form is busy: its busy sign never ends, and the shot
waits until the time limit. For a result that comes from the outbox (the
queue of sends), use
s.reloadUntil. - Put the image on the manual page with the shortcode of
site/layouts/_shortcodes/screenshot.html. Its alt text says what the screen shows. Each step in the text must work without the image. - Run
make -B screenshots, thenmake site.
This is the shortcode on a page:
{{< screenshot name="waiting" alt="The approval page with the send" >}}
A long alt text does not fit on one line of 80 characters. Write it between
back quotes (`) over several lines: the shortcode joins the lines into
one.
To change a shot, change its steps or its want texts. To remove one, remove
its s.shot call and its shortcode. The Hugo build fails when a page uses a
shot that has no images, because the shortcode stops it. The site check fails
when an image is not used. TestScreenshots
removes the old images at the start, so the image of a removed shot does not
stay.
Build and try the container image
A container is a way to run a program in its own closed space, and the image is the package that holds the program. The image is for tests and for building on, not for daily use. The manual page Containers explains why it does not suit use on your own computer.
Build it yourself
These commands build the image from the Dockerfile in the
current folder and name it email-mcp:dev (-t: the name of the image). Then
they run the program in it once to print its version (--rm: delete the
container when it stops). It prints email-mcp dev, because the build argument
VERSION of the Dockerfile is dev by default:
docker build -t email-mcp:dev .
docker run --rm email-mcp:dev version
The Dockerfile compiles the binary from the source code by default. The
release builds its image from the same Dockerfile with the binary that
GoReleaser built (see The container image). The build does not send
the files that .dockerignore lists to the builder, such as
.git/, docs/, site/ and the Markdown files in the root of the repository.
Try it
This starts the server inside the container with a key file in the home
folder of the container. It serves MCP over stdio (standard input and output),
so it reads MCP messages from standard input (-i) and waits for them. -e
sets an environment variable (a named setting that a program reads from its
surroundings) in the container: EMAIL_MCP_KEK says where the master key (the
key that protects the other keys) is. It has no account, so it is only a smoke
test (a short test that only shows that the program starts):
docker run --rm -i -e EMAIL_MCP_KEK=file:/home/nonroot/kek.key email-mcp:dev
The data (the database and the key file) is lost when the container stops, because it is not on a volume (a folder that Docker keeps outside the container). Do not add a real mail account to this container. If you keep its data on a volume, keep the key file in a different place from the database.
Related pages
- Testing
- Making a release
- Map of packages
- One tool call, step by step
- Containers in the user manual
Code covered by this page
Makefile.go-versiongo.mod.golangci.yml.github/workflows/ci.yml.github/dependabot.yml.github/copilot-instructions.mdinternal/mcpserver/server.gointernal/mcpserver/read_tools.gointernal/mcpserver/write_tools.gointernal/mcpserver/capture.gointernal/mcpserver/capture_test.gointernal/mcpserver/read_tools_test.gointernal/mcpserver/write_tools_test.gointernal/mcpserver/useronly_test.gointernal/service/accounts.gointernal/e2e/security_test.gointernal/e2e/capture_test.gocmd/email-mcp/main.gocmd/email-mcp/serve_test.gointernal/store/migrations/internal/e2e/screenshots_test.gointernal/testutil/chrometest/chrometest.gosite/layouts/_shortcodes/screenshot.htmltest/sitecheck/main.gotest/sitecheck/maps.gotest/socialcard/test/docscheck/main.go.github/workflows/docs-check.yml.github/pull_request_template.mdDockerfile.dockerignore.hugo-versionsite/hugo.tomlsite/config/site/assets/