feat: add i18n support

.github/workflows/content-generation.yml

@@ -0,0 +1,105 @@
+name: Content generation
+
+env:
+  CONTENT_GENERATION_BRANCH_NAME: bot-generate-doc-contents
+
+on:
+  push:
+    branches:
+      - master
+
+concurrency:
+  group: content-generation-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  content-generation:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.BOT_PAT }}
+          ref: master
+          fetch-depth: 0
+
+      - name: Setup Node and pnpm
+        uses: silverhand-io/actions-node-pnpm-run-steps@v5
+        with:
+          node-version: 22
+          pnpm-version: 10
+
+      - name: Import GPG key
+        uses: crazy-max/ghaction-import-gpg@v6
+        with:
+          gpg_private_key: ${{ secrets.BOT_GPG_KEY }}
+          passphrase: ${{ secrets.BOT_GPG_PASSPHRASE }}
+          git_user_signingkey: true
+          git_commit_gpgsign: true
+          git_tag_gpgsign: true
+
+      - name: Configure Git user
+        run: |
+          git config --global user.email bot@silverhand.io
+          git config --global user.name silverhand-bot
+
+      - name: Translate documentations
+        env:
+          OPENAI_ORG_ID: ${{ secrets.OPENAI_ORG_ID }}
+          OPENAI_PROJECT_ID: ${{ secrets.OPENAI_PROJECT_ID }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+        run: |
+          node translate.mjs --sync --all --silent
+        continue-on-error: true
+
+      - name: Write heading IDs
+        run: |
+          node write-heading-ids.mjs
+        continue-on-error: true
+
+      - name: Build
+        run: pnpm build
+        continue-on-error: true
+
+      - name: Lint with autofix
+        run: pnpm lint --fix
+        continue-on-error: true
+
+      - name: Check Git status to determine if the PR is needed
+        id: check-changes
+        run: |
+          git add .
+          git status --porcelain
+          if [[ -n "$(git status --porcelain)" ]]; then
+            echo "HAS_CHANGES=true" >> $GITHUB_OUTPUT
+          else
+            echo "HAS_CHANGES=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Create pull request
+        uses: peter-evans/create-pull-request@v7
+        if: steps.check-changes.outputs.HAS_CHANGES == 'true'
+        with:
+          token: ${{ secrets.BOT_PAT }}
+          branch: ${{ env.CONTENT_GENERATION_BRANCH_NAME }}
+          committer: silverhand-bot <bot@silverhand.io>
+          title: "chore: update translations and generated content"
+          commit-message: "chore: update translations and generated content"
+          body: |
+            This is an automatic pull request to update the i18n translations and programmatic SEO content to the latest commit hash.
+            If you want to debug the PR manually, please run the following command:
+
+            ```bash
+            node translate.mjs --sync --all
+            node write-heading-ids.mjs
+            pnpm build
+            pnpm lint
+            ```
+
+            And then commit all generated resources.
+          labels: |
+            i18n
+            tutorial
+            bot
+          draft: false
+          delete-branch: true

.gitignore

@@ -21,3 +21,6 @@ yarn-error.log*
 
 # MCP Auth SDK source files
 /sdk/
+
+# Environment variables
+.env

docs/README.mdx

@@ -8,7 +8,7 @@ import Tabs from '@theme/Tabs';
 
 # Get started
 
-## Choose a compatible OAuth 2.1 or OpenID Connect provider
+## Choose a compatible OAuth 2.1 or OpenID Connect provider \{#choose-a-compatible-oauth-2-1-or-openid-connect-provider}
 
 MCP specification has some [specific requirements](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization#1-3-standards-compliance) for authorization:
 
@@ -24,7 +24,7 @@ In the new MCP draft, RFC 8414 will be mandated for authorization servers (provi
 
 You can check the [MCP-compatible provider list](./provider-list.mdx) to see if your provider is supported.
 
-## Install MCP Auth SDK
+## Install MCP Auth SDK \{#install-mcp-auth-sdk}
 
 MCP Auth is available for both Python and TypeScript. Let us know if you need support for another language or framework!
 
@@ -49,7 +49,7 @@ Or any other package manager you prefer, such as pnpm or yarn.
 </TabItem>
 </Tabs>
 
-## Init MCP Auth
+## Init MCP Auth \{#init-mcp-auth}
 
 The first step is to initialize the MCP Auth instance with your provider's authorization server metadata. If your provider conforms one of:
 
@@ -90,7 +90,7 @@ const mcpAuth = new MCPAuth({
 
 If you need to manually specify the metadata URL or endpoints, check [Other ways to initialize MCP Auth](./configure-server/mcp-auth.mdx#other-ways).
 
-## Mount the metadata endpoint
+## Mount the metadata endpoint \{#mount-the-metadata-endpoint}
 
 To conform to the current MCP specification, MCP Auth mounts the OAuth 2.0 Authorization Server Metadata endpoint (`/.well-known/oauth-authorization-server`) to your MCP server:
 
@@ -120,7 +120,7 @@ app.use(mcpAuth.delegatedRouter());
 
 The URLs in the metadata are kept as-is, so the role of authorization server is fully delegated to the provider. You can test the metadata endpoint by visiting `/.well-known/oauth-authorization-server` in your MCP server.
 
-### Why only the metadata endpoint?
+### Why only the metadata endpoint? \{#why-only-the-metadata-endpoint}
 
 You may see the official SDKs provide an auth router that mounts authorization endpoints like `/authorize`, `/token`, etc. Here is why we don't do that:
 
@@ -131,7 +131,7 @@ You may see the official SDKs provide an auth router that mounts authorization e
 We will update MCP Auth to support the new MCP specification when it is finalized. In the meantime, you can use the current version which is compatible with the current specification.
 :::
 
-## Use the Bearer auth middleware
+## Use the Bearer auth middleware \{#use-the-bearer-auth-middleware}
 
 Once the MCP Auth instance is initialized, you can apply the Bearer auth middleware to protect your MCP routes:
 
@@ -190,7 +190,7 @@ Didn't hear about JWT (JSON Web Token) before? Don't worry, you can keep reading
 
 For more information on the Bearer auth configuration, check the [Configure Bearer auth](./configure-server/bearer-auth.mdx).
 
-## Retrieve the auth info in your MCP implementation
+## Retrieve the auth info in your MCP implementation \{#retrieve-the-auth-info-in-your-mcp-implementation}
 
 Once the Bearer auth middleware is applied, you can access the authenticated user's (or identity's) information in your MCP implementation:
 
@@ -237,6 +237,6 @@ server.tool('add', { a: z.number(), b: z.number() }, async ({ a, b }, { authInfo
 </TabItem>
 </Tabs>
 
-## Next steps
+## Next steps \{#next-steps}
 
 Continue reading to learn an end-to-end example of how to integrate MCP Auth with your MCP server, and how to handle the auth flow in MCP clients.

docs/comparison.mdx

@@ -9,7 +9,7 @@ The MCP ecosystem is evolving. As the Model Context Protocol (MCP) specification
 
 This page outlines the main differences between mcp-auth and other popular solutions, to help you choose the best approach for your project.
 
-## Background: Proxy approach vs. IdP integration
+## Background: Proxy approach vs. IdP integration \{#background-proxy-approach-vs-idp-integration}
 
 Most existing MCP auth solutions use a “proxy approach.” In this model, the MCP server proxies authorization requests to a third-party Identity Provider (IdP), effectively acting as a middleman between the client and the IdP.
 
@@ -59,7 +59,7 @@ sequenceDiagram
 
 The upcoming MCP spec [shifts responsibility for authorization to a dedicated third-party IdP](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/205). In this model, the MCP server only serves as a resource server, and all authorization endpoints come directly from the third-party IdP.
 
-## Why choose MCP Auth?
+## Why choose MCP Auth? \{#why-choose-mcp-auth}
 
 - Spec alignment: MCP Auth directly follows the direction of the latest draft, making it the only solution compatible with both the 03-26 spec and the upcoming spec.
 - No more workarounds: Instead of acting as an authorization server proxy, MCP Auth lets the third-party IdP handle all authorization, as intended in the new spec.

docs/configure-server/bearer-auth.mdx

@@ -13,11 +13,11 @@ MCP Auth provides various ways to configure Bearer authorization in your MCP ser
 - [JWT (JSON Web Token)](https://auth.wiki/jwt) mode: A built-in authorization method that verifies JWTs with claim assertions.
 - Custom mode: Allows you to implement your own authorization logic.
 
-## Configure Bearer auth with JWT mode
+## Configure Bearer auth with JWT mode \{#configure-bearer-auth-with-jwt-mode}
 
 If your OAuth / OIDC provider issues JWTs for authorization, you can use the built-in JWT mode in MCP Auth. It verifies the JWT signature, expiration, and other claims you specify; then it populates the authentication information in the request context for further processing in your MCP implementation.
 
-### Scope validation
+### Scope validation \{#scope-validation}
 
 Here's an example of the basic scope validation:
 
@@ -66,7 +66,7 @@ app.use('/mcp', bearerAuth, (req, res) => {
 
 In the example above, we specified that the JWT requires the `read` and `write` scopes. If the JWT does not contain **any** of these scopes, the request will be rejected with a 403 Forbidden error.
 
-### Resource indicator validation (RFC 8707)
+### Resource indicator validation (RFC 8707) \{#resource-indicator-validation-rfc-8707}
 
 If your provider is based on OIDC, or supports the [Resource Indicator](https://datatracker.ietf.org/doc/html/rfc8707) extension, you may also specify the `audience` option to validate the `aud` (audience) claim in the JWT. This is useful to ensure that the JWT is intended for your MCP server.
 
@@ -100,7 +100,7 @@ const bearerAuth = mcpAuth.bearerAuth('jwt', {
 
 In the example above, MCP Auth will validate **both** the `aud` claim in the JWT and the required scopes.
 
-### Provide custom options to the JWT verification
+### Provide custom options to the JWT verification \{#provide-custom-options-to-the-jwt-verification}
 
 You can also provide custom options to the underlying JWT verification library:
 
@@ -144,7 +144,7 @@ const bearerAuth = mcpAuth.bearerAuth('jwt', {
 </TabItem>
 </Tabs>
 
-## Configure Bearer auth with custom verification
+## Configure Bearer auth with custom verification \{#configure-bearer-auth-with-custom-verification}
 
 If your OAuth / OIDC provider does not issue JWTs, or you want to implement your own authorization logic, MCP Auth allows you to create a custom verification function:
 
@@ -194,7 +194,7 @@ const bearerAuth = mcpAuth.bearerAuth(
 </TabItem>
 </Tabs>
 
-## Apply Bearer auth in your MCP server
+## Apply Bearer auth in your MCP server \{#apply-bearer-auth-in-your-mcp-server}
 
 To protect your MCP server with Bearer auth, you need to apply the Bearer auth middleware to your MCP server instance.
 

docs/configure-server/mcp-auth.mdx

@@ -10,9 +10,9 @@ import Tabs from '@theme/Tabs';
 
 To connect your MCP server to an OAuth 2.1 or OpenID Connect provider, you need to configure the MCP Auth instance. This involves initializing the instance with your provider's authorization server metadata and setting up the necessary authorization flows.
 
-## Init MCP Auth
+## Init MCP Auth \{#init-mcp-auth}
 
-### Automatic metadata fetching
+### Automatic metadata fetching \{#automatic-metadata-fetching}
 
 The easiest way to initialize the MCP Auth instance is by using the built-in functions that fetch the metadata from a well-known URL. If your provider conforms to one of the following standards:
 
@@ -56,7 +56,7 @@ If your issuer includes a path, the behavior differs slightly between OAuth 2.0
 
 ### Other ways to initialize MCP Auth {#other-ways}
 
-#### Custom data transpilation
+#### Custom data transpilation \{#custom-data-transpilation}
 
 In some cases, the metadata returned by the provider may not conform to the expected format. If you are confident that the provider is compliant, you can use the `transpile_data` option to modify the metadata before it is used:
 
@@ -93,7 +93,7 @@ const mcpAuth = new MCPAuth({
 
 This allows you to modify the metadata object before it is used by MCP Auth. For example, you can add or remove fields, change their values, or convert them to a different format.
 
-#### Fetch metadata from a specific URL
+#### Fetch metadata from a specific URL \{#fetch-metadata-from-a-specific-url}
 
 If your provider has a specific metadata URL rather than the standard ones, you can use it similarly:
 
@@ -127,7 +127,7 @@ const mcpAuth = new MCPAuth({
 </TabItem>
 </Tabs>
 
-#### Fetch metadata from a specific URL with custom data transpilation
+#### Fetch metadata from a specific URL with custom data transpilation \{#fetch-metadata-from-a-specific-url-with-custom-data-transpilation}
 
 In some cases, the provider response may be malformed or not conforming to the expected metadata format. If you are confident that the provider is compliant, you can transpile the metadata via the config option:
 
@@ -162,7 +162,7 @@ const mcpAuth = new MCPAuth({
 </TabItem>
 </Tabs>
 
-#### Manually provide metadata
+#### Manually provide metadata \{#manually-provide-metadata}
 
 If your provider does not support metadata fetching, you can manually provide the metadata object:
 

docs/references/js/README.md

@@ -4,7 +4,7 @@ sidebar_label: Node.js SDK
 
 # MCP Auth Node.js SDK reference
 
-## Classes
+## Classes {#classes}
 
 - [MCPAuth](/references/js/classes/MCPAuth.md)
 - [MCPAuthAuthServerError](/references/js/classes/MCPAuthAuthServerError.md)
@@ -13,7 +13,7 @@ sidebar_label: Node.js SDK
 - [MCPAuthError](/references/js/classes/MCPAuthError.md)
 - [MCPAuthTokenVerificationError](/references/js/classes/MCPAuthTokenVerificationError.md)
 
-## Type Aliases
+## Type Aliases {#type-aliases}
 
 - [AuthorizationServerMetadata](/references/js/type-aliases/AuthorizationServerMetadata.md)
 - [AuthServerConfig](/references/js/type-aliases/AuthServerConfig.md)
@@ -34,7 +34,7 @@ sidebar_label: Node.js SDK
 - [VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md)
 - [VerifyAccessTokenMode](/references/js/type-aliases/VerifyAccessTokenMode.md)
 
-## Variables
+## Variables {#variables}
 
 - [authorizationServerMetadataSchema](/references/js/variables/authorizationServerMetadataSchema.md)
 - [authServerErrorDescription](/references/js/variables/authServerErrorDescription.md)
@@ -44,7 +44,7 @@ sidebar_label: Node.js SDK
 - [tokenVerificationErrorDescription](/references/js/variables/tokenVerificationErrorDescription.md)
 - [validateServerConfig](/references/js/variables/validateServerConfig.md)
 
-## Functions
+## Functions {#functions}
 
 - [createVerifyJwt](/references/js/functions/createVerifyJwt.md)
 - [fetchServerConfig](/references/js/functions/fetchServerConfig.md)