tallied

Tallied

Tallied 是一款时间跟踪与开票 MCP 服务。它以连接器为先：Claude 和 ChatGPT（或任何 MCP 客户端）是主要界面——告诉助手你做了什么，它就会记录工时；询问哪些工时尚未开票，它就会起草发票。简约的 Web 应用负责处理聊天不擅长的事务：账户设置、CSV 导入和账单管理。客户可通过公开的令牌化页面上的 Stripe 付款链接支付发票。

Claude / ChatGPT / MCP client
        │  MCP over Streamable HTTP (OAuth 2.1 bearer token)
        ▼
┌───────────────────────────────────────────────┐
│  one origin (BASE_URL)                         │
│  /mcp            MCP endpoint                  │
│  /authorize /token /register /revoke           │
│                   OAuth 2.1 authorization server│
│  /app/*          web app (settings, import,     │
│                   billing)                      │
│  /i/<token>      public invoice page + PDF      │
└───────────────────────────────────────────────┘
        │                    │                │
        ▼                    ▼                ▼
    Postgres              Stripe        SMTP / Resend
 (workspaces, entries,  (subscriptions,  (magic links,
  invoices, tokens,      payment links)   invoice emails)
  audit log)
                                          pdfkit (invoice PDFs, in-process)

快速开始

cp .env.example .env
npm install
npm run db:up          # postgres via docker compose, localhost:5433
npm run db:migrate     # applies src/db/schema.sql idempotently
npm run db:seed        # seeds a demo workspace; prints the login email
# In production (compiled image, no tsx): node dist/scripts/seed.js [email protected]
npm run build:app      # builds the MCP App UI bundle into app/dist/app.html
npm run dev            # tsx watch src/index.ts

然后使用 MCP Inspector 连接：

npm run inspector

选择 Streamable HTTP，将其指向 http://localhost:3000/mcp，然后连接。Inspector 会启动 OAuth 流程，并在浏览器中打开登录页面。如果未设置 SMTP_URL 或 RESEND_API_KEY，魔法链接登录不会发送电子邮件——链接会打印到服务日志中，也会直接显示在“检查你的邮箱”页面上，因此本地开发无需真实邮箱。

项目布局

src/
  index.ts       entry point
  config.ts      env vars, plans, scopes
  db/            schema.sql, migration runner, query helpers
  lib/           dates, duration parsing, rates, ids, errors, money
  services/      workspace, time entries, invoices, propose (catch-up), audit
  mcp/           McpServer setup: tools, resources, prompts (src/mcp/server.ts)
  auth/          OAuth provider, login/consent routes, sessions, Google OIDC
  http/          express app, docs/marketing routes, web app routes, invoice pages
  import/        CSV import (Toggl/Harvest/Clockify)
  stripe/        billing checkout, Connect onboarding, webhook handling
  email/         email sending via SMTP (nodemailer) or Resend (magic links, invoice emails)
  pdf/           invoice PDF rendering (pdfkit)
app/             MCP App UI source; scripts/build-app.ts bundles it into app/dist/app.html,
                 which src/mcp/app-resource.ts embeds as an MCP UI resource and
                 src/http/routes/invoice-public.ts reuses for the public invoice page
skills/          bundled Claude skills (log-day, catch-up, weekly-report,
                 invoice-client, month-close) — also exposed as MCP prompts
.claude-plugin/  Claude plugin/connector manifest
.codex-plugin/   ChatGPT/Codex plugin manifest
docs/            privacy.md, terms.md, docs.md, landing.md, llms.txt — served live
                 at /privacy, /terms, /docs, /, and /llms.txt by src/http/routes/docs.ts
test/            unit tests (vitest) and the golden prompt set

环境变量

变量	必需	用途
NODE_ENV	否（默认值为 development）	production 会启用仅限生产环境的行为（速率限制，不提供开发环境魔法链接快捷方式）
PORT	否（默认值为 3000）	HTTP 端口
BASE_URL	否（默认值为 http://localhost:3000）	公共源地址。默认情况下，MCP、OAuth、Web 应用和发票页面都通过此地址提供
MCP_URL	否（默认值为 ${BASE_URL}/mcp）	可覆盖此值，将 MCP 端点放到独立子域名上
AUTH_ISSUER_URL	否（默认值为 BASE_URL）	可覆盖此值，将 OAuth 授权服务器放到独立子域名上
APP_URL	否（默认值为 ${BASE_URL}/app）	可覆盖此值，将 Web 应用放到独立子域名上
DATABASE_URL	否（默认值为本地 docker-compose Postgres）	Postgres 连接字符串
SESSION_SECRET	生产环境必需	用于签署会话 Cookie 和魔法链接；openssl rand -hex 32
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET	否	启用“使用 Google 继续”；省略则仅提供魔法链接
REVIEWER_EMAIL / REVIEWER_ACCESS_CODE	否	为目录审核者启用访问码登录，并登录到一个预置账户。审核后请移除
SMTP_URL	否	任意 SMTP 服务商，例如 smtps://LOGIN:[email protected]:465；优先于 Resend
RESEND_API_KEY	否	SMTP_URL 的替代选项。两者均未设置时，电子邮件会打印到日志中（仅限开发环境）
EMAIL_FROM	否	外发电子邮件的发件人地址
STRIPE_SECRET_KEY	否	启用账单结账和发票付款链接
STRIPE_WEBHOOK_SECRET	否（设置 STRIPE_SECRET_KEY 时必需）	验证 /webhooks/stripe 负载
STRIPE_PRICE_PRO / STRIPE_PRICE_TEAM	否	付费套餐的价格 ID
STRIPE_CONNECT_FEE_BPS	否（默认值为 0）	Connect 付款链接可选的平台费用，以基点为单位
PRODUCT_NAME	否（默认值为 Tallied）	用于电子邮件、文档页面和 MCP 服务元数据
SUPPORT_EMAIL	否（默认值为 support@localhost）	显示在文档和授权页面中

请参阅 .env.example，查看带有行内注释的相同列表。

OAuth 说明

• @modelcontextprotocol/sdk 路由器（mcpAuthRouter）提供协议接口：动态客户端注册、PKCE（S256）、表单编码的令牌端点，以及 RFC 8414 + RFC 9728 发现元数据。src/http/app.ts 会在 AUTH_ISSUER_URL 挂载该路由器，并将其连接到 TallyOAuthProvider（src/auth/provider.ts），后者会在 Postgres 中持久化客户端、授权码和令牌。
• 身份验证采用 Google OIDC 或通过电子邮件发送的魔法链接，不使用密码。请参阅 src/auth/routes.ts。
• OAuth 同意页面就是注册页面。 尚无工作区的用户会在同意页面内看到一张入门卡片（包含企业名称、默认费率、货币和时区）；点击 Allow 即可创建工作区并一步完成授权。
• 令牌是不透明的，静态存储时会进行哈希处理（绝不会以明文存储）。访问令牌有效期为 1 小时；刷新令牌有效期为 30 天，并会在每次使用时轮换，同时启用重用检测（重用已轮换的刷新令牌会撤销整个令牌系列）。
• 若要改用托管身份验证 / OAuth 提供商（Clerk、WorkOS、Stytch），而非 TallyOAuthProvider，请将其替换为 SDK 的 ProxyOAuthServerProvider，后者会将相同的协议接口委托给上游授权服务器。

部署

Tallied 可运行于任何能提供稳定 HTTPS 源站的主机上，例如 Fly.io、Railway、Render 等。

1. 将 BASE_URL 设置为你的公开源站。仅当需要将这些接口分散到不同子域名时，才设置 MCP_URL、AUTH_ISSUER_URL 和 / 或 APP_URL。
2. 运行 npm run build（依次执行 build:app 和 tsc），然后运行 npm start。
3. 将 Postgres 连接配置到 DATABASE_URL，然后运行 npm run db:migrate。
4. 如果使用 Stripe，请注册 webhook 端点 ${BASE_URL}/webhooks/stripe，并订阅 checkout.session.completed、payment_intent.succeeded、customer.subscription.updated 和 customer.subscription.deleted。
5. 如果使用 Google 登录，请在 Google OAuth 客户端中将 ${BASE_URL}/oauth/google/callback 添加为获授权的重定向 URI。

测试

• npm test — 单元测试（vitest）。
• test/golden-prompts.json — 人工整理的提示词和预期工具调用行为集合。每当工具名称、描述或输入架构发生变化时，都会在 Claude 和 ChatGPT 中手动运行；这些内容实际上构成了模型的公共 API，而相关回归问题不会在单元测试中显现。

提交检查清单

在提交至连接器目录之前，请参阅 docs/listing.md，了解商店列表文案和截图，并参阅产品规格中的提交检查清单，获取完整要求。请注意，Claude 的连接器目录要求提交组织使用 Team（或 Enterprise）计划。