Stash

Stash 是一个使用 Next.js App Router 构建的应用程序，具有第一方电子邮件/密码认证、无状态的 Auth.js 会话、Prisma/PostgreSQL 持久化、通过 Resend 发送的事务性电子邮件，以及通过模型上下文协议 (MCP) 提供的经认证的书签工具。

本地设置

1. 使用 pnpm install 安装依赖。

2. 将 .env.example 复制为 .env 并替换每个占位符。切勿提交 .env。

3. 使用 pnpm exec auth secret（或其他加密安全生成器）生成 AUTH_SECRET。

4. 将 APP_URL 设置为受信任的公共源，本地通常为 http://localhost:3000。生产环境必须使用 HTTPS。

5. 使用在 Resend 中验证过的域名上的发件人配置 EMAIL_FROM。

6. 将 MCP_AUTH_ISSUER 设置为确切的受信任 OAuth 授权服务器颁发者。本地开发可使用回环 HTTP；生产环境颁发者必须使用 HTTPS，且不得包含查询或片段。

7. 使用 pnpm prisma migrate dev 应用迁移。已提交的迁移会创建认证和数据书签表。

8. 使用 pnpm dev 启动应用程序。

服务器会验证 DATABASE_URL、RESEND_API_KEY、AUTH_SECRET、APP_URL、MCP_AUTH_ISSUER 和 EMAIL_FROM，并报告无效的变量名，而不会打印其值。

Related MCP server: bookmark-mcp

认证行为

• /signup 创建凭据用户，发送尽力而为的欢迎电子邮件，并让用户登录。

• /login 创建一个七天的、经过加密的、仅 HTTP 的 Auth.js Cookie 会话。

• /forgot-password 对于有效的电子邮件语法，始终返回抗账户枚举的响应。

• /reset-password 消耗一个经过 SHA-256 哈希的、60 分钟有效的、一次性使用的令牌，并通过递增用户的会话版本来撤销旧会话。

• / 在渲染之前通过 DAL 根据当前数据库记录进行授权。

lib/rate-limit.ts 是未来共享 IP/电子邮件限制器的扩展点。基于数据库的每账户 60 秒冷却本身并不是一个完整的生产环境滥用控制系统。

书签 MCP

无状态的、仅限现代的 MCP 端点是 POST /api/mcp。其规范的 RFC 8707 资源标识符和访问令牌受众始终为 ${APP_URL}/api/mcp。公开的 RFC 9728 发现在 /.well-known/oauth-protected-resource/api/mcp 可用；Stash 不提供授权、令牌、注册、撤销或 JWKS 端点。

该端点恰好暴露四个工具：

• add_bookmark 和 delete_bookmark 需要 bookmarks:write。

• list_bookmarks 和 search_bookmarks 需要 bookmarks:read。

同源的 Stash 客户端可以使用其 Auth.js Cookie 并获得这两种能力。远程原生、桌面和服务端客户端在每个请求中发送不记名访问令牌。浏览器跨源 MCP 调用被有意不支持。401 质询将客户端指向受保护资源文档；403 insufficient_scope 质询标识了有界 OAuth 升级所需的确切范围。

Stash 仅是一个 OAuth 2.1 受保护资源。单独运行的授权服务器必须支持带有 PKCE S256 的授权码、针对确切规范 MCP URI 的资源指示符，以及授权响应颁发者标识。它必须发布经过验证的 RFC 8414 或 OpenID 发现元数据、jwks_uri 和包含允许的非对称算法（RS256 或 ES256）的 access_token_signing_alg_values_supported。

访问令牌必须是短期的 JWT 访问令牌，带有受保护头部 typ: at+jwt 和 kid。必需声明包括确切的 iss、确切的单资源 aud、sub 中的本地 Stash 用户 ID、exp、iat、空格分隔的 scope、client_id（或 azp）以及整数 stash_session_version。授权服务器必须根据当前 Stash 用户行铸造该版本，并将令牌生命周期保持在 60 分钟或以下。它绝不能将电子邮件地址放入 sub 中，也绝不能期望 Stash 从令牌中配置用户。

对于本地远程客户端测试，配置一个回环授权服务器，将 MCP_AUTH_ISSUER 设置为其颁发者，预先注册客户端（或使用客户端 ID 元数据文档），请求确切的 ${APP_URL}/api/mcp 资源加上最少书签范围，并且只将生成的访问令牌发送给 Stash。刷新令牌仅发送给授权服务器。

电子邮件开发

自动化测试模拟 Resend，从不调用其 API。要在不发送邮件的情况下预览模板，请使用本地 React 电子邮件预览工具或仅限开发的私有工具渲染 emails/ 中导出的 React 组件。不要添加公开的 /api/send 端点。对于端到端电子邮件测试，请使用单独的 Resend 测试密钥/发件人和收件箱；切勿使用生产收件人。

验证

pnpm prisma format
pnpm prisma validate
pnpm prisma generate
pnpm lint
pnpm test
pnpm build

数据库集成测试需要隔离的 TEST_DATABASE_URL。浏览器测试需要隔离的测试配置，并使用 pnpm test:e2e 运行。切勿将任一测试套件指向开发或生产数据库，也切勿未经明确批准重置数据库。