tallied

Tallied

Tallied は、時間記録と請求書作成を行う MCP サーバーです。コネクターを中心に設計されており、Claude や ChatGPT（または任意の MCP クライアント）が主な UI です。アシスタントに作業内容を伝えると時間が記録され、未請求の項目を尋ねると請求書の下書きが作成されます。シンプルなウェブアプリでは、チャットに向かないアカウント設定、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、ウェブアプリ、請求書ページのすべてがここから配信されます
MCP_URL	いいえ（デフォルトは ${BASE_URL}/mcp）	MCP エンドポイントを独自のサブドメインに配置する場合に指定します
AUTH_ISSUER_URL	いいえ（デフォルトは BASE_URL）	OAuth 認可サーバーを独自のサブドメインに配置する場合に指定します
APP_URL	いいえ（デフォルトは ${BASE_URL}/app）	ウェブアプリを独自のサブドメインに配置する場合に指定します
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	いいえ	ディレクトリのレビュー担当者が、シード済みの 1 つのアカウントにアクセスコードでサインインできるようにします。レビュー後に削除してください
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 にマウントし、Postgres にクライアント、コード、トークンを永続化する TallyOAuthProvider（src/auth/provider.ts）に接続します。
• ID 認証には Google OIDC またはメールで送信されるマジックリンクを使用します。パスワードは使用しません。src/auth/routes.ts を参照してください。
• OAuth の同意画面がサインアップを兼ねています。 まだワークスペースを持っていないユーザーには、同意ページ上にオンボーディングカード（事業名、デフォルトの料金、通貨、タイムゾーン）が表示されます。「許可」をクリックすると、ワークスペースが作成され、1 回の操作で認可が完了します。
• トークンは不透明で、保存時にはハッシュ化されます（平文では保存されません）。アクセストークンの有効期間は 1 時間、リフレッシュトークンは 30 日で、使用するたびにローテーションされます。再利用検出機能も備えており、ローテーション済みのリフレッシュトークンが再利用されると、トークンファミリー全体が無効になります。
• TallyOAuthProvider の代わりにホスト型の ID／OAuth プロバイダー（Clerk、WorkOS、Stytch）を使用するには、同じプロトコルのインターフェースを上流の認可サーバーに委譲する 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 を使用する場合は、${BASE_URL}/webhooks/stripe に Webhook エンドポイントを登録し、checkout.session.completed、payment_intent.succeeded、customer.subscription.updated、および customer.subscription.deleted を購読します。
5. Google サインインを使用する場合は、Google OAuth クライアントの認可済みリダイレクト URI として ${BASE_URL}/oauth/google/callback を追加します。

テスト

• npm test — ユニットテスト（vitest）。
• test/golden-prompts.json — プロンプトと、期待されるツール呼び出しの動作を厳選してまとめたファイルです。ツール名、説明、入力スキーマを変更する前には、Claude と ChatGPT の両方で手動実行します。これらは実質的にモデル向けの公開 API であり、ここでのリグレッションはユニットテストでは検出されません。

提出チェックリスト

コネクタディレクトリに提出する前に、ストア掲載用の紹介文とスクリーンショットについては docs/listing.md を、要件全体については製品仕様書の提出チェックリストを確認してください。なお、Claude のコネクタディレクトリに提出する組織には、Team または Enterprise プランが必要です。