diff --git a/docs/README.mdx b/docs/README.mdx index 1c1a3e4..1a5f279 100644 --- a/docs/README.mdx +++ b/docs/README.mdx @@ -3,15 +3,15 @@ sidebar_position: 1 sidebar_label: Get started --- -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - # Get started :::info MCP authorization specification support This version supports the [MCP authorization specification (version 2025-06-18)](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization). ::: +:::tip Python SDK available +MCP Auth is also available for Python! Check out the [Python SDK repository](https://github.com/mcp-auth/python) for installation and usage. +::: ## Choose a compatible OAuth 2.1 or OpenID Connect provider \{#choose-a-compatible-oauth-2-1-or-openid-connect-provider} @@ -28,28 +28,9 @@ You can check the [MCP-compatible provider list](/provider-list) to see if your ## 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! - - - - -```bash -pip install mcpauth -``` - -Or any other package manager you prefer, such as pipenv or poetry. - - - - -```bash -npm install mcp-auth -``` - -Or any other package manager you prefer, such as pnpm or yarn. +import { NpmLikeInstallation } from '@site/src/components/NpmLikeInstallation'; - - + ## Init MCP Auth \{#init-mcp-auth} @@ -62,37 +43,6 @@ If your provider conforms to: You can use the built-in function to fetch the metadata and initialize the MCP Auth instance: - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType, ResourceServerConfig, ResourceServerMetadata -from mcpauth.utils import fetch_server_config - -# 1. Define your resource identifier and fetch the config for its trusted authorization server. -resource_id = "https://api.example.com/notes" -auth_server_config = fetch_server_config("https://auth.logto.io/oidc", AuthServerType.OIDC) - -# 2. Initialize MCPAuth in resource server mode. -# `protected_resources` can be a single object or a list for multiple resources. -mcp_auth = MCPAuth( - protected_resources=ResourceServerConfig( - metadata=ResourceServerMetadata( - resource=resource_id, - authorization_servers=[auth_server_config], - scopes_supported=[ - "read:notes", - "write:notes", - ], - ) - ) -) -``` - - - - ```ts import { MCPAuth, fetchServerConfig } from 'mcp-auth'; @@ -103,20 +53,21 @@ const authServerConfig = await fetchServerConfig('https://auth.logto.io/oidc', { // 2. Initialize MCPAuth in resource server mode. // `protectedResources` can be a single object or an array for multiple resources. const mcpAuth = new MCPAuth({ - protectedResources: [ - { - metadata: { - resource: resourceIdentifier, - authorizationServers: [authServerConfig], - scopesSupported: ['read:notes', 'write:notes'], - }, + protectedResources: { + metadata: { + resource: resourceIdentifier, + authorizationServers: [authServerConfig], + scopesSupported: ['read:notes', 'write:notes'], }, - ], + }, }); ``` - - +If you're using edge runtimes like Cloudflare Workers where top-level async fetch is not allowed, use on demand discovery instead: + +```ts +const authServerConfig = { issuer: 'https://auth.logto.io/oidc', type: 'oidc' }; +``` For other ways to configure authorization server metadata including custom metadata URLs, data transpilation, or manual metadata specification, check [Other ways to configure MCP Auth](./configure-server/mcp-auth.mdx#other-ways). @@ -137,23 +88,6 @@ The MCP server now **serves as a resource server** that validates tokens and pro You can use the SDK provided method to mount this endpoint: - - - -```python -from starlette.applications import Starlette - -# Mount the router to serve the Protected Resource Metadata. -# For resource "https://api.example.com" → endpoint: /.well-known/oauth-protected-resource -# For resource "https://api.example.com/notes" → endpoint: /.well-known/oauth-protected-resource/notes -app = Starlette(routes=[ - *mcp_auth.resource_metadata_router().routes, -]) -``` - - - - ```ts import express from 'express'; @@ -165,9 +99,6 @@ const app = express(); app.use(mcpAuth.protectedResourceMetadataRouter()); ``` - - - ## 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. The middleware now requires specifying which resource the endpoint belongs to, enabling proper token validation: @@ -176,33 +107,9 @@ Once the MCP Auth instance is initialized, you can apply the Bearer auth middlew The `audience` parameter is **required** by the OAuth 2.0 specification for secure token validation. However, it is currently **optional** to maintain compatibility with authorization servers that do not yet support resource identifiers. For security reasons, **please always include the audience parameter** when possible. Future versions will enforce audience validation as mandatory to fully comply with the specification. ::: - - - -```python -from starlette.applications import Starlette -from starlette.middleware import Middleware -from starlette.routing import Mount - -# Create the middleware to protect your MCP server with the resource-specific policy. -bearer_auth = Middleware(mcp_auth.bearer_auth_middleware('jwt', - resource=resource_id, - audience=resource_id, # Enable audience validation for security - required_scopes=['read:notes'] -)) - -# Mount the router to serve the Protected Resource Metadata and protect the MCP server. -app = Starlette( - routes=[ - *mcp_auth.resource_metadata_router().routes, - # Protect the MCP server with the Bearer auth middleware. - Mount("/", app=mcp.sse_app(), middleware=[bearer_auth]), - ], -) -``` +import ScopeValidationWarning from './snippets/_scope-validation-warning.mdx'; - - + ```ts import express from 'express'; @@ -230,9 +137,6 @@ app.get( app.listen(3000); ``` - - - In the examples above, we specify the `jwt` token type and the resource identifier. The middleware will automatically validate the JWT token against the trusted authorization servers configured for that specific resource and populate the authenticated user's information. :::info @@ -245,34 +149,6 @@ For more information on the Bearer auth configuration, check the [Configure Bear Once the Bearer auth middleware is applied, you can access the authenticated user's (or identity's) information in your MCP implementation: - - - -MCP Auth will store the authenticated user's information in a context variable after successful authentication once the Bearer auth middleware is applied. You can access it in your MCP tool handlers like this: - -```python -from mcp.server.fastmcp import FastMCP - -mcp = FastMCP() - -# Initialize with MCP Auth as shown in previous examples -# ... - -@mcp.tool() -def add(a: int, b: int): - """ - A tool that adds two numbers. - The authenticated user's information will be available in the context. - """ - auth_info = mcp_auth.auth_info # Access the auth info in the current context - if auth_info: - print(f"Authenticated user: {auth_info.claims}") - return a + b -``` - - - - The second argument of the tool handler will contain the `authInfo` object, which includes the authenticated user's information: ```ts @@ -284,14 +160,18 @@ const server = new McpServer(/* ... */); // Initialize with MCP Auth as shown in previous examples // ... -server.tool('add', { a: z.number(), b: z.number() }, async ({ a, b }, { authInfo }) => { - // Now you can use the `authInfo` object to access the authenticated information -}); +server.registerTool( + 'add', + { + description: 'Add two numbers', + inputSchema: { a: z.number(), b: z.number() }, + }, + async ({ a, b }, { authInfo }) => { + // Now you can use the `authInfo` object to access the authenticated information + } +); ``` - - - ## 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. diff --git a/docs/configure-server/bearer-auth.mdx b/docs/configure-server/bearer-auth.mdx index 7d6fa14..06cea99 100644 --- a/docs/configure-server/bearer-auth.mdx +++ b/docs/configure-server/bearer-auth.mdx @@ -3,9 +3,6 @@ sidebar_position: 2 sidebar_label: Bearer auth --- -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - # Configure Bearer auth in MCP server With the latest MCP specification, your MCP server acts as a **Resource Server** that validates access tokens for protected resources. MCP Auth provides various ways to configure Bearer authorization: @@ -19,37 +16,17 @@ The Bearer auth middleware now requires specifying which resource the endpoint b 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} - -Here's an example of the basic scope validation: +### Scope and audience validation \{#scope-and-audience-validation} - - - -```python -from mcpauth import MCPAuth -from starlette.applications import Starlette -from starlette.middleware import Middleware -from starlette.routing import Mount -from mcp.server.fastmcp import FastMCP +:::note Audience Validation +The `audience` parameter is **required** by the OAuth 2.0 specification for secure token validation. However, it is currently **optional** to maintain compatibility with authorization servers that do not yet support resource identifiers. For security reasons, **please always include the audience parameter** when possible. Future versions will enforce audience validation as mandatory to fully comply with the specification. +::: -mcp = FastMCP("MyMCPServer") -mcp_auth = MCPAuth( - # Initialize with your auth server config -) -bearer_auth = mcp_auth.bearer_auth_middleware("jwt", - resource="https://api.example.com", # Specify which resource this endpoint belongs to - audience="https://api.example.com", # Enable audience validation for security - required_scopes=["read", "write"] # [!code highlight] -) +import ScopeValidationWarning from '../snippets/_scope-validation-warning.mdx'; -app = Starlette( - routes=[Mount('/', app=mcp.sse_app(), middleware=[Middleware(bearer_auth)])] -) -``` + - - +Here's an example of the basic scope and audience validation: ```ts import express from 'express'; @@ -59,10 +36,10 @@ const app = express(); const mcpAuth = new MCPAuth({ /* ... */ }); -const bearerAuth = mcpAuth.bearerAuth('jwt', { +const bearerAuth = mcpAuth.bearerAuth('jwt', { resource: 'https://api.example.com', // Specify which resource this endpoint belongs to audience: 'https://api.example.com', // Enable audience validation for security - requiredScopes: ['read', 'write'] // [!code highlight] + requiredScopes: ['read', 'write'], }); app.use('/mcp', bearerAuth, (req, res) => { @@ -71,74 +48,14 @@ 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. - -### Audience validation (RFC 8707) \{#audience-validation-rfc-8707} - -For secure token validation, you should always include audience validation by specifying the `audience` parameter. This validates the `aud` (audience) claim in the JWT to ensure that the token was specifically issued for your MCP server resource. - -:::note Audience Validation -The `audience` parameter is **required** by the OAuth 2.0 specification for secure token validation. However, it is currently **optional** to maintain compatibility with authorization servers that do not yet support resource identifiers. For security reasons, **please always include the audience parameter** when possible. Future versions will enforce audience validation as mandatory to fully comply with the specification. -::: - -The audience value should typically match your resource identifier: - - - - -```python -bearer_auth = mcp_auth.bearer_auth_middleware( - "jwt", - resource="https://api.example.com", # Specify which resource this endpoint belongs to - audience="https://api.example.com", # Enable audience validation for security [!code highlight] - required_scopes=["read", "write"] -) -``` - - - - -```ts -const bearerAuth = mcpAuth.bearerAuth('jwt', { - resource: 'https://api.example.com', // Specify which resource this endpoint belongs to - audience: 'https://api.example.com', // Enable audience validation for security [!code highlight] - requiredScopes: ['read', 'write'], -}); -``` - - - +In the example above: -In the example above, MCP Auth will validate **both** the `aud` claim in the JWT and the required scopes. +- The `audience` parameter validates the `aud` claim in the JWT to ensure the token was specifically issued for your MCP server resource. The audience value should typically match your resource identifier. +- The `requiredScopes` parameter specifies that the JWT requires the `read` and `write` scopes. If the token does not contain all of these scopes, an error will be thrown. ### 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: - - - - -In Python SDK, we use [PyJWT](https://pyjwt.readthedocs.io/en/stable/) for JWT verification. You can the following options: - -- `leeway`: Allow a certain amount of leeway when verifying the JWT expiration time (in seconds). Default is 60 seconds. - -```python -bearer_auth = mcp_auth.bearer_auth_middleware( - "jwt", - resource="https://api.example.com", - audience="https://api.example.com", - required_scopes=["read", "write"], - leeway=10, # Reduce clock skew by allowing 10 seconds leeway [!code highlight] -) -``` - - - - -In Node.js SDK, we use [jose](https://github.com/panva/jose) library for JWT verification. You can provide the following options: +You can also provide custom options to the underlying JWT verification library. In Node.js SDK, we use [jose](https://github.com/panva/jose) library for JWT verification. You can provide the following options: - `jwtVerify`: Options for the JWT verification process (`jwtVerify` function from `jose`). - `remoteJwtSet`: Options for fetching the remote JWT set (`createRemoteJWKSet` function from `jose`). @@ -157,9 +74,6 @@ const bearerAuth = mcpAuth.bearerAuth('jwt', { }); ``` - - - ## 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: @@ -168,33 +82,6 @@ If your OAuth / OIDC provider does not issue JWTs, or you want to implement your Since the Bearer auth middleware will check against issuer (`iss`), audience (`aud`), and required scopes (`scope`) with the given verification result, there's no need to implement these checks in your custom verification function. You can focus on verifying the token validity (e.g., signature, expiration, etc.) and returning the auth info object. ::: - - - -```python -from mcpauth.exceptions import MCPAuthJwtVerificationException, MCPAuthJwtVerificationExceptionCode -from mcpauth.types import AuthInfo - -async def custom_verification(token: str) -> AuthInfo: - # Implement your custom verification logic here - info = await verify_token(token) - if not info: - raise MCPAuthJwtVerificationException( - MCPAuthJwtVerificationExceptionCode.JWT_VERIFICATION_FAILED - ) - return info # Return the auth info object - -bearer_auth = mcp_auth.bearer_auth_middleware( - custom_verification, - resource="https://api.example.com", - audience="https://api.example.com", # Enable audience validation for security - required_scopes=["read", "write"] -) -``` - - - - ```ts const bearerAuth = mcpAuth.bearerAuth( async (token) => { @@ -205,76 +92,42 @@ const bearerAuth = mcpAuth.bearerAuth( } return info; // Return the auth info object }, - { + { resource: 'https://api.example.com', audience: 'https://api.example.com', // Enable audience validation for security - requiredScopes: ['read', 'write'] + requiredScopes: ['read', 'write'] } ); ``` - - - ## 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. - - - -```python -bearer_auth = mcp_auth.bearer_auth_middleware("jwt", - resource="https://api.example.com", - audience="https://api.example.com", # Enable audience validation for security - required_scopes=["read", "write"] -) -app = Starlette( - routes=[Mount('/', app=mcp.sse_app(), middleware=[Middleware(bearer_auth)])] -) -``` - - - - -```js +```ts const app = express(); -app.use(mcpAuth.bearerAuth('jwt', { +app.use(mcpAuth.bearerAuth('jwt', { resource: 'https://api.example.com', audience: 'https://api.example.com', // Enable audience validation for security - requiredScopes: ['read', 'write'] + requiredScopes: ['read', 'write'] })); ``` - - - This will ensure that all incoming requests are authenticated and authorized according to the configured Bearer auth settings, and the auth information will be available in the request context. You can then access the information in your MCP server implementation: - - - -```python -@mcp.tool() -async def whoami() -> dict: - # `mcp_auth.auth_info` is the context object for the current request - auth_info = mcp_auth.auth_info - print(f"Authenticated user: {auth_info.subject}") - return {"subject": auth_info.subject} -``` - - - - -```js +```ts // `authInfo` will be carried from the `req.auth` object -server.tool('whoami', ({ authInfo }) => { - console.log(`Authenticated user: ${authInfo.subject}`); - return { subject: authInfo.subject }; -}); +server.registerTool( + 'whoami', + { + description: 'Returns the current user info', + inputSchema: {}, + }, + ({ authInfo }) => { + console.log(`Authenticated user: ${authInfo.subject}`); + return { subject: authInfo.subject }; + } +); ``` - - - diff --git a/docs/configure-server/mcp-auth.mdx b/docs/configure-server/mcp-auth.mdx index def4083..9ca8c15 100644 --- a/docs/configure-server/mcp-auth.mdx +++ b/docs/configure-server/mcp-auth.mdx @@ -3,9 +3,6 @@ sidebar_position: 1 sidebar_label: MCP Auth --- -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - # Configure MCP Auth in MCP server With the latest [MCP Specification (2025-06-18)](https://modelcontextprotocol.io/specification/2025-06-18), your MCP server acts as a **Resource Server** that validates access tokens issued by external authorization servers. @@ -25,23 +22,6 @@ The easiest way to configure authorization server metadata is by using the built You can use the `fetchServerConfig` to automatically retrieve the metadata by providing the `issuer` URL: - - - -```python -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -# Fetch authorization server metadata -auth_server_config = fetch_server_config( - "https://auth.logto.io/oidc", - AuthServerType.OIDC # or AuthServerType.OAUTH -) -``` - - - - ```ts import { fetchServerConfig } from 'mcp-auth'; @@ -49,36 +29,24 @@ import { fetchServerConfig } from 'mcp-auth'; const authServerConfig = await fetchServerConfig('https://auth.logto.io/oidc', { type: 'oidc' }); // or 'oauth' ``` - - - If your issuer includes a path, the behavior differs slightly between OAuth 2.0 and OpenID Connect: - **OAuth 2.0**: The well-known URL is appended to the **domain** of the issuer. For example, if your issuer is `https://my-project.logto.app/oauth`, the well-known URL will be `https://auth.logto.io/.well-known/oauth-authorization-server/oauth`. - **OpenID Connect**: The well-known URL is appended directly to the **issuer**. For example, if your issuer is `https://my-project.logto.app/oidc`, the well-known URL will be `https://auth.logto.io/oidc/.well-known/openid-configuration`. -### Other ways to configure authorization server metadata \{#other-ways} - -#### Custom data transpilation \{#custom-data-transpilation} +#### On demand discovery \{#on-demand-discovery} -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: +If you're using edge runtimes like Cloudflare Workers where top-level async fetch is not allowed, you can use on demand discovery instead. Just provide the `issuer` and `type`, and the metadata will be fetched automatically when first needed: - - +```ts +const authServerConfig = { issuer: '', type: 'oidc' }; // or 'oauth' +``` -```python -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config +### Other ways to configure authorization server metadata \{#other-ways} -auth_server_config = fetch_server_config( - '', - type=AuthServerType.OIDC, - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] -) -``` +#### 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 `transpileData` option to modify the metadata before it is used: ```ts import { fetchServerConfig } from 'mcp-auth'; @@ -89,60 +57,22 @@ const authServerConfig = await fetchServerConfig('', { }); ``` - - - 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} If your provider has a specific metadata URL rather than the standard ones, you can use it similarly: - - - -```python -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config_by_well_known_url - -auth_server_config = fetch_server_config_by_well_known_url( - '', - type=AuthServerType.OIDC # or AuthServerType.OAUTH -) -``` - - - - ```ts import { fetchServerConfigByWellKnownUrl } from 'mcp-auth'; const authServerConfig = await fetchServerConfigByWellKnownUrl('', { type: 'oidc' }); // or 'oauth' ``` - - - #### 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: - - - -```python -from mcpauth.config import AuthServerType, fetch_server_config_by_well_known_url - -auth_server_config = fetch_server_config_by_well_known_url( - '', - type=AuthServerType.OIDC, - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] -) -``` - - - - ```ts const authServerConfig = await fetchServerConfigByWellKnownUrl('', { type: 'oidc', @@ -150,32 +80,10 @@ const authServerConfig = await fetchServerConfigByWellKnownUrl('', }); ``` - - - #### Manually provide metadata \{#manually-provide-metadata} If your provider does not support metadata fetching, you can manually provide the metadata object: - - - -```python -from mcpauth.config import AuthServerConfig, AuthServerType, AuthorizationServerMetadata - -auth_server_config = AuthServerConfig( - type=AuthServerType.OIDC, # or AuthServerType.OAUTH - metadata=AuthorizationServerMetadata( - issuer='', - authorization_endpoint='', - # ... other metadata fields - ), -) -``` - - - - ```ts const authServerConfig = { metadata: { @@ -188,43 +96,12 @@ const authServerConfig = { }; ``` - - - ## Step 2: Configure Protected Resource Metadata \{#configure-protected-resource-metadata} After configuring the authorization server metadata, you need to initialize MCPAuth as a Resource Server by defining your protected resources metadata. This step follows the [RFC 9728 (OAuth 2.0 Protected Resource Metadata)](https://datatracker.ietf.org/doc/html/rfc9728) specification to describe your MCP server as a protected resource: - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import ResourceServerConfig, ResourceServerMetadata - -# Define your resource identifier -resource_id = "https://api.example.com/notes" - -# Initialize MCPAuth in resource server mode -mcp_auth = MCPAuth( - protected_resources=ResourceServerConfig( - metadata=ResourceServerMetadata( - resource=resource_id, - authorization_servers=[auth_server_config], # Using the config from Step 1 - scopes_supported=[ - "read:notes", - "write:notes", - ], - ) - ) -) -``` - - - - ```ts import { MCPAuth } from 'mcp-auth'; @@ -233,22 +110,17 @@ const resourceIdentifier = 'https://api.example.com/notes'; // Initialize MCPAuth in resource server mode const mcpAuth = new MCPAuth({ - protectedResources: [ - { - metadata: { - resource: resourceIdentifier, - authorizationServers: [authServerConfig], // Using the config from Step 1 - scopesSupported: ['read:notes', 'write:notes'], - }, + protectedResources: { + metadata: { + resource: resourceIdentifier, + authorizationServers: [authServerConfig], // Using the config from Step 1 + scopesSupported: ['read:notes', 'write:notes'], }, - ], + }, }); ``` - - - -For multiple resources, you can provide an array of protected resources, each with their own metadata configuration. +For multiple resources, you can provide an array of protected resource configs, each with their own metadata configuration. The configuration shown above covers the basic setup. For more advanced metadata parameters, see [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728#name-protected-resource-metadata). @@ -259,23 +131,6 @@ Mount the router to serve the protected resource metadata endpoint. The endpoint - **No path**: `https://api.example.com` → `/.well-known/oauth-protected-resource` - **With path**: `https://api.example.com/notes` → `/.well-known/oauth-protected-resource/notes` - - - -```python -from starlette.applications import Starlette -from mcpauth import MCPAuth - -mcp_auth = MCPAuth({/* ... */}) - -app = Starlette(routes=[ - *mcp_auth.resource_metadata_router().routes, -]) -``` - - - - ```ts import express from 'express'; @@ -285,6 +140,3 @@ const mcpAuth = new MCPAuth({/* ... */}); app.use(mcpAuth.protectedResourceMetadataRouter()); ``` - - - diff --git a/docs/snippets/_get-started-code.mdx b/docs/snippets/_get-started-code.mdx index 00f677a..24e489f 100644 --- a/docs/snippets/_get-started-code.mdx +++ b/docs/snippets/_get-started-code.mdx @@ -1,54 +1,14 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - - - - - -```python -mcp = FastMCP("MyMCPServer") -resource_identifier = "https://api.example.com" - -mcp_auth = MCPAuth( - protected_resources=ResourceServerConfig( - metadata=ResourceServerMetadata( - resource=resource_identifier, - authorization_servers=[fetch_server_config('', AuthServerType.OIDC)], - scopes_supported=["read", "write"], - ) - ) -) - -app = Starlette( - routes=[ - *mcp_auth.resource_metadata_router().routes, - Mount('/', app=mcp.sse_app(), middleware=[Middleware( - mcp_auth.bearer_auth_middleware("jwt", - resource=resource_identifier, - audience=resource_identifier, - required_scopes=["read", "write"] - ) - )]) - ] -) - -@mcp.tool() -def whoami(): - return mcp_auth.auth_info.claims -``` - - - - ```ts const server = new McpServer(/* ... */); const resourceIdentifier = 'https://api.example.com'; +const authServerConfig = await fetchServerConfig('', { type: 'oidc' }); + const mcpAuth = new MCPAuth({ protectedResources: { metadata: { resource: resourceIdentifier, - authorizationServers: [await fetchServerConfig('', { type: 'oidc' })], + authorizationServers: [authServerConfig], scopesSupported: ['read', 'write'], } } @@ -58,16 +18,20 @@ const app = express(); app.use(mcpAuth.protectedResourceMetadataRouter()); -app.use(mcpAuth.bearerAuth('jwt', { +app.use(mcpAuth.bearerAuth('jwt', { resource: resourceIdentifier, audience: resourceIdentifier, - requiredScopes: ['read', 'write'] + requiredScopes: ['read', 'write'] })); -server.tool('whoami', ({ authInfo }) => { - return authInfo.claims; -}); +server.registerTool( + 'whoami', + { + description: 'Returns the current user info', + inputSchema: {}, + }, + ({ authInfo }) => { + return authInfo.claims; + } +); ``` - - - diff --git a/docs/snippets/_scope-validation-warning.mdx b/docs/snippets/_scope-validation-warning.mdx new file mode 100644 index 0000000..2ef6084 --- /dev/null +++ b/docs/snippets/_scope-validation-warning.mdx @@ -0,0 +1,5 @@ +:::warning Always Validate Scopes +In OAuth 2.0, **scopes are the primary mechanism for permission control**. A valid token with the correct `audience` does NOT guarantee the user has permission to perform an action — authorization servers may issue tokens with an empty or limited scope. + +Always use `requiredScopes` to enforce that the token contains the necessary permissions for each operation. Never assume a valid token implies full access. +::: diff --git a/docs/tutorials/todo-manager/README.mdx b/docs/tutorials/todo-manager/README.mdx index e25e8f5..c381686 100644 --- a/docs/tutorials/todo-manager/README.mdx +++ b/docs/tutorials/todo-manager/README.mdx @@ -6,9 +6,12 @@ sidebar_label: 'Tutorial: Build a todo manager' import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; - # Tutorial: Build a todo manager +:::tip Python SDK available +MCP Auth is also available for Python! Check out the [Python SDK repository](https://github.com/mcp-auth/python) for installation and usage. +::: + In this tutorial, we will build a todo manager MCP server with user authentication and authorization. Following the latest MCP specification, our MCP server will act as an OAuth 2.0 **Resource Server** that validates access tokens and enforces scope-based permissions. After completing this tutorial, you will have: @@ -294,32 +297,6 @@ We will use the [MCP official SDKs](https://github.com/modelcontextprotocol) to ### Create a new project \{#create-a-new-project} - - - -Set up a new Python project: - -```bash -mkdir mcp-todo-server -cd mcp-todo-server - -# Initialize a new Python project -uv init - -# Create a new virtual environment using uv -uv venv - -# Activate the virtual environment (optional when using 'uv run') -source .venv/bin/activate -``` - -:::note -This project uses `uv` for package management, but you can use other package managers like `pip`, `poetry`, or `conda` if you prefer. -::: - - - - Set up a new Node.js project: ```bash @@ -335,96 +312,16 @@ npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts" We're using TypeScript in our examples as Node.js v22.6.0+ supports running TypeScript natively using the `--experimental-strip-types` flag. If you're using JavaScript, the code will be similar - just ensure you're using Node.js v22.6.0 or later. See Node.js docs for details. ::: - - - ### Install the MCP SDK and dependencies \{#install-the-mcp-sdk-and-dependencies} - - - -Install the required dependencies: - -```bash -uv add "mcp[cli]" uvicorn starlette -``` - - - - ```bash npm install @modelcontextprotocol/sdk express zod ``` Or any other package manager you prefer, such as `pnpm` or `yarn`. - - - ### Create the MCP server \{#create-the-mcp-server} -First, let's create a basic MCP server with the tool definitions: - - - - -Create a file named `server.py` and add the following code: - -```python -# server.py - -import contextlib -from typing import Any -from mcp.server.fastmcp import FastMCP -from starlette.applications import Starlette -from starlette.routing import Mount - -# Initialize the FastMCP server -mcp = FastMCP(name="Todo Manager", stateless_http=True, streamable_http_path='/') - -@mcp.tool() -def create_todo(content: str) -> dict[str, Any]: - """Create a new todo. Requires 'create:todos' scope.""" - return {"error": "Not implemented"} - -@mcp.tool() -def get_todos() -> dict[str, Any]: - """List todos. Users with 'read:todos' scope can see all todos.""" - return {"error": "Not implemented"} - -@mcp.tool() -def delete_todo(id: str) -> dict[str, Any]: - """Delete a todo by id. Users can delete their own todos.""" - return {"error": "Not implemented"} - -@contextlib.asynccontextmanager -async def lifespan(app: Starlette): - async with contextlib.AsyncExitStack() as stack: - await stack.enter_async_context(mcp.session_manager.run()) - yield - -# Create the app -app = Starlette( - routes=[ - Mount("/", app=mcp.streamable_http_app()), - ], - lifespan=lifespan, -) -``` - -Run the server with: - -```bash -# Start the Todo Manager server using uvicorn -uvicorn server:app --host 127.0.0.1 --port 3001 - -# Or using uv: -# uv run uvicorn server:app --host 127.0.0.1 --port 3001 -``` - - - - Create a file named `todo-manager.ts` and add the following code: ```ts @@ -441,23 +338,44 @@ const server = new McpServer({ version: '0.0.0', }); -server.tool('create-todo', 'Create a new todo', { content: z.string() }, async ({ content }) => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }], - }; -}); +server.registerTool( + 'create-todo', + { + description: 'Create a new todo', + inputSchema: { content: z.string() }, + }, + async ({ content }) => { + return { + content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }], + }; + } +); -server.tool('get-todos', 'List all todos', async () => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }], - }; -}); +server.registerTool( + 'get-todos', + { + description: 'List all todos', + inputSchema: {}, + }, + async () => { + return { + content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }], + }; + } +); -server.tool('delete-todo', 'Delete a todo by id', { id: z.string() }, async ({ id }) => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }], - }; -}); +server.registerTool( + 'delete-todo', + { + description: 'Delete a todo by id', + inputSchema: { id: z.string() }, + }, + async ({ id }) => { + return { + content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }], + }; + } +); // Below is the boilerplate code from MCP SDK documentation const PORT = 3001; @@ -533,9 +451,6 @@ Run the server with: npm start ``` - - - ## Inspect the MCP server \{#inspect-the-mcp-server} ### Clone and run MCP inspector \{#clone-and-run-mcp-inspector} @@ -711,31 +626,20 @@ create:todos read:todos delete:todos First, install the MCP Auth SDK in your MCP server project. - - - -```bash -uv add mcpauth==0.2.0b1 -``` +import { NpmLikeInstallation } from '@site/src/components/NpmLikeInstallation'; - - + -```bash -npm install mcp-auth@0.2.0-beta.1 -``` +Now we need to initialize MCP Auth in your MCP server. With the protected resource mode, you need to configure your resource metadata including the authorization servers. - - +There are two ways to configure authorization servers: -Now we need to initialize MCP Auth in your MCP server. This involves two main steps: +- **Pre-fetched (Recommended)**: Use `fetchServerConfig()` to fetch the metadata before initializing MCPAuth. This ensures the configuration is validated at startup. +- **On-demand discovery**: Only provide `issuer` and `type` - metadata will be fetched on-demand when first needed. This is useful for edge runtimes (like Cloudflare Workers) where top-level async fetch is not allowed. -1. **Fetching authorization server metadata**: Used for subsequent MCP Auth verification of access tokens issued by the Authorization Server, and to include the auth server's issuer identifier in resource metadata -2. **Configure protected resource metadata**: Define your MCP server's resource identifier and supported scopes +#### Configure protected resource metadata \{#configure-protected-resource-metadata} -#### Step 1: Fetch authorization server metadata \{#step-1-fetch-authorization-server-metadata\} - -According to the OAuth / OIDC spec, we can retrieve the authorization server metadata based on the authorization server's issuer URL. +First, get your authorization server's issuer URL: @@ -757,85 +661,26 @@ For OAuth 2.0 providers, you'll need to: -Now, fetch the authorization server metadata using the MCP Auth utility function to retrieve server configuration: - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config +Now, configure the Protected Resource Metadata when building the MCP Auth instance: -issuer_url = "" # Replace with your authorization server's issuer URL - -# Fetch authorization server configuration -auth_server_config = fetch_server_config(issuer_url, AuthServerType.OIDC) # or AuthServerType.OAUTH -``` - - - ```js +// todo-manager.ts + import { MCPAuth, fetchServerConfig } from 'mcp-auth'; const issuerUrl = ''; // Replace with your authorization server's issuer URL -// Fetch authorization server configuration (OIDC Discovery) -const authServerConfig = await fetchServerConfig(issuerUrl, { type: 'oidc' }); // or { type: 'oauth' } -``` - - - - -If you need alternative ways to fetch authorization server metadata or want to customize the configuration, please refer to [other ways to configure authorization server metadata](/docs/configure-server/mcp-auth#other-ways). - -#### Step 2: Configure protected resource metadata \{#step-2-configure-protected-resource-metadata} - -Next, we will configure the Protected Resource Metadata when building the MCP Auth instance. Subsequently, the MCP server will expose the resource metadata configured in MCP Auth. - - - - -```python -# server.py - -# other imports... -from mcpauth.types import ResourceServerConfig, ResourceServerMetadata - -# Define the resource identifier for this MCP server -resource_id = "http://localhost:3001" - -mcp_auth = MCPAuth( - protected_resources=ResourceServerConfig( - metadata=ResourceServerMetadata( - resource=resource_id, - # Authorization server metadata fetched in the previous step - authorization_servers=[auth_server_config], - # Scopes this MCP server understands - scopes_supported=[ - "create:todos", - "read:todos", - "delete:todos" - ] - ) - ) -) -``` - - - -```js -// todo-manager.ts - // Define the resource identifier for this MCP server const resourceId = 'http://localhost:3001'; +// Pre-fetch authorization server configuration (recommended) +const authServerConfig = await fetchServerConfig(issuerUrl, { type: 'oidc' }); + // Configure MCP Auth with protected resource metadata const mcpAuth = new MCPAuth({ protectedResources: { metadata: { resource: resourceId, - // Authorization server metadata fetched in the previous step authorizationServers: [authServerConfig], // Scopes this MCP server understands scopesSupported: [ @@ -847,9 +692,6 @@ const mcpAuth = new MCPAuth({ } }); ``` - - - ### Update MCP server \{#update-mcp-server} @@ -857,26 +699,6 @@ We are almost done! It's time to update the MCP server to apply the MCP Auth rou Now, apply protected resource metadata routes so that MCP clients can retrieve expected resource metadata from the MCP server. - - -```python -# server.py - -# ..other codes - -app = Starlette( - routes=[ - # Set up Protected Resource Metadata routes - # This exposes metadata about this resource server for OAuth clients - *mcp_auth.resource_metadata_router().routes, - Mount("/", app=mcp.streamable_http_app()), - ], - lifespan=lifespan, -) -``` - - - ```ts // todo-manager.ts @@ -885,36 +707,9 @@ app = Starlette( app.use(mcpAuth.protectedResourceMetadataRouter()); ``` - - Next, we will apply the MCP Auth middleware to the MCP server. This middleware will handle authentication and authorization for incoming requests, ensuring that only authorized users can access the todo manager tools. - - -```python -# server.py - -# other imports... -from starlette.middleware import Middleware - -# other codes... - -# Create the middleware -bearer_auth = Middleware(mcp_auth.bearer_auth_middleware('jwt', resource=resource_id, audience=resource_id)) - -app = Starlette( - routes=[ - *mcp_auth.resource_metadata_router().routes, - # Apply the MCP Auth middleware - Mount("/", app=mcp.streamable_http_app(), middleware=[bearer_auth]), - ], - lifespan=lifespan, -) -``` - - - ```ts // todo-manager.ts @@ -928,104 +723,11 @@ app.use( }) ); ``` - - At this point, we can update the todo manager tools to leverage the MCP Auth middleware for authentication and authorization. Let's update the implementation of the tools. - - -```python -# server.py - -# other imports... - -from typing import Any, List, Optional -from mcpauth.exceptions import MCPAuthBearerAuthException, BearerAuthExceptionCode -from mcpauth.types import AuthInfo, ResourceServerConfig, ResourceServerMetadata - -# Will mention in the next section -from service import TodoService - -def assert_user_id(auth_info: Optional[AuthInfo]) -> str: - """Assert that auth_info contains a valid user ID and return it.""" - if not auth_info or not auth_info.subject: - raise Exception("Invalid auth info") - return auth_info.subject - -def has_required_scopes(user_scopes: List[str], required_scopes: List[str]) -> bool: - """Check if user has all required scopes.""" - return all(scope in user_scopes for scope in required_scopes) - -# Create the TodoService instance -todo_service = TodoService() - -@mcp.tool() -def create_todo(content: str) -> dict[str, Any]: - """Create a new todo. Requires 'create:todos' scope.""" - auth_info = mcp_auth.auth_info - user_id = assert_user_id(auth_info) - - # Only users with 'create:todos' scope can create todos - user_scopes = auth_info.scopes if auth_info else [] - if not has_required_scopes(user_scopes, ["create:todos"]): - raise MCPAuthBearerAuthException(BearerAuthExceptionCode.MISSING_REQUIRED_SCOPES) - - created_todo = todo_service.create_todo(content=content, owner_id=user_id) - return created_todo - -@mcp.tool() -def get_todos() -> dict[str, Any]: - """ - List todos. Users with 'read:todos' scope can see all todos, - otherwise they can only see their own todos. - """ - auth_info = mcp_auth.auth_info - user_id = assert_user_id(auth_info) - - # If user has 'read:todos' scope, they can access all todos - # If user doesn't have 'read:todos' scope, they can only access their own todos - user_scopes = auth_info.scopes if auth_info else [] - todo_owner_id = None if has_required_scopes(user_scopes, ["read:todos"]) else user_id - - todos = todo_service.get_all_todos(todo_owner_id) - return {"todos": todos} - -@mcp.tool() -def delete_todo(id: str) -> dict[str, Any]: - """ - Delete a todo by id. Users can delete their own todos. - Users with 'delete:todos' scope can delete any todo. - """ - auth_info = mcp_auth.auth_info - user_id = assert_user_id(auth_info) - - todo = todo_service.get_todo_by_id(id) - - if not todo: - return {"error": "Failed to delete todo"} - - # Users can only delete their own todos - # Users with 'delete:todos' scope can delete any todo - user_scopes = auth_info.scopes if auth_info else [] - if todo.owner_id != user_id and not has_required_scopes(user_scopes, ["delete:todos"]): - return {"error": "Failed to delete todo"} - - deleted_todo = todo_service.delete_todo(id) - - if deleted_todo: - return { - "message": f"Todo {id} deleted", - "details": deleted_todo - } - else: - return {"error": "Failed to delete todo"} -``` - - - ```js // todo-manager.ts @@ -1049,11 +751,13 @@ const hasRequiredScopes = (userScopes: string[], requiredScopes: string[]): bool const todoService = new TodoService(); -server.tool( +server.registerTool( 'create-todo', - 'Create a new todo', - { content: z.string() }, - ({ content }: { content: string }, { authInfo }) => { + { + description: 'Create a new todo', + inputSchema: { content: z.string() }, + }, + ({ content }, { authInfo }) => { const userId = assertUserId(authInfo); /** @@ -1071,29 +775,38 @@ server.tool( } ); -server.tool('get-todos', 'List all todos', ({ authInfo }) => { - const userId = assertUserId(authInfo); +server.registerTool( + 'get-todos', + { + description: 'List all todos', + inputSchema: {}, + }, + (_params, { authInfo }) => { + const userId = assertUserId(authInfo); - /** - * If user has 'read:todos' scope, they can access all todos (todoOwnerId = undefined) - * If user doesn't have 'read:todos' scope, they can only access their own todos (todoOwnerId = userId) - */ - const todoOwnerId = hasRequiredScopes(authInfo?.scopes ?? [], ['read:todos']) - ? undefined - : userId; + /** + * If user has 'read:todos' scope, they can access all todos (todoOwnerId = undefined) + * If user doesn't have 'read:todos' scope, they can only access their own todos (todoOwnerId = userId) + */ + const todoOwnerId = hasRequiredScopes(authInfo?.scopes ?? [], ['read:todos']) + ? undefined + : userId; - const todos = todoService.getAllTodos(todoOwnerId); + const todos = todoService.getAllTodos(todoOwnerId); - return { - content: [{ type: 'text', text: JSON.stringify(todos) }], - }; -}); + return { + content: [{ type: 'text', text: JSON.stringify(todos) }], + }; + } +); -server.tool( +server.registerTool( 'delete-todo', - 'Delete a todo by id', - { id: z.string() }, - ({ id }: { id: string }, { authInfo }) => { + { + description: 'Delete a todo by id', + inputSchema: { id: z.string() }, + }, + ({ id }, { authInfo }) => { const userId = assertUserId(authInfo); const todo = todoService.getTodoById(id); @@ -1135,126 +848,9 @@ server.tool( } ); ``` - - Now, create the "Todo service" used in the above code to implement the related functionality: - - - -Create the `service.py` file for the Todo service: - -```python -""" -A simple Todo service for demonstration purposes. -Uses an in-memory list to store todos. -""" - -from datetime import datetime -from typing import List, Optional, Dict, Any -import random -import string - -class Todo: - """Represents a todo item.""" - - def __init__(self, id: str, content: str, owner_id: str, created_at: str): - self.id = id - self.content = content - self.owner_id = owner_id - self.created_at = created_at - - def to_dict(self) -> Dict[str, Any]: - """Convert todo to dictionary for JSON serialization.""" - return { - "id": self.id, - "content": self.content, - "ownerId": self.owner_id, - "createdAt": self.created_at - } - - -class TodoService: - """A simple Todo service for demonstration purposes.""" - - def __init__(self): - self._todos: List[Todo] = [] - - def get_all_todos(self, owner_id: Optional[str] = None) -> List[Dict[str, Any]]: - """ - Get all todos, optionally filtered by owner_id. - - Args: - owner_id: If provided, only return todos owned by this user - - Returns: - List of todo dictionaries - """ - if owner_id: - filtered_todos = [todo for todo in self._todos if todo.owner_id == owner_id] - return [todo.to_dict() for todo in filtered_todos] - return [todo.to_dict() for todo in self._todos] - - def get_todo_by_id(self, todo_id: str) -> Optional[Todo]: - """ - Get a todo by its ID. - - Args: - todo_id: The ID of the todo to retrieve - - Returns: - Todo object if found, None otherwise - """ - for todo in self._todos: - if todo.id == todo_id: - return todo - return None - - def create_todo(self, content: str, owner_id: str) -> Dict[str, Any]: - """ - Create a new todo. - - Args: - content: The content of the todo - owner_id: The ID of the user who owns this todo - - Returns: - Dictionary representation of the created todo - """ - todo = Todo( - id=self._generate_id(), - content=content, - owner_id=owner_id, - created_at=datetime.now().isoformat() - ) - self._todos.append(todo) - return todo.to_dict() - - def delete_todo(self, todo_id: str) -> Optional[Dict[str, Any]]: - """ - Delete a todo by its ID. - - Args: - todo_id: The ID of the todo to delete - - Returns: - Dictionary representation of the deleted todo if found, None otherwise - """ - for i, todo in enumerate(self._todos): - if todo.id == todo_id: - deleted_todo = self._todos.pop(i) - return deleted_todo.to_dict() - return None - - def _generate_id(self) -> str: - """Generate a random ID for a todo.""" - return ''.join(random.choices(string.ascii_lowercase + string.digits, k=8)) -``` - - - - Create the `todo-service.ts` file for the Todo service: ```ts @@ -1316,30 +912,12 @@ export class TodoService { } ``` - - - -🎉 Congratulations! We've successfully implemented a complete MCP server with authentication and authorization! - -You can also check our sample code for reference: - - - - -:::info -Check out the [MCP Auth Python SDK repository](https://github.com/mcp-auth/python/tree/master/samples/current/todo-manager) for the complete code of the MCP server (OIDC version). -::: - - - +Congratulations! We've successfully implemented a complete MCP server with authentication and authorization! :::info Check out the [MCP Auth Node.js SDK repository](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) for the complete code of the MCP server (OIDC version). ::: - - - ## Checkpoint: Run the `todo-manager` tools \{#checkpoint-run-the-todo-manager-tools} Restart your MCP server and open the MCP inspector in your browser. When you click the "Connect" button, you should be redirected to your authorization server's sign-in page. @@ -1367,26 +945,13 @@ This demonstrates how role-based access control (RBAC) works in practice, where ![MCP inspector todo manager tool result](/docs-assets/images/tutorials/todo-manager/result.png) - - - -:::info -Check out the [MCP Auth Python SDK repository](https://github.com/mcp-auth/python) for the complete code of the MCP server (OIDC version). -::: - - - - :::info Check out the [MCP Auth Node.js SDK repository](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) for the complete code of the MCP server (OIDC version). ::: - - - ## Closing notes \{#closing-notes} -🎊 Congratulations! You have successfully completed the tutorial. Let's recap what we've done: +Congratulations! You have successfully completed the tutorial. Let's recap what we've done: - Setting up a basic MCP server with todo management tools (`create-todo`, `get-todos`, `delete-todo`) - Implementing role-based access control (RBAC) with different permission levels for users and admins diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 8089f6a..64506e3 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -58,21 +58,6 @@ const config: Config = { // Please change this to your repo. // Remove this to remove the "edit this page" links. editUrl: 'https://github.com/mcp-auth/docs/tree/master/', - includeCurrentVersion: true, - lastVersion: 'current', - versions: { - current: { - label: '0.2.0-beta.1', - path: '', - banner: 'none', - }, - '0.1.1': { - label: '0.1.1', - path: '0.1.1', - banner: 'none', - }, - }, - onlyIncludeVersions: ['current', '0.1.1'], beforeDefaultRehypePlugins: [ // https://lachieh.github.io/docusaurus-with-shiki-rehype/docs/intro/ [ @@ -127,10 +112,6 @@ const config: Config = { label: 'Provider list', position: 'right', }, - { - type: 'docsVersionDropdown', - position: 'right', - }, { type: 'localeDropdown', position: 'right', diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1.json b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1.json deleted file mode 100644 index 56d138a..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1.json +++ /dev/null @@ -1,50 +0,0 @@ -{ - "sidebar.docsSidebar.category.Tutorials": { - "message": "Tutorials", - "description": "The label for category Tutorials in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.Tutorials.link.generated-index.title": { - "message": "Tutorials", - "description": "The generated-index page title for category Tutorials in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.Configure MCP server": { - "message": "MCP-Server konfigurieren", - "description": "The label for category Configure MCP server in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.Configure MCP server.link.generated-index.title": { - "message": "MCP-Server konfigurieren", - "description": "The generated-index page title for category Configure MCP server in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.SDK references": { - "message": "SDK-Referenzen", - "description": "The label for category SDK references in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.SDK references.link.generated-index.title": { - "message": "MCP Auth SDK-Referenzen", - "description": "The generated-index page title for category SDK references in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.SDK references.link.generated-index.description": { - "message": "Informationen über Klassen, Methoden und Eigenschaften aus den MCP Auth SDKs.\n", - "description": "The generated-index page description for category SDK references in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.Node.js SDK": { - "message": "Node.js SDK", - "description": "The label for category Node.js SDK in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.classes": { - "message": "Klassen", - "description": "The label for category classes in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.functions": { - "message": "Funktionen", - "description": "The label for category functions in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.type-aliases": { - "message": "Typ-Aliase", - "description": "The label for category type-aliases in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.variables": { - "message": "Variablen", - "description": "The label for category variables in sidebar docsSidebar" - } -} diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/README.mdx b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/README.mdx deleted file mode 100644 index f180d11..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/README.mdx +++ /dev/null @@ -1,242 +0,0 @@ ---- -sidebar_position: 1 -sidebar_label: Erste Schritte ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -# Erste Schritte - -## Wähle einen kompatiblen OAuth 2.1- oder OpenID Connect-Anbieter \{#choose-a-compatible-oauth-2-1-or-openid-connect-provider} - -Die MCP-Spezifikation hat einige [spezifische Anforderungen](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization#1-3-standards-compliance) für die Autorisierung: - -- [OAuth 2.1 IETF DRAFT](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12) -- OAuth 2.0 Authorization Server Metadata ([RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)) -- OAuth 2.0 Dynamic Client Registration Protocol ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) - -Während die letzten beiden nicht zwingend erforderlich sind, ist die erste notwendig, um eine sichere und konforme Implementierung zu gewährleisten. - -:::note -Im neuen MCP-Entwurf wird RFC 8414 für Autorisierungsserver (Anbieter) verpflichtend sein. Wir werden die Dokumentation aktualisieren, sobald der neue Entwurf finalisiert ist. -::: - -Du kannst die [Liste der MCP-kompatiblen Anbieter](/provider-list) prüfen, um zu sehen, ob dein Anbieter unterstützt wird. - -## Installiere MCP Auth SDK \{#install-mcp-auth-sdk} - -MCP Auth ist sowohl für Python als auch für TypeScript verfügbar. Lass uns wissen, wenn du Unterstützung für eine andere Sprache oder ein anderes Framework benötigst! - - - - -```bash -pip install mcpauth -``` - -Oder ein anderer Paketmanager deiner Wahl, wie pipenv oder poetry. - - - - -```bash -npm install mcp-auth -``` - -Oder ein anderer Paketmanager deiner Wahl, wie pnpm oder yarn. - - - - -## Initialisiere MCP Auth \{#init-mcp-auth} - -Der erste Schritt ist die Initialisierung der MCP Auth-Instanz mit den Metadaten deines Anbieter-Autorisierungsservers. Wenn dein Anbieter eine der folgenden Spezifikationen unterstützt: - -- [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) -- [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) - -kannst du die eingebaute Funktion verwenden, um die Metadaten abzurufen und die MCP Auth-Instanz zu initialisieren: - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -mcp_auth = MCPAuth( - server=fetch_server_config( - '', - type=AuthServerType.OIDC # oder AuthServerType.OAUTH - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { type: 'oidc' }), // oder 'oauth' -}); -``` - - - - -Wenn du die Metadaten-URL oder Endpunkte manuell angeben musst, siehe [Weitere Möglichkeiten zur Initialisierung von MCP Auth](./configure-server/mcp-auth.mdx#other-ways). - -## Binde den Metadaten-Endpunkt ein \{#mount-the-metadata-endpoint} - -Um der aktuellen MCP-Spezifikation zu entsprechen, bindet MCP Auth den OAuth 2.0 Authorization Server Metadata-Endpunkt (`/.well-known/oauth-authorization-server`) in deinen MCP-Server ein: - - - - -```python -from starlette.applications import Starlette - -app = Starlette(routes=[ - mcp_auth.metadata_route(), -]) -``` - - - - -```ts -import express from 'express'; - -const app = express(); -app.use(mcpAuth.delegatedRouter()); -``` - - - - -Die URLs in den Metadaten bleiben unverändert, sodass die Rolle des Autorisierungsservers vollständig an den Anbieter delegiert wird. Du kannst den Metadaten-Endpunkt testen, indem du `/.well-known/oauth-authorization-server` in deinem MCP-Server aufrufst. - -### Warum nur der Metadaten-Endpunkt? \{#why-only-the-metadata-endpoint} - -Du wirst vielleicht sehen, dass die offiziellen SDKs einen Auth-Router bereitstellen, der Autorisierungsendpunkte wie `/authorize`, `/token` usw. einbindet. Hier ist der Grund, warum wir das nicht tun: - -1. Nur den Metadaten-Endpunkt einzubinden, ermöglicht es dir, die vollen Fähigkeiten deines Anbieters zu nutzen, ohne das Rad neu zu erfinden und unnötige Komplexität in deinen MCP-Server zu bringen. -2. Es gibt außerdem Bestrebungen, die [Rolle des MCP-Servers zu einem Ressourcenserver zu verschieben](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/205) und OAuth 2.0 Protected Resource Metadata ([RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728)) zu verlangen. Das bedeutet, dass der MCP-Server **keine Autorisierungslogik mehr übernimmt** (einschließlich des Metadaten-Endpunkts), sondern nur noch als Ressourcenserver dient, der sich für Authentifizierung und Autorisierung auf den Anbieter verlässt. - -:::note -Wir werden MCP Auth aktualisieren, um die neue MCP-Spezifikation zu unterstützen, sobald sie finalisiert ist. In der Zwischenzeit kannst du die aktuelle Version verwenden, die mit der aktuellen Spezifikation kompatibel ist. -::: - -## Verwende das Bearer-Auth-Middleware \{#use-the-bearer-auth-middleware} - -Sobald die MCP Auth-Instanz initialisiert ist, kannst du das Bearer-Auth-Middleware anwenden, um deine MCP-Routen zu schützen: - - - - -```python -from starlette.applications import Starlette -from starlette.middleware import Middleware -from starlette.routing import Mount -from mcpauth import MCPAuth -from mcp.server.fastmcp import FastMCP - -mcp = FastMCP() -mcp_auth = MCPAuth( - # Initialisiere mit deiner Auth-Server-Konfiguration -) -bearer_auth = mcp_auth.bearer_auth_middleware( - "jwt", required_scopes=["read", "write"] -) - -app = Starlette(routes=[ - mcp_auth.metadata_route(), - Mount( - "/", - app=mcp.sse_app(), - middleware=[Middleware(bearer_auth)], - ), -]) -``` - - - - -```ts -import express from 'express'; -import { MCPAuth } from 'mcp-auth'; - -const app = express(); -const server = new McpServer(/* ... */); -const mcpAuth = new MCPAuth({ - /* ... */ -}); - -app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] })); -``` - - - - -Im obigen Beispiel haben wir den Token-Typ `jwt` angegeben und die Berechtigungen `read` und `write` gefordert. Es wird automatisch das JWT (JSON Web Token) validieren und ein Objekt mit den Informationen des authentifizierten Benutzers befüllen. - -:::info -Noch nie von JWT (JSON Web Token) gehört? Keine Sorge, du kannst die Dokumentation einfach weiterlesen – wir erklären es, wenn es nötig ist. Du kannst auch das [Auth Wiki](https://auth.wiki/jwt) für eine kurze Einführung besuchen. -::: - -Weitere Informationen zur Bearer-Auth-Konfiguration findest du unter [Bearer-Auth konfigurieren](./configure-server/bearer-auth.mdx). - -## Auth-Informationen in deiner MCP-Implementierung abrufen \{#retrieve-the-auth-info-in-your-mcp-implementation} - -Sobald das Bearer-Auth-Middleware angewendet ist, kannst du auf die Informationen des authentifizierten Benutzers (oder der Identität) in deiner MCP-Implementierung zugreifen: - - - - -MCP Auth speichert die Informationen des authentifizierten Benutzers nach erfolgreicher Authentifizierung in einer Kontextvariablen, sobald das Bearer-Auth-Middleware angewendet wurde. Du kannst darauf in deinen MCP-Tool-Handlern wie folgt zugreifen: - -```python -from mcp.server.fastmcp import FastMCP - -mcp = FastMCP() -mcp_auth = MCPAuth( - # Initialisiere mit deiner Auth-Server-Konfiguration -) - -@mcp.tool() -def add(a: int, b: int): - """ - Ein Tool, das zwei Zahlen addiert. - Die Informationen des authentifizierten Benutzers sind im Kontext verfügbar. - """ - auth_info = mcp_auth.auth_info # Zugriff auf die Auth-Informationen im aktuellen Kontext - if auth_info: - print(f"Authentifizierter Benutzer: {auth_info.claims}") - return a + b -``` - - - - -Das zweite Argument des Tool-Handlers enthält das `authInfo`-Objekt, das die Informationen des authentifizierten Benutzers enthält: - -```ts -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; -import { z } from 'zod'; - -const server = new McpServer(/* ... */); -server.tool('add', { a: z.number(), b: z.number() }, async ({ a, b }, { authInfo }) => { - // Jetzt kannst du das `authInfo`-Objekt verwenden, um auf die authentifizierten Informationen zuzugreifen -}); -``` - - - - -## Nächste Schritte \{#next-steps} - -Lies weiter, um ein End-to-End-Beispiel zu erfahren, wie du MCP Auth mit deinem MCP-Server integrierst und wie du den Auth-Flow in MCP-Clients handhabst. diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/comparison.mdx b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/comparison.mdx deleted file mode 100644 index ca877be..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/comparison.mdx +++ /dev/null @@ -1,80 +0,0 @@ ---- -sidebar_position: 101 -sidebar_label: Vergleich ---- - -# Entscheidung zwischen MCP Auth und anderen Lösungen - -Das MCP-Ökosystem entwickelt sich weiter. Während sich die Model Context Protocol (MCP) Spezifikation vom „Autorisierungsserver“-Ansatz hin zum neuen Modell „Ressourcenserver + Drittanbieter-IdP“ bewegt, ist es wichtig zu verstehen, wie verschiedene Integrationslösungen jetzt und in Zukunft passen. - -Diese Seite zeigt die wichtigsten Unterschiede zwischen mcp-auth und anderen beliebten Lösungen auf, um dir bei der Wahl des besten Ansatzes für dein Projekt zu helfen. - -## Hintergrund: Proxy-Ansatz vs. IdP-Integration \{#background-proxy-approach-vs-idp-integration} - -Die meisten bestehenden MCP Auth-Lösungen verwenden einen „Proxy-Ansatz“. In diesem Modell leitet der MCP-Server Autorisierungsanfragen an einen Drittanbieter-Identitätsanbieter (IdP) weiter und fungiert damit effektiv als Vermittler zwischen dem Client und dem IdP. - -**Proxy-Ansatz ([03-26 Spezifikation](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization))** - -```mermaid -sequenceDiagram - participant Client - participant MCP_Server as MCP-Server - participant ThirdParty_IdP as Drittanbieter-IdP - - Client->>MCP_Server: Autorisierungsanfrage - MCP_Server->>ThirdParty_IdP: Leitet Anfrage weiter - ThirdParty_IdP->>MCP_Server: Antwort - MCP_Server->>Client: Antwort - Client->>MCP_Server: Zugriff auf Ressource - alt Remote-Validierung - MCP_Server->>ThirdParty_IdP: Token validieren - ThirdParty_IdP->>MCP_Server: Token gültig - else Lokale Validierung - MCP_Server->>MCP_Server: Token lokal validieren (z. B. zwischengespeicherter JWK) - end - MCP_Server->>Client: Ressourcendaten -``` - -Obwohl dies mit der aktuellen (2025-03-26) MCP-Spezifikation funktioniert, ist es im Grunde ein Workaround. Es wird davon ausgegangen, dass der MCP-Server auch als Autorisierungsserver fungiert, was jedoch nicht der Richtung der neuesten Entwurfsspezifikation entspricht. - -**MCP Auth / zukünftige Spezifikation (Ressourcenserver + Drittanbieter-IdP)** - -```mermaid -sequenceDiagram - participant Client - participant MCP_Server as MCP-Server - participant ThirdParty_IdP as Drittanbieter-IdP - - Client->>ThirdParty_IdP: Autorisierungsanfrage - ThirdParty_IdP->>Client: Token - Client->>MCP_Server: Zugriff auf Ressource (mit Token) - alt Remote-Validierung - MCP_Server->>ThirdParty_IdP: Token validieren - ThirdParty_IdP->>MCP_Server: Token gültig - else Lokale Validierung - MCP_Server->>MCP_Server: Token lokal validieren (z. B. zwischengespeicherter JWK) - end - MCP_Server->>Client: Ressourcendaten -``` - -Die kommende MCP-Spezifikation [verlagert die Verantwortung für die Autorisierung auf einen dedizierten Drittanbieter-IdP](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/205). In diesem Modell dient der MCP-Server nur noch als Ressourcenserver, und alle Autorisierungsendpunkte kommen direkt vom Drittanbieter-IdP. - -## Warum MCP Auth wählen? \{#why-choose-mcp-auth} - -- Spezifikationskonformität: MCP Auth folgt direkt der Richtung des neuesten Entwurfs und ist damit die einzige Lösung, die sowohl mit der 03-26-Spezifikation als auch mit der kommenden Spezifikation kompatibel ist. -- Keine Workarounds mehr: Anstatt als Proxy für den Autorisierungsserver zu agieren, überlässt MCP Auth dem Drittanbieter-IdP die gesamte Autorisierung, wie in der neuen Spezifikation vorgesehen. -- Anbieterunabhängig: MCP Auth funktioniert mit jedem standardkonformen OAuth 2.0 / OIDC-Anbieter. -- Reibungsloser Übergang: MCP Auth gibt alle Drittanbieter-Endpunkte unverändert über OAuth 2.0 Authorization Server Metadata zurück. Das hält die Integration jetzt einfach und macht sie bereit für zukünftige Änderungen. -- Entwicklererfahrung: Bietet Tutorials, Hilfsprogramme und kommende Funktionen wie [OAuth 2.0 Protected Resource Metadata](https://auth.wiki/protected-resource-metadata), um das Leben für MCP-Server-Entwickler zu erleichtern. - -| Funktion | Proxy-Lösungen | MCP Auth | -| ---------------------------------- | -------------------- | -------- | -| Funktioniert mit 03-26-Spezifikation | ✅ | ✅ | -| Funktioniert mit zukünftiger Spezifikation | ❌ | ✅ | -| Unterstützt Drittanbieter-IdPs direkt | ❌ (nur Workaround) | ✅ | -| Anbieterunabhängig | Eingeschränkt[^1] | Ja | -| Übergangsbereit | ❌ | ✅ | - -Wenn du jetzt Drittanbieter-IdPs unterstützen musst und für die kommende Spezifikation bereit sein willst, ist MCP Auth die empfohlene Lösung. Proxy-basierte Ansätze könnten bald veraltet sein oder eine umfassende Überarbeitung erfordern. - -[^1]: Einige Proxy-Lösungen können bestimmte Parameter oder Endpunkte fest einprogrammieren, was die Flexibilität einschränkt. diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/configure-server/bearer-auth.mdx b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/configure-server/bearer-auth.mdx deleted file mode 100644 index 2e03990..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/configure-server/bearer-auth.mdx +++ /dev/null @@ -1,250 +0,0 @@ ---- -sidebar_position: 2 -sidebar_label: Bearer-Authentifizierung ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -# Bearer-Authentifizierung im MCP-Server konfigurieren - -MCP Auth bietet verschiedene Möglichkeiten, die Bearer-Autorisierung in deinem MCP-Server zu konfigurieren: - -- [JWT (JSON Web Token)](https://auth.wiki/jwt)-Modus: Eine integrierte Autorisierungsmethode, die JWTs mit Anspruchsüberprüfungen verifiziert. -- Benutzerdefinierter Modus: Ermöglicht es dir, deine eigene Autorisierungslogik zu implementieren. - -## Bearer-Authentifizierung mit JWT-Modus konfigurieren \{#configure-bearer-auth-with-jwt-mode} - -Wenn dein OAuth / OIDC-Anbieter JWTs zur Autorisierung ausstellt, kannst du den integrierten JWT-Modus in MCP Auth verwenden. Er überprüft die JWT-Signatur, das Ablaufdatum und andere von dir angegebene Ansprüche; anschließend werden die Authentifizierungsinformationen im Anfragekontext für die weitere Verarbeitung in deiner MCP-Implementierung bereitgestellt. - -### Berechtigungsprüfung (Scope validation) \{#scope-validation} - -Hier ist ein Beispiel für die grundlegende Berechtigungsprüfung: - - - - -```python -from mcpauth import MCPAuth -from starlette.applications import Starlette -from starlette.middleware import Middleware -from starlette.routing import Mount -from mcp.server.fastmcp import FastMCP - -mcp = FastMCP("MyMCPServer") -mcp_auth = MCPAuth( - # Initialize with your auth server config -) -bearer_auth = mcp_auth.bearer_auth_middleware("jwt", required_scopes=["read", "write"]) # [!code highlight] - -app = Starlette( - routes=[Mount('/', app=mcp.sse_app(), middleware=[Middleware(bearer_auth)])] -) -``` - - - - -```ts -import express from 'express'; -import { MCPAuth } from 'mcp-auth'; - -const app = express(); -const mcpAuth = new MCPAuth({ - /* ... */ -}); -const bearerAuth = mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }); // [!code highlight] - -app.use('/mcp', bearerAuth, (req, res) => { - // Now `req.auth` contains the auth info - console.log(req.auth); -}); -``` - - - - -Im obigen Beispiel haben wir angegeben, dass das JWT die Berechtigungen (Scopes) `read` und `write` enthalten muss. Wenn das JWT **keine** dieser Berechtigungen enthält, wird die Anfrage mit einem 403 Forbidden-Fehler abgelehnt. - -### Ressourcenindikator-Prüfung (RFC 8707) \{#resource-indicator-validation-rfc-8707} - -Wenn dein Anbieter auf OIDC basiert oder die [Resource Indicator](https://datatracker.ietf.org/doc/html/rfc8707)-Erweiterung unterstützt, kannst du außerdem die Option `audience` angeben, um den `aud` (Zielgruppe / Audience)-Anspruch im JWT zu validieren. Dies ist nützlich, um sicherzustellen, dass das JWT für deinen MCP-Server bestimmt ist. - -Überprüfe die Dokumentation deines Anbieters, um zu sehen, ob die Resource Indicator-Erweiterung unterstützt wird und wie sie konfiguriert wird. Manche Anbieter verwenden andere Begriffe wie „audience“, „API-Ressource“ oder „API-Indikator“ für dasselbe Konzept. - -Sobald der Ressourcenindikator konfiguriert ist, kannst du ihn in der `bearerAuth`-Middleware angeben: - - - - -```python -bearer_auth = mcp_auth.bearer_auth_middleware( - "jwt", - audience="https://api.example.com/mcp", # Die erwartete Zielgruppe (Audience) für das JWT [!code highlight] - required_scopes=["read", "write"] -) -``` - - - - -```ts -const bearerAuth = mcpAuth.bearerAuth('jwt', { - audience: 'https://api.example.com/mcp', // Die erwartete Zielgruppe (Audience) für das JWT [!code highlight] - requiredScopes: ['read', 'write'], -}); -``` - - - - -Im obigen Beispiel validiert MCP Auth **sowohl** den `aud`-Anspruch im JWT als auch die erforderlichen Berechtigungen. - -### Benutzerdefinierte Optionen für die JWT-Überprüfung angeben \{#provide-custom-options-to-the-jwt-verification} - -Du kannst auch benutzerdefinierte Optionen an die zugrunde liegende JWT-Überprüfungsbibliothek übergeben: - - - - -Im Python SDK verwenden wir [PyJWT](https://pyjwt.readthedocs.io/en/stable/) für die JWT-Überprüfung. Du kannst folgende Optionen nutzen: - -- `leeway`: Erlaubt eine gewisse Toleranz bei der Überprüfung der JWT-Ablaufzeit (in Sekunden). Standard ist 60 Sekunden. - -```python -bearer_auth = mcp_auth.bearer_auth_middleware( - "jwt", - audience="https://api.example.com/mcp", - required_scopes=["read", "write"] - leeway=10, # Reduziert Zeitabweichungen, indem 10 Sekunden Toleranz erlaubt werden [!code highlight] -) -``` - - - - -Im Node.js SDK verwenden wir die [jose](https://github.com/panva/jose)-Bibliothek für die JWT-Überprüfung. Du kannst folgende Optionen angeben: - -- `jwtVerify`: Optionen für den JWT-Überprüfungsprozess (`jwtVerify`-Funktion aus `jose`). -- `remoteJwtSet`: Optionen für das Abrufen des Remote-JWT-Sets (`createRemoteJWKSet`-Funktion aus `jose`). - -```ts {4-9} -const bearerAuth = mcpAuth.bearerAuth('jwt', { - audience: 'https://api.example.com/mcp', - requiredScopes: ['read', 'write'], - jwtVerify: { - clockTolerance: 60, // Erlaubt eine Zeitabweichung von 60 Sekunden - }, - remoteJwtSet: { - timeoutDuration: 10 * 1000, // 10 Sekunden Timeout für das Abrufen des Remote-JWT-Sets - }, -}); -``` - - - - -## Bearer-Authentifizierung mit benutzerdefinierter Überprüfung konfigurieren \{#configure-bearer-auth-with-custom-verification} - -Wenn dein OAuth / OIDC-Anbieter keine JWTs ausstellt oder du deine eigene Autorisierungslogik implementieren möchtest, erlaubt dir MCP Auth, eine benutzerdefinierte Überprüfungsfunktion zu erstellen: - -:::info -Da die Bearer-Authentifizierungs-Middleware den Aussteller (`iss`), die Zielgruppe (`aud`) und die erforderlichen Berechtigungen (`scope`) anhand des Überprüfungsergebnisses prüft, musst du diese Prüfungen nicht in deiner benutzerdefinierten Überprüfungsfunktion implementieren. Du kannst dich darauf konzentrieren, die Token-Gültigkeit zu überprüfen (z. B. Signatur, Ablauf usw.) und das Auth-Info-Objekt zurückzugeben. -::: - - - - -```python -from mcpauth.exceptions import MCPAuthJwtVerificationException, MCPAuthJwtVerificationExceptionCode -from mcpauth.types import AuthInfo - -async def custom_verification(token: str) -> AuthInfo: - # Implementiere hier deine benutzerdefinierte Überprüfungslogik - info = await verify_token(token) - if not info: - raise MCPAuthJwtVerificationException( - MCPAuthJwtVerificationExceptionCode.JWT_VERIFICATION_FAILED - ) - return info # Gib das Auth-Info-Objekt zurück - -bearer_auth = mcp_auth.bearer_auth_middleware( - custom_verification, - required_scopes=["read", "write"] -) -``` - - - - -```ts -const bearerAuth = mcpAuth.bearerAuth( - async (token) => { - // Implementiere hier deine benutzerdefinierte Überprüfungslogik - const info = await verifyToken(token); - if (!info) { - throw new MCPAuthJwtVerificationError('jwt_verification_failed'); - } - return info; // Gib das Auth-Info-Objekt zurück - }, - { requiredScopes: ['read', 'write'] } -); -``` - - - - -## Bearer-Authentifizierung in deinem MCP-Server anwenden \{#apply-bearer-auth-in-your-mcp-server} - -Um deinen MCP-Server mit Bearer-Authentifizierung zu schützen, musst du die Bearer-Authentifizierungs-Middleware auf deine MCP-Server-Instanz anwenden. - - - - -```python -bearer_auth = mcp_auth.bearer_auth_middleware("jwt", required_scopes=["read", "write"]) -app = Starlette( - routes=[Mount('/', app=mcp.sse_app(), middleware=[Middleware(bearer_auth)])] -) -``` - - - - -```js -const app = express(); -app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] })); -``` - - - - -Dadurch wird sichergestellt, dass alle eingehenden Anfragen gemäß den konfigurierten Bearer-Authentifizierungseinstellungen authentifiziert und autorisiert werden und die Authentifizierungsinformationen im Anfragekontext verfügbar sind. - -Du kannst die Informationen dann in deiner MCP-Server-Implementierung abrufen: - - - - -```python -@mcp.tool() -async def whoami() -> dict: - # `mcp_auth.auth_info` ist das Kontextobjekt für die aktuelle Anfrage - auth_info = mcp_auth.auth_info - print(f"Authentifizierter Benutzer: {auth_info.subject}") - return {"subject": auth_info.subject} -``` - - - - -```js -// `authInfo` wird aus dem `req.auth`-Objekt übernommen -server.tool('whoami', ({ authInfo }) => { - console.log(`Authentifizierter Benutzer: ${authInfo.subject}`); - return { subject: authInfo.subject }; -}); -``` - - - diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/configure-server/mcp-auth.mdx b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/configure-server/mcp-auth.mdx deleted file mode 100644 index 4e38346..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/configure-server/mcp-auth.mdx +++ /dev/null @@ -1,208 +0,0 @@ ---- -sidebar_position: 1 -sidebar_label: MCP Auth ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -# MCP Auth im MCP-Server konfigurieren - -Um deinen MCP-Server mit einem OAuth 2.1- oder OpenID Connect-Anbieter zu verbinden, musst du die MCP Auth-Instanz konfigurieren. Dies beinhaltet die Initialisierung der Instanz mit den Metadaten des Autorisierungsservers deines Anbieters und das Einrichten der notwendigen Autorisierungsflüsse. - -## MCP Auth initialisieren \{#init-mcp-auth} - -### Automatisches Metadaten-Fetching \{#automatic-metadata-fetching} - -Der einfachste Weg, die MCP Auth-Instanz zu initialisieren, ist die Verwendung der eingebauten Funktionen, die die Metadaten von einer Well-Known-URL abrufen. Wenn dein Anbieter einem der folgenden Standards entspricht: - -- [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) -- [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) - -Kannst du `fetchServerConfig` verwenden, um die Metadaten automatisch abzurufen, indem du die `issuer`-URL angibst: - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType, fetch_server_config - -mcp_auth = MCPAuth( - server=fetch_server_config( - '', - type=AuthServerType.OIDC # oder AuthServerType.OAUTH - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { type: 'oidc' }), // oder 'oauth' -}); -``` - - - - -Wenn dein Issuer einen Pfad enthält, unterscheidet sich das Verhalten leicht zwischen OAuth 2.0 und OpenID Connect: - -- **OAuth 2.0**: Die Well-Known-URL wird an die **Domain** des Issuers angehängt. Zum Beispiel, wenn dein Issuer `https://my-project.logto.app/oauth` ist, wird die Well-Known-URL `https://auth.logto.io/.well-known/oauth-authorization-server/oauth` sein. -- **OpenID Connect**: Die Well-Known-URL wird direkt an den **Issuer** angehängt. Zum Beispiel, wenn dein Issuer `https://my-project.logto.app/oidc` ist, wird die Well-Known-URL `https://auth.logto.io/oidc/.well-known/openid-configuration` sein. - -### Weitere Möglichkeiten zur Initialisierung von MCP Auth \{#other-ways} - -#### Eigene Daten-Transpilation \{#custom-data-transpilation} - -In manchen Fällen entsprechen die vom Anbieter zurückgegebenen Metadaten nicht dem erwarteten Format. Wenn du sicher bist, dass der Anbieter konform ist, kannst du die Option `transpile_data` verwenden, um die Metadaten vor der Verwendung zu modifizieren: - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -mcp_auth = MCPAuth( - server=fetch_server_config( - '', - type=AuthServerType.OIDC, - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { - type: 'oidc', - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - - -Dies ermöglicht es dir, das Metadaten-Objekt zu modifizieren, bevor es von MCP Auth verwendet wird. Zum Beispiel kannst du Felder hinzufügen oder entfernen, deren Werte ändern oder sie in ein anderes Format umwandeln. - -#### Metadaten von einer spezifischen URL abrufen \{#fetch-metadata-from-a-specific-url} - -Wenn dein Anbieter eine spezifische Metadaten-URL anstelle der Standard-URLs hat, kannst du diese ähnlich verwenden: - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config_by_well_known_url - -mcp_auth = MCPAuth( - server=fetch_server_config_by_well_known_url( - '', - type=AuthServerType.OIDC # oder AuthServerType.OAUTH - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfigByWellKnownUrl } from 'mcp-auth'; - -const mcpAuth = new MCPAuth({ - server: await fetchServerConfigByWellKnownUrl('', { type: 'oidc' }), // oder 'oauth' -}); -``` - - - - -#### Metadaten von einer spezifischen URL mit eigener Daten-Transpilation abrufen \{#fetch-metadata-from-a-specific-url-with-custom-data-transpilation} - -In manchen Fällen kann die Antwort des Anbieters fehlerhaft oder nicht im erwarteten Metadatenformat sein. Wenn du sicher bist, dass der Anbieter konform ist, kannst du die Metadaten über die Konfigurationsoption transpiliert bereitstellen: - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType, fetch_server_config_by_well_known_url - -mcp_auth = MCPAuth( - server=fetch_server_config_by_well_known_url( - '', - type=AuthServerType.OIDC, - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: await fetchServerConfigByWellKnownUrl('', { - type: 'oidc', - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - - -#### Metadaten manuell bereitstellen \{#manually-provide-metadata} - -Wenn dein Anbieter kein Metadaten-Fetching unterstützt, kannst du das Metadaten-Objekt manuell bereitstellen: - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerConfig, AuthServerType, AuthorizationServerMetadata - -mcp_auth = MCPAuth( - server=AuthServerConfig( - type=AuthServerType.OIDC, # oder AuthServerType.OAUTH - metadata=AuthorizationServerMetadata( - issuer='', - authorization_endpoint='', - # ... weitere Metadatenfelder - ), - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: { - metadata: { - issuer: '', - // Metadatenfelder sollten camelCase sein - authorizationEndpoint: '', - // ... weitere Metadatenfelder - }, - type: 'oidc', // oder 'oauth' - }, -}); -``` - - - diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/README.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/README.md deleted file mode 100644 index 81783a7..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/README.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -sidebar_label: Node.js SDK ---- - -# MCP Auth Node.js SDK Referenz - -## Klassen {#classes} - -- [MCPAuth](/references/js/classes/MCPAuth.md) -- [MCPAuthAuthServerError](/references/js/classes/MCPAuthAuthServerError.md) -- [MCPAuthBearerAuthError](/references/js/classes/MCPAuthBearerAuthError.md) -- [MCPAuthConfigError](/references/js/classes/MCPAuthConfigError.md) -- [MCPAuthError](/references/js/classes/MCPAuthError.md) -- [MCPAuthTokenVerificationError](/references/js/classes/MCPAuthTokenVerificationError.md) - -## Typalias {#type-aliases} - -- [AuthorizationServerMetadata](/references/js/type-aliases/AuthorizationServerMetadata.md) -- [AuthServerConfig](/references/js/type-aliases/AuthServerConfig.md) -- [AuthServerConfigError](/references/js/type-aliases/AuthServerConfigError.md) -- [AuthServerConfigErrorCode](/references/js/type-aliases/AuthServerConfigErrorCode.md) -- [AuthServerConfigWarning](/references/js/type-aliases/AuthServerConfigWarning.md) -- [AuthServerConfigWarningCode](/references/js/type-aliases/AuthServerConfigWarningCode.md) -- [AuthServerErrorCode](/references/js/type-aliases/AuthServerErrorCode.md) -- [AuthServerSuccessCode](/references/js/type-aliases/AuthServerSuccessCode.md) -- [AuthServerType](/references/js/type-aliases/AuthServerType.md) -- [BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) -- [BearerAuthErrorCode](/references/js/type-aliases/BearerAuthErrorCode.md) -- [BearerAuthJwtConfig](/references/js/type-aliases/BearerAuthJwtConfig.md) -- [CamelCaseAuthorizationServerMetadata](/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md) -- [MCPAuthBearerAuthErrorDetails](/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md) -- [MCPAuthConfig](/references/js/type-aliases/MCPAuthConfig.md) -- [MCPAuthTokenVerificationErrorCode](/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md) -- [VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) -- [VerifyAccessTokenMode](/references/js/type-aliases/VerifyAccessTokenMode.md) - -## Variablen {#variables} - -- [authorizationServerMetadataSchema](/references/js/variables/authorizationServerMetadataSchema.md) -- [authServerErrorDescription](/references/js/variables/authServerErrorDescription.md) -- [bearerAuthErrorDescription](/references/js/variables/bearerAuthErrorDescription.md) -- [camelCaseAuthorizationServerMetadataSchema](/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md) -- [serverMetadataPaths](/references/js/variables/serverMetadataPaths.md) -- [tokenVerificationErrorDescription](/references/js/variables/tokenVerificationErrorDescription.md) -- [validateServerConfig](/references/js/variables/validateServerConfig.md) - -## Funktionen {#functions} - -- [createVerifyJwt](/references/js/functions/createVerifyJwt.md) -- [fetchServerConfig](/references/js/functions/fetchServerConfig.md) -- [fetchServerConfigByWellKnownUrl](/references/js/functions/fetchServerConfigByWellKnownUrl.md) -- [handleBearerAuth](/references/js/functions/handleBearerAuth.md) diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuth.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuth.md deleted file mode 100644 index 1176522..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuth.md +++ /dev/null @@ -1,195 +0,0 @@ ---- -sidebar_label: MCPAuth ---- - -# Klasse: MCPAuth - -Die Hauptklasse der mcp-auth-Bibliothek, die Methoden zum Erstellen von Routern und nützlichen Handlern für Authentifizierung (Authentifizierung) und Autorisierung (Autorisierung) in MCP-Servern bereitstellt. - -## Siehe {#see} - -[MCP Auth](https://mcp-auth.dev) für weitere Informationen über die Bibliothek und deren Verwendung. - -## Beispiel {#example} - -Ein Beispiel für die Integration mit einem entfernten OIDC-Anbieter: - -```ts -import express from 'express'; -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const app = express(); -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig( - 'https://auth.logto.io/oidc', - { type: 'oidc' } - ), -}); - -// Router einbinden, um OAuth 2.0 Authorization Server Metadata zu bedienen -app.use(mcpAuth.delegatedRouter()); - -// Verwende den Bearer-Auth-Handler für die MCP-Route -app.get( - '/mcp', - mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }), - (req, res) => { - console.log('Auth info:', req.auth); - // Bearbeite hier die MCP-Anfrage - }, -); - -// Verwende die Auth-Info im MCP-Callback -server.tool( - 'add', - { a: z.number(), b: z.number() }, - async ({ a, b }, { authInfo }) => { - console.log('Auth Info:', authInfo); - // ... - }, -); -``` - -## Konstruktoren {#constructors} - -### Konstruktor {#constructor} - -```ts -new MCPAuth(config: MCPAuthConfig): MCPAuth; -``` - -#### Parameter {#parameters} - -##### config {#config} - -[`MCPAuthConfig`](/references/js/type-aliases/MCPAuthConfig.md) - -#### Rückgabewert {#returns} - -`MCPAuth` - -## Eigenschaften {#properties} - -### config {#config} - -```ts -readonly config: MCPAuthConfig; -``` - -## Methoden {#methods} - -### bearerAuth() {#bearerauth} - -#### Aufruf-Signatur {#call-signature} - -```ts -bearerAuth(verifyAccessToken: VerifyAccessTokenFunction, config?: Omit): RequestHandler; -``` - -Erstellt einen Bearer-Auth-Handler (Express-Middleware), der das Zugangstoken (Access token) im `Authorization`-Header der Anfrage überprüft. - -##### Parameter {#parameters} - -###### verifyAccessToken {#verifyaccesstoken} - -[`VerifyAccessTokenFunction`](/references/js/type-aliases/VerifyAccessTokenFunction.md) - -Eine Funktion, die das Zugangstoken (Access token) überprüft. Sie sollte das Zugangstoken als String akzeptieren und ein Promise (oder einen Wert) zurückgeben, das/die das Überprüfungsergebnis liefert. - -**Siehe** - -[VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) für die Typdefinition der `verifyAccessToken`-Funktion. - -###### config? {#config} - -`Omit`\<[`BearerAuthConfig`](/references/js/type-aliases/BearerAuthConfig.md), `"verifyAccessToken"` \| `"issuer"`\> - -Optionale Konfiguration für den Bearer-Auth-Handler. - -**Siehe** - -[BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) für die verfügbaren Konfigurationsoptionen (ohne `verifyAccessToken` und `issuer`). - -##### Rückgabewert {#returns} - -`RequestHandler` - -Eine Express-Middleware-Funktion, die das Zugangstoken (Access token) überprüft und das Überprüfungsergebnis dem Request-Objekt (`req.auth`) hinzufügt. - -##### Siehe {#see} - -[handleBearerAuth](/references/js/functions/handleBearerAuth.md) für Implementierungsdetails und die erweiterten Typen des `req.auth` (`AuthInfo`) Objekts. - -#### Aufruf-Signatur {#call-signature} - -```ts -bearerAuth(mode: "jwt", config?: Omit & BearerAuthJwtConfig): RequestHandler; -``` - -Erstellt einen Bearer-Auth-Handler (Express-Middleware), der das Zugangstoken (Access token) im `Authorization`-Header der Anfrage mit einem vordefinierten Überprüfungsmodus überprüft. - -Im `'jwt'`-Modus erstellt der Handler eine JWT-Überprüfungsfunktion unter Verwendung des JWK Sets von der JWKS-URI des Autorisierungsservers. - -##### Parameter {#parameters} - -###### mode {#mode} - -`"jwt"` - -Der Überprüfungsmodus für das Zugangstoken (Access token). Derzeit wird nur 'jwt' unterstützt. - -**Siehe** - -[VerifyAccessTokenMode](/references/js/type-aliases/VerifyAccessTokenMode.md) für die verfügbaren Modi. - -###### config? {#config} - -`Omit`\<[`BearerAuthConfig`](/references/js/type-aliases/BearerAuthConfig.md), `"verifyAccessToken"` \| `"issuer"`\> & [`BearerAuthJwtConfig`](/references/js/type-aliases/BearerAuthJwtConfig.md) - -Optionale Konfiguration für den Bearer-Auth-Handler, einschließlich JWT-Überprüfungsoptionen und Remote-JWK-Set-Optionen. - -**Siehe** - - - [BearerAuthJwtConfig](/references/js/type-aliases/BearerAuthJwtConfig.md) für die verfügbaren Konfigurationsoptionen für die JWT-Überprüfung. - - [BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) für die verfügbaren Konfigurationsoptionen (ohne `verifyAccessToken` und `issuer`). - -##### Rückgabewert {#returns} - -`RequestHandler` - -Eine Express-Middleware-Funktion, die das Zugangstoken (Access token) überprüft und das Überprüfungsergebnis dem Request-Objekt (`req.auth`) hinzufügt. - -##### Siehe {#see} - -[handleBearerAuth](/references/js/functions/handleBearerAuth.md) für Implementierungsdetails und die erweiterten Typen des `req.auth` (`AuthInfo`) Objekts. - -##### Wirft {#throws} - -wenn die JWKS-URI in den Server-Metadaten nicht bereitgestellt wird, wenn der `'jwt'`-Modus verwendet wird. - -*** - -### delegatedRouter() {#delegatedrouter} - -```ts -delegatedRouter(): Router; -``` - -Erstellt einen delegierten Router, der den OAuth 2.0 Authorization Server Metadata Endpoint (`/.well-known/oauth-authorization-server`) mit den der Instanz bereitgestellten Metadaten bedient. - -#### Rückgabewert {#returns} - -`Router` - -Ein Router, der den OAuth 2.0 Authorization Server Metadata Endpoint mit den der Instanz bereitgestellten Metadaten bedient. - -#### Beispiel {#example} - -```ts -import express from 'express'; -import { MCPAuth } from 'mcp-auth'; - -const app = express(); -const mcpAuth: MCPAuth; // Angenommen, dies ist initialisiert -app.use(mcpAuth.delegatedRouter()); -``` \ No newline at end of file diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthAuthServerError.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthAuthServerError.md deleted file mode 100644 index 8df4229..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthAuthServerError.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -sidebar_label: MCPAuthAuthServerError ---- - -# Klasse: MCPAuthAuthServerError - -Fehler, der ausgelöst wird, wenn ein Problem mit dem entfernten Autorisierungsserver auftritt. - -## Erweitert {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## Konstruktoren {#constructors} - -### Konstruktor {#constructor} - -```ts -new MCPAuthAuthServerError(code: AuthServerErrorCode, cause?: unknown): MCPAuthAuthServerError; -``` - -#### Parameter {#parameters} - -##### code {#code} - -[`AuthServerErrorCode`](/references/js/type-aliases/AuthServerErrorCode.md) - -##### cause? {#cause} - -`unknown` - -#### Rückgabe {#returns} - -`MCPAuthAuthServerError` - -#### Überschreibt {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## Eigenschaften {#properties} - -### cause? {#cause} - -```ts -readonly optional cause: unknown; -``` - -#### Geerbt von {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: AuthServerErrorCode; -``` - -Der Fehlercode im snake_case-Format. - -#### Geerbt von {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### Geerbt von {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthAuthServerError'; -``` - -#### Überschreibt {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### Geerbt von {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -Optionale Überschreibung zur Formatierung von Stacktraces - -#### Parameter {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### Rückgabe {#returns} - -`any` - -#### Siehe {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### Geerbt von {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### Geerbt von {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## Methoden {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -Konvertiert den Fehler in ein HTTP-Response-freundliches JSON-Format. - -#### Parameter {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -Ob die Ursache des Fehlers in die JSON-Antwort aufgenommen werden soll. -Standardmäßig `false`. - -#### Rückgabe {#returns} - -`Record`\<`string`, `unknown`\> - -#### Geerbt von {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -Erstellt die .stack-Eigenschaft auf einem Zielobjekt - -#### Parameter {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### Rückgabe {#returns} - -`void` - -#### Geerbt von {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthBearerAuthError.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthBearerAuthError.md deleted file mode 100644 index b632309..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthBearerAuthError.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -sidebar_label: MCPAuthBearerAuthError ---- - -# Klasse: MCPAuthBearerAuthError - -Fehler, der ausgelöst wird, wenn es ein Problem bei der Authentifizierung mit Bearer-Tokens gibt. - -## Erbt von {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## Konstruktoren {#constructors} - -### Konstruktor {#constructor} - -```ts -new MCPAuthBearerAuthError(code: BearerAuthErrorCode, cause?: MCPAuthBearerAuthErrorDetails): MCPAuthBearerAuthError; -``` - -#### Parameter {#parameters} - -##### code {#code} - -[`BearerAuthErrorCode`](/references/js/type-aliases/BearerAuthErrorCode.md) - -##### cause? {#cause} - -[`MCPAuthBearerAuthErrorDetails`](/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md) - -#### Rückgabewert {#returns} - -`MCPAuthBearerAuthError` - -#### Überschreibt {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## Eigenschaften {#properties} - -### cause? {#cause} - -```ts -readonly optional cause: MCPAuthBearerAuthErrorDetails; -``` - -#### Geerbt von {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: BearerAuthErrorCode; -``` - -Der Fehlercode im snake_case-Format. - -#### Geerbt von {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### Geerbt von {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthBearerAuthError'; -``` - -#### Überschreibt {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### Geerbt von {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -Optionale Überschreibung zur Formatierung von Stacktraces - -#### Parameter {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### Rückgabewert {#returns} - -`any` - -#### Siehe {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### Geerbt von {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### Geerbt von {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## Methoden {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -Konvertiert den Fehler in ein HTTP-Response-freundliches JSON-Format. - -#### Parameter {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -Gibt an, ob die Ursache des Fehlers in der JSON-Antwort enthalten sein soll. -Standardmäßig `false`. - -#### Rückgabewert {#returns} - -`Record`\<`string`, `unknown`\> - -#### Überschreibt {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -Erstellt die .stack-Eigenschaft auf einem Zielobjekt - -#### Parameter {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### Rückgabewert {#returns} - -`void` - -#### Geerbt von {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthConfigError.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthConfigError.md deleted file mode 100644 index 7b69139..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthConfigError.md +++ /dev/null @@ -1,202 +0,0 @@ ---- -sidebar_label: MCPAuthConfigError ---- - -# Klasse: MCPAuthConfigError - -Fehler, der ausgelöst wird, wenn es ein Konfigurationsproblem mit mcp-auth gibt. - -## Erbt von {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## Konstruktoren {#constructors} - -### Konstruktor {#constructor} - -```ts -new MCPAuthConfigError(code: string, message: string): MCPAuthConfigError; -``` - -#### Parameter {#parameters} - -##### code {#code} - -`string` - -Der Fehlercode im snake_case-Format. - -##### message {#message} - -`string` - -Eine menschenlesbare Beschreibung des Fehlers. - -#### Rückgabe {#returns} - -`MCPAuthConfigError` - -#### Geerbt von {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## Eigenschaften {#properties} - -### cause? {#cause} - -```ts -optional cause: unknown; -``` - -#### Geerbt von {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: string; -``` - -Der Fehlercode im snake_case-Format. - -#### Geerbt von {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### Geerbt von {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthConfigError'; -``` - -#### Überschreibt {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### Geerbt von {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -Optionale Überschreibung zur Formatierung von Stacktraces - -#### Parameter {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### Rückgabe {#returns} - -`any` - -#### Siehe {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### Geerbt von {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### Geerbt von {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## Methoden {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -Konvertiert den Fehler in ein HTTP-Response-freundliches JSON-Format. - -#### Parameter {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -Ob die Ursache des Fehlers in der JSON-Antwort enthalten sein soll. -Standardmäßig `false`. - -#### Rückgabe {#returns} - -`Record`\<`string`, `unknown`\> - -#### Geerbt von {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -Erstellt die .stack-Eigenschaft auf einem Zielobjekt - -#### Parameter {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### Rückgabe {#returns} - -`void` - -#### Geerbt von {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthError.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthError.md deleted file mode 100644 index dd66674..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthError.md +++ /dev/null @@ -1,219 +0,0 @@ ---- -sidebar_label: MCPAuthError ---- - -# Klasse: MCPAuthError - -Basisklasse für alle mcp-auth Fehler. - -Sie bietet eine standardisierte Möglichkeit, Fehler im Zusammenhang mit MCP Authentifizierung (Authentication) und Autorisierung (Authorization) zu behandeln. - -## Erweitert {#extends} - -- `Error` - -## Erweitert durch {#extended-by} - -- [`MCPAuthConfigError`](/references/js/classes/MCPAuthConfigError.md) -- [`MCPAuthAuthServerError`](/references/js/classes/MCPAuthAuthServerError.md) -- [`MCPAuthBearerAuthError`](/references/js/classes/MCPAuthBearerAuthError.md) -- [`MCPAuthTokenVerificationError`](/references/js/classes/MCPAuthTokenVerificationError.md) - -## Konstruktoren {#constructors} - -### Konstruktor {#constructor} - -```ts -new MCPAuthError(code: string, message: string): MCPAuthError; -``` - -#### Parameter {#parameters} - -##### code {#code} - -`string` - -Der Fehlercode im snake_case-Format. - -##### message {#message} - -`string` - -Eine menschenlesbare Beschreibung des Fehlers. - -#### Rückgabe {#returns} - -`MCPAuthError` - -#### Überschreibt {#overrides} - -```ts -Error.constructor -``` - -## Eigenschaften {#properties} - -### cause? {#cause} - -```ts -optional cause: unknown; -``` - -#### Geerbt von {#inherited-from} - -```ts -Error.cause -``` - -*** - -### code {#code} - -```ts -readonly code: string; -``` - -Der Fehlercode im snake_case-Format. - -*** - -### message {#message} - -```ts -message: string; -``` - -#### Geerbt von {#inherited-from} - -```ts -Error.message -``` - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthError'; -``` - -#### Überschreibt {#overrides} - -```ts -Error.name -``` - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### Geerbt von {#inherited-from} - -```ts -Error.stack -``` - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -Optionale Überschreibung zur Formatierung von Stacktraces - -#### Parameter {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### Rückgabe {#returns} - -`any` - -#### Siehe {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### Geerbt von {#inherited-from} - -```ts -Error.prepareStackTrace -``` - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### Geerbt von {#inherited-from} - -```ts -Error.stackTraceLimit -``` - -## Methoden {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -Konvertiert den Fehler in ein HTTP-Response-freundliches JSON-Format. - -#### Parameter {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -Ob die Ursache des Fehlers in die JSON-Antwort aufgenommen werden soll. -Standardmäßig `false`. - -#### Rückgabe {#returns} - -`Record`\<`string`, `unknown`\> - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -Erstellt die .stack Eigenschaft auf einem Zielobjekt - -#### Parameter {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### Rückgabe {#returns} - -`void` - -#### Geerbt von {#inherited-from} - -```ts -Error.captureStackTrace -``` diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthTokenVerificationError.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthTokenVerificationError.md deleted file mode 100644 index 856fca7..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthTokenVerificationError.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -sidebar_label: MCPAuthTokenVerificationError ---- - -# Klasse: MCPAuthTokenVerificationError - -Fehler, der ausgelöst wird, wenn es ein Problem bei der Überprüfung von Tokens gibt. - -## Erbt von {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## Konstruktoren {#constructors} - -### Konstruktor {#constructor} - -```ts -new MCPAuthTokenVerificationError(code: MCPAuthTokenVerificationErrorCode, cause?: unknown): MCPAuthTokenVerificationError; -``` - -#### Parameter {#parameters} - -##### code {#code} - -[`MCPAuthTokenVerificationErrorCode`](/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md) - -##### cause? {#cause} - -`unknown` - -#### Rückgabewert {#returns} - -`MCPAuthTokenVerificationError` - -#### Überschreibt {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## Eigenschaften {#properties} - -### cause? {#cause} - -```ts -readonly optional cause: unknown; -``` - -#### Geerbt von {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: MCPAuthTokenVerificationErrorCode; -``` - -Der Fehlercode im snake_case-Format. - -#### Geerbt von {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### Geerbt von {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthTokenVerificationError'; -``` - -#### Überschreibt {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### Geerbt von {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -Optionale Überschreibung zur Formatierung von Stacktraces - -#### Parameter {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### Rückgabewert {#returns} - -`any` - -#### Siehe {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### Geerbt von {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### Geerbt von {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## Methoden {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -Konvertiert den Fehler in ein HTTP-Response-freundliches JSON-Format. - -#### Parameter {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -Ob die Ursache des Fehlers in der JSON-Antwort enthalten sein soll. -Standardmäßig `false`. - -#### Rückgabewert {#returns} - -`Record`\<`string`, `unknown`\> - -#### Geerbt von {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -Erstellt die .stack-Eigenschaft auf einem Zielobjekt - -#### Parameter {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### Rückgabewert {#returns} - -`void` - -#### Geerbt von {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/createVerifyJwt.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/createVerifyJwt.md deleted file mode 100644 index 25e1d36..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/createVerifyJwt.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -sidebar_label: createVerifyJwt ---- - -# Funktion: createVerifyJwt() - -```ts -function createVerifyJwt(getKey: JWTVerifyGetKey, options?: JWTVerifyOptions): VerifyAccessTokenFunction; -``` - -Erstellt eine Funktion zur Überprüfung von JWT-Zugangstokens (Access tokens) mithilfe der bereitgestellten Schlüsselabruf-Funktion und Optionen. - -## Parameter {#parameters} - -### getKey {#getkey} - -`JWTVerifyGetKey` - -Die Funktion zum Abrufen des Schlüssels, der zur Überprüfung des JWT verwendet wird. - -**Siehe** - -JWTVerifyGetKey für die Typdefinition der Schlüsselabruf-Funktion. - -### options? {#options} - -`JWTVerifyOptions` - -Optionale Optionen zur JWT-Überprüfung. - -**Siehe** - -JWTVerifyOptions für die Typdefinition der Optionen. - -## Rückgabewert {#returns} - -[`VerifyAccessTokenFunction`](/references/js/type-aliases/VerifyAccessTokenFunction.md) - -Eine Funktion, die JWT-Zugangstokens (Access tokens) überprüft und ein AuthInfo-Objekt zurückgibt, wenn das Token gültig ist. Das JWT muss die Felder `iss`, `client_id` und `sub` im Payload enthalten und kann optional die Felder `scope` oder `scopes` enthalten. Die Funktion verwendet intern die `jose`-Bibliothek, um die JWT-Überprüfung durchzuführen. - -## Siehe {#see} - -[VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) für die Typdefinition der zurückgegebenen Funktion. diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfig.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfig.md deleted file mode 100644 index 7b48c3c..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfig.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -sidebar_label: fetchServerConfig ---- - -# Funktion: fetchServerConfig() - -```ts -function fetchServerConfig(issuer: string, config: ServerMetadataConfig): Promise; -``` - -Ruft die Serverkonfiguration entsprechend dem Aussteller (Issuer) und dem Typ des Autorisierungsservers ab. - -Diese Funktion bestimmt automatisch die Well-Known-URL basierend auf dem Servertyp, da OAuth und OpenID Connect Server unterschiedliche Konventionen für ihre Metadaten-Endpunkte haben. - -## Parameter {#parameters} - -### issuer {#issuer} - -`string` - -Die Aussteller-URL (Issuer URL) des Autorisierungsservers. - -### config {#config} - -`ServerMetadataConfig` - -Das Konfigurationsobjekt, das den Servertyp und eine optionale Transpile-Funktion enthält. - -## Rückgabewert {#returns} - -`Promise`\<[`AuthServerConfig`](/references/js/type-aliases/AuthServerConfig.md)\> - -Ein Promise, das mit der Serverkonfiguration aufgelöst wird. - -## Siehe auch {#see} - - - [fetchServerConfigByWellKnownUrl](/references/js/functions/fetchServerConfigByWellKnownUrl.md) für die zugrundeliegende Implementierung. - - [https://www.rfc-editor.org/rfc/rfc8414](https://www.rfc-editor.org/rfc/rfc8414) für die OAuth 2.0 Authorization Server Metadata Spezifikation. - - [https://openid.net/specs/openid-connect-discovery-1\_0.html](https://openid.net/specs/openid-connect-discovery-1_0.html) für die OpenID Connect Discovery Spezifikation. - -## Beispiel {#example} - -```ts -import { fetchServerConfig } from 'mcp-auth'; -// Abrufen der OAuth-Serverkonfiguration -// Dies ruft die Metadaten von `https://auth.logto.io/.well-known/oauth-authorization-server/oauth` ab -const oauthConfig = await fetchServerConfig('https://auth.logto.io/oauth', { type: 'oauth' }); - -// Abrufen der OpenID Connect-Serverkonfiguration -// Dies ruft die Metadaten von `https://auth.logto.io/oidc/.well-known/openid-configuration` ab -const oidcConfig = await fetchServerConfig('https://auth.logto.io/oidc', { type: 'oidc' }); -``` - -## Fehlerfälle {#throws} - -wenn der Abrufvorgang fehlschlägt. - -## Fehlerfälle {#throws} - -wenn die Server-Metadaten ungültig sind oder nicht der MCP-Spezifikation entsprechen. diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfigByWellKnownUrl.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfigByWellKnownUrl.md deleted file mode 100644 index 5289229..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfigByWellKnownUrl.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -sidebar_label: fetchServerConfigByWellKnownUrl ---- - -# Funktion: fetchServerConfigByWellKnownUrl() - -```ts -function fetchServerConfigByWellKnownUrl(wellKnownUrl: string | URL, config: ServerMetadataConfig): Promise; -``` - -Ruft die Serverkonfiguration von der angegebenen Well-Known-URL ab und validiert sie gegen die -MCP-Spezifikation. - -Wenn die Server-Metadaten nicht dem erwarteten Schema entsprechen, du dir aber sicher bist, dass sie -kompatibel sind, kannst du eine `transpileData`-Funktion definieren, um die Metadaten in das -erwartete Format zu transformieren. - -## Parameter {#parameters} - -### wellKnownUrl {#wellknownurl} - -Die Well-Known-URL, von der die Serverkonfiguration abgerufen werden soll. Dies kann ein -String oder ein URL-Objekt sein. - -`string` | `URL` - -### config {#config} - -`ServerMetadataConfig` - -Das Konfigurationsobjekt, das den Servertyp und optional eine Transpile-Funktion enthält. - -## Rückgabewert {#returns} - -`Promise`\<[`AuthServerConfig`](/references/js/type-aliases/AuthServerConfig.md)\> - -Ein Promise, das mit der Serverkonfiguration aufgelöst wird. - -## Fehler {#throws} - -wenn der Abrufvorgang fehlschlägt. - -## Fehler {#throws} - -wenn die Server-Metadaten ungültig sind oder nicht der -MCP-Spezifikation entsprechen. diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/handleBearerAuth.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/handleBearerAuth.md deleted file mode 100644 index fa2f5ef..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/handleBearerAuth.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -sidebar_label: handleBearerAuth ---- - -# Funktion: handleBearerAuth() - -```ts -function handleBearerAuth(param0: BearerAuthConfig): RequestHandler; -``` - -Erstellt eine Middleware-Funktion zur Behandlung von Bearer-Authentifizierung in einer Express-Anwendung. - -Diese Middleware extrahiert das Bearer-Token aus dem `Authorization`-Header, überprüft es mit der bereitgestellten Funktion `verifyAccessToken` und prüft den Aussteller (Issuer), die Zielgruppe (Audience) und die erforderlichen Berechtigungen (Scopes). - -- Wenn das Token gültig ist, fügt es die Authentifizierungsinformationen zur Eigenschaft `request.auth` hinzu; andernfalls antwortet es mit einer entsprechenden Fehlermeldung. -- Wenn die Zugangstoken (Access token) Überprüfung fehlschlägt, wird mit einem 401 Unauthorized-Fehler geantwortet. -- Wenn das Token nicht über die erforderlichen Berechtigungen (Scopes) verfügt, wird mit einem 403 Forbidden-Fehler geantwortet. -- Wenn unerwartete Fehler während des Authentifizierungsprozesses auftreten, wirft die Middleware diese erneut. - -**Hinweis:** Das Objekt `request.auth` enthält erweiterte Felder im Vergleich zur Standard-AuthInfo-Schnittstelle, die im Modul `@modelcontextprotocol/sdk` definiert ist. Siehe die erweiterte Schnittstelle in dieser Datei für Details. - -## Parameter {#parameters} - -### param0 {#param0} - -[`BearerAuthConfig`](/references/js/type-aliases/BearerAuthConfig.md) - -Konfiguration für den Bearer-Authentifizierungs-Handler. - -## Rückgabe {#returns} - -`RequestHandler` - -Eine Middleware-Funktion für Express, die Bearer-Authentifizierung behandelt. - -## Siehe auch {#see} - -[BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) für die Konfigurationsoptionen. diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfig.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfig.md deleted file mode 100644 index 3137e60..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfig.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -sidebar_label: AuthServerConfig ---- - -# Typalias: AuthServerConfig - -```ts -type AuthServerConfig = { - metadata: CamelCaseAuthorizationServerMetadata; - type: AuthServerType; -}; -``` - -Konfiguration für den entfernten Autorisierungsserver (Authorization Server), der mit dem MCP-Server integriert ist. - -## Eigenschaften {#properties} - -### metadata {#metadata} - -```ts -metadata: CamelCaseAuthorizationServerMetadata; -``` - -Die Metadaten des Autorisierungsservers (Authorization Server), die der MCP-Spezifikation entsprechen sollten -(basierend auf OAuth 2.0 Authorization Server Metadata). - -Diese Metadaten werden typischerweise vom Well-Known-Endpunkt des Servers abgerufen (OAuth 2.0 -Authorization Server Metadata oder OpenID Connect Discovery); sie können auch direkt in der Konfiguration bereitgestellt werden, wenn der Server solche Endpunkte nicht unterstützt. - -**Hinweis:** Die Metadaten sollten im camelCase-Format vorliegen, wie von der mcp-auth-Bibliothek bevorzugt. - -#### Siehe {#see} - - - [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) - - [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) - -*** - -### type {#type} - -```ts -type: AuthServerType; -``` - -Der Typ des Autorisierungsservers (Authorization Server). - -#### Siehe {#see} - -[AuthServerType](/references/js/type-aliases/AuthServerType.md) für die möglichen Werte. diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigError.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigError.md deleted file mode 100644 index c636932..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigError.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -sidebar_label: AuthServerConfigError ---- - -# Typalias: AuthServerConfigError - -```ts -type AuthServerConfigError = { - cause?: Error; - code: AuthServerConfigErrorCode; - description: string; -}; -``` - -Stellt einen Fehler dar, der während der Validierung der Metadaten des Autorisierungsservers (authorization server) auftritt. - -## Eigenschaften {#properties} - -### cause? {#cause} - -```ts -optional cause: Error; -``` - -Eine optionale Ursache des Fehlers, typischerweise eine Instanz von `Error`, die mehr Kontext liefert. - -*** - -### code {#code} - -```ts -code: AuthServerConfigErrorCode; -``` - -Der Code, der den spezifischen Validierungsfehler repräsentiert. - -*** - -### description {#description} - -```ts -description: string; -``` - -Eine menschenlesbare Beschreibung des Fehlers. diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigErrorCode.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigErrorCode.md deleted file mode 100644 index c2e38c3..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigErrorCode.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_label: AuthServerConfigErrorCode ---- - -# Typalias: AuthServerConfigErrorCode - -```ts -type AuthServerConfigErrorCode = - | "invalid_server_metadata" - | "code_response_type_not_supported" - | "authorization_code_grant_not_supported" - | "pkce_not_supported" - | "s256_code_challenge_method_not_supported"; -``` - -Die Codes für Fehler, die bei der Validierung der Metadaten des Autorisierungsservers auftreten können. \ No newline at end of file diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarning.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarning.md deleted file mode 100644 index 4b372f5..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarning.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -sidebar_label: AuthServerConfigWarning ---- - -# Typalias: AuthServerConfigWarning - -```ts -type AuthServerConfigWarning = { - code: AuthServerConfigWarningCode; - description: string; -}; -``` - -Stellt eine Warnung dar, die während der Validierung der Metadaten des Autorisierungsservers (authorization server) auftritt. - -## Eigenschaften {#properties} - -### code {#code} - -```ts -code: AuthServerConfigWarningCode; -``` - -Der Code, der die spezifische Validierungswarnung darstellt. - -*** - -### description {#description} - -```ts -description: string; -``` - -Eine für Menschen lesbare Beschreibung der Warnung. diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarningCode.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarningCode.md deleted file mode 100644 index d6aca4c..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarningCode.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -sidebar_label: AuthServerConfigWarningCode ---- - -# Typalias: AuthServerConfigWarningCode - -```ts -type AuthServerConfigWarningCode = "dynamic_registration_not_supported"; -``` - -Die Codes für Warnungen, die beim Validieren der Metadaten des Autorisierungsservers auftreten können. \ No newline at end of file diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerErrorCode.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerErrorCode.md deleted file mode 100644 index fe86fa0..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerErrorCode.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_label: AuthServerErrorCode ---- - -# Typalias: AuthServerErrorCode - -```ts -type AuthServerErrorCode = - | "invalid_server_metadata" - | "invalid_server_config" - | "missing_jwks_uri"; -``` diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerSuccessCode.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerSuccessCode.md deleted file mode 100644 index e20bee1..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerSuccessCode.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -sidebar_label: AuthServerSuccessCode ---- - -# Typalias: AuthServerSuccessCode - -```ts -type AuthServerSuccessCode = - | "server_metadata_valid" - | "dynamic_registration_supported" - | "pkce_supported" - | "s256_code_challenge_method_supported" - | "authorization_code_grant_supported" - | "code_response_type_supported"; -``` - -Die Codes für die erfolgreiche Validierung der Metadaten des Autorisierungsservers (authorization server metadata). \ No newline at end of file diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerType.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerType.md deleted file mode 100644 index 2374399..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerType.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -sidebar_label: AuthServerType ---- - -# Typalias: AuthServerType - -```ts -type AuthServerType = "oauth" | "oidc"; -``` - -Der Typ des Autorisierungsservers (authorization server). Diese Information sollte durch die Serverkonfiguration bereitgestellt werden und gibt an, ob der Server ein OAuth 2.0- oder OpenID Connect (OIDC)-Autorisierungsserver ist. diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthorizationServerMetadata.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthorizationServerMetadata.md deleted file mode 100644 index 6915b1f..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthorizationServerMetadata.md +++ /dev/null @@ -1,227 +0,0 @@ ---- -sidebar_label: AuthorizationServerMetadata ---- - -# Typalias: AuthorizationServerMetadata - -```ts -type AuthorizationServerMetadata = { - authorization_endpoint: string; - code_challenge_methods_supported?: string[]; - grant_types_supported?: string[]; - introspection_endpoint?: string; - introspection_endpoint_auth_methods_supported?: string[]; - introspection_endpoint_auth_signing_alg_values_supported?: string[]; - issuer: string; - jwks_uri?: string; - op_policy_uri?: string; - op_tos_uri?: string; - registration_endpoint?: string; - response_modes_supported?: string[]; - response_types_supported: string[]; - revocation_endpoint?: string; - revocation_endpoint_auth_methods_supported?: string[]; - revocation_endpoint_auth_signing_alg_values_supported?: string[]; - scope_supported?: string[]; - service_documentation?: string; - token_endpoint: string; - token_endpoint_auth_methods_supported?: string[]; - token_endpoint_auth_signing_alg_values_supported?: string[]; - ui_locales_supported?: string[]; - userinfo_endpoint?: string; -}; -``` - -Schema für OAuth 2.0 Autorisierungsserver-Metadaten wie in RFC 8414 definiert. - -## Typdeklaration {#type-declaration} - -### authorization\_endpoint {#authorization-endpoint} - -```ts -authorization_endpoint: string; -``` - -URL des Autorisierungsendpunkts des Autorisierungsservers [[RFC6749](https://rfc-editor.org/rfc/rfc6749)]. -Dies ist ERFORDERLICH, sofern keine Grant-Typen unterstützt werden, die den Autorisierungsendpunkt verwenden. - -#### Siehe {#see} - -https://rfc-editor.org/rfc/rfc6749#section-3.1 - -### code\_challenge\_methods\_supported? {#code-challenge-methods-supported} - -```ts -optional code_challenge_methods_supported: string[]; -``` - -JSON-Array mit einer Liste der von diesem Autorisierungsserver unterstützten Proof Key for Code Exchange (PKCE) -[[RFC7636](https://www.rfc-editor.org/rfc/rfc7636)] Code-Challenge-Methoden. - -### grant\_types\_supported? {#grant-types-supported} - -```ts -optional grant_types_supported: string[]; -``` - -JSON-Array mit einer Liste der OAuth 2.0 Grant-Typ-Werte, die dieser Autorisierungsserver unterstützt. -Die Array-Werte entsprechen denen, die mit dem `grant_types`-Parameter verwendet werden, wie im "OAuth 2.0 Dynamic Client Registration Protocol" [[RFC7591](https://www.rfc-editor.org/rfc/rfc7591)] definiert. -Wenn weggelassen, ist der Standardwert `["authorization_code", "implicit"]`. - -### introspection\_endpoint? {#introspection-endpoint} - -```ts -optional introspection_endpoint: string; -``` - -URL des OAuth 2.0 Introspektionsendpunkts des Autorisierungsservers -[[RFC7662](https://www.rfc-editor.org/rfc/rfc7662)]. - -### introspection\_endpoint\_auth\_methods\_supported? {#introspection-endpoint-auth-methods-supported} - -```ts -optional introspection_endpoint_auth_methods_supported: string[]; -``` - -### introspection\_endpoint\_auth\_signing\_alg\_values\_supported? {#introspection-endpoint-auth-signing-alg-values-supported} - -```ts -optional introspection_endpoint_auth_signing_alg_values_supported: string[]; -``` - -### issuer {#issuer} - -```ts -issuer: string; -``` - -Der Aussteller (Issuer) des Autorisierungsservers, eine URL, die das `https`-Schema verwendet und keine Query- oder Fragment-Komponenten enthält. - -### jwks\_uri? {#jwks-uri} - -```ts -optional jwks_uri: string; -``` - -URL des JWK-Set-Dokuments [[JWK](https://www.rfc-editor.org/rfc/rfc8414.html#ref-JWK)] des Autorisierungsservers. -Das referenzierte Dokument enthält die Signierschlüssel, die der Client verwendet, um Signaturen des Autorisierungsservers zu validieren. Diese URL MUSS das `https`-Schema verwenden. - -### op\_policy\_uri? {#op-policy-uri} - -```ts -optional op_policy_uri: string; -``` - -### op\_tos\_uri? {#op-tos-uri} - -```ts -optional op_tos_uri: string; -``` - -### registration\_endpoint? {#registration-endpoint} - -```ts -optional registration_endpoint: string; -``` - -URL des OAuth 2.0 Dynamic Client Registration Endpunkts des Autorisierungsservers -[[RFC7591](https://www.rfc-editor.org/rfc/rfc7591)]. - -### response\_modes\_supported? {#response-modes-supported} - -```ts -optional response_modes_supported: string[]; -``` - -JSON-Array mit einer Liste der OAuth 2.0 `response_mode`-Werte, die dieser Autorisierungsserver unterstützt, wie in "OAuth 2.0 Multiple Response Type Encoding Practices" -[[OAuth.Responses](https://datatracker.ietf.org/doc/html/rfc8414#ref-OAuth.Responses)] spezifiziert. - -Wenn weggelassen, ist der Standardwert `["query", "fragment"]`. Der Response-Mode-Wert `"form_post"` ist ebenfalls in "OAuth 2.0 Form Post Response Mode" -[[OAuth.FormPost](https://datatracker.ietf.org/doc/html/rfc8414#ref-OAuth.Post)] definiert. - -### response\_types\_supported {#response-types-supported} - -```ts -response_types_supported: string[]; -``` - -JSON-Array mit einer Liste der OAuth 2.0 `response_type`-Werte, die dieser Autorisierungsserver unterstützt. -Die Array-Werte entsprechen denen, die mit dem `response_types`-Parameter verwendet werden, wie im "OAuth 2.0 Dynamic Client Registration Protocol" -[[RFC7591](https://www.rfc-editor.org/rfc/rfc7591)] definiert. - -### revocation\_endpoint? {#revocation-endpoint} - -```ts -optional revocation_endpoint: string; -``` - -URL des OAuth 2.0 Widerrufsendpunkts des Autorisierungsservers -[[RFC7009](https://www.rfc-editor.org/rfc/rfc7009)]. - -### revocation\_endpoint\_auth\_methods\_supported? {#revocation-endpoint-auth-methods-supported} - -```ts -optional revocation_endpoint_auth_methods_supported: string[]; -``` - -### revocation\_endpoint\_auth\_signing\_alg\_values\_supported? {#revocation-endpoint-auth-signing-alg-values-supported} - -```ts -optional revocation_endpoint_auth_signing_alg_values_supported: string[]; -``` - -### scope\_supported? {#scope-supported} - -```ts -optional scope_supported: string[]; -``` - -### service\_documentation? {#service-documentation} - -```ts -optional service_documentation: string; -``` - -### token\_endpoint {#token-endpoint} - -```ts -token_endpoint: string; -``` - -URL des Token-Endpunkts des Autorisierungsservers [[RFC6749](https://rfc-editor.org/rfc/rfc6749)]. -Dies ist ERFORDERLICH, sofern nur der Implicit Grant-Typ unterstützt wird. - -#### Siehe {#see} - -https://rfc-editor.org/rfc/rfc6749#section-3.2 - -### token\_endpoint\_auth\_methods\_supported? {#token-endpoint-auth-methods-supported} - -```ts -optional token_endpoint_auth_methods_supported: string[]; -``` - -### token\_endpoint\_auth\_signing\_alg\_values\_supported? {#token-endpoint-auth-signing-alg-values-supported} - -```ts -optional token_endpoint_auth_signing_alg_values_supported: string[]; -``` - -### ui\_locales\_supported? {#ui-locales-supported} - -```ts -optional ui_locales_supported: string[]; -``` - -### userinfo\_endpoint? {#userinfo-endpoint} - -```ts -optional userinfo_endpoint: string; -``` - -URL des OpenID Connect [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo). -Dieser Endpunkt wird verwendet, um Informationen über den authentifizierten Benutzer abzurufen. - -## Siehe {#see} - -https://datatracker.ietf.org/doc/html/rfc8414 \ No newline at end of file diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthConfig.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthConfig.md deleted file mode 100644 index 5434919..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthConfig.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -sidebar_label: BearerAuthConfig ---- - -# Typalias: BearerAuthConfig - -```ts -type BearerAuthConfig = { - audience?: string; - issuer: string; - requiredScopes?: string[]; - showErrorDetails?: boolean; - verifyAccessToken: VerifyAccessTokenFunction; -}; -``` - -## Eigenschaften {#properties} - -### audience? {#audience} - -```ts -optional audience: string; -``` - -Die erwartete Zielgruppe (Audience) des Zugangstokens (Zugangstoken (`aud` Anspruch)). Dies ist typischerweise der Ressourcenserver -(API), für den das Token bestimmt ist. Wenn nicht angegeben, wird die Überprüfung der Zielgruppe übersprungen. - -**Hinweis:** Wenn dein Autorisierungsserver keine Ressourcenindikatoren (RFC 8707) unterstützt, -kannst du dieses Feld weglassen, da die Zielgruppe möglicherweise nicht relevant ist. - -#### Siehe {#see} - -https://datatracker.ietf.org/doc/html/rfc8707 - -*** - -### issuer {#issuer} - -```ts -issuer: string; -``` - -Der erwartete Aussteller (Issuer) des Zugangstokens (Zugangstoken (`iss` Anspruch)). Dies sollte die URL des -Autorisierungsservers sein, der das Token ausgestellt hat. - -*** - -### requiredScopes? {#requiredscopes} - -```ts -optional requiredScopes: string[]; -``` - -Ein Array der erforderlichen Berechtigungen (Scopes), die das Zugangstoken besitzen muss. Wenn das Token nicht -alle diese Berechtigungen enthält, wird ein Fehler ausgelöst. - -**Hinweis:** Der Handler prüft den `scope`-Anspruch im Token, der je nach Implementierung des Autorisierungsservers -eine durch Leerzeichen getrennte Zeichenkette oder ein Array von Zeichenketten sein kann. Wenn der `scope`-Anspruch nicht vorhanden ist, -prüft der Handler den `scopes`-Anspruch, sofern verfügbar. - -*** - -### showErrorDetails? {#showerrordetails} - -```ts -optional showErrorDetails: boolean; -``` - -Ob detaillierte Fehlerinformationen in der Antwort angezeigt werden sollen. Dies ist während der Entwicklung zum Debuggen nützlich, -sollte aber in der Produktion deaktiviert werden, um das Offenlegen sensibler Informationen zu vermeiden. - -#### Standardwert {#default} - -```ts -false -``` - -*** - -### verifyAccessToken {#verifyaccesstoken} - -```ts -verifyAccessToken: VerifyAccessTokenFunction; -``` - -Funktionstyp zur Überprüfung eines Zugangstokens. - -Diese Funktion sollte einen [MCPAuthTokenVerificationError](/references/js/classes/MCPAuthTokenVerificationError.md) auslösen, wenn das Token ungültig ist, -oder ein AuthInfo-Objekt zurückgeben, wenn das Token gültig ist. - -#### Siehe {#see} - -[VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) für weitere Details. diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthErrorCode.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthErrorCode.md deleted file mode 100644 index 290f126..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthErrorCode.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_label: BearerAuthErrorCode ---- - -# Typalias: BearerAuthErrorCode - -```ts -type BearerAuthErrorCode = - | "missing_auth_header" - | "invalid_auth_header_format" - | "missing_bearer_token" - | "invalid_issuer" - | "invalid_audience" - | "missing_required_scopes" - | "invalid_token"; -``` diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthJwtConfig.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthJwtConfig.md deleted file mode 100644 index 4a6a82e..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthJwtConfig.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -sidebar_label: BearerAuthJwtConfig ---- - -# Typalias: BearerAuthJwtConfig - -```ts -type BearerAuthJwtConfig = { - jwtVerify?: JWTVerifyOptions; - remoteJwkSet?: RemoteJWKSetOptions; -}; -``` - -Konfiguration für den Bearer-Auth-Handler bei Verwendung der JWT-Verifizierung. - -## Eigenschaften {#properties} - -### jwtVerify? {#jwtverify} - -```ts -optional jwtVerify: JWTVerifyOptions; -``` - -Optionen, die an die `jwtVerify`-Funktion der `jose`-Bibliothek übergeben werden. - -#### Siehe {#see} - -JWTVerifyOptions für die Typdefinition der Optionen. - -*** - -### remoteJwkSet? {#remotejwkset} - -```ts -optional remoteJwkSet: RemoteJWKSetOptions; -``` - -Optionen, die an die `createRemoteJWKSet`-Funktion der `jose`-Bibliothek übergeben werden. - -#### Siehe {#see} - -RemoteJWKSetOptions für die Typdefinition der Optionen. diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md deleted file mode 100644 index 74be434..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -sidebar_label: CamelCaseAuthorizationServerMetadata ---- - -# Typalias: CamelCaseAuthorizationServerMetadata - -```ts -type CamelCaseAuthorizationServerMetadata = { - authorizationEndpoint: string; - codeChallengeMethodsSupported?: string[]; - grantTypesSupported?: string[]; - introspectionEndpoint?: string; - introspectionEndpointAuthMethodsSupported?: string[]; - introspectionEndpointAuthSigningAlgValuesSupported?: string[]; - issuer: string; - jwksUri?: string; - opPolicyUri?: string; - opTosUri?: string; - registrationEndpoint?: string; - responseModesSupported?: string[]; - responseTypesSupported: string[]; - revocationEndpoint?: string; - revocationEndpointAuthMethodsSupported?: string[]; - revocationEndpointAuthSigningAlgValuesSupported?: string[]; - scopeSupported?: string[]; - serviceDocumentation?: string; - tokenEndpoint: string; - tokenEndpointAuthMethodsSupported?: string[]; - tokenEndpointAuthSigningAlgValuesSupported?: string[]; - uiLocalesSupported?: string[]; - userinfoEndpoint?: string; -}; -``` - -Die camelCase-Version des OAuth 2.0 Authorization Server Metadata-Typs. - -## Typdeklaration {#type-declaration} - -### authorizationEndpoint {#authorizationendpoint} - -```ts -authorizationEndpoint: string; -``` - -### codeChallengeMethodsSupported? {#codechallengemethodssupported} - -```ts -optional codeChallengeMethodsSupported: string[]; -``` - -### grantTypesSupported? {#granttypessupported} - -```ts -optional grantTypesSupported: string[]; -``` - -### introspectionEndpoint? {#introspectionendpoint} - -```ts -optional introspectionEndpoint: string; -``` - -### introspectionEndpointAuthMethodsSupported? {#introspectionendpointauthmethodssupported} - -```ts -optional introspectionEndpointAuthMethodsSupported: string[]; -``` - -### introspectionEndpointAuthSigningAlgValuesSupported? {#introspectionendpointauthsigningalgvaluessupported} - -```ts -optional introspectionEndpointAuthSigningAlgValuesSupported: string[]; -``` - -### issuer {#issuer} - -```ts -issuer: string; -``` - -### jwksUri? {#jwksuri} - -```ts -optional jwksUri: string; -``` - -### opPolicyUri? {#oppolicyuri} - -```ts -optional opPolicyUri: string; -``` - -### opTosUri? {#optosuri} - -```ts -optional opTosUri: string; -``` - -### registrationEndpoint? {#registrationendpoint} - -```ts -optional registrationEndpoint: string; -``` - -### responseModesSupported? {#responsemodessupported} - -```ts -optional responseModesSupported: string[]; -``` - -### responseTypesSupported {#responsetypessupported} - -```ts -responseTypesSupported: string[]; -``` - -### revocationEndpoint? {#revocationendpoint} - -```ts -optional revocationEndpoint: string; -``` - -### revocationEndpointAuthMethodsSupported? {#revocationendpointauthmethodssupported} - -```ts -optional revocationEndpointAuthMethodsSupported: string[]; -``` - -### revocationEndpointAuthSigningAlgValuesSupported? {#revocationendpointauthsigningalgvaluessupported} - -```ts -optional revocationEndpointAuthSigningAlgValuesSupported: string[]; -``` - -### scopeSupported? {#scopesupported} - -```ts -optional scopeSupported: string[]; -``` - -### serviceDocumentation? {#servicedocumentation} - -```ts -optional serviceDocumentation: string; -``` - -### tokenEndpoint {#tokenendpoint} - -```ts -tokenEndpoint: string; -``` - -### tokenEndpointAuthMethodsSupported? {#tokenendpointauthmethodssupported} - -```ts -optional tokenEndpointAuthMethodsSupported: string[]; -``` - -### tokenEndpointAuthSigningAlgValuesSupported? {#tokenendpointauthsigningalgvaluessupported} - -```ts -optional tokenEndpointAuthSigningAlgValuesSupported: string[]; -``` - -### uiLocalesSupported? {#uilocalessupported} - -```ts -optional uiLocalesSupported: string[]; -``` - -### userinfoEndpoint? {#userinfoendpoint} - -```ts -optional userinfoEndpoint: string; -``` - -## Siehe auch {#see} - -[AuthorizationServerMetadata](/references/js/type-aliases/AuthorizationServerMetadata.md) für den Originaltyp und Feldinformationen. diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md deleted file mode 100644 index f8be37f..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -sidebar_label: MCPAuthBearerAuthErrorDetails ---- - -# Typalias: MCPAuthBearerAuthErrorDetails - -```ts -type MCPAuthBearerAuthErrorDetails = { - actual?: unknown; - cause?: unknown; - expected?: unknown; - missingScopes?: string[]; - uri?: URL; -}; -``` - -## Eigenschaften {#properties} - -### actual? {#actual} - -```ts -optional actual: unknown; -``` - -*** - -### cause? {#cause} - -```ts -optional cause: unknown; -``` - -*** - -### expected? {#expected} - -```ts -optional expected: unknown; -``` - -*** - -### missingScopes? {#missingscopes} - -```ts -optional missingScopes: string[]; -``` - -*** - -### uri? {#uri} - -```ts -optional uri: URL; -``` diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthConfig.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthConfig.md deleted file mode 100644 index eac45c4..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthConfig.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -sidebar_label: MCPAuthConfig ---- - -# Typalias: MCPAuthConfig - -```ts -type MCPAuthConfig = { - server: AuthServerConfig; -}; -``` - -Konfiguration für die [MCPAuth](/references/js/classes/MCPAuth.md)-Klasse. - -## Eigenschaften {#properties} - -### server {#server} - -```ts -server: AuthServerConfig; -``` - -Konfiguration für den entfernten Autorisierungsserver. diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md deleted file mode 100644 index d090ace..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: MCPAuthTokenVerificationErrorCode ---- - -# Typalias: MCPAuthTokenVerificationErrorCode - -```ts -type MCPAuthTokenVerificationErrorCode = "invalid_token" | "token_verification_failed"; -``` diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenFunction.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenFunction.md deleted file mode 100644 index abf3900..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenFunction.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -sidebar_label: VerifyAccessTokenFunction ---- - -# Typalias: VerifyAccessTokenFunction() - -```ts -type VerifyAccessTokenFunction = (token: string) => MaybePromise; -``` - -Funktionstyp zur Überprüfung eines Zugangstokens (Access token). - -Diese Funktion sollte einen [MCPAuthTokenVerificationError](/references/js/classes/MCPAuthTokenVerificationError.md) auslösen, wenn das Token ungültig ist, -oder ein AuthInfo-Objekt zurückgeben, wenn das Token gültig ist. - -Wenn du zum Beispiel eine JWT-Überprüfungsfunktion hast, sollte sie mindestens die Signatur des Tokens -überprüfen, das Ablaufdatum validieren und die notwendigen Ansprüche (Claims) extrahieren, um ein `AuthInfo`- -Objekt zurückzugeben. - -**Hinweis:** Es ist nicht notwendig, die folgenden Felder im Token zu überprüfen, da sie vom Handler geprüft werden: - -- `iss` (Aussteller / issuer) -- `aud` (Zielgruppe / audience) -- `scope` (Berechtigungen / scopes) - -## Parameter {#parameters} - -### token {#token} - -`string` - -Der zu überprüfende Zugangstoken-String (Access token). - -## Rückgabewert {#returns} - -`MaybePromise`\<`AuthInfo`\> - -Ein Promise, das sich auf ein AuthInfo-Objekt auflöst, oder ein synchroner Wert, wenn das -Token gültig ist. diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenMode.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenMode.md deleted file mode 100644 index ff3a04b..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenMode.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: VerifyAccessTokenMode ---- - -# Typalias: VerifyAccessTokenMode - -```ts -type VerifyAccessTokenMode = "jwt"; -``` diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authServerErrorDescription.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authServerErrorDescription.md deleted file mode 100644 index b4726e8..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authServerErrorDescription.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: authServerErrorDescription ---- - -# Variable: authServerErrorDescription - -```ts -const authServerErrorDescription: Readonly>; -``` diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authorizationServerMetadataSchema.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authorizationServerMetadataSchema.md deleted file mode 100644 index 67260d1..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authorizationServerMetadataSchema.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: authorizationServerMetadataSchema ---- - -# Variable: authorizationServerMetadataSchema - -```ts -const authorizationServerMetadataSchema: ZodObject; -``` - -Zod-Schema für OAuth 2.0 Authorization Server Metadata wie in RFC 8414 definiert. - -## Siehe {#see} - -https://datatracker.ietf.org/doc/html/rfc8414 \ No newline at end of file diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/bearerAuthErrorDescription.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/bearerAuthErrorDescription.md deleted file mode 100644 index ed1a931..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/bearerAuthErrorDescription.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: bearerAuthErrorDescription ---- - -# Variable: bearerAuthErrorDescription - -```ts -const bearerAuthErrorDescription: Readonly>; -``` diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md deleted file mode 100644 index 6ecab80..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: camelCaseAuthorizationServerMetadataSchema ---- - -# Variable: camelCaseAuthorizationServerMetadataSchema - -```ts -const camelCaseAuthorizationServerMetadataSchema: ZodObject; -``` - -Die camelCase-Version des OAuth 2.0 Authorization Server Metadata Zod-Schemas. - -## Siehe {#see} - -[authorizationServerMetadataSchema](/references/js/variables/authorizationServerMetadataSchema.md) für das ursprüngliche Schema und Feldinformationen. diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/serverMetadataPaths.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/serverMetadataPaths.md deleted file mode 100644 index 68cbf41..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/serverMetadataPaths.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_label: serverMetadataPaths ---- - -# Variable: serverMetadataPaths - -```ts -const serverMetadataPaths: Readonly<{ - oauth: "/.well-known/oauth-authorization-server"; - oidc: "/.well-known/openid-configuration"; -}>; -``` diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/tokenVerificationErrorDescription.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/tokenVerificationErrorDescription.md deleted file mode 100644 index 3d6e760..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/tokenVerificationErrorDescription.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: tokenVerificationErrorDescription ---- - -# Variable: tokenVerificationErrorDescription - -```ts -const tokenVerificationErrorDescription: Readonly>; -``` diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/validateServerConfig.md b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/validateServerConfig.md deleted file mode 100644 index e60de41..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/validateServerConfig.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: validateServerConfig ---- - -# Variable: validateServerConfig - -```ts -const validateServerConfig: ValidateServerConfig; -``` diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/snippets/_get-started-code.mdx b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/snippets/_get-started-code.mdx deleted file mode 100644 index 693d98e..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/snippets/_get-started-code.mdx +++ /dev/null @@ -1,41 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - - - - - -```python -mcp = FastMCP("MyMCPServer") -mcp_auth = MCPAuth(server=fetch_server_config('', type=AuthServerType.OIDC)) -app = Starlette( - # ... your MCP server setup - middleware=[Middleware( - mcp_auth.bearer_auth_middleware("jwt", required_scopes=["read", "write"]) - )] -) - -# Verwende `mcp_auth.auth_info`, um auf die Authentifizierungsinformationen (auth information) der aktuellen Anfrage zuzugreifen -@mcp.tool() -def whoami() -> dict[str, Any]: - return mcp_auth.auth_info.claims -``` - - - - -```ts -const server = new McpServer(/* ... */); -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { type: 'oidc' }), -}); -const app = express(); - -app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] })); -server.tool('whoami', ({ authInfo }) => { - // Verwende `authInfo`, um auf die Authentifizierungsinformationen (auth information) aus `req.auth` zuzugreifen -}); -``` - - - diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/README.mdx b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/README.mdx deleted file mode 100644 index 25a255d..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/README.mdx +++ /dev/null @@ -1,1149 +0,0 @@ ---- -sidebar_position: 2 -sidebar_label: 'Tutorial: Baue einen Todo-Manager' ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import SetupOauthOrOidc from './_setup-oauth-or-oidc.mdx'; -import SetupOidc from './_setup-oidc.mdx'; - -# Tutorial: Baue einen Todo-Manager - -In diesem Tutorial bauen wir einen Todo-Manager-MCP-Server mit Benutzer-Authentifizierung (Authentifizierung) und Autorisierung (Autorisierung). - -Nach Abschluss dieses Tutorials hast du: - -- ✅ Ein grundlegendes Verständnis, wie du rollenbasierte Zugangskontrolle (RBAC) in deinem MCP-Server einrichtest. -- ✅ Einen MCP-Server, der persönliche Todo-Listen verwalten kann. - -:::note -Bevor du beginnst, empfehlen wir dir dringend, zuerst das [Who am I Tutorial](./whoami) durchzugehen, falls du mit dem MCP-Server und OAuth 2 nicht vertraut bist. -::: - -## Überblick \{#overview} - -Das Tutorial umfasst folgende Komponenten: - -- **MCP-Server**: Ein einfacher MCP-Server, der die offiziellen MCP-SDKs verwendet, um Anfragen zu bearbeiten, mit einem integrierten Todo-Service zur Verwaltung der Todo-Einträge der Benutzer. -- **MCP Inspector**: Ein visuelles Test-Tool für MCP-Server. Es agiert auch als OAuth / OIDC-Client, um den Autorisierungsfluss zu starten und Zugangstokens abzurufen. -- **Autorisierungsserver**: Ein OAuth 2.1- oder OpenID Connect-Anbieter, der Benutzeridentitäten verwaltet und Zugangstokens ausstellt. - -Hier ist ein Überblicksdiagramm der Interaktion zwischen diesen Komponenten: - -```mermaid -sequenceDiagram - participant Client as MCP Inspector - participant Server as MCP Server - participant Auth as Autorisierungsserver - - Client->>Server: Todo-Operation anfordern - Server->>Client: 401 Nicht autorisiert zurückgeben - Client->>Auth: Autorisierungsfluss starten - Auth->>Auth: Autorisierungsfluss abschließen - Auth->>Client: Mit Autorisierungscode zurückleiten - Client->>Auth: Code gegen Zugangstoken tauschen - Auth->>Client: Zugangstoken zurückgeben - Client->>Server: Todo-Operation mit Zugangstoken anfordern - Server->>Server: Zugangstoken validieren und Benutzer-Berechtigungen aus Zugangstoken abrufen - Note over Server: Todo-Operation ausführen - Server->>Client: Ergebnis der Todo-Operation zurückgeben -``` - -## Verstehe deinen Autorisierungsserver \{#understand-your-authorization-server} - -### Zugangstokens mit Berechtigungen (Scopes) \{#access-tokens-with-scopes} - -Um [rollenbasierte Zugangskontrolle (RBAC)](https://auth.wiki/rbac) in deinem MCP-Server zu implementieren, muss dein Autorisierungsserver das Ausstellen von Zugangstokens mit Berechtigungen (Scopes) unterstützen. Berechtigungen repräsentieren die Rechte, die einem Benutzer gewährt wurden. - - - - -[Logto](https://logto.io) bietet RBAC-Unterstützung über seine API-Ressourcen (gemäß [RFC 8707: Resource Indicators for OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)) und Rollenfunktionen. So richtest du es ein: - -1. Melde dich bei der [Logto Console](https://cloud.logto.io) (oder deiner selbst gehosteten Logto Console) an. - -2. Erstelle API-Ressource und Berechtigungen: - - - Gehe zu "API-Ressourcen" - - Erstelle eine neue API-Ressource namens "Todo Manager" - - Füge folgende Berechtigungen hinzu: - - `create:todos`: "Neue Todo-Einträge erstellen" - - `read:todos`: "Alle Todo-Einträge lesen" - - `delete:todos`: "Beliebigen Todo-Eintrag löschen" - -3. Erstelle Rollen (empfohlen für einfachere Verwaltung): - - - Gehe zu "Rollen" - - Erstelle eine "Admin"-Rolle und weise alle Berechtigungen zu (`create:todos`, `read:todos`, `delete:todos`) - - Erstelle eine "User"-Rolle und weise nur die Berechtigung `create:todos` zu - -4. Berechtigungen zuweisen: - - Gehe zu "Benutzer" - - Wähle einen Benutzer aus - - Du kannst entweder: - - Rollen im Tab "Rollen" zuweisen (empfohlen) - - Oder direkt Berechtigungen im Tab "Berechtigungen" zuweisen - -Die Berechtigungen werden im `scope`-Anspruch des JWT-Zugangstokens als durch Leerzeichen getrennte Zeichenkette enthalten sein. - - - - -OAuth 2.0 / OIDC-Anbieter unterstützen in der Regel berechtigungsbasierte Zugangskontrolle. Bei der Implementierung von RBAC: - -1. Definiere die benötigten Berechtigungen in deinem Autorisierungsserver -2. Konfiguriere deinen Client so, dass diese Berechtigungen während des Autorisierungsflusses angefordert werden -3. Stelle sicher, dass dein Autorisierungsserver die gewährten Berechtigungen im Zugangstoken einschließt -4. Die Berechtigungen sind normalerweise im `scope`-Anspruch des JWT-Zugangstokens enthalten - -Sieh in der Dokumentation deines Anbieters nach, wie: - -- Berechtigungen definiert und verwaltet werden -- Berechtigungen im Zugangstoken enthalten sind -- Zusätzliche RBAC-Funktionen wie Rollenverwaltung funktionieren - - - - -### Tokens validieren und Berechtigungen prüfen \{#validating-tokens-and-checking-permissions} - -Wenn dein MCP-Server eine Anfrage erhält, muss er: - -1. Die Signatur und das Ablaufdatum des Zugangstokens validieren -2. Die Berechtigungen aus dem validierten Token extrahieren -3. Prüfen, ob das Token die erforderlichen Berechtigungen für die angeforderte Operation enthält - -Wenn ein Benutzer z. B. einen neuen Todo-Eintrag erstellen möchte, muss sein Zugangstoken die Berechtigung `create:todos` enthalten. So funktioniert der Ablauf: - -```mermaid -sequenceDiagram - participant Client - participant MCP Server - participant Auth Server - - Client->>MCP Server: Anfrage mit Zugangstoken - - alt JWT-Validierung - MCP Server->>Auth Server: JWKS abrufen - Auth Server-->>MCP Server: JWKS zurückgeben - MCP Server->>MCP Server: JWT lokal validieren - else Token-Introspektion - MCP Server->>Auth Server: POST /introspect
(token=access_token) - Auth Server-->>MCP Server: Token-Info zurückgeben
(active, scope, etc.) - end - - MCP Server->>MCP Server: Berechtigungen extrahieren & prüfen - - alt Hat erforderliche Berechtigungen - MCP Server->>Client: Operation erlauben - else Fehlende Berechtigungen - MCP Server->>Client: 403 Verboten zurückgeben - end -``` - -### Dynamische Client-Registrierung \{#dynamic-client-registration} - -Die dynamische Client-Registrierung ist für dieses Tutorial nicht erforderlich, kann aber nützlich sein, wenn du die MCP-Client-Registrierung mit deinem Autorisierungsserver automatisieren möchtest. Siehe [Ist Dynamic Client Registration erforderlich?](/provider-list#is-dcr-required) für weitere Details. - -## Verstehe RBAC im Todo-Manager \{#understand-rbac-in-todo-manager} - -Zu Demonstrationszwecken implementieren wir ein einfaches rollenbasiertes Zugangskontrollsystem (RBAC) in unserem Todo-Manager-MCP-Server. Das zeigt dir die Grundprinzipien von RBAC bei überschaubarer Implementierung. - -:::note -Auch wenn dieses Tutorial RBAC-basierte Berechtigungsverwaltung demonstriert, ist es wichtig zu wissen, dass nicht alle Authentifizierungsanbieter die Berechtigungsverwaltung über Rollen implementieren. Manche Anbieter haben eigene Mechanismen zur Verwaltung von Zugangskontrolle und Berechtigungen. -::: - -### Tools und Berechtigungen \{#tools-and-scopes} - -Unser Todo-Manager-MCP-Server stellt drei Haupttools bereit: - -- `create-todo`: Einen neuen Todo-Eintrag erstellen -- `get-todos`: Alle Todos auflisten -- `delete-todo`: Ein Todo anhand der ID löschen - -Um den Zugriff auf diese Tools zu steuern, definieren wir folgende Berechtigungen: - -- `create:todos`: Erlaubt das Erstellen neuer Todo-Einträge -- `delete:todos`: Erlaubt das Löschen bestehender Todo-Einträge -- `read:todos`: Erlaubt das Abfragen und Abrufen aller Todo-Einträge - -### Rollen und Berechtigungen \{#roles-and-permissions} - -Wir definieren zwei Rollen mit unterschiedlichen Zugriffsrechten: - -| Rolle | create:todos | read:todos | delete:todos | -| ------ | ------------ | ---------- | ------------ | -| Admin | ✅ | ✅ | ✅ | -| User | ✅ | | | - -- **User**: Ein normaler Benutzer, der Todo-Einträge erstellen und nur seine eigenen Todos ansehen oder löschen kann -- **Admin**: Ein Administrator, der alle Todo-Einträge erstellen, ansehen und löschen kann, unabhängig vom Eigentümer - -### Ressourcenbesitz \{#resource-ownership} - -Obwohl die obige Berechtigungstabelle die explizit zugewiesenen Berechtigungen pro Rolle zeigt, gibt es ein wichtiges Prinzip des Ressourcenbesitzes zu beachten: - -- **Benutzer** haben nicht die Berechtigungen `read:todos` oder `delete:todos`, können aber trotzdem: - - Ihre eigenen Todo-Einträge lesen - - Ihre eigenen Todo-Einträge löschen -- **Admins** haben volle Berechtigungen (`read:todos` und `delete:todos`) und können: - - Alle Todo-Einträge im System ansehen - - Jeden Todo-Eintrag löschen, unabhängig vom Eigentümer - -Das demonstriert ein häufiges Muster in RBAC-Systemen, bei dem der Besitz einer Ressource implizite Berechtigungen für eigene Ressourcen gewährt, während administrative Rollen explizite Berechtigungen für alle Ressourcen erhalten. - -:::tip Mehr erfahren -Um tiefer in RBAC-Konzepte und Best Practices einzutauchen, sieh dir [Mastering RBAC: A Comprehensive Real-World Example](https://blog.logto.io/mastering-rbac) an. -::: - -## Autorisierung in deinem Anbieter konfigurieren \{#configure-authorization-in-your-provider} - -Um das oben beschriebene Zugangskontrollsystem zu implementieren, musst du deinen Autorisierungsserver so konfigurieren, dass er die benötigten Berechtigungen unterstützt. So geht es bei verschiedenen Anbietern: - - - - -[Logto](https://logto.io) bietet RBAC-Unterstützung über seine API-Ressourcen und Rollenfunktionen. So richtest du es ein: - -1. Melde dich bei der [Logto Console](https://cloud.logto.io) (oder deiner selbst gehosteten Logto Console) an. - -2. Erstelle API-Ressource und Berechtigungen: - - - Gehe zu "API-Ressourcen" - - Erstelle eine neue API-Ressource namens "Todo Manager" und verwende `https://todo.mcp-server.app` (zu Demo-Zwecken) als Indikator. - - Erstelle folgende Berechtigungen: - - `create:todos`: "Neue Todo-Einträge erstellen" - - `read:todos`: "Alle Todo-Einträge lesen" - - `delete:todos`: "Beliebigen Todo-Eintrag löschen" - -3. Erstelle Rollen (empfohlen für einfachere Verwaltung): - - - Gehe zu "Rollen" - - Erstelle eine "Admin"-Rolle und weise alle Berechtigungen zu (`create:todos`, `read:todos`, `delete:todos`) - - Erstelle eine "User"-Rolle und weise nur die Berechtigung `create:todos` zu - - Wechsle auf der Detailseite der "User"-Rolle zum Tab "Allgemein" und setze die "User"-Rolle als "Standardrolle". - -4. Benutzerrollen und Berechtigungen verwalten: - - Für neue Benutzer: - - Sie erhalten automatisch die "User"-Rolle, da wir sie als Standardrolle gesetzt haben - - Für bestehende Benutzer: - - Gehe zu "Benutzerverwaltung" - - Wähle einen Benutzer aus - - Weise dem Benutzer Rollen im Tab "Rollen" zu - -:::tip Programmatische Rollenverwaltung -Du kannst auch die [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api) von Logto verwenden, um Benutzerrollen programmatisch zu verwalten. Das ist besonders nützlich für automatisierte Benutzerverwaltung oder beim Erstellen von Admin-Panels. -::: - -Beim Anfordern eines Zugangstokens wird Logto die Berechtigungen im `scope`-Anspruch des Tokens basierend auf den Rollenberechtigungen des Benutzers einfügen. - - - - -In [Keycloak](https://www.keycloak.org) kannst du die erforderlichen Berechtigungen mit Client-Scopes einrichten: - -1. Client-Scopes erstellen: - - - Gehe in deinem Realm zu "Client scopes" - - Erstelle drei neue Client-Scopes: - - `create:todos` - - `read:todos` - - `delete:todos` - -2. Den Client konfigurieren: - - - Gehe zu deinen Client-Einstellungen - - Füge im Tab "Client scopes" alle erstellten Scopes hinzu - - Stelle sicher, dass der Token-Mapper so konfiguriert ist, dass die Scopes enthalten sind - -3. Optional: Rollen für einfachere Verwaltung nutzen - - Wenn du rollenbasierte Verwaltung bevorzugst: - - Erstelle Realm-Rollen für verschiedene Zugriffsebenen - - Mappe Scopes auf Rollen - - Weise Rollen Benutzern zu - - Alternativ kannst du Scopes direkt Benutzern oder über clientseitige Berechtigungen zuweisen - -Keycloak wird die gewährten Scopes im `scope`-Anspruch des Zugangstokens enthalten. - - - - -Für OAuth 2.0- oder OpenID Connect-Anbieter musst du die Scopes konfigurieren, die verschiedene Berechtigungen repräsentieren. Die genauen Schritte hängen von deinem Anbieter ab, aber im Allgemeinen: - -1. Scopes definieren: - - - Konfiguriere deinen Autorisierungsserver so, dass er unterstützt: - - `create:todos` - - `read:todos` - - `delete:todos` - -2. Client konfigurieren: - - - Registriere oder aktualisiere deinen Client, um diese Scopes anzufordern - - Stelle sicher, dass die Scopes im Zugangstoken enthalten sind - -3. Berechtigungen zuweisen: - - Verwende die Oberfläche deines Anbieters, um Benutzern die passenden Scopes zuzuweisen - - Manche Anbieter unterstützen rollenbasierte Verwaltung, andere nutzen direkte Scope-Zuweisungen - - Sieh in der Dokumentation deines Anbieters nach, was empfohlen wird - -:::tip -Die meisten Anbieter werden die gewährten Scopes im `scope`-Anspruch des Zugangstokens enthalten. Das Format ist typischerweise eine durch Leerzeichen getrennte Zeichenkette von Scope-Werten. -::: - - - - -Nach der Konfiguration deines Autorisierungsservers erhalten Benutzer Zugangstokens mit ihren gewährten Berechtigungen. Der MCP-Server nutzt diese Berechtigungen, um zu bestimmen: - -- Ob ein Benutzer neue Todos erstellen darf (`create:todos`) -- Ob ein Benutzer alle Todos (`read:todos`) oder nur seine eigenen sehen darf -- Ob ein Benutzer beliebige Todos (`delete:todos`) oder nur seine eigenen löschen darf - -## MCP-Server einrichten \{#set-up-the-mcp-server} - -Wir verwenden die [offiziellen MCP-SDKs](https://github.com/modelcontextprotocol), um unseren Todo-Manager-MCP-Server zu erstellen. - -### Neues Projekt erstellen \{#create-a-new-project} - - - - -```bash -mkdir mcp-server -cd mcp-server -uv init # Oder verwende `pipenv` oder `poetry`, um eine neue virtuelle Umgebung zu erstellen -``` - - - - -Richte ein neues Node.js-Projekt ein: - -```bash -mkdir mcp-server -cd mcp-server -npm init -y # Oder verwende `pnpm init` -npm pkg set type="module" -npm pkg set main="todo-manager.ts" -npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts" -``` - -:::note -Wir verwenden TypeScript in unseren Beispielen, da Node.js v22.6.0+ TypeScript nativ mit dem Flag `--experimental-strip-types` ausführen kann. Wenn du JavaScript verwendest, ist der Code ähnlich – stelle nur sicher, dass du Node.js v22.6.0 oder neuer nutzt. Siehe Node.js-Dokumentation für Details. -::: - - - - -### MCP-SDK und Abhängigkeiten installieren \{#install-the-mcp-sdk-and-dependencies} - - - - -```bash -pip install "mcp[cli]" starlette uvicorn -``` - -Oder ein anderer Paketmanager deiner Wahl, wie `uv` oder `poetry`. - - - - -```bash -npm install @modelcontextprotocol/sdk express zod -``` - -Oder ein anderer Paketmanager deiner Wahl, wie `pnpm` oder `yarn`. - - - - -### MCP-Server erstellen \{#create-the-mcp-server} - -Erstelle zunächst einen einfachen MCP-Server mit den Tool-Definitionen: - - - - -Erstelle eine Datei namens `todo-manager.py` und füge folgenden Code hinzu: - -```python -from typing import Any -from mcp.server.fastmcp import FastMCP -from starlette.applications import Starlette -from starlette.routing import Mount - -mcp = FastMCP("Todo Manager") - -@mcp.tool() -def create_todo(content: str) -> dict[str, Any]: - """Neues Todo erstellen.""" - return {"error": "Nicht implementiert"} - -@mcp.tool() -def get_todos() -> dict[str, Any]: - """Alle Todos auflisten.""" - return {"error": "Nicht implementiert"} - -@mcp.tool() -def delete_todo(id: str) -> dict[str, Any]: - """Todo anhand der ID löschen.""" - return {"error": "Nicht implementiert"} - -app = Starlette( - routes=[Mount('/', app=mcp.sse_app())] -) -``` - -Starte den Server mit: - -```bash -uvicorn todo_manager:app --host 0.0.0.0 --port 3001 -``` - - - - -:::note -Da die aktuelle MCP Inspector-Implementierung keine Autorisierungsflüsse behandelt, verwenden wir den SSE-Ansatz, um den MCP-Server einzurichten. Wir aktualisieren den Code hier, sobald der MCP Inspector Autorisierungsflüsse unterstützt. -::: - -Du kannst auch `pnpm` oder `yarn` verwenden, wenn du möchtest. - -Erstelle eine Datei namens `todo-manager.ts` und füge folgenden Code hinzu: - -```ts -// todo-manager.ts - -import { z } from 'zod'; -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; -import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'; -import express from 'express'; - -// MCP-Server erstellen -const server = new McpServer({ - name: 'Todo Manager', - version: '0.0.0', -}); - -server.tool('create-todo', 'Neues Todo erstellen', { content: z.string() }, async ({ content }) => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Nicht implementiert' }) }], - }; -}); - -server.tool('get-todos', 'Alle Todos auflisten', async () => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Nicht implementiert' }) }], - }; -}); - -server.tool('delete-todo', 'Todo anhand der ID löschen', { id: z.string() }, async ({ id }) => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Nicht implementiert' }) }], - }; -}); - -// Boilerplate-Code aus der MCP SDK-Dokumentation -const PORT = 3001; -const app = express(); - -const transports = {}; - -app.get('/sse', async (_req, res) => { - const transport = new SSEServerTransport('/messages', res); - transports[transport.sessionId] = transport; - - res.on('close', () => { - delete transports[transport.sessionId]; - }); - - await server.connect(transport); -}); - -app.post('/messages', async (req, res) => { - const sessionId = String(req.query.sessionId); - const transport = transports[sessionId]; - if (transport) { - await transport.handlePostMessage(req, res, req.body); - } else { - res.status(400).send('Kein Transport für sessionId gefunden'); - } -}); - -app.listen(PORT); -``` - -Starte den Server mit: - -```bash -npm start -``` - - - - -## MCP-Server inspizieren \{#inspect-the-mcp-server} - -### MCP Inspector klonen und starten \{#clone-and-run-mcp-inspector} - -Jetzt, da der MCP-Server läuft, können wir den MCP Inspector verwenden, um zu prüfen, ob das `whoami`-Tool verfügbar ist. - -Aufgrund der aktuellen Implementierung haben wir den [MCP Inspector](https://github.com/mcp-auth/inspector) geforkt, um ihn flexibler und skalierbarer für Authentifizierung und Autorisierung zu machen. Wir haben auch einen Pull Request an das Original-Repository eingereicht, um unsere Änderungen einzubringen. - -Um den MCP Inspector zu starten, verwende folgenden Befehl (Node.js wird benötigt): - -```bash -git clone https://github.com/mcp-auth/inspector.git -cd inspector -npm install -npm run dev -``` - -Öffne dann deinen Browser und gehe zu `http://localhost:6274/` (oder eine andere im Terminal angezeigte URL), um den MCP Inspector zu nutzen. - -### MCP Inspector mit dem MCP-Server verbinden \{#connect-mcp-inspector-to-the-mcp-server} - -Prüfe vor dem Fortfahren folgende Konfiguration im MCP Inspector: - -- **Transporttyp**: Setze auf `SSE`. -- **URL**: Setze auf die URL deines MCP-Servers. In unserem Fall sollte das `http://localhost:3001/sse` sein. - -Jetzt kannst du auf die Schaltfläche "Connect" klicken, um zu sehen, ob der MCP Inspector eine Verbindung zum MCP-Server herstellen kann. Wenn alles in Ordnung ist, solltest du im MCP Inspector den Status "Connected" sehen. - -### Checkpoint: Todo-Manager-Tools ausführen \{#checkpoint-run-todo-manager-tools} - -1. Klicke im oberen Menü des MCP Inspectors auf den Tab "Tools". -2. Klicke auf die Schaltfläche "List Tools". -3. Du solltest die Tools `create-todo`, `get-todos` und `delete-todo` auf der Seite sehen. Klicke darauf, um die Tool-Details zu öffnen. -4. Du solltest rechts die Schaltfläche "Run Tool" sehen. Klicke darauf und gib die erforderlichen Parameter ein, um das Tool auszuführen. -5. Du solltest das Tool-Ergebnis mit der JSON-Antwort `{"error": "Nicht implementiert"}` sehen. - -![MCP Inspector erster Start](/docs-assets/images/tutorials/todo-manager/inspector-first-run.png) - -## Mit deinem Autorisierungsserver integrieren \{#integrate-with-your-authorization-server} - -Für diesen Abschnitt gibt es einige Überlegungen: - -
-**Die Issuer-URL deines Autorisierungsservers** - -Dies ist normalerweise die Basis-URL deines Autorisierungsservers, z. B. `https://auth.example.com`. Manche Anbieter haben einen Pfad wie `https://example.logto.app/oidc`, prüfe daher die Dokumentation deines Anbieters. - -
- -
-**Wie du die Metadaten des Autorisierungsservers abrufst** - -- Wenn dein Autorisierungsserver dem [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) oder [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) entspricht, kannst du die eingebauten MCP Auth-Utilities verwenden, um die Metadaten automatisch abzurufen. -- Wenn dein Autorisierungsserver diesen Standards nicht entspricht, musst du die Metadaten-URL oder Endpunkte manuell in der MCP-Server-Konfiguration angeben. Prüfe die Dokumentation deines Anbieters für die spezifischen Endpunkte. - -
- -
-**Wie du den MCP Inspector als Client in deinem Autorisierungsserver registrierst** - -- Wenn dein Autorisierungsserver [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591) unterstützt, kannst du diesen Schritt überspringen, da der MCP Inspector sich automatisch als Client registriert. -- Wenn dein Autorisierungsserver Dynamic Client Registration nicht unterstützt, musst du den MCP Inspector manuell als Client in deinem Autorisierungsserver registrieren. - -
- -
-**Verstehe die Token-Anfrageparameter** - -Beim Anfordern von Zugangstokens von verschiedenen Autorisierungsservern wirst du verschiedene Ansätze zur Angabe der Zielressource und Berechtigungen sehen. Hier sind die Hauptmuster: - -- **Ressourcenindikator-basiert**: - - - Verwendet den Parameter `resource`, um die Ziel-API anzugeben (siehe [RFC 8707: Resource Indicators for OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)) - - Häufig in modernen OAuth 2.0-Implementierungen - - Beispielanfrage: - ```json - { - "resource": "https://todo.mcp-server.app", - "scope": "create:todos read:todos" - } - ``` - - Der Server stellt Tokens aus, die speziell an die angeforderte Ressource gebunden sind - -- **Audience-basiert**: - - - Verwendet den Parameter `audience`, um den beabsichtigten Token-Empfänger anzugeben - - Ähnlich wie Ressourcenindikatoren, aber mit anderer Semantik - - Beispielanfrage: - ```json - { - "audience": "todo-api", - "scope": "create:todos read:todos" - } - ``` - -- **Rein scope-basiert**: - - Verwendet ausschließlich Scopes ohne resource/audience-Parameter - - Traditioneller OAuth 2.0-Ansatz - - Beispielanfrage: - ```json - { - "scope": "todo-api:create todo-api:read openid profile" - } - ``` - - Nutzt oft vorangestellte Scopes, um Berechtigungen zu namespacen - - Häufig in einfacheren OAuth 2.0-Implementierungen - -:::tip Best Practices - -- Prüfe die Dokumentation deines Anbieters auf unterstützte Parameter -- Manche Anbieter unterstützen mehrere Ansätze gleichzeitig -- Ressourcenindikatoren bieten bessere Sicherheit durch Audience-Beschränkung -- Nutze Ressourcenindikatoren, wenn verfügbar, für bessere Zugangskontrolle - ::: - -
- -Auch wenn jeder Anbieter eigene Anforderungen hat, führen dich die folgenden Schritte durch die Integration des MCP Inspectors und MCP Servers mit anbieter-spezifischen Konfigurationen. - -### MCP Inspector als Client registrieren \{#register-mcp-inspector-as-a-client} - - - - -Die Integration des Todo-Managers mit [Logto](https://logto.io) ist unkompliziert, da es sich um einen OpenID Connect-Anbieter handelt, der Ressourcenindikatoren und Scopes unterstützt. So kannst du deine Todo-API mit `https://todo.mcp-server.app` als Ressourcenindikator absichern. - -Da Logto Dynamic Client Registration noch nicht unterstützt, musst du den MCP Inspector manuell als Client in deinem Logto-Tenant registrieren: - -1. Öffne deinen MCP Inspector, klicke auf die Schaltfläche "OAuth Configuration". Kopiere den **Redirect URL (auto-populated)**-Wert, z. B. `http://localhost:6274/oauth/callback`. -2. Melde dich bei der [Logto Console](https://cloud.logto.io) (oder deiner selbst gehosteten Logto Console) an. -3. Navigiere zum Tab "Anwendungen", klicke auf "Anwendung erstellen". Klicke unten auf der Seite auf "App ohne Framework erstellen". -4. Fülle die Anwendungsdetails aus und klicke dann auf "Anwendung erstellen": - - **Wähle einen Anwendungstyp**: "Single-page application" - - **Anwendungsname**: z. B. "MCP Inspector" -5. Im Bereich "Einstellungen / Redirect URIs" füge den kopierten **Redirect URL (auto-populated)**-Wert ein. Klicke dann unten auf "Änderungen speichern". -6. Im oberen Bereich siehst du den Wert "App ID". Kopiere ihn. -7. Gehe zurück zum MCP Inspector und füge den "App ID"-Wert im Bereich "OAuth Configuration" unter "Client ID" ein. -8. Gib den Wert `{"scope": "create:todos read:todos delete:todos", "resource": "https://todo.mcp-server.app"}` im Feld "Auth Params" ein. Dadurch enthält das von Logto zurückgegebene Zugangstoken die erforderlichen Berechtigungen für den Zugriff auf den Todo-Manager. - - - - -:::note -Dies ist eine generische OAuth 2.0 / OpenID Connect-Anbieter-Integrationsanleitung. Beide folgen ähnlichen Schritten, da OIDC auf OAuth 2.0 aufbaut. Prüfe die Dokumentation deines Anbieters für Details. -::: - -Wenn dein Anbieter Dynamic Client Registration unterstützt, kannst du direkt zu Schritt 8 unten gehen, um den MCP Inspector zu konfigurieren; andernfalls musst du den MCP Inspector manuell als Client registrieren: - -1. Öffne deinen MCP Inspector, klicke auf die Schaltfläche "OAuth Configuration". Kopiere den **Redirect URL (auto-populated)**-Wert, z. B. `http://localhost:6274/oauth/callback`. - -2. Melde dich bei der Konsole deines Anbieters an. - -3. Navigiere zum Bereich "Anwendungen" oder "Clients" und erstelle eine neue Anwendung oder einen neuen Client. - -4. Falls dein Anbieter einen Client-Typ verlangt, wähle "Single-page application" oder "Public client". - -5. Nach dem Erstellen der Anwendung musst du die Redirect-URI konfigurieren. Füge den kopierten **Redirect URL (auto-populated)**-Wert ein. - -6. Finde die "Client ID" oder "Application ID" der neu erstellten Anwendung und kopiere sie. - -7. Gehe zurück zum MCP Inspector und füge den "Client ID"-Wert im Bereich "OAuth Configuration" unter "Client ID" ein. - -8. Gib folgenden Wert im Feld "Auth Params" ein, um die erforderlichen Berechtigungen für Todo-Operationen anzufordern: - -```json -{ "scope": "create:todos read:todos delete:todos" } -``` - - - - -### MCP Auth einrichten \{#set-up-mcp-auth} - -In deinem MCP-Server-Projekt musst du das MCP Auth SDK installieren und so konfigurieren, dass es die Metadaten deines Autorisierungsservers verwendet. - - - - -Installiere zuerst das `mcpauth`-Paket: - -```bash -pip install mcpauth -``` - -Oder ein anderer Paketmanager deiner Wahl, wie `uv` oder `poetry`. - - - - -Installiere zuerst das `mcp-auth`-Paket: - -```bash -npm install mcp-auth -``` - - - - -MCP Auth benötigt die Metadaten des Autorisierungsservers zur Initialisierung. Je nach Anbieter: - - - - - -Die Issuer-URL findest du auf der Anwendungsdetailseite in der Logto Console im Bereich "Endpoints & Credentials / Issuer endpoint". Sie sieht etwa so aus: `https://my-project.logto.app/oidc`. - - - - - - - -Für OAuth 2.0-Anbieter musst du: - -1. In der Dokumentation deines Anbieters nach der Autorisierungsserver-URL suchen (oft als Issuer-URL oder Basis-URL bezeichnet) -2. Manche Anbieter stellen dies unter `https://{your-domain}/.well-known/oauth-authorization-server` bereit -3. Im Admin-Bereich deines Anbieters unter OAuth/API-Einstellungen nachsehen - - - - - - - - - - - -Aktualisiere die `todo-manager.py`, um die MCP Auth-Konfiguration einzubinden: - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # Ersetze durch deinen Issuer-Endpunkt -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -Aktualisiere die `todo-manager.ts`, um die MCP Auth-Konfiguration einzubinden: - -```ts -// todo-manager.ts - -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // Ersetze durch deinen Issuer-Endpunkt -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oidc' }), -}); -``` - - - - -### MCP-Server aktualisieren \{#update-mcp-server} - -Wir sind fast fertig! Jetzt aktualisieren wir den MCP-Server, um die MCP Auth-Route und Middleware-Funktion anzuwenden und die berechtigungsbasierte Zugangskontrolle für die Todo-Manager-Tools basierend auf den Benutzerberechtigungen zu implementieren. - - - - -```python -@mcp.tool() -def create_todo(content: str) -> dict[str, Any]: - """Neues Todo erstellen.""" - return ( - mcp_auth.auth_info.scopes - if mcp_auth.auth_info # Wird durch die Bearer-Auth-Middleware befüllt - else {"error": "Nicht authentifiziert"} - ) - -# ... - -bearer_auth = Middleware(mcp_auth.bearer_auth_middleware("jwt")) -app = Starlette( - routes=[ - # Metadaten-Route hinzufügen (`/.well-known/oauth-authorization-server`) - mcp_auth.metadata_route(), - # MCP-Server mit Bearer-Auth-Middleware schützen - Mount('/', app=mcp.sse_app(), middleware=[bearer_auth]), - ], -) -``` - - - - -```js -server.tool( - 'create-todo', - 'Neues Todo erstellen', - { content: z.string() }, - async ({ content, authInfo }) => { - return { - content: [ - { type: 'text', text: JSON.stringify(authInfo?.scopes ?? { error: 'Nicht authentifiziert' }) }, - ], - }; - } -); - -// ... - -app.use(mcpAuth.delegatedRouter()); -app.use(mcpAuth.bearerAuth('jwt')); -``` - - - - -Als Nächstes implementieren wir die spezifischen Tools. - -Zuerst erstellen wir einen einfachen Todo-Service, der grundlegende CRUD-Operationen für die Verwaltung von Todo-Einträgen im Speicher bereitstellt. - - - -```python -# service.py - -""" -Ein einfacher Todo-Service zu Demonstrationszwecken. -Verwendet eine In-Memory-Liste zur Speicherung der Todos. -""" - -from datetime import datetime -from typing import List, Optional, Dict, Any -import random -import string - -class Todo: -"""Repräsentiert einen Todo-Eintrag.""" - - def __init__(self, id: str, content: str, owner_id: str, created_at: str): - self.id = id - self.content = content - self.owner_id = owner_id - self.created_at = created_at - - def to_dict(self) -> Dict[str, Any]: - """Todo in ein Dictionary für die JSON-Serialisierung umwandeln.""" - return { - "id": self.id, - "content": self.content, - "ownerId": self.owner_id, - "createdAt": self.created_at - } - -class TodoService: -"""Ein einfacher Todo-Service zu Demonstrationszwecken.""" - - def __init__(self): - self._todos: List[Todo] = [] - - def get_all_todos(self, owner_id: Optional[str] = None) -> List[Dict[str, Any]]: - """ - Alle Todos abrufen, optional gefiltert nach owner_id. - - Args: - owner_id: Falls angegeben, nur Todos dieses Benutzers zurückgeben - - Returns: - Liste von Todo-Dictionaries - """ - if owner_id: - filtered_todos = [todo for todo in self._todos if todo.owner_id == owner_id] - return [todo.to_dict() for todo in filtered_todos] - return [todo.to_dict() for todo in self._todos] - - def get_todo_by_id(self, todo_id: str) -> Optional[Todo]: - """ - Ein Todo anhand seiner ID abrufen. - - Args: - todo_id: Die ID des abzurufenden Todos - - Returns: - Todo-Objekt, falls gefunden, sonst None - """ - for todo in self._todos: - if todo.id == todo_id: - return todo - return None - - def create_todo(self, content: str, owner_id: str) -> Dict[str, Any]: - """ - Ein neues Todo erstellen. - - Args: - content: Der Inhalt des Todos - owner_id: Die ID des Benutzers, dem dieses Todo gehört - - Returns: - Dictionary-Darstellung des erstellten Todos - """ - todo = Todo( - id=self._generate_id(), - content=content, - owner_id=owner_id, - created_at=datetime.now().isoformat() - ) - self._todos.append(todo) - return todo.to_dict() - - def delete_todo(self, todo_id: str) -> Optional[Dict[str, Any]]: - """ - Ein Todo anhand seiner ID löschen. - - Args: - todo_id: Die ID des zu löschenden Todos - - Returns: - Dictionary-Darstellung des gelöschten Todos, falls gefunden, sonst None - """ - for i, todo in enumerate(self._todos): - if todo.id == todo_id: - deleted_todo = self._todos.pop(i) - return deleted_todo.to_dict() - return None - - def _generate_id(self) -> str: - """Eine zufällige ID für ein Todo generieren.""" - return ''.join(random.choices(string.ascii_lowercase + string.digits, k=8)) - -```` - - - - - -```ts -// todo-service.ts - -type Todo = { - id: string; - content: string; - ownerId: string; - createdAt: string; -}; - -/** - * Ein einfacher Todo-Service zu Demonstrationszwecken. - * Verwendet ein In-Memory-Array zur Speicherung der Todos - */ -export class TodoService { - private readonly todos: Todo[] = []; - - getAllTodos(ownerId?: string): Todo[] { - if (ownerId) { - return this.todos.filter((todo) => todo.ownerId === ownerId); - } - return this.todos; - } - - getTodoById(id: string): Todo | undefined { - return this.todos.find((todo) => todo.id === id); - } - - createTodo({ content, ownerId }: { content: string; ownerId: string }): Todo { - const todo: Todo = { - id: this.genId(), - content, - ownerId, - createdAt: new Date().toISOString(), - }; - - // eslint-disable-next-line @silverhand/fp/no-mutating-methods - this.todos.push(todo); - return todo; - } - - deleteTodo(id: string): Todo | undefined { - const index = this.todos.findIndex((todo) => todo.id === id); - - if (index === -1) { - return undefined; - } - - // eslint-disable-next-line @silverhand/fp/no-mutating-methods - const [deleted] = this.todos.splice(index, 1); - return deleted; - } - - private genId(): string { - return Math.random().toString(36).slice(2, 10); - } -} -```` - - - - -Dann bestimmen wir in der Tool-Schicht, ob Operationen basierend auf den Benutzerberechtigungen erlaubt sind: - - - - -```python -# todo-manager.py - -from typing import Any, Optional -from mcpauth.errors import MCPAuthBearerAuthError - -def assert_user_id(auth_info: Optional[dict]) -> str: - """Benutzer-ID aus den Auth-Informationen extrahieren und validieren.""" - subject = auth_info.get('subject') if auth_info else None - if not subject: - raise ValueError('Ungültige Auth-Informationen') - return subject - -def has_required_scopes(user_scopes: list[str], required_scopes: list[str]) -> bool: - """Prüfen, ob der Benutzer alle erforderlichen Berechtigungen hat.""" - return all(scope in user_scopes for scope in required_scopes) - -# Instanz von TodoService erstellen -todo_service = TodoService() - -@mcp.tool() -def create_todo(content: str) -> dict[str, Any]: - """Neues Todo erstellen. - - Nur Benutzer mit 'create:todos'-Berechtigung dürfen Todos erstellen. - """ - # Authentifizierungsinformationen abrufen - auth_info = mcp_auth.auth_info - - # Benutzer-ID validieren - try: - user_id = assert_user_id(auth_info) - except ValueError as e: - return {"error": str(e)} - - # Prüfen, ob der Benutzer die erforderlichen Berechtigungen hat - if not has_required_scopes(auth_info.scopes if auth_info else [], ['create:todos']): - raise MCPAuthBearerAuthError('missing_required_scopes') - - # Neues Todo erstellen - created_todo = todo_service.create_todo(content=content, owner_id=user_id) - - # Erstelltes Todo zurückgeben - return created_todo.__dict__ - -# ... -``` - -Du findest unseren [Beispielcode](https://github.com/mcp-auth/python/tree/master/samples/server) für alle weiteren Implementierungsdetails. - - - - -```ts -// todo-manager.ts - -// ... weitere Importe -import assert from 'node:assert'; -import { type AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js'; -import { TodoService } from './todo-service.js'; - -const todoService = new TodoService(); - -const assertUserId = (authInfo?: AuthInfo) => { - const { subject } = authInfo ?? {}; - assert(subject, 'Ungültige Auth-Informationen'); - return subject; -}; - -/** - * Prüfen, ob der Benutzer alle erforderlichen Berechtigungen für eine Operation hat - */ -const hasRequiredScopes = (userScopes: string[], requiredScopes: string[]): boolean => { - return requiredScopes.every((scope) => userScopes.includes(scope)); -}; - -server.tool( - 'create-todo', - 'Neues Todo erstellen', - { content: z.string() }, - ({ content }: { content: string }, { authInfo }) => { - const userId = assertUserId(authInfo); - - /** - * Nur Benutzer mit 'create:todos'-Berechtigung dürfen Todos erstellen - */ - if (!hasRequiredScopes(authInfo?.scopes ?? [], ['create:todos'])) { - throw new MCPAuthBearerAuthError('missing_required_scopes'); - } - - const createdTodo = todoService.createTodo({ content, ownerId: userId }); - - return { - content: [{ type: 'text', text: JSON.stringify(createdTodo) }], - }; - } -); - -// ... -``` - -Du findest unseren [Beispielcode](https://github.com/mcp-auth/js/tree/master/packages/sample-servers/src/todo-manager) für alle weiteren Implementierungsdetails. - - - - -## Checkpoint: Die `todo-manager`-Tools ausführen \{#checkpoint-run-the-todo-manager-tools} - -Starte deinen MCP-Server neu und öffne den MCP Inspector im Browser. Wenn du auf die Schaltfläche "Connect" klickst, solltest du zur Anmeldeseite deines Autorisierungsservers weitergeleitet werden. - -Nachdem du dich angemeldet hast und zum MCP Inspector zurückkehrst, wiederhole die Aktionen aus dem vorherigen Checkpoint, um die Todo-Manager-Tools auszuführen. Dieses Mal kannst du die Tools mit deiner authentifizierten Benutzeridentität nutzen. Das Verhalten der Tools hängt von den Rollen und Berechtigungen ab, die deinem Benutzer zugewiesen sind: - -- Wenn du als **User** (nur mit `create:todos`-Berechtigung) angemeldet bist: - - - Du kannst neue Todos mit dem Tool `create-todo` erstellen - - Du kannst nur deine eigenen Todos ansehen und löschen - - Du kannst keine Todos anderer Benutzer sehen oder löschen - -- Wenn du als **Admin** (mit allen Berechtigungen: `create:todos`, `read:todos`, `delete:todos`) angemeldet bist: - - Du kannst neue Todos erstellen - - Du kannst mit dem Tool `get-todos` alle Todos im System ansehen - - Du kannst mit dem Tool `delete-todo` beliebige Todos löschen, unabhängig davon, wer sie erstellt hat - -Du kannst diese verschiedenen Berechtigungsstufen testen, indem du: - -1. Die aktuelle Sitzung abmeldest (klicke auf "Disconnect" im MCP Inspector) -2. Dich mit einem anderen Benutzerkonto anmeldest, das andere Rollen/Berechtigungen hat -3. Die gleichen Tools erneut ausprobierst, um zu sehen, wie sich das Verhalten je nach Benutzerberechtigungen ändert - -Das zeigt, wie rollenbasierte Zugangskontrolle (RBAC) in der Praxis funktioniert, wobei verschiedene Benutzer unterschiedliche Zugriffsebenen auf die Funktionen des Systems haben. - -![MCP Inspector Todo-Manager-Tool-Ergebnis](/docs-assets/images/tutorials/todo-manager/result.png) - - - - -:::info -Sieh dir das [MCP Auth Python SDK Repository](https://github.com/mcp-auth/python/blob/master/samples/server/todo-manager/server.py) für den vollständigen Code des MCP-Servers (OIDC-Version) an. -::: - - - - -:::info -Sieh dir das [MCP Auth Node.js SDK Repository](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) für den vollständigen Code des MCP-Servers (OIDC-Version) an. -::: - - - - -## Abschließende Hinweise \{#closing-notes} - -🎊 Glückwunsch! Du hast das Tutorial erfolgreich abgeschlossen. Lass uns zusammenfassen, was wir gemacht haben: - -- Einen einfachen MCP-Server mit Todo-Management-Tools (`create-todo`, `get-todos`, `delete-todo`) eingerichtet -- Rollenbasierte Zugangskontrolle (RBAC) mit unterschiedlichen Berechtigungsstufen für Benutzer und Admins implementiert -- Den MCP-Server mit einem Autorisierungsserver über MCP Auth integriert -- Den MCP Inspector so konfiguriert, dass Benutzer authentifiziert werden und Zugangstokens mit Berechtigungen zum Aufrufen von Tools verwendet werden - -Sieh dir auch andere Tutorials und die Dokumentation an, um das Beste aus MCP Auth herauszuholen. diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_manual-metadata-fetching.mdx b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_manual-metadata-fetching.mdx deleted file mode 100644 index 214d152..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_manual-metadata-fetching.mdx +++ /dev/null @@ -1,3 +0,0 @@ -:::note -Wenn dein Anbieter {props.oidc ? 'OpenID Connect Discovery' : 'OAuth 2.0 Authorization Server Metadata'} nicht unterstützt, kannst du die Metadata-URL oder Endpunkte manuell angeben. Sieh dir [Weitere Möglichkeiten zur Initialisierung von MCP Auth](../../configure-server/mcp-auth.mdx#other-ways) für mehr Details an. -::: \ No newline at end of file diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oauth-or-oidc.mdx b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oauth-or-oidc.mdx deleted file mode 100644 index 2c6bea3..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oauth-or-oidc.mdx +++ /dev/null @@ -1,41 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -Aktualisiere die `todo-manager.py`, um die MCP Auth-Konfiguration einzubinden: - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # Ersetze dies durch deinen Aussteller-Endpunkt -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OAUTH) # oder AuthServerType.OIDC -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -Aktualisiere die `todo-manager.ts`, um die MCP Auth-Konfiguration einzubinden: - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // Ersetze dies durch deinen Aussteller-Endpunkt -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oauth' }), // oder { type: 'oidc' } -}); -``` - - - - - - \ No newline at end of file diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oidc.mdx b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oidc.mdx deleted file mode 100644 index 0724a55..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oidc.mdx +++ /dev/null @@ -1,41 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -Aktualisiere die `todo-manager.py`, um die MCP Auth-Konfiguration einzubinden: - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # Ersetze durch deinen Issuer-Endpunkt -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -Aktualisiere die `todo-manager.ts`, um die MCP Auth-Konfiguration einzubinden: - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // Ersetze durch deinen Issuer-Endpunkt -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oidc' }), -}); -``` - - - - -{props.showAlternative && } -{props.showAlternative && } \ No newline at end of file diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_transpile-metadata.mdx b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_transpile-metadata.mdx deleted file mode 100644 index d988b13..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_transpile-metadata.mdx +++ /dev/null @@ -1,31 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -In einigen Fällen kann die Antwort des Providers fehlerhaft oder nicht dem erwarteten Metadatenformat entsprechend sein. Wenn du sicher bist, dass der Provider konform ist, kannst du die Metadaten über die Konfigurationsoption transpiliieren: - - - - -```python -mcp_auth = MCPAuth( - server=fetch_server_config( - # ...andere Optionen - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { - // ...andere Optionen - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/README.mdx b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/README.mdx deleted file mode 100644 index 1450110..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/README.mdx +++ /dev/null @@ -1,611 +0,0 @@ ---- -sidebar_position: 1 -sidebar_label: 'Tutorial: Wer bin ich?' ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import SetupOauth from './_setup-oauth.mdx'; -import SetupOidc from './_setup-oidc.mdx'; - -# Tutorial: Wer bin ich? (Tutorial: Who am I?) - -Dieses Tutorial führt dich durch den Prozess der Einrichtung von MCP Auth, um Benutzer zu authentifizieren und deren Identitätsinformationen vom Autorisierungsserver abzurufen. - -Nach Abschluss dieses Tutorials hast du: - -- ✅ Ein grundlegendes Verständnis davon, wie du MCP Auth zur Authentifizierung von Benutzern verwendest. -- ✅ Einen MCP-Server, der ein Tool zum Abrufen von Benutzeridentitätsinformationen bereitstellt. - -## Überblick \{#overview} - -Das Tutorial umfasst die folgenden Komponenten: - -- **MCP-Server**: Ein einfacher MCP-Server, der die offiziellen MCP SDKs verwendet, um Anfragen zu verarbeiten. -- **MCP Inspector**: Ein visuelles Testwerkzeug für MCP-Server. Es fungiert auch als OAuth / OIDC-Client, um den Autorisierungsfluss zu starten und Zugangstokens abzurufen. -- **Autorisierungsserver**: Ein OAuth 2.1- oder OpenID Connect-Anbieter, der Benutzeridentitäten verwaltet und Zugangstokens ausstellt. - -Hier ist ein Überblicksdiagramm der Interaktion zwischen diesen Komponenten: - -```mermaid -sequenceDiagram - participant Client as MCP Inspector - participant Server as MCP Server - participant Auth as Autorisierungsserver - - Client->>Server: Tool `whoami` anfordern - Server->>Client: 401 Nicht autorisiert zurückgeben - Client->>Auth: Autorisierungsfluss starten - Auth->>Auth: Autorisierungsfluss abschließen - Auth->>Client: Mit Autorisierungscode zurückleiten - Client->>Auth: Code gegen Zugangstoken austauschen - Auth->>Client: Zugangstoken zurückgeben - Client->>Server: `whoami` mit Zugangstoken anfordern - Server->>Auth: Benutzeridentität mit Zugangstoken abrufen - Auth->>Server: Benutzeridentität zurückgeben - Server->>Client: Benutzeridentität zurückgeben -``` - -## Deinen Autorisierungsserver verstehen \{#understand-your-authorization-server} - -### Benutzeridentitätsinformationen abrufen \{#retrieving-user-identity-information} - -Um dieses Tutorial abzuschließen, sollte dein Autorisierungsserver eine API zum Abrufen von Benutzeridentitätsinformationen bereitstellen: - - - - -[Logto](https://logto.io) ist ein OpenID Connect-Anbieter, der den Standard-[userinfo-Endpunkt](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) unterstützt, um Benutzeridentitätsinformationen abzurufen. - -Um ein Zugangstoken zu erhalten, das für den Zugriff auf den userinfo-Endpunkt verwendet werden kann, sind mindestens zwei Berechtigungen (`scopes`) erforderlich: `openid` und `profile`. Du kannst weiterlesen, da wir die Berechtigungskonfiguration später behandeln. - - - - -[Keycloak](https://www.keycloak.org) ist eine Open-Source-Lösung für Identitäts- und Zugriffsmanagement, die mehrere Protokolle unterstützt, darunter OpenID Connect (OIDC). Als OIDC-Anbieter implementiert es den Standard-[userinfo-Endpunkt](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) zum Abrufen von Benutzeridentitätsinformationen. - -Um ein Zugangstoken zu erhalten, das für den Zugriff auf den userinfo-Endpunkt verwendet werden kann, sind mindestens zwei Berechtigungen (`scopes`) erforderlich: `openid` und `profile`. Du kannst weiterlesen, da wir die Berechtigungskonfiguration später behandeln. - - - - -Die meisten OpenID Connect-Anbieter unterstützen den [userinfo-Endpunkt](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) zum Abrufen von Benutzeridentitätsinformationen. - -Überprüfe die Dokumentation deines Anbieters, um zu sehen, ob dieser Endpunkt unterstützt wird. Wenn dein Anbieter [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) unterstützt, kannst du auch prüfen, ob der `userinfo_endpoint` im Discovery-Dokument (Antwort vom `.well-known/openid-configuration`-Endpunkt) enthalten ist. - -Um ein Zugangstoken zu erhalten, das für den Zugriff auf den userinfo-Endpunkt verwendet werden kann, sind mindestens zwei Berechtigungen (`scopes`) erforderlich: `openid` und `profile`. Überprüfe die Dokumentation deines Anbieters, um die Zuordnung der Berechtigungen zu Benutzeridentitätsansprüchen zu sehen. - - - - -Während OAuth 2.0 keine standardisierte Methode zum Abrufen von Benutzeridentitätsinformationen definiert, implementieren viele Anbieter eigene Endpunkte dafür. Überprüfe die Dokumentation deines Anbieters, um zu erfahren, wie du mit einem Zugangstoken Benutzeridentitätsinformationen abrufen kannst und welche Parameter erforderlich sind, um ein solches Zugangstoken beim Starten des Autorisierungsflusses zu erhalten. - - - - -### Dynamische Client-Registrierung \{#dynamic-client-registration} - -Die dynamische Client-Registrierung ist für dieses Tutorial nicht erforderlich, kann aber nützlich sein, wenn du den MCP-Client-Registrierungsprozess mit deinem Autorisierungsserver automatisieren möchtest. Siehe [Ist Dynamic Client Registration erforderlich?](/provider-list#is-dcr-required) für weitere Details. - -## MCP-Server einrichten \{#set-up-the-mcp-server} - -Wir verwenden die [offiziellen MCP SDKs](https://github.com/modelcontextprotocol), um einen MCP-Server mit einem `whoami`-Tool zu erstellen, das Benutzeridentitätsinformationen vom Autorisierungsserver abruft. - -### Ein neues Projekt erstellen \{#create-a-new-project} - - - - -```bash -mkdir mcp-server -cd mcp-server -uv init # Oder verwende `pipenv` oder `poetry`, um eine neue virtuelle Umgebung zu erstellen -``` - - - - -Richte ein neues Node.js-Projekt ein: - -```bash -mkdir mcp-server -cd mcp-server -npm init -y # Oder verwende `pnpm init` -npm pkg set type="module" -npm pkg set main="whoami.js" -npm pkg set scripts.start="node whoami.js" -``` - - - - -### MCP SDK und Abhängigkeiten installieren \{#install-the-mcp-sdk-and-dependencies} - - - - -```bash -pip install "mcp[cli]" starlette uvicorn -``` - -Oder ein anderes Paketverwaltungstool deiner Wahl, wie `uv` oder `poetry`. - - - - -```bash -npm install @modelcontextprotocol/sdk express -``` - -Oder ein anderes Paketverwaltungstool deiner Wahl, wie `pnpm` oder `yarn`. - - - - -### MCP-Server erstellen \{#create-the-mcp-server} - -Erstellen wir zunächst einen MCP-Server, der ein `whoami`-Tool implementiert. - - - - -Erstelle eine Datei namens `whoami.py` und füge folgenden Code hinzu: - -```python -from mcp.server.fastmcp import FastMCP -from starlette.applications import Starlette -from starlette.routing import Mount -from typing import Any - -mcp = FastMCP("WhoAmI") - -@mcp.tool() -def whoami() -> dict[str, Any]: - """Ein Tool, das die Informationen des aktuellen Benutzers zurückgibt.""" - return {"error": "Nicht authentifiziert"} - -app = Starlette( - routes=[Mount('/', app=mcp.sse_app())] -) -``` - -Starte den Server mit: - -```bash -uvicorn whoami:app --host 0.0.0.0 --port 3001 -``` - - - - -:::note -Da die aktuelle MCP Inspector-Implementierung keine Autorisierungsflüsse verarbeitet, verwenden wir den SSE-Ansatz, um den MCP-Server einzurichten. Wir aktualisieren den Code hier, sobald der MCP Inspector Autorisierungsflüsse unterstützt. -::: - -Du kannst auch `pnpm` oder `yarn` verwenden, wenn du möchtest. - -Erstelle eine Datei namens `whoami.js` und füge folgenden Code hinzu: - -```js -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; -import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'; -import express from 'express'; - -// Erstelle einen MCP-Server -const server = new McpServer({ - name: 'WhoAmI', - version: '0.0.0', -}); - -// Füge dem Server ein Tool hinzu, das die Informationen des aktuellen Benutzers zurückgibt -server.tool('whoami', async () => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Nicht authentifiziert' }) }], - }; -}); - -// Nachfolgend der Boilerplate-Code aus der MCP SDK-Dokumentation -const PORT = 3001; -const app = express(); - -const transports = {}; - -app.get('/sse', async (_req, res) => { - const transport = new SSEServerTransport('/messages', res); - transports[transport.sessionId] = transport; - - res.on('close', () => { - delete transports[transport.sessionId]; - }); - - await server.connect(transport); -}); - -app.post('/messages', async (req, res) => { - const sessionId = String(req.query.sessionId); - const transport = transports[sessionId]; - if (transport) { - await transport.handlePostMessage(req, res, req.body); - } else { - res.status(400).send('Kein Transport für sessionId gefunden'); - } -}); - -app.listen(PORT); -``` - -Starte den Server mit: - -```bash -npm start -``` - - - - -## MCP-Server inspizieren \{#inspect-the-mcp-server} - -### MCP Inspector klonen und ausführen \{#clone-and-run-mcp-inspector} - -Jetzt, da der MCP-Server läuft, können wir den MCP Inspector verwenden, um zu sehen, ob das `whoami`-Tool verfügbar ist. - -Aufgrund der aktuellen Implementierung haben wir den [MCP Inspector](https://github.com/mcp-auth/inspector) geforkt, um ihn flexibler und skalierbarer für Authentifizierung und Autorisierung zu machen. Wir haben auch einen Pull Request an das Original-Repository eingereicht, um unsere Änderungen einzubringen. - -Um den MCP Inspector auszuführen, kannst du folgenden Befehl verwenden (Node.js wird benötigt): - -```bash -git clone https://github.com/mcp-auth/inspector.git -cd inspector -npm install -npm run dev -``` - -Öffne dann deinen Browser und navigiere zu `http://localhost:6274/` (oder einer anderen im Terminal angezeigten URL), um auf den MCP Inspector zuzugreifen. - -### MCP Inspector mit dem MCP-Server verbinden \{#connect-mcp-inspector-to-the-mcp-server} - -Bevor wir fortfahren, überprüfe folgende Konfiguration im MCP Inspector: - -- **Transporttyp**: Auf `SSE` setzen. -- **URL**: Auf die URL deines MCP-Servers setzen. In unserem Fall sollte das `http://localhost:3001/sse` sein. - -Jetzt kannst du auf die Schaltfläche "Connect" klicken, um zu sehen, ob der MCP Inspector eine Verbindung zum MCP-Server herstellen kann. Wenn alles in Ordnung ist, solltest du den Status "Connected" im MCP Inspector sehen. - -### Checkpoint: Das `whoami`-Tool ausführen \{#checkpoint-run-the-whoami-tool} - -1. Klicke im oberen Menü des MCP Inspectors auf den Tab "Tools". -2. Klicke auf die Schaltfläche "List Tools". -3. Du solltest das `whoami`-Tool auf der Seite sehen. Klicke darauf, um die Tool-Details zu öffnen. -4. Du solltest auf der rechten Seite die Schaltfläche "Run Tool" sehen. Klicke darauf, um das Tool auszuführen. -5. Du solltest das Tool-Ergebnis mit der JSON-Antwort `{"error": "Nicht authentifiziert"}` sehen. - -![MCP Inspector erster Lauf](/docs-assets/images/tutorials/whoami/inspector-first-run.png) - -## Integration mit deinem Autorisierungsserver \{#integrate-with-your-authorization-server} - -Um diesen Abschnitt abzuschließen, sind mehrere Überlegungen zu beachten: - -
-**Die Issuer-URL deines Autorisierungsservers** - -Dies ist normalerweise die Basis-URL deines Autorisierungsservers, z. B. `https://auth.example.com`. Einige Anbieter haben einen Pfad wie `https://example.logto.app/oidc`, daher solltest du die Dokumentation deines Anbieters prüfen. - -
- -
-**Wie du die Metadaten des Autorisierungsservers abrufst** - -- Wenn dein Autorisierungsserver dem [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) oder [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) entspricht, kannst du die integrierten MCP Auth-Utilities verwenden, um die Metadaten automatisch abzurufen. -- Wenn dein Autorisierungsserver diese Standards nicht unterstützt, musst du die Metadaten-URL oder Endpunkte manuell in der MCP-Server-Konfiguration angeben. Prüfe die Dokumentation deines Anbieters für die spezifischen Endpunkte. - -
- -
-**Wie du den MCP Inspector als Client in deinem Autorisierungsserver registrierst** - -- Wenn dein Autorisierungsserver [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591) unterstützt, kannst du diesen Schritt überspringen, da sich der MCP Inspector automatisch als Client registriert. -- Wenn dein Autorisierungsserver keine Dynamic Client Registration unterstützt, musst du den MCP Inspector manuell als Client in deinem Autorisierungsserver registrieren. - -
- -
-**Wie du Benutzeridentitätsinformationen abrufst und wie du die Parameter der Autorisierungsanfrage konfigurierst** - -- Für OpenID Connect-Anbieter: In der Regel musst du beim Starten des Autorisierungsflusses mindestens die Berechtigungen `openid` und `profile` anfordern. Dadurch wird sichergestellt, dass das vom Autorisierungsserver zurückgegebene Zugangstoken die erforderlichen Berechtigungen für den Zugriff auf den [userinfo-Endpunkt](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) enthält, um Benutzeridentitätsinformationen abzurufen. - - Hinweis: Einige Anbieter unterstützen den userinfo-Endpunkt möglicherweise nicht. - -- Für OAuth 2.0 / OAuth 2.1-Anbieter: Prüfe die Dokumentation deines Anbieters, um zu erfahren, wie du mit einem Zugangstoken Benutzeridentitätsinformationen abrufen kannst und welche Parameter erforderlich sind, um ein solches Zugangstoken beim Starten des Autorisierungsflusses zu erhalten. - -
- -Während jeder Anbieter eigene spezifische Anforderungen haben kann, führen dich die folgenden Schritte durch den Prozess der Integration des MCP Inspectors und MCP Servers mit anbieter-spezifischen Konfigurationen. - -### MCP Inspector als Client registrieren \{#register-mcp-inspector-as-a-client} - - - - -Die Integration mit [Logto](https://logto.io) ist unkompliziert, da es sich um einen OpenID Connect-Anbieter handelt, der den Standard-[userinfo-Endpunkt](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) unterstützt, um Benutzeridentitätsinformationen abzurufen. - -Da Logto derzeit keine Dynamic Client Registration unterstützt, musst du den MCP Inspector manuell als Client in deinem Logto-Tenant registrieren: - -1. Öffne deinen MCP Inspector, klicke auf die Schaltfläche "OAuth Configuration". Kopiere den **Redirect URL (auto-populated)**-Wert, der etwa so aussehen sollte: `http://localhost:6274/oauth/callback`. -2. Melde dich bei der [Logto Console](https://cloud.logto.io) (oder deiner selbst gehosteten Logto Console) an. -3. Navigiere zum Tab "Applications", klicke auf "Create application". Klicke unten auf der Seite auf "Create app without framework". -4. Fülle die Anwendungsdetails aus und klicke dann auf "Create application": - - **Wähle einen Anwendungstyp**: Wähle "Single-page application". - - **Anwendungsname**: Gib einen Namen für deine Anwendung ein, z. B. "MCP Inspector". -5. Im Bereich "Settings / Redirect URIs" füge den zuvor kopierten **Redirect URL (auto-populated)**-Wert ein. Klicke dann unten auf "Save changes". -6. Im oberen Bereich siehst du den Wert "App ID". Kopiere ihn. -7. Gehe zurück zum MCP Inspector und füge den "App ID"-Wert im Bereich "OAuth Configuration" unter "Client ID" ein. -8. Gib den Wert `{"scope": "openid profile email"}` im Feld "Auth Params" ein. Dadurch wird sichergestellt, dass das von Logto zurückgegebene Zugangstoken die erforderlichen Berechtigungen für den Zugriff auf den userinfo-Endpunkt enthält. - - - - -[Keycloak](https://www.keycloak.org) ist eine Open-Source-Lösung für Identitäts- und Zugriffsmanagement, die das OpenID Connect-Protokoll unterstützt. - -Obwohl Keycloak die dynamische Client-Registrierung unterstützt, unterstützt sein Client-Registrierungsendpunkt kein CORS, was die direkte Registrierung der meisten MCP-Clients verhindert. Daher müssen wir unseren Client manuell registrieren. - -:::note -Obwohl Keycloak auf [verschiedene Arten](https://www.keycloak.org/guides#getting-started) (Bare Metal, Kubernetes usw.) installiert werden kann, verwenden wir für dieses Tutorial Docker für eine schnelle und einfache Einrichtung. -::: - -Richte eine Keycloak-Instanz ein und konfiguriere sie wie folgt: - -1. Starte eine Keycloak-Instanz mit Docker gemäß der [offiziellen Dokumentation](https://www.keycloak.org/getting-started/getting-started-docker): - -```bash -docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.2.4 start-dev -``` - -2. Greife auf die Keycloak Admin Console (http://localhost:8080/admin) zu und melde dich mit diesen Zugangsdaten an: - - - Benutzername: `admin` - - Passwort: `admin` - -3. Erstelle ein neues Realm: - - - Klicke oben links auf "Create Realm" - - Gib `mcp-realm` im Feld "Realm name" ein - - Klicke auf "Create" - -4. Erstelle einen Testbenutzer: - - - Klicke im linken Menü auf "Users" - - Klicke auf "Create new user" - - Fülle die Benutzerdetails aus: - - Benutzername: `testuser` - - Vorname und Nachname können beliebige Werte sein - - Klicke auf "Create" - - Setze im Tab "Credentials" ein Passwort und deaktiviere "Temporary" - -5. Registriere den MCP Inspector als Client: - - - Öffne deinen MCP Inspector, klicke auf die Schaltfläche "OAuth Configuration". Kopiere den **Redirect URL (auto-populated)**-Wert, der etwa so aussehen sollte: `http://localhost:6274/oauth/callback`. - - Klicke in der Keycloak Admin Console im linken Menü auf "Clients" - - Klicke auf "Create client" - - Fülle die Client-Details aus: - - Client-Typ: Wähle "OpenID Connect" - - Client ID: Gib `mcp-inspector` ein - - Klicke auf "Next" - - Auf der Seite "Capability config": - - Stelle sicher, dass "Standard flow" aktiviert ist - - Klicke auf "Next" - - Auf der Seite "Login settings": - - Füge die zuvor kopierte MCP Inspector Callback-URL in "Valid redirect URIs" ein - - Gib `http://localhost:6274` in "Web origins" ein - - Klicke auf "Save" - - Kopiere die "Client ID" (das ist `mcp-inspector`) - -6. Zurück im MCP Inspector: - - Füge die kopierte Client ID in das Feld "Client ID" im Bereich "OAuth Configuration" ein - - Gib folgenden Wert im Feld "Auth Params" ein, um die erforderlichen Berechtigungen anzufordern: - -```json -{ "scope": "openid profile email" } -``` - - - - -:::note -Dies ist eine allgemeine Anleitung zur Integration eines OpenID Connect-Anbieters. Prüfe die Dokumentation deines Anbieters für spezifische Details. -::: - -Wenn dein OpenID Connect-Anbieter die dynamische Client-Registrierung unterstützt, kannst du direkt zu Schritt 8 unten gehen, um den MCP Inspector zu konfigurieren; andernfalls musst du den MCP Inspector manuell als Client in deinem OpenID Connect-Anbieter registrieren: - -1. Öffne deinen MCP Inspector, klicke auf die Schaltfläche "OAuth Configuration". Kopiere den **Redirect URL (auto-populated)**-Wert, der etwa so aussehen sollte: `http://localhost:6274/oauth/callback`. -2. Melde dich bei der Konsole deines OpenID Connect-Anbieters an. -3. Navigiere zum Bereich "Applications" oder "Clients" und erstelle eine neue Anwendung oder einen neuen Client. -4. Wenn dein Anbieter einen Client-Typ verlangt, wähle "Single-page application" oder "Public client". -5. Nach dem Erstellen der Anwendung musst du die Redirect URI konfigurieren. Füge den zuvor kopierten **Redirect URL (auto-populated)**-Wert ein. -6. Finde die "Client ID" oder "Application ID" der neu erstellten Anwendung und kopiere sie. -7. Gehe zurück zum MCP Inspector und füge die "Client ID" im Bereich "OAuth Configuration" unter "Client ID" ein. -8. Für Standard-OpenID Connect-Anbieter kannst du folgenden Wert im Feld "Auth Params" eingeben, um die erforderlichen Berechtigungen für den Zugriff auf den userinfo-Endpunkt anzufordern: - -```json -{ "scope": "openid profile email" } -``` - - - - -:::note -Dies ist eine allgemeine Anleitung zur Integration eines OAuth 2.0 / OAuth 2.1-Anbieters. Prüfe die Dokumentation deines Anbieters für spezifische Details. -::: - -Wenn dein OAuth 2.0 / OAuth 2.1-Anbieter die dynamische Client-Registrierung unterstützt, kannst du direkt zu Schritt 8 unten gehen, um den MCP Inspector zu konfigurieren; andernfalls musst du den MCP Inspector manuell als Client in deinem OAuth 2.0 / OAuth 2.1-Anbieter registrieren: - -1. Öffne deinen MCP Inspector, klicke auf die Schaltfläche "OAuth Configuration". Kopiere den **Redirect URL (auto-populated)**-Wert, der etwa so aussehen sollte: `http://localhost:6274/oauth/callback`. -2. Melde dich bei der Konsole deines OAuth 2.0 / OAuth 2.1-Anbieters an. -3. Navigiere zum Bereich "Applications" oder "Clients" und erstelle eine neue Anwendung oder einen neuen Client. -4. Wenn dein Anbieter einen Client-Typ verlangt, wähle "Single-page application" oder "Public client". -5. Nach dem Erstellen der Anwendung musst du die Redirect URI konfigurieren. Füge den zuvor kopierten **Redirect URL (auto-populated)**-Wert ein. -6. Finde die "Client ID" oder "Application ID" der neu erstellten Anwendung und kopiere sie. -7. Gehe zurück zum MCP Inspector und füge die "Client ID" im Bereich "OAuth Configuration" unter "Client ID" ein. -8. Lies die Dokumentation deines Anbieters, um zu erfahren, wie du Zugangstokens für Benutzeridentitätsinformationen abrufst. Möglicherweise musst du die erforderlichen Berechtigungen oder Parameter angeben, um das Zugangstoken zu erhalten. Wenn dein Anbieter z. B. die Berechtigung `profile` für den Zugriff auf Benutzeridentitätsinformationen verlangt, kannst du folgenden Wert im Feld "Auth Params" eingeben: - -```json -{ "scope": "profile" } -``` - - - - -### MCP Auth einrichten \{#set-up-mcp-auth} - -In deinem MCP-Server-Projekt musst du das MCP Auth SDK installieren und es so konfigurieren, dass es die Metadaten deines Autorisierungsservers verwendet. - - - - -Installiere zunächst das `mcpauth`-Paket: - -```bash -pip install mcpauth -``` - -Oder ein anderes Paketverwaltungstool deiner Wahl, wie `uv` oder `poetry`. - - - - -Installiere zunächst das `mcp-auth`-Paket: - -```bash -npm install mcp-auth -``` - - - - -MCP Auth benötigt die Metadaten des Autorisierungsservers, um initialisiert werden zu können. Je nach Anbieter: - - - - - -Die Issuer-URL findest du auf der Anwendungsdetailseite in der Logto Console im Abschnitt "Endpoints & Credentials / Issuer endpoint". Sie sollte etwa so aussehen: `https://my-project.logto.app/oidc`. - - - - - - - -Die Issuer-URL findest du in deiner Keycloak Admin Console. Navigiere in deinem 'mcp-realm' zum Abschnitt "Realm settings / Endpoints" und klicke auf den Link "OpenID Endpoint Configuration". Das Feld `issuer` im JSON-Dokument enthält deine Issuer-URL, die etwa so aussehen sollte: `http://localhost:8080/realms/mcp-realm`. - - - - - - - -Der folgende Code geht ebenfalls davon aus, dass der Autorisierungsserver den [userinfo-Endpunkt](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) zum Abrufen von Benutzeridentitätsinformationen unterstützt. Wenn dein Anbieter diesen Endpunkt nicht unterstützt, musst du die Dokumentation deines Anbieters für den spezifischen Endpunkt prüfen und die userinfo-Endpunkt-Variable durch die korrekte URL ersetzen. - - - - - - -Wie bereits erwähnt, definiert OAuth 2.0 keine standardisierte Methode zum Abrufen von Benutzeridentitätsinformationen. Der folgende Code geht davon aus, dass dein Anbieter einen spezifischen Endpunkt zum Abrufen von Benutzeridentitätsinformationen mit einem Zugangstoken bereitstellt. Du musst die Dokumentation deines Anbieters für den spezifischen Endpunkt prüfen und die userinfo-Endpunkt-Variable durch die korrekte URL ersetzen. - - - - - - -### MCP-Server aktualisieren \{#update-mcp-server} - -Wir sind fast fertig! Jetzt ist es an der Zeit, den MCP-Server zu aktualisieren, um die MCP Auth-Route und Middleware-Funktion anzuwenden und das `whoami`-Tool so zu gestalten, dass es die tatsächlichen Benutzeridentitätsinformationen zurückgibt. - - - - -```python -@mcp.tool() -def whoami() -> dict[str, Any]: - """Ein Tool, das die Informationen des aktuellen Benutzers zurückgibt.""" - return ( - mcp_auth.auth_info.claims - if mcp_auth.auth_info # Dies wird durch die Bearer-Auth-Middleware befüllt - else {"error": "Nicht authentifiziert"} - ) - -# ... - -bearer_auth = Middleware(mcp_auth.bearer_auth_middleware(verify_access_token)) -app = Starlette( - routes=[ - # Füge die Metadaten-Route hinzu (`/.well-known/oauth-authorization-server`) - mcp_auth.metadata_route(), - # Schütze den MCP-Server mit der Bearer-Auth-Middleware - Mount('/', app=mcp.sse_app(), middleware=[bearer_auth]), - ], -) -``` - - - - -```js -server.tool('whoami', ({ authInfo }) => { - return { - content: [ - { type: 'text', text: JSON.stringify(authInfo?.claims ?? { error: 'Nicht authentifiziert' }) }, - ], - }; -}); - -// ... - -app.use(mcpAuth.delegatedRouter()); -app.use(mcpAuth.bearerAuth(verifyToken)); -``` - - - - -## Checkpoint: Das `whoami`-Tool mit Authentifizierung ausführen \{#checkpoint-run-the-whoami-tool-with-authentication} - -Starte deinen MCP-Server neu und öffne den MCP Inspector in deinem Browser. Wenn du auf die Schaltfläche "Connect" klickst, solltest du zur Anmeldeseite deines Autorisierungsservers weitergeleitet werden. - -Sobald du dich angemeldet hast und zum MCP Inspector zurückkehrst, wiederhole die Schritte aus dem vorherigen Checkpoint, um das `whoami`-Tool auszuführen. Dieses Mal solltest du die vom Autorisierungsserver zurückgegebenen Benutzeridentitätsinformationen sehen. - -![MCP Inspector whoami Tool Ergebnis](/docs-assets/images/tutorials/whoami/result.png) - - - - -:::info -Sieh dir das [MCP Auth Python SDK Repository](https://github.com/mcp-auth/python/blob/master/samples/server/whoami.py) für den vollständigen Code des MCP-Servers (OIDC-Version) an. -::: - - - - -:::info -Sieh dir das [MCP Auth Node.js SDK Repository](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) für den vollständigen Code des MCP-Servers (OIDC-Version) an. Dieses Verzeichnis enthält sowohl TypeScript- als auch JavaScript-Versionen des Codes. -::: - - - - -## Abschließende Hinweise \{#closing-notes} - -🎊 Glückwunsch! Du hast das Tutorial erfolgreich abgeschlossen. Lass uns zusammenfassen, was wir gemacht haben: - -- Einen grundlegenden MCP-Server mit dem `whoami`-Tool eingerichtet -- Den MCP-Server mit einem Autorisierungsserver unter Verwendung von MCP Auth integriert -- Den MCP Inspector so konfiguriert, dass Benutzer authentifiziert und deren Identitätsinformationen abgerufen werden - -Du möchtest vielleicht auch einige fortgeschrittene Themen erkunden, darunter: - -- Die Verwendung von [JWT (JSON Web Token)](https://auth.wiki/jwt) für Authentifizierung und Autorisierung -- Die Nutzung von [Ressourcenindikatoren (RFC 8707)](https://auth-wiki.logto.io/resource-indicator), um die zuzugreifenden Ressourcen anzugeben -- Die Implementierung eigener Zugangskontrollmechanismen, wie [rollenbasierte Zugangskontrolle (RBAC)](https://auth.wiki/rbac) oder [attributbasierte Zugangskontrolle (ABAC)](https://auth.wiki/abac) - -Sieh dir unbedingt weitere Tutorials und die Dokumentation an, um das Beste aus MCP Auth herauszuholen. diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_manual-metadata-fetching.mdx b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_manual-metadata-fetching.mdx deleted file mode 100644 index 214d152..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_manual-metadata-fetching.mdx +++ /dev/null @@ -1,3 +0,0 @@ -:::note -Wenn dein Anbieter {props.oidc ? 'OpenID Connect Discovery' : 'OAuth 2.0 Authorization Server Metadata'} nicht unterstützt, kannst du die Metadata-URL oder Endpunkte manuell angeben. Sieh dir [Weitere Möglichkeiten zur Initialisierung von MCP Auth](../../configure-server/mcp-auth.mdx#other-ways) für mehr Details an. -::: \ No newline at end of file diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oauth.mdx b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oauth.mdx deleted file mode 100644 index 6e48e7a..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oauth.mdx +++ /dev/null @@ -1,140 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -Aktualisiere die `whoami.py`, um die MCP Auth-Konfiguration einzubinden: - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # Ersetze dies durch deinen Issuer-Endpunkt -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OAUTH) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -Aktualisiere die `whoami.js`, um die MCP Auth-Konfiguration einzubinden: - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // Ersetze dies durch deinen Issuer-Endpunkt -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oauth' }), -}); -``` - - - - - - - -Nun müssen wir einen benutzerdefinierten Zugangstoken (Access token) Verifizierer erstellen, der die Benutzeridentitätsinformationen vom Autorisierungsserver abruft, indem er das vom MCP-Inspector bereitgestellte Zugangstoken verwendet. - - - - -```python -import pydantic -import requests -from mcpauth.exceptions import ( - MCPAuthTokenVerificationException, - MCPAuthTokenVerificationExceptionCode, -) -from mcpauth.types import AuthInfo - -def verify_access_token(token: str) -> AuthInfo: - """ - Überprüft das bereitgestellte Bearer-Token, indem Benutzerinformationen vom Autorisierungsserver abgerufen werden. - Wenn das Token gültig ist, wird ein `AuthInfo`-Objekt zurückgegeben, das die Benutzerinformationen enthält. - - :param token: Das Bearer-Token, das vom MCP-Inspector empfangen wurde. - """ - - try: - # Der folgende Code geht davon aus, dass dein Autorisierungsserver einen Endpunkt zum Abrufen von Benutzerinformationen hat, - # der das im Autorisierungsablauf ausgestellte Zugangstoken verwendet. - # Passe die URL und Header nach Bedarf entsprechend der API deines Providers an. - response = requests.get( - "https://your-authorization-server.com/userinfo", - headers={"Authorization": f"Bearer {token}"}, - ) - response.raise_for_status() # Stelle sicher, dass wir bei HTTP-Fehlern einen Fehler auslösen - json = response.json() # Parsen der JSON-Antwort - - # Der folgende Code geht davon aus, dass die Benutzerinfo-Antwort ein Objekt mit einem 'sub'-Feld ist, - # das den Benutzer identifiziert. Du musst dies ggf. entsprechend der API deines Providers anpassen. - return AuthInfo( - token=token, - subject=json.get("sub"), - issuer=auth_issuer, # Verwende den konfigurierten Aussteller (Issuer) - claims=json, # Füge alle Ansprüche (Claims / JSON-Felder) hinzu, die vom Endpunkt zurückgegeben werden - ) - # `AuthInfo` ist ein Pydantic-Modell, daher bedeuten Validierungsfehler normalerweise, dass die Antwort nicht der erwarteten Struktur entspricht - except pydantic.ValidationError as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.INVALID_TOKEN, - cause=e, - ) - # Behandle andere Ausnahmen, die während der Anfrage auftreten können - except Exception as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.TOKEN_VERIFICATION_FAILED, - cause=e, - ) -``` - - - - -```js -import { MCPAuthTokenVerificationError } from 'mcp-auth'; - -/** - * Überprüft das bereitgestellte Bearer-Token, indem Benutzerinformationen vom Autorisierungsserver abgerufen werden. - * Wenn das Token gültig ist, wird ein `AuthInfo`-Objekt zurückgegeben, das die Benutzerinformationen enthält. - */ -const verifyToken = async (token) => { - // Der folgende Code geht davon aus, dass dein Autorisierungsserver einen Endpunkt zum Abrufen von Benutzerinformationen hat, - // der das im Autorisierungsablauf ausgestellte Zugangstoken verwendet. - // Passe die URL und Header nach Bedarf entsprechend der API deines Providers an. - const response = await fetch('https://your-authorization-server.com/userinfo', { - headers: { Authorization: `Bearer ${token}` }, - }); - - if (!response.ok) { - throw new MCPAuthTokenVerificationError('token_verification_failed', response); - } - - const userInfo = await response.json(); - - // Der folgende Code geht davon aus, dass die Benutzerinfo-Antwort ein Objekt mit einem 'sub'-Feld ist, - // das den Benutzer identifiziert. Du musst dies ggf. entsprechend der API deines Providers anpassen. - if (typeof userInfo !== 'object' || userInfo === null || !('sub' in userInfo)) { - throw new MCPAuthTokenVerificationError('invalid_token', response); - } - - return { - token, - issuer: authIssuer, - subject: String(userInfo.sub), // Passe dies ggf. an das User-ID-Feld deines Providers an - clientId: '', // Die Client-ID wird in diesem Beispiel nicht verwendet, kann aber gesetzt werden, falls benötigt - scopes: [], - claims: userInfo, - }; -}; -``` - - - diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oidc.mdx b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oidc.mdx deleted file mode 100644 index 52a8045..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oidc.mdx +++ /dev/null @@ -1,142 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -Aktualisiere die `whoami.py`, um die MCP Auth-Konfiguration einzubinden: - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # Ersetze dies durch deinen Issuer-Endpunkt -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -Aktualisiere die `whoami.js`, um die MCP Auth-Konfiguration einzubinden: - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // Ersetze dies durch deinen Issuer-Endpunkt -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oidc' }), -}); -``` - - - - -{props.showAlternative && } -{props.showAlternative && } - -Nun müssen wir einen benutzerdefinierten Zugangstoken (Access token) Verifizierer erstellen, der die Benutzeridentitätsinformationen vom Autorisierungsserver mit dem vom MCP-Inspector bereitgestellten Zugangstoken abruft. - - - - -```python -import pydantic -import requests -from mcpauth.exceptions import ( - MCPAuthTokenVerificationException, - MCPAuthTokenVerificationExceptionCode, -) -from mcpauth.types import AuthInfo - -def verify_access_token(token: str) -> AuthInfo: - """ - Überprüft das bereitgestellte Bearer-Token, indem Benutzerinformationen vom Autorisierungsserver abgerufen werden. - Wenn das Token gültig ist, wird ein `AuthInfo`-Objekt mit den Benutzerinformationen zurückgegeben. - - :param token: Das vom MCP-Inspector erhaltene Bearer-Token. - """ - - issuer = auth_server_config.metadata.issuer - endpoint = auth_server_config.metadata.userinfo_endpoint # Der Anbieter sollte den userinfo-Endpunkt unterstützen - if not endpoint: - raise ValueError( - "Userinfo-Endpunkt ist in den Auth-Server-Metadaten nicht konfiguriert." - ) - - try: - response = requests.get( - endpoint, - headers={"Authorization": f"Bearer {token}"}, # Standard Bearer-Token-Header - ) - response.raise_for_status() # Fehler bei HTTP-Fehlern auslösen - json = response.json() # Die JSON-Antwort parsen - return AuthInfo( - token=token, - subject=json.get("sub"), # 'sub' ist ein Standard-Anspruch (Claim) für das Subjekt (Benutzer-ID) - issuer=issuer, # Verwende den Aussteller (Issuer) aus den Metadaten - claims=json, # Alle Ansprüche (Claims) (JSON-Felder), die vom userinfo-Endpunkt zurückgegeben werden - ) - # `AuthInfo` ist ein Pydantic-Modell, daher bedeuten Validierungsfehler meist, dass die Antwort nicht der erwarteten Struktur entspricht - except pydantic.ValidationError as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.INVALID_TOKEN, - cause=e, - ) - # Andere Ausnahmen behandeln, die während der Anfrage auftreten können - except Exception as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.TOKEN_VERIFICATION_FAILED, - cause=e, - ) -``` - - - - -```js -import { MCPAuthTokenVerificationError } from 'mcp-auth'; - -/** - * Überprüft das bereitgestellte Bearer-Token, indem Benutzerinformationen vom Autorisierungsserver abgerufen werden. - * Wenn das Token gültig ist, wird ein `AuthInfo`-Objekt mit den Benutzerinformationen zurückgegeben. - */ -const verifyToken = async (token) => { - const { issuer, userinfoEndpoint } = mcpAuth.config.server.metadata; - - if (!userinfoEndpoint) { - throw new Error('Userinfo-Endpunkt ist in den Server-Metadaten nicht konfiguriert'); - } - - const response = await fetch(userinfoEndpoint, { - headers: { Authorization: `Bearer ${token}` }, - }); - - if (!response.ok) { - throw new MCPAuthTokenVerificationError('token_verification_failed', response); - } - - const userInfo = await response.json(); - - if (typeof userInfo !== 'object' || userInfo === null || !('sub' in userInfo)) { - throw new MCPAuthTokenVerificationError('invalid_token', response); - } - - return { - token, - issuer, - subject: String(userInfo.sub), // 'sub' ist ein Standard-Anspruch (Claim) für das Subjekt (Benutzer-ID) - clientId: '', // Client ID wird in diesem Beispiel nicht verwendet, kann aber gesetzt werden - scopes: [], - claims: userInfo, - }; -}; -``` - - - diff --git a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_transpile-metadata.mdx b/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_transpile-metadata.mdx deleted file mode 100644 index b602ffc..0000000 --- a/i18n/de/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_transpile-metadata.mdx +++ /dev/null @@ -1,31 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -In einigen Fällen kann die Antwort des Providers fehlerhaft oder nicht dem erwarteten Metadatenformat entsprechend sein. Wenn du sicher bist, dass der Provider konform ist, kannst du die Metadaten über die Konfigurationsoption transpiliieren: - - - - -```python -mcp_auth = MCPAuth( - server=fetch_server_config( - # ...other options - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { - // ...other options - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1.json b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1.json deleted file mode 100644 index c2f1e10..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1.json +++ /dev/null @@ -1,50 +0,0 @@ -{ - "sidebar.docsSidebar.category.Tutorials": { - "message": "Tutoriales", - "description": "The label for category Tutorials in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.Tutorials.link.generated-index.title": { - "message": "Tutoriales", - "description": "The generated-index page title for category Tutorials in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.Configure MCP server": { - "message": "Configurar servidor MCP", - "description": "The label for category Configure MCP server in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.Configure MCP server.link.generated-index.title": { - "message": "Configurar servidor MCP", - "description": "The generated-index page title for category Configure MCP server in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.SDK references": { - "message": "Referencias de SDK", - "description": "The label for category SDK references in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.SDK references.link.generated-index.title": { - "message": "Referencias de SDK de MCP Auth", - "description": "The generated-index page title for category SDK references in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.SDK references.link.generated-index.description": { - "message": "Información sobre clases, métodos y propiedades extraídas de los SDKs de MCP Auth.\n", - "description": "The generated-index page description for category SDK references in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.Node.js SDK": { - "message": "SDK de Node.js", - "description": "The label for category Node.js SDK in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.classes": { - "message": "clases", - "description": "The label for category classes in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.functions": { - "message": "funciones", - "description": "The label for category functions in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.type-aliases": { - "message": "alias de tipos", - "description": "The label for category type-aliases in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.variables": { - "message": "variables", - "description": "The label for category variables in sidebar docsSidebar" - } -} diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/README.mdx b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/README.mdx deleted file mode 100644 index 2a196cf..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/README.mdx +++ /dev/null @@ -1,242 +0,0 @@ ---- -sidebar_position: 1 -sidebar_label: Comenzar ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -# Comenzar - -## Elige un proveedor compatible con OAuth 2.1 u OpenID Connect \{#choose-a-compatible-oauth-2-1-or-openid-connect-provider} - -La especificación MCP tiene algunos [requisitos específicos](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization#1-3-standards-compliance) para la autorización: - -- [OAuth 2.1 IETF DRAFT](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12) -- Metadatos del servidor de autorización OAuth 2.0 ([RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)) -- Protocolo de registro dinámico de clientes OAuth 2.0 ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) - -Aunque los dos últimos no son obligatorios, el primero es necesario para garantizar una implementación segura y conforme. - -:::note -En el nuevo borrador de MCP, RFC 8414 será obligatorio para los servidores de autorización (proveedores). Actualizaremos la documentación una vez que el nuevo borrador esté finalizado. -::: - -Puedes consultar la [lista de proveedores compatibles con MCP](/provider-list) para ver si tu proveedor es compatible. - -## Instala MCP Auth SDK \{#install-mcp-auth-sdk} - -MCP Auth está disponible tanto para Python como para TypeScript. ¡Avísanos si necesitas soporte para otro lenguaje o framework! - - - - -```bash -pip install mcpauth -``` - -O cualquier otro gestor de paquetes que prefieras, como pipenv o poetry. - - - - -```bash -npm install mcp-auth -``` - -O cualquier otro gestor de paquetes que prefieras, como pnpm o yarn. - - - - -## Inicializa MCP Auth \{#init-mcp-auth} - -El primer paso es inicializar la instancia de MCP Auth con los metadatos del servidor de autorización de tu proveedor. Si tu proveedor cumple con uno de estos: - -- [Metadatos del servidor de autorización OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8414) -- [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) - -Puedes usar la función incorporada para obtener los metadatos e inicializar la instancia de MCP Auth: - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -mcp_auth = MCPAuth( - server=fetch_server_config( - '', - type=AuthServerType.OIDC # o AuthServerType.OAUTH - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { type: 'oidc' }), // o 'oauth' -}); -``` - - - - -Si necesitas especificar manualmente la URL de los metadatos o los endpoints, consulta [Otras formas de inicializar MCP Auth](./configure-server/mcp-auth.mdx#other-ways). - -## Monta el endpoint de metadatos \{#mount-the-metadata-endpoint} - -Para cumplir con la especificación MCP actual, MCP Auth monta el endpoint de Metadatos del Servidor de Autorización OAuth 2.0 (`/.well-known/oauth-authorization-server`) en tu servidor MCP: - - - - -```python -from starlette.applications import Starlette - -app = Starlette(routes=[ - mcp_auth.metadata_route(), -]) -``` - - - - -```ts -import express from 'express'; - -const app = express(); -app.use(mcpAuth.delegatedRouter()); -``` - - - - -Las URLs en los metadatos se mantienen tal cual, por lo que el rol de servidor de autorización se delega completamente al proveedor. Puedes probar el endpoint de metadatos visitando `/.well-known/oauth-authorization-server` en tu servidor MCP. - -### ¿Por qué solo el endpoint de metadatos? \{#why-only-the-metadata-endpoint} - -Puede que veas que los SDK oficiales proporcionan un router de autenticación que monta endpoints de autorización como `/authorize`, `/token`, etc. Aquí te explicamos por qué no hacemos eso: - -1. Montar solo el endpoint de metadatos te permite aprovechar todas las capacidades de tu proveedor sin "reinventar la rueda" e inyectar complejidad innecesaria en tu servidor MCP. -2. También hay un esfuerzo en curso para cambiar el [rol del servidor MCP a un servidor de recursos](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/205) y requerir Metadatos de Recursos Protegidos OAuth 2.0 ([RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728)). Lo que significa que el servidor MCP **ya no manejará ninguna lógica de autorización** (incluido el endpoint de metadatos), sino que solo servirá como un servidor de recursos que depende del proveedor para la autenticación y autorización. - -:::note -Actualizaremos MCP Auth para soportar la nueva especificación MCP cuando esté finalizada. Mientras tanto, puedes usar la versión actual que es compatible con la especificación vigente. -::: - -## Usa el middleware Bearer auth \{#use-the-bearer-auth-middleware} - -Una vez que la instancia de MCP Auth está inicializada, puedes aplicar el middleware Bearer auth para proteger tus rutas MCP: - - - - -```python -from starlette.applications import Starlette -from starlette.middleware import Middleware -from starlette.routing import Mount -from mcpauth import MCPAuth -from mcp.server.fastmcp import FastMCP - -mcp = FastMCP() -mcp_auth = MCPAuth( - # Inicializa con la configuración de tu servidor de autenticación -) -bearer_auth = mcp_auth.bearer_auth_middleware( - "jwt", required_scopes=["read", "write"] -) - -app = Starlette(routes=[ - mcp_auth.metadata_route(), - Mount( - "/", - app=mcp.sse_app(), - middleware=[Middleware(bearer_auth)], - ), -]) -``` - - - - -```ts -import express from 'express'; -import { MCPAuth } from 'mcp-auth'; - -const app = express(); -const server = new McpServer(/* ... */); -const mcpAuth = new MCPAuth({ - /* ... */ -}); - -app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] })); -``` - - - - -En el ejemplo anterior, especificamos el tipo de token `jwt` y requerimos los alcances `read` y `write`. Validará automáticamente el JWT (JSON Web Token) y rellenará un objeto con la información del usuario autenticado. - -:::info -¿No has oído hablar de JWT (JSON Web Token) antes? No te preocupes, puedes seguir leyendo la documentación y lo explicaremos cuando sea necesario. También puedes consultar [Auth Wiki](https://auth.wiki/jwt) para una introducción rápida. -::: - -Para más información sobre la configuración de Bearer auth, consulta [Configurar Bearer auth](./configure-server/bearer-auth.mdx). - -## Recupera la información de autenticación en tu implementación MCP \{#retrieve-the-auth-info-in-your-mcp-implementation} - -Una vez aplicado el middleware Bearer auth, puedes acceder a la información del usuario autenticado (o identidad) en tu implementación MCP: - - - - -MCP Auth almacenará la información del usuario autenticado en una variable de contexto tras la autenticación exitosa una vez aplicado el middleware Bearer auth. Puedes acceder a ella en tus handlers de herramientas MCP así: - -```python -from mcp.server.fastmcp import FastMCP - -mcp = FastMCP() -mcp_auth = MCPAuth( - # Inicializa con la configuración de tu servidor de autenticación -) - -@mcp.tool() -def add(a: int, b: int): - """ - Una herramienta que suma dos números. - La información del usuario autenticado estará disponible en el contexto. - """ - auth_info = mcp_auth.auth_info # Accede a la información de autenticación en el contexto actual - if auth_info: - print(f"Usuario autenticado: {auth_info.claims}") - return a + b -``` - - - - -El segundo argumento del handler de la herramienta contendrá el objeto `authInfo`, que incluye la información del usuario autenticado: - -```ts -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; -import { z } from 'zod'; - -const server = new McpServer(/* ... */); -server.tool('add', { a: z.number(), b: z.number() }, async ({ a, b }, { authInfo }) => { - // Ahora puedes usar el objeto `authInfo` para acceder a la información autenticada -}); -``` - - - - -## Próximos pasos \{#next-steps} - -Continúa leyendo para aprender un ejemplo de extremo a extremo sobre cómo integrar MCP Auth con tu servidor MCP y cómo manejar el flujo de autenticación en los clientes MCP. \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/comparison.mdx b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/comparison.mdx deleted file mode 100644 index 948261a..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/comparison.mdx +++ /dev/null @@ -1,80 +0,0 @@ ---- -sidebar_position: 101 -sidebar_label: Comparación ---- - -# Elegir entre MCP Auth y otras soluciones - -El ecosistema MCP está evolucionando. A medida que la especificación del Model Context Protocol (MCP) avanza desde el enfoque de “servidor de autorización” hacia el nuevo modelo de “servidor de recursos + IdP de terceros”, es importante comprender cómo encajan las diferentes soluciones de integración, tanto ahora como en el futuro. - -Esta página describe las principales diferencias entre mcp-auth y otras soluciones populares, para ayudarte a elegir el mejor enfoque para tu proyecto. - -## Antecedentes: Enfoque proxy vs. integración con IdP \{#background-proxy-approach-vs-idp-integration} - -La mayoría de las soluciones de autenticación MCP existentes utilizan un “enfoque proxy”. En este modelo, el servidor MCP actúa como intermediario y reenvía las solicitudes de autorización a un Proveedor de Identidad (IdP) de terceros, funcionando efectivamente como un intermediario entre el cliente y el IdP. - -**Enfoque proxy ([03-26 spec](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization))** - -```mermaid -sequenceDiagram - participant Cliente - participant MCP_Servidor as Servidor MCP - participant IdP_Tercero as IdP de terceros - - Cliente->>MCP_Servidor: Solicitud de autorización - MCP_Servidor->>IdP_Tercero: Reenvía solicitud - IdP_Tercero->>MCP_Servidor: Respuesta - MCP_Servidor->>Cliente: Respuesta - Cliente->>MCP_Servidor: Acceso a recurso - alt Validación remota - MCP_Servidor->>IdP_Tercero: Validar token - IdP_Tercero->>MCP_Servidor: Token válido - else Validación local - MCP_Servidor->>MCP_Servidor: Validar token localmente (por ejemplo, JWK en caché) - end - MCP_Servidor->>Cliente: Datos del recurso -``` - -Aunque esto funciona con la especificación MCP actual (2025-03-26), en esencia es una solución temporal. Supone que el servidor MCP también actuará como servidor de autorización, lo cual no es la dirección del último borrador de la especificación. - -**MCP Auth / especificación futura (servidor de recursos + IdP de terceros)** - -```mermaid -sequenceDiagram - participant Cliente - participant MCP_Servidor as Servidor MCP - participant IdP_Tercero as IdP de terceros - - Cliente->>IdP_Tercero: Solicitud de autorización - IdP_Tercero->>Cliente: Token - Cliente->>MCP_Servidor: Acceso a recurso (con token) - alt Validación remota - MCP_Servidor->>IdP_Tercero: Validar token - IdP_Tercero->>MCP_Servidor: Token válido - else Validación local - MCP_Servidor->>MCP_Servidor: Validar token localmente (por ejemplo, JWK en caché) - end - MCP_Servidor->>Cliente: Datos del recurso -``` - -La próxima especificación de MCP [traslada la responsabilidad de la autorización a un IdP de terceros dedicado](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/205). En este modelo, el servidor MCP solo actúa como servidor de recursos, y todos los endpoints de autorización provienen directamente del IdP de terceros. - -## ¿Por qué elegir MCP Auth? \{#why-choose-mcp-auth} - -- Alineación con la especificación: MCP Auth sigue directamente la dirección del último borrador, siendo la única solución compatible tanto con la especificación 03-26 como con la próxima. -- Sin más soluciones temporales: En lugar de actuar como proxy de servidor de autorización, MCP Auth permite que el IdP de terceros gestione toda la autorización, como está previsto en la nueva especificación. -- Agnóstico al proveedor: MCP Auth funciona con cualquier proveedor compatible con los estándares OAuth 2.0 / OIDC. -- Transición fluida: MCP Auth devuelve todos los endpoints de terceros tal cual mediante OAuth 2.0 Authorization Server Metadata. Esto mantiene la integración simple ahora y lista para futuros cambios. -- Experiencia para desarrolladores: Ofrece tutoriales, utilidades y próximas funciones como [OAuth 2.0 Protected Resource Metadata](https://auth.wiki/protected-resource-metadata) para facilitar la vida a los desarrolladores de servidores MCP. - -| Característica | Soluciones proxy | MCP Auth | -| -------------------------------------- | --------------------- | -------- | -| Funciona con la especificación 03-26 | ✅ | ✅ | -| Funciona con la especificación futura | ❌ | ✅ | -| Soporta IdPs de terceros directamente | ❌ (solo solución temporal) | ✅ | -| Agnóstico al proveedor | Limitado[^1] | Sí | -| Listo para la transición | ❌ | ✅ | - -Si necesitas soportar IdPs de terceros ahora y quieres estar preparado para la próxima especificación, MCP Auth es la solución recomendada. Los enfoques basados en proxy pueden quedar obsoletos pronto o requerir una reestructuración significativa. - -[^1]: Algunas soluciones proxy pueden codificar parámetros o endpoints específicos, limitando la flexibilidad. \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/configure-server/bearer-auth.mdx b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/configure-server/bearer-auth.mdx deleted file mode 100644 index 46e9c1b..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/configure-server/bearer-auth.mdx +++ /dev/null @@ -1,250 +0,0 @@ ---- -sidebar_position: 2 -sidebar_label: Bearer auth ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -# Configura la autenticación Bearer en el servidor MCP - -MCP Auth proporciona varias formas de configurar la autorización Bearer en tu servidor MCP: - -- Modo [JWT (JSON Web Token)](https://auth.wiki/jwt): Un método de autorización integrado que verifica JWTs con aserciones de reclamos. -- Modo personalizado: Te permite implementar tu propia lógica de autorización. - -## Configura la autenticación Bearer con el modo JWT \{#configure-bearer-auth-with-jwt-mode} - -Si tu proveedor OAuth / OIDC emite JWTs para la autorización, puedes usar el modo JWT integrado en MCP Auth. Este verifica la firma del JWT, la expiración y otros reclamos que especifiques; luego, rellena la información de autenticación en el contexto de la solicitud para su posterior procesamiento en tu implementación MCP. - -### Validación de alcance (Scope) \{#scope-validation} - -Aquí tienes un ejemplo de la validación básica de alcances: - - - - -```python -from mcpauth import MCPAuth -from starlette.applications import Starlette -from starlette.middleware import Middleware -from starlette.routing import Mount -from mcp.server.fastmcp import FastMCP - -mcp = FastMCP("MyMCPServer") -mcp_auth = MCPAuth( - # Initialize with your auth server config -) -bearer_auth = mcp_auth.bearer_auth_middleware("jwt", required_scopes=["read", "write"]) # [!code highlight] - -app = Starlette( - routes=[Mount('/', app=mcp.sse_app(), middleware=[Middleware(bearer_auth)])] -) -``` - - - - -```ts -import express from 'express'; -import { MCPAuth } from 'mcp-auth'; - -const app = express(); -const mcpAuth = new MCPAuth({ - /* ... */ -}); -const bearerAuth = mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }); // [!code highlight] - -app.use('/mcp', bearerAuth, (req, res) => { - // Now `req.auth` contains the auth info - console.log(req.auth); -}); -``` - - - - -En el ejemplo anterior, especificamos que el JWT requiere los alcances (scopes) `read` y `write`. Si el JWT no contiene **ninguno** de estos alcances, la solicitud será rechazada con un error 403 Forbidden. - -### Validación del indicador de recurso (RFC 8707) \{#resource-indicator-validation-rfc-8707} - -Si tu proveedor está basado en OIDC, o admite la extensión [Resource Indicator](https://datatracker.ietf.org/doc/html/rfc8707), también puedes especificar la opción `audience` para validar el reclamo `aud` (audiencia) en el JWT. Esto es útil para asegurar que el JWT está destinado a tu servidor MCP. - -Consulta la documentación de tu proveedor para ver si admite la extensión Resource Indicator y cómo configurarla. Algunos proveedores pueden usar otros términos como "audience", "API resource" o "API indicator" para referirse al mismo concepto. - -Una vez que el indicador de recurso esté configurado, puedes especificarlo en el middleware `bearerAuth`: - - - - -```python -bearer_auth = mcp_auth.bearer_auth_middleware( - "jwt", - audience="https://api.example.com/mcp", # La audiencia esperada para el JWT [!code highlight] - required_scopes=["read", "write"] -) -``` - - - - -```ts -const bearerAuth = mcpAuth.bearerAuth('jwt', { - audience: 'https://api.example.com/mcp', // La audiencia esperada para el JWT [!code highlight] - requiredScopes: ['read', 'write'], -}); -``` - - - - -En el ejemplo anterior, MCP Auth validará **tanto** el reclamo `aud` en el JWT como los alcances requeridos. - -### Proporciona opciones personalizadas a la verificación JWT \{#provide-custom-options-to-the-jwt-verification} - -También puedes proporcionar opciones personalizadas a la biblioteca subyacente de verificación JWT: - - - - -En el SDK de Python, usamos [PyJWT](https://pyjwt.readthedocs.io/en/stable/) para la verificación de JWT. Puedes usar las siguientes opciones: - -- `leeway`: Permite cierta tolerancia al verificar el tiempo de expiración del JWT (en segundos). El valor predeterminado es 60 segundos. - -```python -bearer_auth = mcp_auth.bearer_auth_middleware( - "jwt", - audience="https://api.example.com/mcp", - required_scopes=["read", "write"] - leeway=10, # Reduce la diferencia de reloj permitiendo 10 segundos de tolerancia [!code highlight] -) -``` - - - - -En el SDK de Node.js, usamos la biblioteca [jose](https://github.com/panva/jose) para la verificación de JWT. Puedes proporcionar las siguientes opciones: - -- `jwtVerify`: Opciones para el proceso de verificación JWT (función `jwtVerify` de `jose`). -- `remoteJwtSet`: Opciones para obtener el conjunto remoto de JWT (función `createRemoteJWKSet` de `jose`). - -```ts {4-9} -const bearerAuth = mcpAuth.bearerAuth('jwt', { - audience: 'https://api.example.com/mcp', - requiredScopes: ['read', 'write'], - jwtVerify: { - clockTolerance: 60, // Permite una diferencia de reloj de 60 segundos - }, - remoteJwtSet: { - timeoutDuration: 10 * 1000, // 10 segundos de tiempo de espera para obtener el conjunto remoto de JWT - }, -}); -``` - - - - -## Configura la autenticación Bearer con verificación personalizada \{#configure-bearer-auth-with-custom-verification} - -Si tu proveedor OAuth / OIDC no emite JWTs, o deseas implementar tu propia lógica de autorización, MCP Auth te permite crear una función de verificación personalizada: - -:::info -Dado que el middleware de autenticación Bearer verificará el emisor (`iss`), la audiencia (`aud`) y los alcances requeridos (`scope`) con el resultado de la verificación proporcionado, no es necesario implementar estas comprobaciones en tu función de verificación personalizada. Puedes centrarte en verificar la validez del token (por ejemplo, firma, expiración, etc.) y devolver el objeto de información de autenticación. -::: - - - - -```python -from mcpauth.exceptions import MCPAuthJwtVerificationException, MCPAuthJwtVerificationExceptionCode -from mcpauth.types import AuthInfo - -async def custom_verification(token: str) -> AuthInfo: - # Implementa aquí tu lógica personalizada de verificación - info = await verify_token(token) - if not info: - raise MCPAuthJwtVerificationException( - MCPAuthJwtVerificationExceptionCode.JWT_VERIFICATION_FAILED - ) - return info # Devuelve el objeto de información de autenticación - -bearer_auth = mcp_auth.bearer_auth_middleware( - custom_verification, - required_scopes=["read", "write"] -) -``` - - - - -```ts -const bearerAuth = mcpAuth.bearerAuth( - async (token) => { - // Implementa aquí tu lógica personalizada de verificación - const info = await verifyToken(token); - if (!info) { - throw new MCPAuthJwtVerificationError('jwt_verification_failed'); - } - return info; // Devuelve el objeto de información de autenticación - }, - { requiredScopes: ['read', 'write'] } -); -``` - - - - -## Aplica la autenticación Bearer en tu servidor MCP \{#apply-bearer-auth-in-your-mcp-server} - -Para proteger tu servidor MCP con autenticación Bearer, necesitas aplicar el middleware de autenticación Bearer a tu instancia del servidor MCP. - - - - -```python -bearer_auth = mcp_auth.bearer_auth_middleware("jwt", required_scopes=["read", "write"]) -app = Starlette( - routes=[Mount('/', app=mcp.sse_app(), middleware=[Middleware(bearer_auth)])] -) -``` - - - - -```js -const app = express(); -app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] })); -``` - - - - -Esto asegurará que todas las solicitudes entrantes sean autenticadas y autorizadas de acuerdo con la configuración de autenticación Bearer, y la información de autenticación estará disponible en el contexto de la solicitud. - -Luego puedes acceder a la información en tu implementación del servidor MCP: - - - - -```python -@mcp.tool() -async def whoami() -> dict: - # `mcp_auth.auth_info` es el objeto de contexto para la solicitud actual - auth_info = mcp_auth.auth_info - print(f"Usuario autenticado: {auth_info.subject}") - return {"subject": auth_info.subject} -``` - - - - -```js -// `authInfo` se obtendrá del objeto `req.auth` -server.tool('whoami', ({ authInfo }) => { - console.log(`Usuario autenticado: ${authInfo.subject}`); - return { subject: authInfo.subject }; -}); -``` - - - \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/configure-server/mcp-auth.mdx b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/configure-server/mcp-auth.mdx deleted file mode 100644 index f0995ae..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/configure-server/mcp-auth.mdx +++ /dev/null @@ -1,208 +0,0 @@ ---- -sidebar_position: 1 -sidebar_label: MCP Auth ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -# Configurar MCP Auth en el servidor MCP - -Para conectar tu servidor MCP con un proveedor OAuth 2.1 u OpenID Connect, necesitas configurar la instancia de MCP Auth. Esto implica inicializar la instancia con los metadatos del servidor de autorización de tu proveedor y configurar los flujos de autorización necesarios. - -## Inicializar MCP Auth \{#init-mcp-auth} - -### Obtención automática de metadatos \{#automatic-metadata-fetching} - -La forma más sencilla de inicializar la instancia de MCP Auth es utilizando las funciones integradas que obtienen los metadatos desde una URL bien conocida. Si tu proveedor cumple con uno de los siguientes estándares: - -- [Metadatos del servidor de autorización OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8414) -- [Descubrimiento OpenID Connect](https://openid.net/specs/openid-connect-discovery-1_0.html) - -Puedes usar `fetchServerConfig` para recuperar automáticamente los metadatos proporcionando la URL del `issuer`: - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType, fetch_server_config - -mcp_auth = MCPAuth( - server=fetch_server_config( - '', - type=AuthServerType.OIDC # o AuthServerType.OAUTH - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { type: 'oidc' }), // o 'oauth' -}); -``` - - - - -Si tu issuer incluye una ruta, el comportamiento difiere ligeramente entre OAuth 2.0 y OpenID Connect: - -- **OAuth 2.0**: La URL bien conocida se añade al **dominio** del issuer. Por ejemplo, si tu issuer es `https://my-project.logto.app/oauth`, la URL bien conocida será `https://auth.logto.io/.well-known/oauth-authorization-server/oauth`. -- **OpenID Connect**: La URL bien conocida se añade directamente al **issuer**. Por ejemplo, si tu issuer es `https://my-project.logto.app/oidc`, la URL bien conocida será `https://auth.logto.io/oidc/.well-known/openid-configuration`. - -### Otras formas de inicializar MCP Auth \{#other-ways} - -#### Transpilación personalizada de datos \{#custom-data-transpilation} - -En algunos casos, los metadatos devueltos por el proveedor pueden no ajustarse al formato esperado. Si estás seguro de que el proveedor es compatible, puedes usar la opción `transpile_data` para modificar los metadatos antes de que se utilicen: - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -mcp_auth = MCPAuth( - server=fetch_server_config( - '', - type=AuthServerType.OIDC, - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { - type: 'oidc', - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - - -Esto te permite modificar el objeto de metadatos antes de que sea utilizado por MCP Auth. Por ejemplo, puedes añadir o eliminar campos, cambiar sus valores o convertirlos a un formato diferente. - -#### Obtener metadatos desde una URL específica \{#fetch-metadata-from-a-specific-url} - -Si tu proveedor tiene una URL de metadatos específica en lugar de las estándar, puedes usarla de manera similar: - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config_by_well_known_url - -mcp_auth = MCPAuth( - server=fetch_server_config_by_well_known_url( - '', - type=AuthServerType.OIDC # o AuthServerType.OAUTH - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfigByWellKnownUrl } from 'mcp-auth'; - -const mcpAuth = new MCPAuth({ - server: await fetchServerConfigByWellKnownUrl('', { type: 'oidc' }), // o 'oauth' -}); -``` - - - - -#### Obtener metadatos desde una URL específica con transpilación personalizada de datos \{#fetch-metadata-from-a-specific-url-with-custom-data-transpilation} - -En algunos casos, la respuesta del proveedor puede estar malformada o no ajustarse al formato de metadatos esperado. Si estás seguro de que el proveedor es compatible, puedes transpilar los metadatos mediante la opción de configuración: - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType, fetch_server_config_by_well_known_url - -mcp_auth = MCPAuth( - server=fetch_server_config_by_well_known_url( - '', - type=AuthServerType.OIDC, - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: await fetchServerConfigByWellKnownUrl('', { - type: 'oidc', - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - - -#### Proporcionar manualmente los metadatos \{#manually-provide-metadata} - -Si tu proveedor no admite la obtención de metadatos, puedes proporcionar manualmente el objeto de metadatos: - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerConfig, AuthServerType, AuthorizationServerMetadata - -mcp_auth = MCPAuth( - server=AuthServerConfig( - type=AuthServerType.OIDC, # o AuthServerType.OAUTH - metadata=AuthorizationServerMetadata( - issuer='', - authorization_endpoint='', - # ... otros campos de metadatos - ), - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: { - metadata: { - issuer: '', - // Los campos de metadatos deben estar en camelCase - authorizationEndpoint: '', - // ... otros campos de metadatos - }, - type: 'oidc', // o 'oauth' - }, -}); -``` - - - \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/README.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/README.md deleted file mode 100644 index 7e31103..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/README.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -sidebar_label: Node.js SDK ---- - -# Referencia del SDK MCP Auth Node.js - -## Clases {#classes} - -- [MCPAuth](/references/js/classes/MCPAuth.md) -- [MCPAuthAuthServerError](/references/js/classes/MCPAuthAuthServerError.md) -- [MCPAuthBearerAuthError](/references/js/classes/MCPAuthBearerAuthError.md) -- [MCPAuthConfigError](/references/js/classes/MCPAuthConfigError.md) -- [MCPAuthError](/references/js/classes/MCPAuthError.md) -- [MCPAuthTokenVerificationError](/references/js/classes/MCPAuthTokenVerificationError.md) - -## Alias de tipos {#type-aliases} - -- [AuthorizationServerMetadata](/references/js/type-aliases/AuthorizationServerMetadata.md) -- [AuthServerConfig](/references/js/type-aliases/AuthServerConfig.md) -- [AuthServerConfigError](/references/js/type-aliases/AuthServerConfigError.md) -- [AuthServerConfigErrorCode](/references/js/type-aliases/AuthServerConfigErrorCode.md) -- [AuthServerConfigWarning](/references/js/type-aliases/AuthServerConfigWarning.md) -- [AuthServerConfigWarningCode](/references/js/type-aliases/AuthServerConfigWarningCode.md) -- [AuthServerErrorCode](/references/js/type-aliases/AuthServerErrorCode.md) -- [AuthServerSuccessCode](/references/js/type-aliases/AuthServerSuccessCode.md) -- [AuthServerType](/references/js/type-aliases/AuthServerType.md) -- [BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) -- [BearerAuthErrorCode](/references/js/type-aliases/BearerAuthErrorCode.md) -- [BearerAuthJwtConfig](/references/js/type-aliases/BearerAuthJwtConfig.md) -- [CamelCaseAuthorizationServerMetadata](/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md) -- [MCPAuthBearerAuthErrorDetails](/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md) -- [MCPAuthConfig](/references/js/type-aliases/MCPAuthConfig.md) -- [MCPAuthTokenVerificationErrorCode](/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md) -- [VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) -- [VerifyAccessTokenMode](/references/js/type-aliases/VerifyAccessTokenMode.md) - -## Variables {#variables} - -- [authorizationServerMetadataSchema](/references/js/variables/authorizationServerMetadataSchema.md) -- [authServerErrorDescription](/references/js/variables/authServerErrorDescription.md) -- [bearerAuthErrorDescription](/references/js/variables/bearerAuthErrorDescription.md) -- [camelCaseAuthorizationServerMetadataSchema](/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md) -- [serverMetadataPaths](/references/js/variables/serverMetadataPaths.md) -- [tokenVerificationErrorDescription](/references/js/variables/tokenVerificationErrorDescription.md) -- [validateServerConfig](/references/js/variables/validateServerConfig.md) - -## Funciones {#functions} - -- [createVerifyJwt](/references/js/functions/createVerifyJwt.md) -- [fetchServerConfig](/references/js/functions/fetchServerConfig.md) -- [fetchServerConfigByWellKnownUrl](/references/js/functions/fetchServerConfigByWellKnownUrl.md) -- [handleBearerAuth](/references/js/functions/handleBearerAuth.md) diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuth.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuth.md deleted file mode 100644 index 478abf1..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuth.md +++ /dev/null @@ -1,195 +0,0 @@ ---- -sidebar_label: MCPAuth ---- - -# Clase: MCPAuth - -La clase principal para la librería mcp-auth, que proporciona métodos para crear routers y manejadores útiles para la autenticación (Autenticación) y autorización (Autorización) en servidores MCP. - -## Ver también {#see} - -[MCP Auth](https://mcp-auth.dev) para más información sobre la librería y su uso. - -## Ejemplo {#example} - -Un ejemplo integrando con un proveedor OIDC remoto: - -```ts -import express from 'express'; -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const app = express(); -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig( - 'https://auth.logto.io/oidc', - { type: 'oidc' } - ), -}); - -// Monta el router para manejar el endpoint de metadatos del servidor de autorización OAuth 2.0 -app.use(mcpAuth.delegatedRouter()); - -// Usa el manejador Bearer auth en la ruta MCP -app.get( - '/mcp', - mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }), - (req, res) => { - console.log('Auth info:', req.auth); - // Maneja aquí la solicitud MCP - }, -); - -// Usa la información de autenticación en el callback MCP -server.tool( - 'add', - { a: z.number(), b: z.number() }, - async ({ a, b }, { authInfo }) => { - console.log('Auth Info:', authInfo); - // ... - }, -); -``` - -## Constructores {#constructors} - -### Constructor {#constructor} - -```ts -new MCPAuth(config: MCPAuthConfig): MCPAuth; -``` - -#### Parámetros {#parameters} - -##### config {#config} - -[`MCPAuthConfig`](/references/js/type-aliases/MCPAuthConfig.md) - -#### Devuelve {#returns} - -`MCPAuth` - -## Propiedades {#properties} - -### config {#config} - -```ts -readonly config: MCPAuthConfig; -``` - -## Métodos {#methods} - -### bearerAuth() {#bearerauth} - -#### Firma de llamada {#call-signature} - -```ts -bearerAuth(verifyAccessToken: VerifyAccessTokenFunction, config?: Omit): RequestHandler; -``` - -Crea un manejador Bearer auth (middleware de Express) que verifica el token de acceso (Token de acceso) en el encabezado `Authorization` de la solicitud. - -##### Parámetros {#parameters} - -###### verifyAccessToken {#verifyaccesstoken} - -[`VerifyAccessTokenFunction`](/references/js/type-aliases/VerifyAccessTokenFunction.md) - -Una función que verifica el token de acceso (Token de acceso). Debe aceptar el token de acceso como una cadena y devolver una promesa (o un valor) que resuelva el resultado de la verificación. - -**Ver también** - -[VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) para la definición de tipo de la función `verifyAccessToken`. - -###### config? {#config} - -`Omit`\<[`BearerAuthConfig`](/references/js/type-aliases/BearerAuthConfig.md), `"verifyAccessToken"` \| `"issuer"`\> - -Configuración opcional para el manejador Bearer auth. - -**Ver también** - -[BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) para las opciones de configuración disponibles (excluyendo `verifyAccessToken` y `issuer`). - -##### Devuelve {#returns} - -`RequestHandler` - -Una función middleware de Express que verifica el token de acceso (Token de acceso) y añade el resultado de la verificación al objeto de la solicitud (`req.auth`). - -##### Ver también {#see} - -[handleBearerAuth](/references/js/functions/handleBearerAuth.md) para detalles de implementación y los tipos extendidos del objeto `req.auth` (`AuthInfo`). - -#### Firma de llamada {#call-signature} - -```ts -bearerAuth(mode: "jwt", config?: Omit & BearerAuthJwtConfig): RequestHandler; -``` - -Crea un manejador Bearer auth (middleware de Express) que verifica el token de acceso (Token de acceso) en el encabezado `Authorization` de la solicitud usando un modo de verificación predefinido. - -En el modo `'jwt'`, el manejador creará una función de verificación JWT usando el JWK Set del URI JWKS del servidor de autorización (Autorización). - -##### Parámetros {#parameters} - -###### mode {#mode} - -`"jwt"` - -El modo de verificación para el token de acceso (Token de acceso). Actualmente, solo se admite 'jwt'. - -**Ver también** - -[VerifyAccessTokenMode](/references/js/type-aliases/VerifyAccessTokenMode.md) para los modos disponibles. - -###### config? {#config} - -`Omit`\<[`BearerAuthConfig`](/references/js/type-aliases/BearerAuthConfig.md), `"verifyAccessToken"` \| `"issuer"`\> & [`BearerAuthJwtConfig`](/references/js/type-aliases/BearerAuthJwtConfig.md) - -Configuración opcional para el manejador Bearer auth, incluyendo opciones de verificación JWT y opciones remotas de JWK set. - -**Ver también** - - - [BearerAuthJwtConfig](/references/js/type-aliases/BearerAuthJwtConfig.md) para las opciones de configuración disponibles para la verificación JWT. - - [BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) para las opciones de configuración disponibles (excluyendo `verifyAccessToken` y `issuer`). - -##### Devuelve {#returns} - -`RequestHandler` - -Una función middleware de Express que verifica el token de acceso (Token de acceso) y añade el resultado de la verificación al objeto de la solicitud (`req.auth`). - -##### Ver también {#see} - -[handleBearerAuth](/references/js/functions/handleBearerAuth.md) para detalles de implementación y los tipos extendidos del objeto `req.auth` (`AuthInfo`). - -##### Lanza {#throws} - -si el URI JWKS no se proporciona en los metadatos del servidor al usar el modo `'jwt'`. - -*** - -### delegatedRouter() {#delegatedrouter} - -```ts -delegatedRouter(): Router; -``` - -Crea un router delegado que sirve el endpoint de metadatos del servidor de autorización OAuth 2.0 (`/.well-known/oauth-authorization-server`) con los metadatos proporcionados a la instancia. - -#### Devuelve {#returns} - -`Router` - -Un router que sirve el endpoint de metadatos del servidor de autorización OAuth 2.0 con los metadatos proporcionados a la instancia. - -#### Ejemplo {#example} - -```ts -import express from 'express'; -import { MCPAuth } from 'mcp-auth'; - -const app = express(); -const mcpAuth: MCPAuth; // Se asume que está inicializado -app.use(mcpAuth.delegatedRouter()); -``` \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthAuthServerError.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthAuthServerError.md deleted file mode 100644 index 6042bc9..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthAuthServerError.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -sidebar_label: MCPAuthAuthServerError ---- - -# Clase: MCPAuthAuthServerError - -Error lanzado cuando hay un problema con el servidor de autorización remoto. - -## Hereda de {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## Constructores {#constructors} - -### Constructor {#constructor} - -```ts -new MCPAuthAuthServerError(code: AuthServerErrorCode, cause?: unknown): MCPAuthAuthServerError; -``` - -#### Parámetros {#parameters} - -##### code {#code} - -[`AuthServerErrorCode`](/references/js/type-aliases/AuthServerErrorCode.md) - -##### cause? {#cause} - -`unknown` - -#### Devuelve {#returns} - -`MCPAuthAuthServerError` - -#### Sobrescribe {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## Propiedades {#properties} - -### cause? {#cause} - -```ts -readonly optional cause: unknown; -``` - -#### Heredado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: AuthServerErrorCode; -``` - -El código de error en formato snake_case. - -#### Heredado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### Heredado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthAuthServerError'; -``` - -#### Sobrescribe {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### Heredado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -Sobrescritura opcional para formatear los stack traces - -#### Parámetros {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### Devuelve {#returns} - -`any` - -#### Ver {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### Heredado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### Heredado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## Métodos {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -Convierte el error a un formato JSON amigable para respuestas HTTP. - -#### Parámetros {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -Indica si se debe incluir la causa del error en la respuesta JSON. -Por defecto es `false`. - -#### Devuelve {#returns} - -`Record`\<`string`, `unknown`\> - -#### Heredado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -Crea la propiedad .stack en un objeto objetivo - -#### Parámetros {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### Devuelve {#returns} - -`void` - -#### Heredado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthBearerAuthError.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthBearerAuthError.md deleted file mode 100644 index 3bb856f..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthBearerAuthError.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -sidebar_label: MCPAuthBearerAuthError ---- - -# Clase: MCPAuthBearerAuthError - -Error lanzado cuando hay un problema al autenticar con tokens Bearer. - -## Hereda de {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## Constructores {#constructors} - -### Constructor {#constructor} - -```ts -new MCPAuthBearerAuthError(code: BearerAuthErrorCode, cause?: MCPAuthBearerAuthErrorDetails): MCPAuthBearerAuthError; -``` - -#### Parámetros {#parameters} - -##### code {#code} - -[`BearerAuthErrorCode`](/references/js/type-aliases/BearerAuthErrorCode.md) - -##### cause? {#cause} - -[`MCPAuthBearerAuthErrorDetails`](/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md) - -#### Devuelve {#returns} - -`MCPAuthBearerAuthError` - -#### Sobrescribe {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## Propiedades {#properties} - -### cause? {#cause} - -```ts -readonly optional cause: MCPAuthBearerAuthErrorDetails; -``` - -#### Heredado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: BearerAuthErrorCode; -``` - -El código de error en formato snake_case. - -#### Heredado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### Heredado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthBearerAuthError'; -``` - -#### Sobrescribe {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### Heredado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -Sobrescritura opcional para formatear los stack traces - -#### Parámetros {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### Devuelve {#returns} - -`any` - -#### Ver {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### Heredado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### Heredado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## Métodos {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -Convierte el error a un formato JSON amigable para respuestas HTTP. - -#### Parámetros {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -Indica si se debe incluir la causa del error en la respuesta JSON. -Por defecto es `false`. - -#### Devuelve {#returns} - -`Record`\<`string`, `unknown`\> - -#### Sobrescribe {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -Crea la propiedad .stack en un objeto objetivo - -#### Parámetros {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### Devuelve {#returns} - -`void` - -#### Heredado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthConfigError.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthConfigError.md deleted file mode 100644 index 9e86cde..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthConfigError.md +++ /dev/null @@ -1,202 +0,0 @@ ---- -sidebar_label: MCPAuthConfigError ---- - -# Clase: MCPAuthConfigError - -Error lanzado cuando hay un problema de configuración con mcp-auth. - -## Hereda de {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## Constructores {#constructors} - -### Constructor {#constructor} - -```ts -new MCPAuthConfigError(code: string, message: string): MCPAuthConfigError; -``` - -#### Parámetros {#parameters} - -##### code {#code} - -`string` - -El código de error en formato snake_case. - -##### message {#message} - -`string` - -Una descripción legible para humanos del error. - -#### Devuelve {#returns} - -`MCPAuthConfigError` - -#### Heredado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## Propiedades {#properties} - -### cause? {#cause} - -```ts -optional cause: unknown; -``` - -#### Heredado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: string; -``` - -El código de error en formato snake_case. - -#### Heredado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### Heredado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthConfigError'; -``` - -#### Sobrescribe {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### Heredado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -Sobrescritura opcional para formatear los stack traces - -#### Parámetros {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### Devuelve {#returns} - -`any` - -#### Ver {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### Heredado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### Heredado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## Métodos {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -Convierte el error a un formato JSON amigable para respuestas HTTP. - -#### Parámetros {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -Indica si se debe incluir la causa del error en la respuesta JSON. -Por defecto es `false`. - -#### Devuelve {#returns} - -`Record`\<`string`, `unknown`\> - -#### Heredado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -Crea la propiedad .stack en un objeto objetivo - -#### Parámetros {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### Devuelve {#returns} - -`void` - -#### Heredado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthError.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthError.md deleted file mode 100644 index 0982b6d..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthError.md +++ /dev/null @@ -1,219 +0,0 @@ ---- -sidebar_label: MCPAuthError ---- - -# Clase: MCPAuthError - -Clase base para todos los errores de mcp-auth. - -Proporciona una forma estandarizada de manejar errores relacionados con la autenticación (Authentication) y autorización (Authorization) de MCP. - -## Hereda de {#extends} - -- `Error` - -## Extendida por {#extended-by} - -- [`MCPAuthConfigError`](/references/js/classes/MCPAuthConfigError.md) -- [`MCPAuthAuthServerError`](/references/js/classes/MCPAuthAuthServerError.md) -- [`MCPAuthBearerAuthError`](/references/js/classes/MCPAuthBearerAuthError.md) -- [`MCPAuthTokenVerificationError`](/references/js/classes/MCPAuthTokenVerificationError.md) - -## Constructores {#constructors} - -### Constructor {#constructor} - -```ts -new MCPAuthError(code: string, message: string): MCPAuthError; -``` - -#### Parámetros {#parameters} - -##### code {#code} - -`string` - -El código de error en formato snake_case. - -##### message {#message} - -`string` - -Una descripción legible para humanos del error. - -#### Devuelve {#returns} - -`MCPAuthError` - -#### Sobrescribe {#overrides} - -```ts -Error.constructor -``` - -## Propiedades {#properties} - -### cause? {#cause} - -```ts -optional cause: unknown; -``` - -#### Heredado de {#inherited-from} - -```ts -Error.cause -``` - -*** - -### code {#code} - -```ts -readonly code: string; -``` - -El código de error en formato snake_case. - -*** - -### message {#message} - -```ts -message: string; -``` - -#### Heredado de {#inherited-from} - -```ts -Error.message -``` - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthError'; -``` - -#### Sobrescribe {#overrides} - -```ts -Error.name -``` - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### Heredado de {#inherited-from} - -```ts -Error.stack -``` - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -Sobrescritura opcional para formatear los stack traces - -#### Parámetros {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### Devuelve {#returns} - -`any` - -#### Ver {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### Heredado de {#inherited-from} - -```ts -Error.prepareStackTrace -``` - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### Heredado de {#inherited-from} - -```ts -Error.stackTraceLimit -``` - -## Métodos {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -Convierte el error a un formato JSON amigable para respuestas HTTP. - -#### Parámetros {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -Indica si se debe incluir la causa del error en la respuesta JSON. -Por defecto es `false`. - -#### Devuelve {#returns} - -`Record`\<`string`, `unknown`\> - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -Crea la propiedad .stack en un objeto objetivo - -#### Parámetros {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### Devuelve {#returns} - -`void` - -#### Heredado de {#inherited-from} - -```ts -Error.captureStackTrace -``` diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthTokenVerificationError.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthTokenVerificationError.md deleted file mode 100644 index 48c95fa..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthTokenVerificationError.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -sidebar_label: MCPAuthTokenVerificationError ---- - -# Clase: MCPAuthTokenVerificationError - -Error lanzado cuando hay un problema al verificar tokens. - -## Hereda de {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## Constructores {#constructors} - -### Constructor {#constructor} - -```ts -new MCPAuthTokenVerificationError(code: MCPAuthTokenVerificationErrorCode, cause?: unknown): MCPAuthTokenVerificationError; -``` - -#### Parámetros {#parameters} - -##### code {#code} - -[`MCPAuthTokenVerificationErrorCode`](/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md) - -##### cause? {#cause} - -`unknown` - -#### Devuelve {#returns} - -`MCPAuthTokenVerificationError` - -#### Sobrescribe {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## Propiedades {#properties} - -### cause? {#cause} - -```ts -readonly optional cause: unknown; -``` - -#### Heredado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: MCPAuthTokenVerificationErrorCode; -``` - -El código de error en formato snake_case. - -#### Heredado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### Heredado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthTokenVerificationError'; -``` - -#### Sobrescribe {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### Heredado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -Sobrescritura opcional para formatear trazas de pila - -#### Parámetros {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### Devuelve {#returns} - -`any` - -#### Ver {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### Heredado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### Heredado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## Métodos {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -Convierte el error a un formato JSON amigable para respuestas HTTP. - -#### Parámetros {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -Indica si se debe incluir la causa del error en la respuesta JSON. -Por defecto es `false`. - -#### Devuelve {#returns} - -`Record`\<`string`, `unknown`\> - -#### Heredado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -Crea la propiedad .stack en un objeto objetivo - -#### Parámetros {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### Devuelve {#returns} - -`void` - -#### Heredado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/createVerifyJwt.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/createVerifyJwt.md deleted file mode 100644 index ad32674..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/createVerifyJwt.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -sidebar_label: createVerifyJwt ---- - -# Función: createVerifyJwt() - -```ts -function createVerifyJwt(getKey: JWTVerifyGetKey, options?: JWTVerifyOptions): VerifyAccessTokenFunction; -``` - -Crea una función para verificar tokens de acceso JWT utilizando la función de recuperación de clave proporcionada y opciones. - -## Parámetros {#parameters} - -### getKey {#getkey} - -`JWTVerifyGetKey` - -La función para recuperar la clave utilizada para verificar el JWT. - -**Ver** - -JWTVerifyGetKey para la definición de tipo de la función de recuperación de clave. - -### options? {#options} - -`JWTVerifyOptions` - -Opciones opcionales de verificación de JWT. - -**Ver** - -JWTVerifyOptions para la definición de tipo de las opciones. - -## Retorna {#returns} - -[`VerifyAccessTokenFunction`](/references/js/type-aliases/VerifyAccessTokenFunction.md) - -Una función que verifica tokens de acceso JWT (Access tokens) y retorna un objeto AuthInfo si el token es válido. Requiere que el JWT contenga los campos `iss`, `client_id` y `sub` en su payload, y opcionalmente puede contener los campos `scope` o `scopes`. La función utiliza la librería `jose` internamente para realizar la verificación del JWT. - -## Ver {#see} - -[VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) para la definición de tipo de la función retornada. \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfig.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfig.md deleted file mode 100644 index 694f870..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfig.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -sidebar_label: fetchServerConfig ---- - -# Función: fetchServerConfig() - -```ts -function fetchServerConfig(issuer: string, config: ServerMetadataConfig): Promise; -``` - -Obtiene la configuración del servidor según el emisor (Issuer) y el tipo de servidor de autorización (Authorization). - -Esta función determina automáticamente la URL well-known en función del tipo de servidor, ya que los servidores OAuth y OpenID Connect tienen convenciones diferentes para sus endpoints de metadatos. - -## Parámetros {#parameters} - -### issuer {#issuer} - -`string` - -La URL del emisor (Issuer) del servidor de autorización (Authorization). - -### config {#config} - -`ServerMetadataConfig` - -El objeto de configuración que contiene el tipo de servidor y una función de transpilación opcional. - -## Devuelve {#returns} - -`Promise`\<[`AuthServerConfig`](/references/js/type-aliases/AuthServerConfig.md)\> - -Una promesa que se resuelve con la configuración del servidor. - -## Consulta también {#see} - - - [fetchServerConfigByWellKnownUrl](/references/js/functions/fetchServerConfigByWellKnownUrl.md) para la implementación subyacente. - - [https://www.rfc-editor.org/rfc/rfc8414](https://www.rfc-editor.org/rfc/rfc8414) para la especificación de metadatos del servidor de autorización OAuth 2.0 (Authorization). - - [https://openid.net/specs/openid-connect-discovery-1\_0.html](https://openid.net/specs/openid-connect-discovery-1_0.html) para la especificación de descubrimiento de OpenID Connect. - -## Ejemplo {#example} - -```ts -import { fetchServerConfig } from 'mcp-auth'; -// Obteniendo la configuración del servidor OAuth -// Esto obtendrá los metadatos desde `https://auth.logto.io/.well-known/oauth-authorization-server/oauth` -const oauthConfig = await fetchServerConfig('https://auth.logto.io/oauth', { type: 'oauth' }); - -// Obteniendo la configuración del servidor OpenID Connect -// Esto obtendrá los metadatos desde `https://auth.logto.io/oidc/.well-known/openid-configuration` -const oidcConfig = await fetchServerConfig('https://auth.logto.io/oidc', { type: 'oidc' }); -``` - -## Lanza {#throws} - -si la operación de obtención falla. - -## Lanza {#throws} - -si los metadatos del servidor son inválidos o no coinciden con la especificación MCP. \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfigByWellKnownUrl.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfigByWellKnownUrl.md deleted file mode 100644 index 636b5e8..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfigByWellKnownUrl.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -sidebar_label: fetchServerConfigByWellKnownUrl ---- - -# Función: fetchServerConfigByWellKnownUrl() - -```ts -function fetchServerConfigByWellKnownUrl(wellKnownUrl: string | URL, config: ServerMetadataConfig): Promise; -``` - -Obtiene la configuración del servidor desde la URL well-known proporcionada y la valida contra la -especificación MCP. - -Si los metadatos del servidor no se ajustan al esquema esperado, pero estás seguro de que son -compatibles, puedes definir una función `transpileData` para transformar los metadatos al -formato esperado. - -## Parámetros {#parameters} - -### wellKnownUrl {#wellknownurl} - -La URL well-known desde la que obtener la configuración del servidor. Puede ser una -cadena de texto o un objeto URL. - -`string` | `URL` - -### config {#config} - -`ServerMetadataConfig` - -El objeto de configuración que contiene el tipo de servidor y una función opcional de transformación. - -## Devuelve {#returns} - -`Promise`\<[`AuthServerConfig`](/references/js/type-aliases/AuthServerConfig.md)\> - -Una promesa que se resuelve con la configuración del servidor. - -## Lanza {#throws} - -si la operación de obtención falla. - -## Lanza {#throws} - -si los metadatos del servidor son inválidos o no coinciden con la -especificación MCP. \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/handleBearerAuth.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/handleBearerAuth.md deleted file mode 100644 index 66c065d..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/handleBearerAuth.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -sidebar_label: handleBearerAuth ---- - -# Función: handleBearerAuth() - -```ts -function handleBearerAuth(param0: BearerAuthConfig): RequestHandler; -``` - -Crea una función middleware para manejar la autenticación Bearer en una aplicación Express. - -Este middleware extrae el token Bearer del encabezado `Authorization`, lo verifica usando la función -`verifyAccessToken` proporcionada y comprueba el emisor (Issuer), la audiencia (Audience) y los alcances (Scopes) requeridos. - -- Si el token es válido, añade la información de autenticación al campo `request.auth`; -si no, responde con un mensaje de error apropiado. -- Si la verificación del token de acceso (Access token) falla, responde con un error 401 No autorizado. -- Si el token no tiene los alcances (Scopes) requeridos, responde con un error 403 Prohibido. -- Si ocurren errores inesperados durante el proceso de autenticación (Authentication), el middleware los volverá a lanzar. - -**Nota:** El objeto `request.auth` contendrá campos extendidos en comparación con la interfaz estándar -AuthInfo definida en el módulo `@modelcontextprotocol/sdk`. Consulta la interfaz extendida en este archivo para más detalles. - -## Parámetros {#parameters} - -### param0 {#param0} - -[`BearerAuthConfig`](/references/js/type-aliases/BearerAuthConfig.md) - -Configuración para el manejador de autenticación Bearer. - -## Devuelve {#returns} - -`RequestHandler` - -Una función middleware para Express que maneja la autenticación Bearer. - -## Consulta también {#see} - -[BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) para las opciones de configuración. \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfig.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfig.md deleted file mode 100644 index cbcbe35..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfig.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -sidebar_label: AuthServerConfig ---- - -# Alias de tipo: AuthServerConfig - -```ts -type AuthServerConfig = { - metadata: CamelCaseAuthorizationServerMetadata; - type: AuthServerType; -}; -``` - -Configuración para el servidor de autorización remoto integrado con el servidor MCP. - -## Propiedades {#properties} - -### metadata {#metadata} - -```ts -metadata: CamelCaseAuthorizationServerMetadata; -``` - -Los metadatos del servidor de autorización (Authorization Server), que deben cumplir con la especificación MCP -(basada en los metadatos del servidor de autorización OAuth 2.0). - -Estos metadatos normalmente se obtienen del endpoint well-known del servidor (metadatos del servidor de autorización OAuth 2.0 o descubrimiento OpenID Connect); también pueden proporcionarse directamente en la configuración si el servidor no admite dichos endpoints. - -**Nota:** Los metadatos deben estar en formato camelCase según lo preferido por la librería mcp-auth. - -#### Ver {#see} - - - [Metadatos del servidor de autorización OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8414) - - [Descubrimiento OpenID Connect](https://openid.net/specs/openid-connect-discovery-1_0.html) - -*** - -### type {#type} - -```ts -type: AuthServerType; -``` - -El tipo de servidor de autorización (Authorization Server). - -#### Ver {#see} - -[AuthServerType](/references/js/type-aliases/AuthServerType.md) para los valores posibles. \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigError.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigError.md deleted file mode 100644 index eb9b91f..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigError.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -sidebar_label: AuthServerConfigError ---- - -# Alias de tipo: AuthServerConfigError - -```ts -type AuthServerConfigError = { - cause?: Error; - code: AuthServerConfigErrorCode; - description: string; -}; -``` - -Representa un error que ocurre durante la validación de los metadatos del servidor de autorización (authorization server). - -## Propiedades {#properties} - -### cause? {#cause} - -```ts -optional cause: Error; -``` - -Una causa opcional del error, típicamente una instancia de `Error` que proporciona más contexto. - -*** - -### code {#code} - -```ts -code: AuthServerConfigErrorCode; -``` - -El código que representa el error de validación específico. - -*** - -### description {#description} - -```ts -description: string; -``` - -Una descripción legible para humanos del error. \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigErrorCode.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigErrorCode.md deleted file mode 100644 index 8ff6e61..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigErrorCode.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_label: AuthServerConfigErrorCode ---- - -# Alias de tipo: AuthServerConfigErrorCode - -```ts -type AuthServerConfigErrorCode = - | "invalid_server_metadata" - | "code_response_type_not_supported" - | "authorization_code_grant_not_supported" - | "pkce_not_supported" - | "s256_code_challenge_method_not_supported"; -``` - -Los códigos para los errores que pueden ocurrir al validar los metadatos del servidor de autorización. \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarning.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarning.md deleted file mode 100644 index b2f60ad..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarning.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -sidebar_label: AuthServerConfigWarning ---- - -# Alias de tipo: AuthServerConfigWarning - -```ts -type AuthServerConfigWarning = { - code: AuthServerConfigWarningCode; - description: string; -}; -``` - -Representa una advertencia que ocurre durante la validación de los metadatos del servidor de autorización (authorization server). - -## Propiedades {#properties} - -### code {#code} - -```ts -code: AuthServerConfigWarningCode; -``` - -El código que representa la advertencia de validación específica. - -*** - -### description {#description} - -```ts -description: string; -``` - -Una descripción legible para humanos de la advertencia. \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarningCode.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarningCode.md deleted file mode 100644 index 80cc2b4..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarningCode.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -sidebar_label: AuthServerConfigWarningCode ---- - -# Alias de tipo: AuthServerConfigWarningCode - -```ts -type AuthServerConfigWarningCode = "dynamic_registration_not_supported"; -``` - -Los códigos para advertencias que pueden ocurrir al validar los metadatos del servidor de autorización (authorization server). \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerErrorCode.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerErrorCode.md deleted file mode 100644 index 98ed927..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerErrorCode.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_label: AuthServerErrorCode ---- - -# Alias de tipo: AuthServerErrorCode - -```ts -type AuthServerErrorCode = - | "invalid_server_metadata" - | "invalid_server_config" - | "missing_jwks_uri"; -``` diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerSuccessCode.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerSuccessCode.md deleted file mode 100644 index 4a6ba45..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerSuccessCode.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -sidebar_label: AuthServerSuccessCode ---- - -# Alias de tipo: AuthServerSuccessCode - -```ts -type AuthServerSuccessCode = - | "server_metadata_valid" - | "dynamic_registration_supported" - | "pkce_supported" - | "s256_code_challenge_method_supported" - | "authorization_code_grant_supported" - | "code_response_type_supported"; -``` - -Los códigos para la validación exitosa de los metadatos del servidor de autorización. \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerType.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerType.md deleted file mode 100644 index 9b36c07..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerType.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -sidebar_label: AuthServerType ---- - -# Alias de tipo: AuthServerType - -```ts -type AuthServerType = "oauth" | "oidc"; -``` - -El tipo del servidor de autorización (authorization server). Esta información debe ser proporcionada por la configuración del servidor y señala si el servidor es un servidor de autorización OAuth 2.0 o OpenID Connect (OIDC). \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthorizationServerMetadata.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthorizationServerMetadata.md deleted file mode 100644 index 02bfe50..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthorizationServerMetadata.md +++ /dev/null @@ -1,233 +0,0 @@ ---- -sidebar_label: AuthorizationServerMetadata ---- - -# Alias de tipo: AuthorizationServerMetadata - -```ts -type AuthorizationServerMetadata = { - authorization_endpoint: string; - code_challenge_methods_supported?: string[]; - grant_types_supported?: string[]; - introspection_endpoint?: string; - introspection_endpoint_auth_methods_supported?: string[]; - introspection_endpoint_auth_signing_alg_values_supported?: string[]; - issuer: string; - jwks_uri?: string; - op_policy_uri?: string; - op_tos_uri?: string; - registration_endpoint?: string; - response_modes_supported?: string[]; - response_types_supported: string[]; - revocation_endpoint?: string; - revocation_endpoint_auth_methods_supported?: string[]; - revocation_endpoint_auth_signing_alg_values_supported?: string[]; - scope_supported?: string[]; - service_documentation?: string; - token_endpoint: string; - token_endpoint_auth_methods_supported?: string[]; - token_endpoint_auth_signing_alg_values_supported?: string[]; - ui_locales_supported?: string[]; - userinfo_endpoint?: string; -}; -``` - -Esquema para los metadatos del servidor de autorización OAuth 2.0 según lo definido en RFC 8414. - -## Declaración de tipo {#type-declaration} - -### authorization\_endpoint {#authorization-endpoint} - -```ts -authorization_endpoint: string; -``` - -URL del endpoint de autorización del servidor de autorización [[RFC6749](https://rfc-editor.org/rfc/rfc6749)]. -Esto es OBLIGATORIO a menos que no se admitan tipos de concesión que utilicen el endpoint de autorización. - -#### Ver {#see} - -https://rfc-editor.org/rfc/rfc6749#section-3.1 - -### code\_challenge\_methods\_supported? {#code-challenge-methods-supported} - -```ts -optional code_challenge_methods_supported: string[]; -``` - -Arreglo JSON que contiene una lista de métodos de desafío de código Proof Key for Code Exchange (PKCE) -[[RFC7636](https://www.rfc-editor.org/rfc/rfc7636)] admitidos por este servidor de autorización. - -### grant\_types\_supported? {#grant-types-supported} - -```ts -optional grant_types_supported: string[]; -``` - -Arreglo JSON que contiene una lista de los valores de tipo de concesión OAuth 2.0 que este servidor de autorización -admite. Los valores del arreglo son los mismos que se usan con el parámetro `grant_types` -definido por el "Protocolo de Registro Dinámico de Clientes OAuth 2.0" [[RFC7591](https://www.rfc-editor.org/rfc/rfc7591)]. -Si se omite, el valor predeterminado es `["authorization_code", "implicit"]`. - -### introspection\_endpoint? {#introspection-endpoint} - -```ts -optional introspection_endpoint: string; -``` - -URL del endpoint de introspección OAuth 2.0 del servidor de autorización -[[RFC7662](https://www.rfc-editor.org/rfc/rfc7662)]. - -### introspection\_endpoint\_auth\_methods\_supported? {#introspection-endpoint-auth-methods-supported} - -```ts -optional introspection_endpoint_auth_methods_supported: string[]; -``` - -### introspection\_endpoint\_auth\_signing\_alg\_values\_supported? {#introspection-endpoint-auth-signing-alg-values-supported} - -```ts -optional introspection_endpoint_auth_signing_alg_values_supported: string[]; -``` - -### issuer {#issuer} - -```ts -issuer: string; -``` - -El identificador del emisor (Issuer) del servidor de autorización, que es una URL que utiliza el esquema `https` y -no tiene componentes de consulta ni fragmentos. - -### jwks\_uri? {#jwks-uri} - -```ts -optional jwks_uri: string; -``` - -URL del documento JWK Set [[JWK](https://www.rfc-editor.org/rfc/rfc8414.html#ref-JWK)] -del servidor de autorización. El documento referenciado contiene la(s) clave(s) de firma que el cliente utiliza para validar -firmas del servidor de autorización. Esta URL DEBE utilizar el esquema `https`. - -### op\_policy\_uri? {#op-policy-uri} - -```ts -optional op_policy_uri: string; -``` - -### op\_tos\_uri? {#op-tos-uri} - -```ts -optional op_tos_uri: string; -``` - -### registration\_endpoint? {#registration-endpoint} - -```ts -optional registration_endpoint: string; -``` - -URL del endpoint de registro dinámico de clientes OAuth 2.0 del servidor de autorización -[[RFC7591](https://www.rfc-editor.org/rfc/rfc7591)]. - -### response\_modes\_supported? {#response-modes-supported} - -```ts -optional response_modes_supported: string[]; -``` - -Arreglo JSON que contiene una lista de los valores `response_mode` de OAuth 2.0 que este -servidor de autorización admite, según lo especificado en "Prácticas de codificación de tipo de respuesta múltiple de OAuth 2.0" -[[OAuth.Responses](https://datatracker.ietf.org/doc/html/rfc8414#ref-OAuth.Responses)]. - -Si se omite, el valor predeterminado es `["query", "fragment"]`. El valor de modo de respuesta `"form_post"` también está -definido en "OAuth 2.0 Form Post Response Mode" -[[OAuth.FormPost](https://datatracker.ietf.org/doc/html/rfc8414#ref-OAuth.Post)]. - -### response\_types\_supported {#response-types-supported} - -```ts -response_types_supported: string[]; -``` - -Arreglo JSON que contiene una lista de los valores `response_type` de OAuth 2.0 que este servidor de autorización -admite. Los valores del arreglo son los mismos que se usan con el parámetro `response_types` -definido por el "Protocolo de Registro Dinámico de Clientes OAuth 2.0" -[[RFC7591](https://www.rfc-editor.org/rfc/rfc7591)]. - -### revocation\_endpoint? {#revocation-endpoint} - -```ts -optional revocation_endpoint: string; -``` - -URL del endpoint de revocación OAuth 2.0 del servidor de autorización -[[RFC7009](https://www.rfc-editor.org/rfc/rfc7009)]. - -### revocation\_endpoint\_auth\_methods\_supported? {#revocation-endpoint-auth-methods-supported} - -```ts -optional revocation_endpoint_auth_methods_supported: string[]; -``` - -### revocation\_endpoint\_auth\_signing\_alg\_values\_supported? {#revocation-endpoint-auth-signing-alg-values-supported} - -```ts -optional revocation_endpoint_auth_signing_alg_values_supported: string[]; -``` - -### scope\_supported? {#scope-supported} - -```ts -optional scope_supported: string[]; -``` - -### service\_documentation? {#service-documentation} - -```ts -optional service_documentation: string; -``` - -### token\_endpoint {#token-endpoint} - -```ts -token_endpoint: string; -``` - -URL del endpoint de token del servidor de autorización [[RFC6749](https://rfc-editor.org/rfc/rfc6749)]. -Esto es OBLIGATORIO a menos que solo se admita el tipo de concesión implícita. - -#### Ver {#see} - -https://rfc-editor.org/rfc/rfc6749#section-3.2 - -### token\_endpoint\_auth\_methods\_supported? {#token-endpoint-auth-methods-supported} - -```ts -optional token_endpoint_auth_methods_supported: string[]; -``` - -### token\_endpoint\_auth\_signing\_alg\_values\_supported? {#token-endpoint-auth-signing-alg-values-supported} - -```ts -optional token_endpoint_auth_signing_alg_values_supported: string[]; -``` - -### ui\_locales\_supported? {#ui-locales-supported} - -```ts -optional ui_locales_supported: string[]; -``` - -### userinfo\_endpoint? {#userinfo-endpoint} - -```ts -optional userinfo_endpoint: string; -``` - -URL del [endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) de OpenID Connect. -Este endpoint se utiliza para recuperar información sobre el usuario autenticado. - -## Ver {#see} - -https://datatracker.ietf.org/doc/html/rfc8414 \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthConfig.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthConfig.md deleted file mode 100644 index b2320f6..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthConfig.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -sidebar_label: BearerAuthConfig ---- - -# Alias de tipo: BearerAuthConfig - -```ts -type BearerAuthConfig = { - audience?: string; - issuer: string; - requiredScopes?: string[]; - showErrorDetails?: boolean; - verifyAccessToken: VerifyAccessTokenFunction; -}; -``` - -## Propiedades {#properties} - -### audience? {#audience} - -```ts -optional audience: string; -``` - -La audiencia esperada del token de acceso (reclamo `aud`). Normalmente, este es el servidor de recursos -(API) para el que está destinado el token. Si no se proporciona, se omitirá la verificación de la audiencia. - -**Nota:** Si tu servidor de autorización no admite Indicadores de recurso (RFC 8707), -puedes omitir este campo ya que la audiencia puede no ser relevante. - -#### Ver {#see} - -https://datatracker.ietf.org/doc/html/rfc8707 - -*** - -### issuer {#issuer} - -```ts -issuer: string; -``` - -El emisor esperado del token de acceso (reclamo `iss`). Debe ser la URL del -servidor de autorización que emitió el token. - -*** - -### requiredScopes? {#requiredscopes} - -```ts -optional requiredScopes: string[]; -``` - -Un arreglo de alcances requeridos que el token de acceso debe tener. Si el token no contiene -todos estos alcances, se lanzará un error. - -**Nota:** El manejador verificará el reclamo `scope` en el token, que puede ser una cadena separada por espacios -o un arreglo de cadenas, dependiendo de la implementación del servidor de autorización. Si el reclamo `scope` no está presente, el manejador verificará el reclamo `scopes` -si está disponible. - -*** - -### showErrorDetails? {#showerrordetails} - -```ts -optional showErrorDetails: boolean; -``` - -Indica si se debe mostrar información detallada de errores en la respuesta. Esto es útil para depuración -durante el desarrollo, pero debe deshabilitarse en producción para evitar la filtración de información sensible. - -#### Valor predeterminado {#default} - -```ts -false -``` - -*** - -### verifyAccessToken {#verifyaccesstoken} - -```ts -verifyAccessToken: VerifyAccessTokenFunction; -``` - -Tipo de función para verificar un token de acceso. - -Esta función debe lanzar un [MCPAuthTokenVerificationError](/references/js/classes/MCPAuthTokenVerificationError.md) si el token es inválido, -o devolver un objeto AuthInfo si el token es válido. - -#### Ver {#see} - -[VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) para más detalles. \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthErrorCode.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthErrorCode.md deleted file mode 100644 index f752c9f..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthErrorCode.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_label: BearerAuthErrorCode ---- - -# Alias de tipo: BearerAuthErrorCode - -```ts -type BearerAuthErrorCode = - | "missing_auth_header" - | "invalid_auth_header_format" - | "missing_bearer_token" - | "invalid_issuer" - | "invalid_audience" - | "missing_required_scopes" - | "invalid_token"; -``` diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthJwtConfig.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthJwtConfig.md deleted file mode 100644 index d448579..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthJwtConfig.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -sidebar_label: BearerAuthJwtConfig ---- - -# Alias de tipo: BearerAuthJwtConfig - -```ts -type BearerAuthJwtConfig = { - jwtVerify?: JWTVerifyOptions; - remoteJwkSet?: RemoteJWKSetOptions; -}; -``` - -Configuración para el manejador de autenticación Bearer al usar la verificación JWT. - -## Propiedades {#properties} - -### jwtVerify? {#jwtverify} - -```ts -optional jwtVerify: JWTVerifyOptions; -``` - -Opciones para pasar a la función `jwtVerify` de la librería `jose`. - -#### Ver {#see} - -JWTVerifyOptions para la definición de tipo de las opciones. - -*** - -### remoteJwkSet? {#remotejwkset} - -```ts -optional remoteJwkSet: RemoteJWKSetOptions; -``` - -Opciones para pasar a la función `createRemoteJWKSet` de la librería `jose`. - -#### Ver {#see} - -RemoteJWKSetOptions para la definición de tipo de las opciones. \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md deleted file mode 100644 index e5485b5..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -sidebar_label: CamelCaseAuthorizationServerMetadata ---- - -# Alias de tipo: CamelCaseAuthorizationServerMetadata - -```ts -type CamelCaseAuthorizationServerMetadata = { - authorizationEndpoint: string; - codeChallengeMethodsSupported?: string[]; - grantTypesSupported?: string[]; - introspectionEndpoint?: string; - introspectionEndpointAuthMethodsSupported?: string[]; - introspectionEndpointAuthSigningAlgValuesSupported?: string[]; - issuer: string; - jwksUri?: string; - opPolicyUri?: string; - opTosUri?: string; - registrationEndpoint?: string; - responseModesSupported?: string[]; - responseTypesSupported: string[]; - revocationEndpoint?: string; - revocationEndpointAuthMethodsSupported?: string[]; - revocationEndpointAuthSigningAlgValuesSupported?: string[]; - scopeSupported?: string[]; - serviceDocumentation?: string; - tokenEndpoint: string; - tokenEndpointAuthMethodsSupported?: string[]; - tokenEndpointAuthSigningAlgValuesSupported?: string[]; - uiLocalesSupported?: string[]; - userinfoEndpoint?: string; -}; -``` - -La versión en camelCase del tipo de metadatos del servidor de autorización OAuth 2.0. - -## Declaración de tipo {#type-declaration} - -### authorizationEndpoint {#authorizationendpoint} - -```ts -authorizationEndpoint: string; -``` - -### codeChallengeMethodsSupported? {#codechallengemethodssupported} - -```ts -optional codeChallengeMethodsSupported: string[]; -``` - -### grantTypesSupported? {#granttypessupported} - -```ts -optional grantTypesSupported: string[]; -``` - -### introspectionEndpoint? {#introspectionendpoint} - -```ts -optional introspectionEndpoint: string; -``` - -### introspectionEndpointAuthMethodsSupported? {#introspectionendpointauthmethodssupported} - -```ts -optional introspectionEndpointAuthMethodsSupported: string[]; -``` - -### introspectionEndpointAuthSigningAlgValuesSupported? {#introspectionendpointauthsigningalgvaluessupported} - -```ts -optional introspectionEndpointAuthSigningAlgValuesSupported: string[]; -``` - -### issuer {#issuer} - -```ts -issuer: string; -``` - -### jwksUri? {#jwksuri} - -```ts -optional jwksUri: string; -``` - -### opPolicyUri? {#oppolicyuri} - -```ts -optional opPolicyUri: string; -``` - -### opTosUri? {#optosuri} - -```ts -optional opTosUri: string; -``` - -### registrationEndpoint? {#registrationendpoint} - -```ts -optional registrationEndpoint: string; -``` - -### responseModesSupported? {#responsemodessupported} - -```ts -optional responseModesSupported: string[]; -``` - -### responseTypesSupported {#responsetypessupported} - -```ts -responseTypesSupported: string[]; -``` - -### revocationEndpoint? {#revocationendpoint} - -```ts -optional revocationEndpoint: string; -``` - -### revocationEndpointAuthMethodsSupported? {#revocationendpointauthmethodssupported} - -```ts -optional revocationEndpointAuthMethodsSupported: string[]; -``` - -### revocationEndpointAuthSigningAlgValuesSupported? {#revocationendpointauthsigningalgvaluessupported} - -```ts -optional revocationEndpointAuthSigningAlgValuesSupported: string[]; -``` - -### scopeSupported? {#scopesupported} - -```ts -optional scopeSupported: string[]; -``` - -### serviceDocumentation? {#servicedocumentation} - -```ts -optional serviceDocumentation: string; -``` - -### tokenEndpoint {#tokenendpoint} - -```ts -tokenEndpoint: string; -``` - -### tokenEndpointAuthMethodsSupported? {#tokenendpointauthmethodssupported} - -```ts -optional tokenEndpointAuthMethodsSupported: string[]; -``` - -### tokenEndpointAuthSigningAlgValuesSupported? {#tokenendpointauthsigningalgvaluessupported} - -```ts -optional tokenEndpointAuthSigningAlgValuesSupported: string[]; -``` - -### uiLocalesSupported? {#uilocalessupported} - -```ts -optional uiLocalesSupported: string[]; -``` - -### userinfoEndpoint? {#userinfoendpoint} - -```ts -optional userinfoEndpoint: string; -``` - -## Ver también {#see} - -[AuthorizationServerMetadata](/references/js/type-aliases/AuthorizationServerMetadata.md) para el tipo original e información de los campos. \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md deleted file mode 100644 index c215b31..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -sidebar_label: MCPAuthBearerAuthErrorDetails ---- - -# Alias de tipo: MCPAuthBearerAuthErrorDetails - -```ts -type MCPAuthBearerAuthErrorDetails = { - actual?: unknown; - cause?: unknown; - expected?: unknown; - missingScopes?: string[]; - uri?: URL; -}; -``` - -## Propiedades {#properties} - -### actual? {#actual} - -```ts -optional actual: unknown; -``` - -*** - -### cause? {#cause} - -```ts -optional cause: unknown; -``` - -*** - -### expected? {#expected} - -```ts -optional expected: unknown; -``` - -*** - -### missingScopes? {#missingscopes} - -```ts -optional missingScopes: string[]; -``` - -*** - -### uri? {#uri} - -```ts -optional uri: URL; -``` diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthConfig.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthConfig.md deleted file mode 100644 index 977b416..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthConfig.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -sidebar_label: MCPAuthConfig ---- - -# Alias de tipo: MCPAuthConfig - -```ts -type MCPAuthConfig = { - server: AuthServerConfig; -}; -``` - -Configuración para la clase [MCPAuth](/references/js/classes/MCPAuth.md). - -## Propiedades {#properties} - -### server {#server} - -```ts -server: AuthServerConfig; -``` - -Configuración para el servidor de autorización remoto. \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md deleted file mode 100644 index 3d44fff..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: MCPAuthTokenVerificationErrorCode ---- - -# Alias de tipo: MCPAuthTokenVerificationErrorCode - -```ts -type MCPAuthTokenVerificationErrorCode = "invalid_token" | "token_verification_failed"; -``` diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenFunction.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenFunction.md deleted file mode 100644 index a2d7194..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenFunction.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -sidebar_label: VerifyAccessTokenFunction ---- - -# Alias de tipo: VerifyAccessTokenFunction() - -```ts -type VerifyAccessTokenFunction = (token: string) => MaybePromise; -``` - -Tipo de función para verificar un token de acceso (Access token). - -Esta función debe lanzar un [MCPAuthTokenVerificationError](/references/js/classes/MCPAuthTokenVerificationError.md) si el token es inválido, -o devolver un objeto AuthInfo si el token es válido. - -Por ejemplo, si tienes una función de verificación de JWT, al menos debe comprobar la -firma del token, validar su expiración y extraer los reclamos (Claims) necesarios para devolver un objeto `AuthInfo`. - -**Nota:** No es necesario verificar los siguientes campos en el token, ya que serán comprobados -por el manejador: - -- `iss` (emisor / issuer) -- `aud` (audiencia / audience) -- `scope` (alcances / scopes) - -## Parámetros {#parameters} - -### token {#token} - -`string` - -La cadena del token de acceso (Access token) a verificar. - -## Retorna {#returns} - -`MaybePromise`\<`AuthInfo`\> - -Una promesa que se resuelve en un objeto AuthInfo o un valor sincrónico si el -token es válido. \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenMode.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenMode.md deleted file mode 100644 index a23291d..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenMode.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: VerifyAccessTokenMode ---- - -# Alias de tipo: VerifyAccessTokenMode - -```ts -type VerifyAccessTokenMode = "jwt"; -``` diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authServerErrorDescription.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authServerErrorDescription.md deleted file mode 100644 index b4726e8..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authServerErrorDescription.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: authServerErrorDescription ---- - -# Variable: authServerErrorDescription - -```ts -const authServerErrorDescription: Readonly>; -``` diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authorizationServerMetadataSchema.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authorizationServerMetadataSchema.md deleted file mode 100644 index 6eba06b..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authorizationServerMetadataSchema.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: authorizationServerMetadataSchema ---- - -# Variable: authorizationServerMetadataSchema - -```ts -const authorizationServerMetadataSchema: ZodObject; -``` - -Esquema Zod para los metadatos del servidor de autorización OAuth 2.0 según lo definido en RFC 8414. - -## Ver {#see} - -https://datatracker.ietf.org/doc/html/rfc8414 \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/bearerAuthErrorDescription.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/bearerAuthErrorDescription.md deleted file mode 100644 index ed1a931..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/bearerAuthErrorDescription.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: bearerAuthErrorDescription ---- - -# Variable: bearerAuthErrorDescription - -```ts -const bearerAuthErrorDescription: Readonly>; -``` diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md deleted file mode 100644 index 8b4ab4c..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: camelCaseAuthorizationServerMetadataSchema ---- - -# Variable: camelCaseAuthorizationServerMetadataSchema - -```ts -const camelCaseAuthorizationServerMetadataSchema: ZodObject; -``` - -La versión en camelCase del esquema Zod de metadatos del servidor de autorización OAuth 2.0. - -## Ver {#see} - -Consulta [authorizationServerMetadataSchema](/references/js/variables/authorizationServerMetadataSchema.md) para el esquema original y la información de los campos. \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/serverMetadataPaths.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/serverMetadataPaths.md deleted file mode 100644 index 68cbf41..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/serverMetadataPaths.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_label: serverMetadataPaths ---- - -# Variable: serverMetadataPaths - -```ts -const serverMetadataPaths: Readonly<{ - oauth: "/.well-known/oauth-authorization-server"; - oidc: "/.well-known/openid-configuration"; -}>; -``` diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/tokenVerificationErrorDescription.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/tokenVerificationErrorDescription.md deleted file mode 100644 index b0004b3..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/tokenVerificationErrorDescription.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: tokenVerificationErrorDescription ---- - -# Variable: tokenVerificationErrorDescription - -```ts -const tokenVerificationErrorDescription: Readonly>; -``` \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/validateServerConfig.md b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/validateServerConfig.md deleted file mode 100644 index e60de41..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/validateServerConfig.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: validateServerConfig ---- - -# Variable: validateServerConfig - -```ts -const validateServerConfig: ValidateServerConfig; -``` diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/snippets/_get-started-code.mdx b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/snippets/_get-started-code.mdx deleted file mode 100644 index 09675f0..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/snippets/_get-started-code.mdx +++ /dev/null @@ -1,41 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - - - - - -```python -mcp = FastMCP("MyMCPServer") -mcp_auth = MCPAuth(server=fetch_server_config('', type=AuthServerType.OIDC)) -app = Starlette( - # ... tu configuración del servidor MCP - middleware=[Middleware( - mcp_auth.bearer_auth_middleware("jwt", required_scopes=["read", "write"]) - )] -) - -# Usa `mcp_auth.auth_info` para acceder a la información de autenticación para la solicitud actual -@mcp.tool() -def whoami() -> dict[str, Any]: - return mcp_auth.auth_info.claims -``` - - - - -```ts -const server = new McpServer(/* ... */); -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { type: 'oidc' }), -}); -const app = express(); - -app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] })); -server.tool('whoami', ({ authInfo }) => { - // Usa `authInfo` para acceder a la información de autenticación proveniente de `req.auth` -}); -``` - - - \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/README.mdx b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/README.mdx deleted file mode 100644 index 40d806d..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/README.mdx +++ /dev/null @@ -1,1149 +0,0 @@ ---- -sidebar_position: 2 -sidebar_label: 'Tutorial: Crea un gestor de tareas' ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import SetupOauthOrOidc from './_setup-oauth-or-oidc.mdx'; -import SetupOidc from './_setup-oidc.mdx'; - -# Tutorial: Crea un gestor de tareas - -En este tutorial, construiremos un servidor MCP gestor de tareas con autenticación y autorización de usuarios. - -Después de completar este tutorial, tendrás: - -- ✅ Una comprensión básica de cómo configurar el control de acceso basado en roles (RBAC) en tu servidor MCP. -- ✅ Un servidor MCP que puede gestionar listas de tareas personales. - -:::note -Antes de comenzar, te recomendamos encarecidamente que revises primero el [tutorial ¿Quién soy?](./whoami) si no estás familiarizado con el servidor MCP y OAuth 2. -::: - -## Descripción general \{#overview} - -El tutorial involucrará los siguientes componentes: - -- **Servidor MCP**: Un servidor MCP sencillo que utiliza los SDK oficiales de MCP para manejar solicitudes, con un servicio integrado de tareas para gestionar los elementos de tareas del usuario. -- **Inspector MCP**: Una herramienta visual de pruebas para servidores MCP. También actúa como un cliente OAuth / OIDC para iniciar el flujo de autorización y obtener tokens de acceso. -- **Servidor de autorización**: Un proveedor OAuth 2.1 u OpenID Connect que gestiona identidades de usuario y emite tokens de acceso. - -Aquí tienes un diagrama de alto nivel de la interacción entre estos componentes: - -```mermaid -sequenceDiagram - participant Cliente as Inspector MCP - participant Servidor as Servidor MCP - participant Auth as Servidor de autorización - - Cliente->>Servidor: Solicitar operación de tareas - Servidor->>Cliente: Retornar 401 No autorizado - Cliente->>Auth: Iniciar flujo de autorización - Auth->>Auth: Completar flujo de autorización - Auth->>Cliente: Redirigir de vuelta con código de autorización - Cliente->>Auth: Intercambiar código por token de acceso - Auth->>Cliente: Retornar token de acceso - Cliente->>Servidor: Solicitar operación de tareas con token de acceso - Servidor->>Servidor: Validar token de acceso y obtener alcances del token de acceso - Note over Servidor: Ejecutar operación de tareas - Servidor->>Cliente: Retornar resultado de la operación de tareas -``` - -## Comprende tu servidor de autorización \{#understand-your-authorization-server} - -### Tokens de acceso con alcances \{#access-tokens-with-scopes} - -Para implementar el [control de acceso basado en roles (RBAC)](https://auth.wiki/rbac) en tu servidor MCP, tu servidor de autorización debe admitir la emisión de tokens de acceso con alcances. Los alcances representan los permisos que se le han otorgado a un usuario. - - - - -[Logto](https://logto.io) proporciona soporte para RBAC a través de sus recursos de API (conforme a [RFC 8707: Indicadores de recurso para OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)) y funciones de roles. Así es como se configura: - -1. Inicia sesión en [Logto Console](https://cloud.logto.io) (o en tu Logto Console autoalojado) - -2. Crea recurso de API y alcances: - - - Ve a "Recursos de API" - - Crea un nuevo recurso de API llamado "Gestor de tareas" - - Añade los siguientes alcances: - - `create:todos`: "Crear nuevas tareas" - - `read:todos`: "Leer todas las tareas" - - `delete:todos`: "Eliminar cualquier tarea" - -3. Crea roles (recomendado para una gestión más sencilla): - - - Ve a "Roles" - - Crea un rol "Admin" y asigna todos los alcances (`create:todos`, `read:todos`, `delete:todos`) - - Crea un rol "User" y asigna solo el alcance `create:todos` - -4. Asigna permisos: - - Ve a "Usuarios" - - Selecciona un usuario - - Puedes: - - Asignar roles en la pestaña "Roles" (recomendado) - - O asignar alcances directamente en la pestaña "Permisos" - -Los alcances se incluirán en el reclamo `scope` del token de acceso JWT como una cadena separada por espacios. - - - - -Los proveedores OAuth 2.0 / OIDC suelen admitir el control de acceso basado en alcances. Al implementar RBAC: - -1. Define los alcances requeridos en tu servidor de autorización -2. Configura tu cliente para solicitar estos alcances durante el flujo de autorización -3. Asegúrate de que tu servidor de autorización incluya los alcances otorgados en el token de acceso -4. Los alcances suelen incluirse en el reclamo `scope` del token de acceso JWT - -Consulta la documentación de tu proveedor para detalles específicos sobre: - -- Cómo definir y gestionar alcances -- Cómo se incluyen los alcances en el token de acceso -- Cualquier característica adicional de RBAC como la gestión de roles - - - - -### Validación de tokens y comprobación de permisos \{#validating-tokens-and-checking-permissions} - -Cuando tu servidor MCP recibe una solicitud, debe: - -1. Validar la firma y expiración del token de acceso -2. Extraer los alcances del token validado -3. Comprobar si el token tiene los alcances requeridos para la operación solicitada - -Por ejemplo, si un usuario quiere crear una nueva tarea, su token de acceso debe incluir el alcance `create:todos`. Así funciona el flujo: - -```mermaid -sequenceDiagram - participant Cliente - participant Servidor MCP - participant Servidor Auth - - Cliente->>Servidor MCP: Solicitud con token de acceso - - alt Validación JWT - Servidor MCP->>Servidor Auth: Obtener JWKS - Servidor Auth-->>Servidor MCP: Retornar JWKS - Servidor MCP->>Servidor MCP: Validar JWT localmente - else Introspección de token - Servidor MCP->>Servidor Auth: POST /introspect
(token=access_token) - Servidor Auth-->>Servidor MCP: Retornar información del token
(activo, alcance, etc.) - end - - Servidor MCP->>Servidor MCP: Extraer y comprobar alcances - - alt Tiene los alcances requeridos - Servidor MCP->>Cliente: Permitir operación - else Faltan alcances - Servidor MCP->>Cliente: Retornar 403 Prohibido - end -``` - -### Registro dinámico de clientes \{#dynamic-client-registration} - -El registro dinámico de clientes no es necesario para este tutorial, pero puede ser útil si deseas automatizar el proceso de registro del cliente MCP con tu servidor de autorización. Consulta [¿Es necesario el registro dinámico de clientes?](/provider-list#is-dcr-required) para más detalles. - -## Comprende RBAC en el gestor de tareas \{#understand-rbac-in-todo-manager} - -Con fines demostrativos, implementaremos un sistema sencillo de control de acceso basado en roles (RBAC) en nuestro servidor MCP gestor de tareas. Esto te mostrará los principios básicos de RBAC manteniendo la implementación simple. - -:::note -Aunque este tutorial demuestra la gestión de alcances basada en RBAC, es importante señalar que no todos los proveedores de autenticación implementan la gestión de alcances a través de roles. Algunos proveedores pueden tener sus propias implementaciones y mecanismos únicos para gestionar el control de acceso y los permisos. -::: - -### Herramientas y alcances \{#tools-and-scopes} - -Nuestro servidor MCP gestor de tareas proporciona tres herramientas principales: - -- `create-todo`: Crear una nueva tarea -- `get-todos`: Listar todas las tareas -- `delete-todo`: Eliminar una tarea por ID - -Para controlar el acceso a estas herramientas, definimos los siguientes alcances: - -- `create:todos`: Permite crear nuevas tareas -- `delete:todos`: Permite eliminar tareas existentes -- `read:todos`: Permite consultar y recuperar la lista de todas las tareas - -### Roles y permisos \{#roles-and-permissions} - -Definiremos dos roles con diferentes niveles de acceso: - -| Rol | create:todos | read:todos | delete:todos | -| ----- | ------------ | ---------- | ------------ | -| Admin | ✅ | ✅ | ✅ | -| User | ✅ | | | - -- **User**: Un usuario regular que puede crear tareas y ver o eliminar solo sus propias tareas -- **Admin**: Un administrador que puede crear, ver y eliminar todas las tareas, sin importar la propiedad - -### Propiedad de recursos \{#resource-ownership} - -Aunque la tabla de permisos anterior muestra los alcances explícitos asignados a cada rol, hay un principio importante de propiedad de recursos a considerar: - -- **Los usuarios** no tienen los alcances `read:todos` o `delete:todos`, pero aún pueden: - - Leer sus propias tareas - - Eliminar sus propias tareas -- **Los administradores** tienen todos los permisos (`read:todos` y `delete:todos`), lo que les permite: - - Ver todas las tareas del sistema - - Eliminar cualquier tarea, sin importar la propiedad - -Esto demuestra un patrón común en los sistemas RBAC donde la propiedad de recursos otorga permisos implícitos a los usuarios para sus propios recursos, mientras que los roles administrativos reciben permisos explícitos para todos los recursos. - -:::tip Aprende más -Para profundizar en los conceptos y mejores prácticas de RBAC, consulta [Dominando RBAC: Un ejemplo completo del mundo real](https://blog.logto.io/mastering-rbac). -::: - -## Configura la autorización en tu proveedor \{#configure-authorization-in-your-provider} - -Para implementar el sistema de control de acceso que describimos antes, deberás configurar tu servidor de autorización para admitir los alcances requeridos. Así es como hacerlo con diferentes proveedores: - - - - -[Logto](https://logto.io) proporciona soporte para RBAC a través de sus recursos de API y funciones de roles. Así es como se configura: - -1. Inicia sesión en [Logto Console](https://cloud.logto.io) (o en tu Logto Console autoalojado) - -2. Crea recurso de API y alcances: - - - Ve a "Recursos de API" - - Crea un nuevo recurso de API llamado "Gestor de tareas" y usa `https://todo.mcp-server.app` (para demostración) como el indicador. - - Crea los siguientes alcances: - - `create:todos`: "Crear nuevas tareas" - - `read:todos`: "Leer todas las tareas" - - `delete:todos`: "Eliminar cualquier tarea" - -3. Crea roles (recomendado para una gestión más sencilla): - - - Ve a "Roles" - - Crea un rol "Admin" y asigna todos los alcances (`create:todos`, `read:todos`, `delete:todos`) - - Crea un rol "User" y asigna solo el alcance `create:todos` - - En la página de detalles del rol "User", cambia a la pestaña "General" y establece el rol "User" como el "Rol predeterminado". - -4. Gestiona roles y permisos de usuario: - - Para nuevos usuarios: - - Obtendrán automáticamente el rol "User" ya que lo establecimos como rol predeterminado - - Para usuarios existentes: - - Ve a "Gestión de usuarios" - - Selecciona un usuario - - Asigna roles al usuario en la pestaña "Roles" - -:::tip Gestión programática de roles -También puedes usar la [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api) de Logto para gestionar roles de usuario de forma programática. Esto es especialmente útil para la gestión automatizada de usuarios o al construir paneles de administración. -::: - -Al solicitar un token de acceso, Logto incluirá los alcances en el reclamo `scope` del token según los permisos de rol del usuario. - - - - -En [Keycloak](https://www.keycloak.org), puedes configurar los permisos requeridos usando client scopes: - -1. Crea client scopes: - - - En tu realm, ve a "Client scopes" - - Crea tres nuevos client scopes: - - `create:todos` - - `read:todos` - - `delete:todos` - -2. Configura el cliente: - - - Ve a la configuración de tu cliente - - En la pestaña "Client scopes", añade todos los scopes que creaste - - Asegúrate de que el token mapper esté configurado para incluir los scopes - -3. Opcional: Usa roles para una gestión más sencilla - - Si prefieres la gestión basada en roles: - - Crea roles de realm para diferentes niveles de acceso - - Mapea scopes a roles - - Asigna roles a los usuarios - - De lo contrario, puedes asignar scopes directamente a los usuarios o a través de permisos a nivel de cliente - -Keycloak incluirá los scopes otorgados en el reclamo `scope` del token de acceso. - - - - -Para proveedores OAuth 2.0 u OpenID Connect, deberás configurar los scopes que representan diferentes permisos. Los pasos exactos dependerán de tu proveedor, pero generalmente: - -1. Define scopes: - - - Configura tu servidor de autorización para admitir: - - `create:todos` - - `read:todos` - - `delete:todos` - -2. Configura el cliente: - - - Registra o actualiza tu cliente para solicitar estos scopes - - Asegúrate de que los scopes estén incluidos en el token de acceso - -3. Asigna permisos: - - Usa la interfaz de tu proveedor para otorgar los scopes apropiados a los usuarios - - Algunos proveedores pueden admitir la gestión basada en roles, mientras que otros pueden usar asignaciones directas de scopes - - Consulta la documentación de tu proveedor para el enfoque recomendado - -:::tip -La mayoría de los proveedores incluirán los scopes otorgados en el reclamo `scope` del token de acceso. El formato suele ser una cadena de valores de scope separados por espacios. -::: - - - - -Después de configurar tu servidor de autorización, los usuarios recibirán tokens de acceso que contienen los scopes otorgados. El servidor MCP usará estos scopes para determinar: - -- Si un usuario puede crear nuevas tareas (`create:todos`) -- Si un usuario puede ver todas las tareas (`read:todos`) o solo las suyas -- Si un usuario puede eliminar cualquier tarea (`delete:todos`) o solo las suyas - -## Configura el servidor MCP \{#set-up-the-mcp-server} - -Usaremos los [SDK oficiales de MCP](https://github.com/modelcontextprotocol) para crear nuestro servidor MCP gestor de tareas. - -### Crea un nuevo proyecto \{#create-a-new-project} - - - - -```bash -mkdir mcp-server -cd mcp-server -uv init # O usa `pipenv` o `poetry` para crear un nuevo entorno virtual -``` - - - - -Configura un nuevo proyecto Node.js: - -```bash -mkdir mcp-server -cd mcp-server -npm init -y # O usa `pnpm init` -npm pkg set type="module" -npm pkg set main="todo-manager.ts" -npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts" -``` - -:::note -Usamos TypeScript en nuestros ejemplos ya que Node.js v22.6.0+ admite la ejecución de TypeScript de forma nativa usando la bandera `--experimental-strip-types`. Si usas JavaScript, el código será similar; solo asegúrate de usar Node.js v22.6.0 o posterior. Consulta la documentación de Node.js para más detalles. -::: - - - - -### Instala el SDK de MCP y dependencias \{#install-the-mcp-sdk-and-dependencies} - - - - -```bash -pip install "mcp[cli]" starlette uvicorn -``` - -O cualquier otro gestor de paquetes que prefieras, como `uv` o `poetry`. - - - - -```bash -npm install @modelcontextprotocol/sdk express zod -``` - -O cualquier otro gestor de paquetes que prefieras, como `pnpm` o `yarn`. - - - - -### Crea el servidor MCP \{#create-the-mcp-server} - -Primero, vamos a crear un servidor MCP básico con las definiciones de herramientas: - - - - -Crea un archivo llamado `todo-manager.py` y añade el siguiente código: - -```python -from typing import Any -from mcp.server.fastmcp import FastMCP -from starlette.applications import Starlette -from starlette.routing import Mount - -mcp = FastMCP("Gestor de tareas") - -@mcp.tool() -def create_todo(content: str) -> dict[str, Any]: - """Crear una nueva tarea.""" - return {"error": "No implementado"} - -@mcp.tool() -def get_todos() -> dict[str, Any]: - """Listar todas las tareas.""" - return {"error": "No implementado"} - -@mcp.tool() -def delete_todo(id: str) -> dict[str, Any]: - """Eliminar una tarea por id.""" - return {"error": "No implementado"} - -app = Starlette( - routes=[Mount('/', app=mcp.sse_app())] -) -``` - -Ejecuta el servidor con: - -```bash -uvicorn todo_manager:app --host 0.0.0.0 --port 3001 -``` - - - - -:::note -Dado que la implementación actual del inspector MCP no maneja flujos de autorización, usaremos el enfoque SSE para configurar el servidor MCP. Actualizaremos el código aquí una vez que el inspector MCP admita flujos de autorización. -::: - -También puedes usar `pnpm` o `yarn` si lo prefieres. - -Crea un archivo llamado `todo-manager.ts` y añade el siguiente código: - -```ts -// todo-manager.ts - -import { z } from 'zod'; -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; -import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'; -import express from 'express'; - -// Crear un servidor MCP -const server = new McpServer({ - name: 'Gestor de tareas', - version: '0.0.0', -}); - -server.tool('create-todo', 'Crear una nueva tarea', { content: z.string() }, async ({ content }) => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'No implementado' }) }], - }; -}); - -server.tool('get-todos', 'Listar todas las tareas', async () => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'No implementado' }) }], - }; -}); - -server.tool('delete-todo', 'Eliminar una tarea por id', { id: z.string() }, async ({ id }) => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'No implementado' }) }], - }; -}); - -// Código boilerplate de la documentación del SDK de MCP -const PORT = 3001; -const app = express(); - -const transports = {}; - -app.get('/sse', async (_req, res) => { - const transport = new SSEServerTransport('/messages', res); - transports[transport.sessionId] = transport; - - res.on('close', () => { - delete transports[transport.sessionId]; - }); - - await server.connect(transport); -}); - -app.post('/messages', async (req, res) => { - const sessionId = String(req.query.sessionId); - const transport = transports[sessionId]; - if (transport) { - await transport.handlePostMessage(req, res, req.body); - } else { - res.status(400).send('No transport found for sessionId'); - } -}); - -app.listen(PORT); -``` - -Ejecuta el servidor con: - -```bash -npm start -``` - - - - -## Inspecciona el servidor MCP \{#inspect-the-mcp-server} - -### Clona y ejecuta el inspector MCP \{#clone-and-run-mcp-inspector} - -Ahora que tenemos el servidor MCP en funcionamiento, podemos usar el inspector MCP para ver si la herramienta `whoami` está disponible. - -Debido a la limitación de la implementación actual, hemos bifurcado el [inspector MCP](https://github.com/mcp-auth/inspector) para hacerlo más flexible y escalable para autenticación y autorización. También hemos enviado un pull request al repositorio original para incluir nuestros cambios. - -Para ejecutar el inspector MCP, puedes usar el siguiente comando (se requiere Node.js): - -```bash -git clone https://github.com/mcp-auth/inspector.git -cd inspector -npm install -npm run dev -``` - -Luego, abre tu navegador y navega a `http://localhost:6274/` (u otra URL mostrada en la terminal) para acceder al inspector MCP. - -### Conecta el inspector MCP al servidor MCP \{#connect-mcp-inspector-to-the-mcp-server} - -Antes de continuar, verifica la siguiente configuración en el inspector MCP: - -- **Tipo de transporte**: Establece en `SSE`. -- **URL**: Establece la URL de tu servidor MCP. En nuestro caso, debe ser `http://localhost:3001/sse`. - -Ahora puedes hacer clic en el botón "Connect" para ver si el inspector MCP puede conectarse al servidor MCP. Si todo está bien, deberías ver el estado "Connected" en el inspector MCP. - -### Punto de control: Ejecuta las herramientas del gestor de tareas \{#checkpoint-run-todo-manager-tools} - -1. En el menú superior del inspector MCP, haz clic en la pestaña "Tools". -2. Haz clic en el botón "List Tools". -3. Deberías ver las herramientas `create-todo`, `get-todos` y `delete-todo` listadas en la página. Haz clic en una para ver los detalles de la herramienta. -4. Deberías ver el botón "Run Tool" en el lado derecho. Haz clic en él e ingresa los parámetros requeridos para ejecutar la herramienta. -5. Deberías ver el resultado de la herramienta con la respuesta JSON `{"error": "No implementado"}`. - -![Primera ejecución del inspector MCP](/docs-assets/images/tutorials/todo-manager/inspector-first-run.png) - -## Integra con tu servidor de autorización \{#integrate-with-your-authorization-server} - -Para completar esta sección, hay varias consideraciones a tener en cuenta: - -
-**La URL del emisor de tu servidor de autorización** - -Normalmente es la URL base de tu servidor de autorización, como `https://auth.example.com`. Algunos proveedores pueden tener una ruta como `https://example.logto.app/oidc`, así que asegúrate de consultar la documentación de tu proveedor. - -
- -
-**Cómo obtener los metadatos del servidor de autorización** - -- Si tu servidor de autorización cumple con [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) o [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html), puedes usar las utilidades integradas de MCP Auth para obtener los metadatos automáticamente. -- Si tu servidor de autorización no cumple con estos estándares, deberás especificar manualmente la URL de metadatos o los endpoints en la configuración del servidor MCP. Consulta la documentación de tu proveedor para los endpoints específicos. - -
- -
-**Cómo registrar el inspector MCP como cliente en tu servidor de autorización** - -- Si tu servidor de autorización admite [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591), puedes omitir este paso ya que el inspector MCP se registrará automáticamente como cliente. -- Si tu servidor de autorización no admite Dynamic Client Registration, deberás registrar manualmente el inspector MCP como cliente en tu servidor de autorización. - -
- -
-**Comprende los parámetros de solicitud de token** - -Al solicitar tokens de acceso de diferentes servidores de autorización, encontrarás varios enfoques para especificar el recurso objetivo y los permisos. Aquí los principales patrones: - -- **Basado en indicador de recurso**: - - - Usa el parámetro `resource` para especificar la API objetivo (ver [RFC 8707: Indicadores de recurso para OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)) - - Común en implementaciones modernas de OAuth 2.0 - - Ejemplo de solicitud: - ```json - { - "resource": "https://todo.mcp-server.app", - "scope": "create:todos read:todos" - } - ``` - - El servidor emite tokens vinculados específicamente al recurso solicitado - -- **Basado en audiencia**: - - - Usa el parámetro `audience` para especificar el destinatario previsto del token - - Similar a los indicadores de recurso pero con semántica diferente - - Ejemplo de solicitud: - ```json - { - "audience": "todo-api", - "scope": "create:todos read:todos" - } - ``` - -- **Basado solo en scopes**: - - Se basa únicamente en scopes sin parámetros de recurso/audiencia - - Enfoque tradicional de OAuth 2.0 - - Ejemplo de solicitud: - ```json - { - "scope": "todo-api:create todo-api:read openid profile" - } - ``` - - A menudo usa scopes con prefijo para namespacing de permisos - - Común en implementaciones más simples de OAuth 2.0 - -:::tip Mejores prácticas - -- Consulta la documentación de tu proveedor para los parámetros admitidos -- Algunos proveedores admiten varios enfoques simultáneamente -- Los indicadores de recurso proporcionan mejor seguridad mediante restricción de audiencia -- Considera usar indicadores de recurso cuando estén disponibles para un mejor control de acceso - ::: - -
- -Aunque cada proveedor puede tener sus propios requisitos específicos, los siguientes pasos te guiarán en el proceso de integración del inspector MCP y el servidor MCP con configuraciones específicas del proveedor. - -### Registra el inspector MCP como cliente \{#register-mcp-inspector-as-a-client} - - - - -Integrar el gestor de tareas con [Logto](https://logto.io) es sencillo ya que es un proveedor OpenID Connect que admite indicadores de recurso y scopes, lo que te permite asegurar tu API de tareas con `https://todo.mcp-server.app` como indicador de recurso. - -Dado que Logto aún no admite Dynamic Client Registration, deberás registrar manualmente el inspector MCP como cliente en tu tenant de Logto: - -1. Abre tu inspector MCP, haz clic en el botón "OAuth Configuration". Copia el valor de **Redirect URL (auto-populated)**, que debería ser algo como `http://localhost:6274/oauth/callback`. -2. Inicia sesión en [Logto Console](https://cloud.logto.io) (o en tu Logto Console autoalojado). -3. Navega a la pestaña "Applications", haz clic en "Create application". En la parte inferior de la página, haz clic en "Create app without framework". -4. Completa los detalles de la aplicación y haz clic en "Create application": - - **Selecciona un tipo de aplicación**: Elige "Single-page application". - - **Nombre de la aplicación**: Ingresa un nombre para tu aplicación, por ejemplo, "MCP Inspector". -5. En la sección "Settings / Redirect URIs", pega el valor de **Redirect URL (auto-populated)** que copiaste del inspector MCP. Luego haz clic en "Save changes" en la barra inferior. -6. En la tarjeta superior, verás el valor "App ID". Cópialo. -7. Vuelve al inspector MCP y pega el valor "App ID" en la sección "OAuth Configuration" bajo "Client ID". -8. Ingresa el valor `{"scope": "create:todos read:todos delete:todos", "resource": "https://todo.mcp-server.app"}` en el campo "Auth Params". Esto asegurará que el token de acceso devuelto por Logto contenga los scopes necesarios para acceder al gestor de tareas. - - - - -:::note -Esta es una guía genérica de integración de proveedor OAuth 2.0 / OpenID Connect. Ambos siguen pasos similares ya que OIDC se basa en OAuth 2.0. Consulta la documentación de tu proveedor para detalles específicos. -::: - -Si tu proveedor admite Dynamic Client Registration, puedes ir directamente al paso 8 para configurar el inspector MCP; de lo contrario, deberás registrar manualmente el inspector MCP como cliente: - -1. Abre tu inspector MCP, haz clic en el botón "OAuth Configuration". Copia el valor de **Redirect URL (auto-populated)**, que debería ser algo como `http://localhost:6274/oauth/callback`. - -2. Inicia sesión en la consola de tu proveedor. - -3. Navega a la sección "Applications" o "Clients", luego crea una nueva aplicación o cliente. - -4. Si tu proveedor requiere un tipo de cliente, selecciona "Single-page application" o "Public client". - -5. Después de crear la aplicación, deberás configurar la URI de redirección. Pega el valor de **Redirect URL (auto-populated)** que copiaste del inspector MCP. - -6. Busca el "Client ID" o "Application ID" de la nueva aplicación y cópialo. - -7. Vuelve al inspector MCP y pega el valor "Client ID" en la sección "OAuth Configuration" bajo "Client ID". - -8. Ingresa el siguiente valor en el campo "Auth Params" para solicitar los scopes necesarios para las operaciones de tareas: - -```json -{ "scope": "create:todos read:todos delete:todos" } -``` - - - - -### Configura MCP auth \{#set-up-mcp-auth} - -En tu proyecto del servidor MCP, necesitas instalar el SDK de MCP Auth y configurarlo para usar los metadatos de tu servidor de autorización. - - - - -Primero, instala el paquete `mcpauth`: - -```bash -pip install mcpauth -``` - -O cualquier otro gestor de paquetes que prefieras, como `uv` o `poetry`. - - - - -Primero, instala el paquete `mcp-auth`: - -```bash -npm install mcp-auth -``` - - - - -MCP Auth requiere los metadatos del servidor de autorización para poder inicializarse. Dependiendo de tu proveedor: - - - - - -La URL del emisor se puede encontrar en la página de detalles de tu aplicación en Logto Console, en la sección "Endpoints & Credentials / Issuer endpoint". Debería verse como `https://my-project.logto.app/oidc`. - - - - - - - -Para proveedores OAuth 2.0, deberás: - -1. Consultar la documentación de tu proveedor para la URL del servidor de autorización (a menudo llamada issuer URL o base URL) -2. Algunos proveedores pueden exponer esto en `https://{your-domain}/.well-known/oauth-authorization-server` -3. Busca en la consola de administración de tu proveedor bajo la configuración OAuth/API - - - - - - - - - - - -Actualiza el `todo-manager.py` para incluir la configuración de MCP Auth: - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # Reemplaza con tu endpoint de emisor -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -Actualiza el `todo-manager.ts` para incluir la configuración de MCP Auth: - -```ts -// todo-manager.ts - -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // Reemplaza con tu endpoint de emisor -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oidc' }), -}); -``` - - - - -### Actualiza el servidor MCP \{#update-mcp-server} - -¡Ya casi terminamos! Es momento de actualizar el servidor MCP para aplicar la ruta y función middleware de MCP Auth, luego implementar el control de acceso basado en permisos para las herramientas del gestor de tareas según los scopes del usuario. - - - - -```python -@mcp.tool() -def create_todo(content: str) -> dict[str, Any]: - """Crear una nueva tarea.""" - return ( - mcp_auth.auth_info.scopes - if mcp_auth.auth_info # Esto será rellenado por el middleware Bearer auth - else {"error": "No autenticado"} - ) - -# ... - -bearer_auth = Middleware(mcp_auth.bearer_auth_middleware("jwt")) -app = Starlette( - routes=[ - # Añade la ruta de metadatos (`/.well-known/oauth-authorization-server`) - mcp_auth.metadata_route(), - # Protege el servidor MCP con el middleware Bearer auth - Mount('/', app=mcp.sse_app(), middleware=[bearer_auth]), - ], -) -``` - - - - -```js -server.tool( - 'create-todo', - 'Crear una nueva tarea', - { content: z.string() }, - async ({ content, authInfo }) => { - return { - content: [ - { type: 'text', text: JSON.stringify(authInfo?.scopes ?? { error: 'No autenticado' }) }, - ], - }; - } -); - -// ... - -app.use(mcpAuth.delegatedRouter()); -app.use(mcpAuth.bearerAuth('jwt')); -``` - - - - -A continuación, implementemos las herramientas específicas. - -Primero, vamos a crear un servicio de tareas sencillo para proporcionar operaciones CRUD básicas para gestionar tareas en memoria. - - - -```python -# service.py - -""" -Un servicio de tareas sencillo para fines demostrativos. -Utiliza una lista en memoria para almacenar tareas. -""" - -from datetime import datetime -from typing import List, Optional, Dict, Any -import random -import string - -class Todo: -"""Representa una tarea.""" - - def __init__(self, id: str, content: str, owner_id: str, created_at: str): - self.id = id - self.content = content - self.owner_id = owner_id - self.created_at = created_at - - def to_dict(self) -> Dict[str, Any]: - """Convierte la tarea a diccionario para serialización JSON.""" - return { - "id": self.id, - "content": self.content, - "ownerId": self.owner_id, - "createdAt": self.created_at - } - -class TodoService: -"""Un servicio de tareas sencillo para fines demostrativos.""" - - def __init__(self): - self._todos: List[Todo] = [] - - def get_all_todos(self, owner_id: Optional[str] = None) -> List[Dict[str, Any]]: - """ - Obtiene todas las tareas, opcionalmente filtradas por owner_id. - - Args: - owner_id: Si se proporciona, solo retorna tareas de este usuario - - Returns: - Lista de diccionarios de tareas - """ - if owner_id: - filtered_todos = [todo for todo in self._todos if todo.owner_id == owner_id] - return [todo.to_dict() for todo in filtered_todos] - return [todo.to_dict() for todo in self._todos] - - def get_todo_by_id(self, todo_id: str) -> Optional[Todo]: - """ - Obtiene una tarea por su ID. - - Args: - todo_id: El ID de la tarea a recuperar - - Returns: - Objeto Todo si se encuentra, None en caso contrario - """ - for todo in self._todos: - if todo.id == todo_id: - return todo - return None - - def create_todo(self, content: str, owner_id: str) -> Dict[str, Any]: - """ - Crea una nueva tarea. - - Args: - content: El contenido de la tarea - owner_id: El ID del usuario propietario de la tarea - - Returns: - Diccionario de la tarea creada - """ - todo = Todo( - id=self._generate_id(), - content=content, - owner_id=owner_id, - created_at=datetime.now().isoformat() - ) - self._todos.append(todo) - return todo.to_dict() - - def delete_todo(self, todo_id: str) -> Optional[Dict[str, Any]]: - """ - Elimina una tarea por su ID. - - Args: - todo_id: El ID de la tarea a eliminar - - Returns: - Diccionario de la tarea eliminada si se encuentra, None en caso contrario - """ - for i, todo in enumerate(self._todos): - if todo.id == todo_id: - deleted_todo = self._todos.pop(i) - return deleted_todo.to_dict() - return None - - def _generate_id(self) -> str: - """Genera un ID aleatorio para una tarea.""" - return ''.join(random.choices(string.ascii_lowercase + string.digits, k=8)) - -```` - - - - - -```ts -// todo-service.ts - -type Todo = { - id: string; - content: string; - ownerId: string; - createdAt: string; -}; - -/** - * Un servicio de tareas sencillo para fines demostrativos. - * Usa un array en memoria para almacenar tareas - */ -export class TodoService { - private readonly todos: Todo[] = []; - - getAllTodos(ownerId?: string): Todo[] { - if (ownerId) { - return this.todos.filter((todo) => todo.ownerId === ownerId); - } - return this.todos; - } - - getTodoById(id: string): Todo | undefined { - return this.todos.find((todo) => todo.id === id); - } - - createTodo({ content, ownerId }: { content: string; ownerId: string }): Todo { - const todo: Todo = { - id: this.genId(), - content, - ownerId, - createdAt: new Date().toISOString(), - }; - - // eslint-disable-next-line @silverhand/fp/no-mutating-methods - this.todos.push(todo); - return todo; - } - - deleteTodo(id: string): Todo | undefined { - const index = this.todos.findIndex((todo) => todo.id === id); - - if (index === -1) { - return undefined; - } - - // eslint-disable-next-line @silverhand/fp/no-mutating-methods - const [deleted] = this.todos.splice(index, 1); - return deleted; - } - - private genId(): string { - return Math.random().toString(36).slice(2, 10); - } -} -```` - - - - -luego en la capa de herramientas, determinaremos si las operaciones están permitidas según los scopes del usuario: - - - - -```python -# todo-manager.py - -from typing import Any, Optional -from mcpauth.errors import MCPAuthBearerAuthError - -def assert_user_id(auth_info: Optional[dict]) -> str: - """Extrae y valida el ID de usuario del auth info.""" - subject = auth_info.get('subject') if auth_info else None - if not subject: - raise ValueError('Información de autenticación inválida') - return subject - -def has_required_scopes(user_scopes: list[str], required_scopes: list[str]) -> bool: - """Comprueba si el usuario tiene todos los scopes requeridos.""" - return all(scope in user_scopes for scope in required_scopes) - -# Crea una instancia de TodoService -todo_service = TodoService() - -@mcp.tool() -def create_todo(content: str) -> dict[str, Any]: - """Crear una nueva tarea. - - Solo los usuarios con el scope 'create:todos' pueden crear tareas. - """ - # Obtiene la información de autenticación - auth_info = mcp_auth.auth_info - - # Valida el ID de usuario - try: - user_id = assert_user_id(auth_info) - except ValueError as e: - return {"error": str(e)} - - # Comprueba si el usuario tiene los permisos requeridos - if not has_required_scopes(auth_info.scopes if auth_info else [], ['create:todos']): - raise MCPAuthBearerAuthError('missing_required_scopes') - - # Crea nueva tarea - created_todo = todo_service.create_todo(content=content, owner_id=user_id) - - # Retorna la tarea creada - return created_todo.__dict__ - -# ... -``` - -Puedes consultar nuestro [código de ejemplo](https://github.com/mcp-auth/python/tree/master/samples/server) para todas las implementaciones detalladas. - - - - -```ts -// todo-manager.ts - -// ... otros imports -import assert from 'node:assert'; -import { type AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js'; -import { TodoService } from './todo-service.js'; - -const todoService = new TodoService(); - -const assertUserId = (authInfo?: AuthInfo) => { - const { subject } = authInfo ?? {}; - assert(subject, 'Información de autenticación inválida'); - return subject; -}; - -/** - * Comprueba si el usuario tiene todos los scopes requeridos para una operación - */ -const hasRequiredScopes = (userScopes: string[], requiredScopes: string[]): boolean => { - return requiredScopes.every((scope) => userScopes.includes(scope)); -}; - -server.tool( - 'create-todo', - 'Crear una nueva tarea', - { content: z.string() }, - ({ content }: { content: string }, { authInfo }) => { - const userId = assertUserId(authInfo); - - /** - * Solo los usuarios con el scope 'create:todos' pueden crear tareas - */ - if (!hasRequiredScopes(authInfo?.scopes ?? [], ['create:todos'])) { - throw new MCPAuthBearerAuthError('missing_required_scopes'); - } - - const createdTodo = todoService.createTodo({ content, ownerId: userId }); - - return { - content: [{ type: 'text', text: JSON.stringify(createdTodo) }], - }; - } -); - -// ... -``` - -Puedes consultar nuestro [código de ejemplo](https://github.com/mcp-auth/js/tree/master/packages/sample-servers/src/todo-manager) para todas las implementaciones detalladas. - - - - -## Punto de control: Ejecuta las herramientas `todo-manager` \{#checkpoint-run-the-todo-manager-tools} - -Reinicia tu servidor MCP y abre el inspector MCP en tu navegador. Cuando hagas clic en el botón "Connect", deberías ser redirigido a la página de inicio de sesión de tu servidor de autorización. - -Una vez que inicies sesión y regreses al inspector MCP, repite las acciones que hicimos en el punto de control anterior para ejecutar las herramientas del gestor de tareas. Esta vez, puedes usar estas herramientas con tu identidad de usuario autenticada. El comportamiento de las herramientas dependerá de los roles y permisos asignados a tu usuario: - -- Si has iniciado sesión como **User** (con solo el scope `create:todos`): - - - Puedes crear nuevas tareas usando la herramienta `create-todo` - - Solo puedes ver y eliminar tus propias tareas - - No podrás ver ni eliminar tareas de otros usuarios - -- Si has iniciado sesión como **Admin** (con todos los scopes: `create:todos`, `read:todos`, `delete:todos`): - - Puedes crear nuevas tareas - - Puedes ver todas las tareas del sistema usando la herramienta `get-todos` - - Puedes eliminar cualquier tarea usando la herramienta `delete-todo`, sin importar quién la creó - -Puedes probar estos diferentes niveles de permisos: - -1. Cerrando la sesión actual (haz clic en el botón "Disconnect" en el inspector MCP) -2. Iniciando sesión con una cuenta de usuario diferente que tenga otros roles/permisos -3. Probando las mismas herramientas de nuevo para observar cómo cambia el comportamiento según los permisos del usuario - -Esto demuestra cómo funciona el control de acceso basado en roles (RBAC) en la práctica, donde diferentes usuarios tienen diferentes niveles de acceso a la funcionalidad del sistema. - -![Resultado de la herramienta gestor de tareas en el inspector MCP](/docs-assets/images/tutorials/todo-manager/result.png) - - - - -:::info -Consulta el [repositorio del SDK de MCP Auth Python](https://github.com/mcp-auth/python/blob/master/samples/server/todo-manager/server.py) para el código completo del servidor MCP (versión OIDC). -::: - - - - -:::info -Consulta el [repositorio del SDK de MCP Auth Node.js](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) para el código completo del servidor MCP (versión OIDC). -::: - - - - -## Notas finales \{#closing-notes} - -🎊 ¡Felicidades! Has completado con éxito el tutorial. Recapitulemos lo que hemos hecho: - -- Configuración de un servidor MCP básico con herramientas de gestión de tareas (`create-todo`, `get-todos`, `delete-todo`) -- Implementación de control de acceso basado en roles (RBAC) con diferentes niveles de permisos para usuarios y administradores -- Integración del servidor MCP con un servidor de autorización usando MCP Auth -- Configuración del Inspector MCP para autenticar usuarios y usar tokens de acceso con scopes para llamar a herramientas - -Asegúrate de consultar otros tutoriales y documentación para sacar el máximo provecho de MCP Auth. \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_manual-metadata-fetching.mdx b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_manual-metadata-fetching.mdx deleted file mode 100644 index 5babd90..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_manual-metadata-fetching.mdx +++ /dev/null @@ -1,3 +0,0 @@ -:::note -Si tu proveedor no admite {props.oidc ? 'OpenID Connect Discovery' : 'Metadatos del servidor de autorización OAuth 2.0'}, puedes especificar manualmente la URL de metadatos o los endpoints. Consulta [Otras formas de inicializar MCP Auth](../../configure-server/mcp-auth.mdx#other-ways) para más detalles. -::: \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oauth-or-oidc.mdx b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oauth-or-oidc.mdx deleted file mode 100644 index df73564..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oauth-or-oidc.mdx +++ /dev/null @@ -1,41 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -Actualiza el archivo `todo-manager.py` para incluir la configuración de MCP Auth: - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # Reemplaza con tu endpoint de emisor -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OAUTH) # o AuthServerType.OIDC -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -Actualiza el archivo `todo-manager.ts` para incluir la configuración de MCP Auth: - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // Reemplaza con tu endpoint de emisor -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oauth' }), // o { type: 'oidc' } -}); -``` - - - - - - \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oidc.mdx b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oidc.mdx deleted file mode 100644 index f8fd53c..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oidc.mdx +++ /dev/null @@ -1,41 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -Actualiza el archivo `todo-manager.py` para incluir la configuración de MCP Auth: - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # Reemplaza con tu endpoint de emisor -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -Actualiza el archivo `todo-manager.ts` para incluir la configuración de MCP Auth: - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // Reemplaza con tu endpoint de emisor -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oidc' }), -}); -``` - - - - -{props.showAlternative && } -{props.showAlternative && } \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_transpile-metadata.mdx b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_transpile-metadata.mdx deleted file mode 100644 index 12ef5cb..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_transpile-metadata.mdx +++ /dev/null @@ -1,31 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -En algunos casos, la respuesta del proveedor puede estar malformada o no ajustarse al formato de metadatos esperado. Si estás seguro de que el proveedor es compatible, puedes transpilar los metadatos mediante la opción de configuración: - - - - -```python -mcp_auth = MCPAuth( - server=fetch_server_config( - # ...otras opciones - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { - // ...otras opciones - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/README.mdx b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/README.mdx deleted file mode 100644 index 9ab7990..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/README.mdx +++ /dev/null @@ -1,611 +0,0 @@ ---- -sidebar_position: 1 -sidebar_label: 'Tutorial: ¿Quién soy?' ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import SetupOauth from './_setup-oauth.mdx'; -import SetupOidc from './_setup-oidc.mdx'; - -# Tutorial: ¿Quién soy? (Who am I?) - -Este tutorial te guiará a través del proceso de configurar MCP Auth para autenticar usuarios y obtener su información de identidad desde el servidor de autorización. - -Después de completar este tutorial, tendrás: - -- ✅ Una comprensión básica de cómo usar MCP Auth para autenticar usuarios. -- ✅ Un servidor MCP que ofrece una herramienta para obtener información de identidad del usuario. - -## Descripción general \{#overview} - -El tutorial involucrará los siguientes componentes: - -- **Servidor MCP**: Un servidor MCP sencillo que utiliza los SDKs oficiales de MCP para manejar solicitudes. -- **Inspector MCP**: Una herramienta visual de pruebas para servidores MCP. También actúa como un cliente OAuth / OIDC para iniciar el flujo de autorización y obtener tokens de acceso. -- **Servidor de autorización**: Un proveedor OAuth 2.1 u OpenID Connect que gestiona identidades de usuario y emite tokens de acceso. - -Aquí tienes un diagrama de alto nivel de la interacción entre estos componentes: - -```mermaid -sequenceDiagram - participant Client as Inspector MCP - participant Server as Servidor MCP - participant Auth as Servidor de autorización - - Client->>Server: Solicitar herramienta `whoami` - Server->>Client: Retornar 401 No autorizado - Client->>Auth: Iniciar flujo de autorización - Auth->>Auth: Completar flujo de autorización - Auth->>Client: Redirigir de vuelta con código de autorización - Client->>Auth: Intercambiar código por token de acceso - Auth->>Client: Retornar token de acceso - Client->>Server: Solicitar `whoami` con token de acceso - Server->>Auth: Obtener identidad de usuario con token de acceso - Auth->>Server: Retornar identidad de usuario - Server->>Client: Retornar identidad de usuario -``` - -## Comprende tu servidor de autorización \{#understand-your-authorization-server} - -### Obtener información de identidad del usuario \{#retrieving-user-identity-information} - -Para completar este tutorial, tu servidor de autorización debe ofrecer una API para obtener información de identidad del usuario: - - - - -[Logto](https://logto.io) es un proveedor OpenID Connect que admite el [endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) estándar para obtener información de identidad del usuario. - -Para obtener un token de acceso que pueda usarse para acceder al endpoint userinfo, se requieren al menos dos alcances: `openid` y `profile`. Puedes seguir leyendo, ya que cubriremos la configuración de alcances más adelante. - - - - -[Keycloak](https://www.keycloak.org) es una solución de gestión de identidad y acceso de código abierto que admite múltiples protocolos, incluido OpenID Connect (OIDC). Como proveedor OIDC, implementa el [endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) estándar para obtener información de identidad del usuario. - -Para obtener un token de acceso que pueda usarse para acceder al endpoint userinfo, se requieren al menos dos alcances: `openid` y `profile`. Puedes seguir leyendo, ya que cubriremos la configuración de alcances más adelante. - - - - -La mayoría de los proveedores OpenID Connect admiten el [endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) para obtener información de identidad del usuario. - -Consulta la documentación de tu proveedor para ver si admite este endpoint. Si tu proveedor admite [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html), también puedes comprobar si el `userinfo_endpoint` está incluido en el documento de descubrimiento (respuesta del endpoint `.well-known/openid-configuration`). - -Para obtener un token de acceso que pueda usarse para acceder al endpoint userinfo, se requieren al menos dos alcances: `openid` y `profile`. Consulta la documentación de tu proveedor para ver el mapeo de alcances a reclamos de identidad del usuario. - - - - -Aunque OAuth 2.0 no define una forma estándar de obtener información de identidad del usuario, muchos proveedores implementan sus propios endpoints para hacerlo. Consulta la documentación de tu proveedor para ver cómo obtener información de identidad del usuario usando un token de acceso y qué parámetros se requieren para obtener dicho token al invocar el flujo de autorización. - - - - -### Registro dinámico de clientes \{#dynamic-client-registration} - -El registro dinámico de clientes no es necesario para este tutorial, pero puede ser útil si deseas automatizar el proceso de registro del cliente MCP con tu servidor de autorización. Consulta [¿Es necesario el registro dinámico de clientes?](/provider-list#is-dcr-required) para más detalles. - -## Configura el servidor MCP \{#set-up-the-mcp-server} - -Usaremos los [SDKs oficiales de MCP](https://github.com/modelcontextprotocol) para crear un servidor MCP con una herramienta `whoami` que obtiene información de identidad del usuario desde el servidor de autorización. - -### Crea un nuevo proyecto \{#create-a-new-project} - - - - -```bash -mkdir mcp-server -cd mcp-server -uv init # O usa `pipenv` o `poetry` para crear un nuevo entorno virtual -``` - - - - -Configura un nuevo proyecto Node.js: - -```bash -mkdir mcp-server -cd mcp-server -npm init -y # O usa `pnpm init` -npm pkg set type="module" -npm pkg set main="whoami.js" -npm pkg set scripts.start="node whoami.js" -``` - - - - -### Instala el SDK de MCP y dependencias \{#install-the-mcp-sdk-and-dependencies} - - - - -```bash -pip install "mcp[cli]" starlette uvicorn -``` - -O cualquier otro gestor de paquetes que prefieras, como `uv` o `poetry`. - - - - -```bash -npm install @modelcontextprotocol/sdk express -``` - -O cualquier otro gestor de paquetes que prefieras, como `pnpm` o `yarn`. - - - - -### Crea el servidor MCP \{#create-the-mcp-server} - -Primero, vamos a crear un servidor MCP que implemente una herramienta `whoami`. - - - - -Crea un archivo llamado `whoami.py` y añade el siguiente código: - -```python -from mcp.server.fastmcp import FastMCP -from starlette.applications import Starlette -from starlette.routing import Mount -from typing import Any - -mcp = FastMCP("WhoAmI") - -@mcp.tool() -def whoami() -> dict[str, Any]: - """Una herramienta que retorna la información del usuario actual.""" - return {"error": "Not authenticated"} - -app = Starlette( - routes=[Mount('/', app=mcp.sse_app())] -) -``` - -Ejecuta el servidor con: - -```bash -uvicorn whoami:app --host 0.0.0.0 --port 3001 -``` - - - - -:::note -Dado que la implementación actual del inspector MCP no maneja flujos de autorización, usaremos el enfoque SSE para configurar el servidor MCP. Actualizaremos el código aquí una vez que el inspector MCP admita flujos de autorización. -::: - -También puedes usar `pnpm` o `yarn` si lo prefieres. - -Crea un archivo llamado `whoami.js` y añade el siguiente código: - -```js -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; -import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'; -import express from 'express'; - -// Crear un servidor MCP -const server = new McpServer({ - name: 'WhoAmI', - version: '0.0.0', -}); - -// Añadir una herramienta al servidor que retorna la información del usuario actual -server.tool('whoami', async () => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Not authenticated' }) }], - }; -}); - -// Abajo está el código boilerplate de la documentación del SDK de MCP -const PORT = 3001; -const app = express(); - -const transports = {}; - -app.get('/sse', async (_req, res) => { - const transport = new SSEServerTransport('/messages', res); - transports[transport.sessionId] = transport; - - res.on('close', () => { - delete transports[transport.sessionId]; - }); - - await server.connect(transport); -}); - -app.post('/messages', async (req, res) => { - const sessionId = String(req.query.sessionId); - const transport = transports[sessionId]; - if (transport) { - await transport.handlePostMessage(req, res, req.body); - } else { - res.status(400).send('No transport found for sessionId'); - } -}); - -app.listen(PORT); -``` - -Ejecuta el servidor con: - -```bash -npm start -``` - - - - -## Inspecciona el servidor MCP \{#inspect-the-mcp-server} - -### Clona y ejecuta el inspector MCP \{#clone-and-run-mcp-inspector} - -Ahora que tenemos el servidor MCP en funcionamiento, podemos usar el inspector MCP para ver si la herramienta `whoami` está disponible. - -Debido a la limitación de la implementación actual, hemos bifurcado el [inspector MCP](https://github.com/mcp-auth/inspector) para hacerlo más flexible y escalable para autenticación y autorización. También hemos enviado un pull request al repositorio original para incluir nuestros cambios. - -Para ejecutar el inspector MCP, puedes usar el siguiente comando (se requiere Node.js): - -```bash -git clone https://github.com/mcp-auth/inspector.git -cd inspector -npm install -npm run dev -``` - -Luego, abre tu navegador y navega a `http://localhost:6274/` (u otra URL mostrada en la terminal) para acceder al inspector MCP. - -### Conecta el inspector MCP al servidor MCP \{#connect-mcp-inspector-to-the-mcp-server} - -Antes de continuar, revisa la siguiente configuración en el inspector MCP: - -- **Tipo de transporte**: Establece en `SSE`. -- **URL**: Establece la URL de tu servidor MCP. En nuestro caso, debería ser `http://localhost:3001/sse`. - -Ahora puedes hacer clic en el botón "Connect" para ver si el inspector MCP puede conectarse al servidor MCP. Si todo está bien, deberías ver el estado "Connected" en el inspector MCP. - -### Punto de control: Ejecuta la herramienta `whoami` \{#checkpoint-run-the-whoami-tool} - -1. En el menú superior del inspector MCP, haz clic en la pestaña "Tools". -2. Haz clic en el botón "List Tools". -3. Deberías ver la herramienta `whoami` listada en la página. Haz clic en ella para abrir los detalles de la herramienta. -4. Deberías ver el botón "Run Tool" en el lado derecho. Haz clic en él para ejecutar la herramienta. -5. Deberías ver el resultado de la herramienta con la respuesta JSON `{"error": "Not authenticated"}`. - -![Primera ejecución del inspector MCP](/docs-assets/images/tutorials/whoami/inspector-first-run.png) - -## Integra con tu servidor de autorización \{#integrate-with-your-authorization-server} - -Para completar esta sección, hay varias consideraciones a tener en cuenta: - -
-**La URL del emisor de tu servidor de autorización** - -Normalmente es la URL base de tu servidor de autorización, como `https://auth.example.com`. Algunos proveedores pueden tener una ruta como `https://example.logto.app/oidc`, así que asegúrate de consultar la documentación de tu proveedor. - -
- -
-**Cómo obtener los metadatos del servidor de autorización** - -- Si tu servidor de autorización cumple con [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) o [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html), puedes usar las utilidades integradas de MCP Auth para obtener los metadatos automáticamente. -- Si tu servidor de autorización no cumple con estos estándares, deberás especificar manualmente la URL de metadatos o los endpoints en la configuración del servidor MCP. Consulta la documentación de tu proveedor para los endpoints específicos. - -
- -
-**Cómo registrar el inspector MCP como cliente en tu servidor de autorización** - -- Si tu servidor de autorización admite [registro dinámico de clientes](https://datatracker.ietf.org/doc/html/rfc7591), puedes omitir este paso ya que el inspector MCP se registrará automáticamente como cliente. -- Si tu servidor de autorización no admite el registro dinámico de clientes, deberás registrar manualmente el inspector MCP como cliente en tu servidor de autorización. - -
- -
-**Cómo obtener información de identidad del usuario y cómo configurar los parámetros de la solicitud de autorización** - -- Para proveedores OpenID Connect: normalmente necesitas solicitar al menos los alcances `openid` y `profile` al iniciar el flujo de autorización. Esto asegurará que el token de acceso devuelto por el servidor de autorización contenga los alcances necesarios para acceder al [endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) y obtener información de identidad del usuario. - - Nota: Algunos proveedores pueden no admitir el endpoint userinfo. - -- Para proveedores OAuth 2.0 / OAuth 2.1: consulta la documentación de tu proveedor para ver cómo obtener información de identidad del usuario usando un token de acceso y qué parámetros se requieren para obtener dicho token al invocar el flujo de autorización. - -
- -Aunque cada proveedor puede tener sus propios requisitos específicos, los siguientes pasos te guiarán en el proceso de integración del inspector MCP y el servidor MCP con configuraciones específicas del proveedor. - -### Registra el inspector MCP como cliente \{#register-mcp-inspector-as-a-client} - - - - -Integrar con [Logto](https://logto.io) es sencillo, ya que es un proveedor OpenID Connect que admite el [endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) estándar para obtener información de identidad del usuario. - -Como Logto aún no admite el registro dinámico de clientes, deberás registrar manualmente el inspector MCP como cliente en tu tenant de Logto: - -1. Abre tu inspector MCP, haz clic en el botón "OAuth Configuration". Copia el valor de **Redirect URL (auto-populated)**, que debería ser algo como `http://localhost:6274/oauth/callback`. -2. Inicia sesión en [Logto Console](https://cloud.logto.io) (o tu instancia autoalojada de Logto Console). -3. Navega a la pestaña "Applications", haz clic en "Create application". En la parte inferior de la página, haz clic en "Create app without framework". -4. Completa los detalles de la aplicación y haz clic en "Create application": - - **Selecciona un tipo de aplicación**: Elige "Single-page application". - - **Nombre de la aplicación**: Ingresa un nombre para tu aplicación, por ejemplo, "MCP Inspector". -5. En la sección "Settings / Redirect URIs", pega el valor de **Redirect URL (auto-populated)** que copiaste del inspector MCP. Luego haz clic en "Save changes" en la barra inferior. -6. En la tarjeta superior, verás el valor "App ID". Cópialo. -7. Vuelve al inspector MCP y pega el valor "App ID" en la sección "OAuth Configuration" bajo "Client ID". -8. Ingresa el valor `{"scope": "openid profile email"}` en el campo "Auth Params". Esto asegurará que el token de acceso devuelto por Logto contenga los alcances necesarios para acceder al endpoint userinfo. - - - - -[Keycloak](https://www.keycloak.org) es una solución de gestión de identidad y acceso de código abierto que admite el protocolo OpenID Connect. - -Aunque Keycloak admite el registro dinámico de clientes, su endpoint de registro de clientes no admite CORS, lo que impide que la mayoría de los clientes MCP se registren directamente. Por lo tanto, necesitaremos registrar nuestro cliente manualmente. - -:::note -Aunque Keycloak puede instalarse de [varias formas](https://www.keycloak.org/guides#getting-started) (bare metal, kubernetes, etc.), para este tutorial, usaremos Docker para una configuración rápida y sencilla. -::: - -Vamos a configurar una instancia de Keycloak y ajustarla a nuestras necesidades: - -1. Primero, ejecuta una instancia de Keycloak usando Docker siguiendo la [documentación oficial](https://www.keycloak.org/getting-started/getting-started-docker): - -```bash -docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.2.4 start-dev -``` - -2. Accede a la consola de administración de Keycloak (http://localhost:8080/admin) e inicia sesión con estas credenciales: - - - Usuario: `admin` - - Contraseña: `admin` - -3. Crea un nuevo Realm: - - - Haz clic en "Create Realm" en la esquina superior izquierda - - Ingresa `mcp-realm` en el campo "Realm name" - - Haz clic en "Create" - -4. Crea un usuario de prueba: - - - Haz clic en "Users" en el menú de la izquierda - - Haz clic en "Create new user" - - Completa los detalles del usuario: - - Usuario: `testuser` - - Nombre y apellido pueden ser cualquier valor - - Haz clic en "Create" - - En la pestaña "Credentials", establece una contraseña y desmarca "Temporary" - -5. Registra el inspector MCP como cliente: - - - Abre tu inspector MCP, haz clic en el botón "OAuth Configuration". Copia el valor de **Redirect URL (auto-populated)**, que debería ser algo como `http://localhost:6274/oauth/callback`. - - En la consola de administración de Keycloak, haz clic en "Clients" en el menú de la izquierda - - Haz clic en "Create client" - - Completa los detalles del cliente: - - Tipo de cliente: Selecciona "OpenID Connect" - - Client ID: Ingresa `mcp-inspector` - - Haz clic en "Next" - - En la página "Capability config": - - Asegúrate de que "Standard flow" esté habilitado - - Haz clic en "Next" - - En la página "Login settings": - - Pega la URL de callback del inspector MCP previamente copiada en "Valid redirect URIs" - - Ingresa `http://localhost:6274` en "Web origins" - - Haz clic en "Save" - - Copia el "Client ID" (que es `mcp-inspector`) - -6. De vuelta en el inspector MCP: - - Pega el Client ID copiado en el campo "Client ID" en la sección "OAuth Configuration" - - Ingresa el siguiente valor en el campo "Auth Params" para solicitar los alcances necesarios: - -```json -{ "scope": "openid profile email" } -``` - - - - -:::note -Esta es una guía genérica de integración con proveedores OpenID Connect. Consulta la documentación de tu proveedor para detalles específicos. -::: - -Si tu proveedor OpenID Connect admite el registro dinámico de clientes, puedes ir directamente al paso 8 a continuación para configurar el inspector MCP; de lo contrario, deberás registrar manualmente el inspector MCP como cliente en tu proveedor OpenID Connect: - -1. Abre tu inspector MCP, haz clic en el botón "OAuth Configuration". Copia el valor de **Redirect URL (auto-populated)**, que debería ser algo como `http://localhost:6274/oauth/callback`. -2. Inicia sesión en la consola de tu proveedor OpenID Connect. -3. Navega a la sección "Applications" o "Clients", luego crea una nueva aplicación o cliente. -4. Si tu proveedor requiere un tipo de cliente, selecciona "Single-page application" o "Public client". -5. Después de crear la aplicación, deberás configurar la URI de redirección. Pega el valor de **Redirect URL (auto-populated)** que copiaste del inspector MCP. -6. Busca el "Client ID" o "Application ID" de la nueva aplicación y cópialo. -7. Vuelve al inspector MCP y pega el valor "Client ID" en la sección "OAuth Configuration" bajo "Client ID". -8. Para proveedores OpenID Connect estándar, puedes ingresar el siguiente valor en el campo "Auth Params" para solicitar los alcances necesarios para acceder al endpoint userinfo: - -```json -{ "scope": "openid profile email" } -``` - - - - -:::note -Esta es una guía genérica de integración con proveedores OAuth 2.0 / OAuth 2.1. Consulta la documentación de tu proveedor para detalles específicos. -::: - -Si tu proveedor OAuth 2.0 / OAuth 2.1 admite el registro dinámico de clientes, puedes ir directamente al paso 8 a continuación para configurar el inspector MCP; de lo contrario, deberás registrar manualmente el inspector MCP como cliente en tu proveedor OAuth 2.0 / OAuth 2.1: - -1. Abre tu inspector MCP, haz clic en el botón "OAuth Configuration". Copia el valor de **Redirect URL (auto-populated)**, que debería ser algo como `http://localhost:6274/oauth/callback`. -2. Inicia sesión en la consola de tu proveedor OAuth 2.0 / OAuth 2.1. -3. Navega a la sección "Applications" o "Clients", luego crea una nueva aplicación o cliente. -4. Si tu proveedor requiere un tipo de cliente, selecciona "Single-page application" o "Public client". -5. Después de crear la aplicación, deberás configurar la URI de redirección. Pega el valor de **Redirect URL (auto-populated)** que copiaste del inspector MCP. -6. Busca el "Client ID" o "Application ID" de la nueva aplicación y cópialo. -7. Vuelve al inspector MCP y pega el valor "Client ID" en la sección "OAuth Configuration" bajo "Client ID". -8. Lee la documentación de tu proveedor para ver cómo obtener tokens de acceso para información de identidad del usuario. Es posible que debas especificar los alcances o parámetros requeridos para obtener el token de acceso. Por ejemplo, si tu proveedor requiere el alcance `profile` para acceder a la información de identidad del usuario, puedes ingresar el siguiente valor en el campo "Auth Params": - -```json -{ "scope": "profile" } -``` - - - - -### Configura MCP Auth \{#set-up-mcp-auth} - -En tu proyecto del servidor MCP, necesitas instalar el SDK de MCP Auth y configurarlo para usar los metadatos de tu servidor de autorización. - - - - -Primero, instala el paquete `mcpauth`: - -```bash -pip install mcpauth -``` - -O cualquier otro gestor de paquetes que prefieras, como `uv` o `poetry`. - - - - -Primero, instala el paquete `mcp-auth`: - -```bash -npm install mcp-auth -``` - - - - -MCP Auth requiere los metadatos del servidor de autorización para poder inicializarse. Dependiendo de tu proveedor: - - - - - -La URL del emisor se puede encontrar en la página de detalles de tu aplicación en Logto Console, en la sección "Endpoints & Credentials / Issuer endpoint". Debería verse como `https://my-project.logto.app/oidc`. - - - - - - - -La URL del emisor se puede encontrar en tu consola de administración de Keycloak. En tu 'mcp-realm', navega a la sección "Realm settings / Endpoints" y haz clic en el enlace "OpenID Endpoint Configuration". El campo `issuer` en el documento JSON contendrá tu URL de emisor, que debería verse como `http://localhost:8080/realms/mcp-realm`. - - - - - - - -El siguiente código también asume que el servidor de autorización admite el [endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) para obtener información de identidad del usuario. Si tu proveedor no admite este endpoint, deberás consultar la documentación de tu proveedor para el endpoint específico y reemplazar la variable del endpoint userinfo con la URL correcta. - - - - - - -Como mencionamos antes, OAuth 2.0 no define una forma estándar de obtener información de identidad del usuario. El siguiente código asume que tu proveedor tiene un endpoint específico para obtener información de identidad del usuario usando un token de acceso. Deberás consultar la documentación de tu proveedor para el endpoint específico y reemplazar la variable del endpoint userinfo con la URL correcta. - - - - - - -### Actualiza el servidor MCP \{#update-mcp-server} - -¡Ya casi terminamos! Es momento de actualizar el servidor MCP para aplicar la ruta y función middleware de MCP Auth, y luego hacer que la herramienta `whoami` retorne la información real de identidad del usuario. - - - - -```python -@mcp.tool() -def whoami() -> dict[str, Any]: - """Una herramienta que retorna la información del usuario actual.""" - return ( - mcp_auth.auth_info.claims - if mcp_auth.auth_info # Esto será poblado por el middleware Bearer auth - else {"error": "Not authenticated"} - ) - -# ... - -bearer_auth = Middleware(mcp_auth.bearer_auth_middleware(verify_access_token)) -app = Starlette( - routes=[ - # Añade la ruta de metadatos (`/.well-known/oauth-authorization-server`) - mcp_auth.metadata_route(), - # Protege el servidor MCP con el middleware Bearer auth - Mount('/', app=mcp.sse_app(), middleware=[bearer_auth]), - ], -) -``` - - - - -```js -server.tool('whoami', ({ authInfo }) => { - return { - content: [ - { type: 'text', text: JSON.stringify(authInfo?.claims ?? { error: 'Not authenticated' }) }, - ], - }; -}); - -// ... - -app.use(mcpAuth.delegatedRouter()); -app.use(mcpAuth.bearerAuth(verifyToken)); -``` - - - - -## Punto de control: Ejecuta la herramienta `whoami` con autenticación \{#checkpoint-run-the-whoami-tool-with-authentication} - -Reinicia tu servidor MCP y abre el inspector MCP en tu navegador. Cuando hagas clic en el botón "Connect", deberías ser redirigido a la página de inicio de sesión de tu servidor de autorización. - -Una vez que inicies sesión y regreses al inspector MCP, repite las acciones que hicimos en el punto de control anterior para ejecutar la herramienta `whoami`. Esta vez, deberías ver la información de identidad del usuario retornada por el servidor de autorización. - -![Resultado de la herramienta whoami en el inspector MCP](/docs-assets/images/tutorials/whoami/result.png) - - - - -:::info -Consulta el [repositorio del SDK de MCP Auth para Python](https://github.com/mcp-auth/python/blob/master/samples/server/whoami.py) para ver el código completo del servidor MCP (versión OIDC). -::: - - - - -:::info -Consulta el [repositorio del SDK de MCP Auth para Node.js](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) para ver el código completo del servidor MCP (versión OIDC). Este directorio contiene versiones en TypeScript y JavaScript del código. -::: - - - - -## Notas finales \{#closing-notes} - -🎊 ¡Felicidades! Has completado exitosamente el tutorial. Recapitulemos lo que hemos hecho: - -- Configuración de un servidor MCP básico con la herramienta `whoami` -- Integración del servidor MCP con un servidor de autorización usando MCP Auth -- Configuración del Inspector MCP para autenticar usuarios y obtener su información de identidad - -También puedes explorar algunos temas avanzados, incluyendo: - -- Uso de [JWT (JSON Web Token)](https://auth.wiki/jwt) para autenticación y autorización -- Aprovechar [indicadores de recurso (RFC 8707)](https://auth-wiki.logto.io/resource-indicator) para especificar los recursos a los que se accede -- Implementar mecanismos de control de acceso personalizados, como [control de acceso basado en roles (RBAC)](https://auth.wiki/rbac) o [control de acceso basado en atributos (ABAC)](https://auth.wiki/abac) - -Asegúrate de consultar otros tutoriales y documentación para sacar el máximo provecho de MCP Auth. \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_manual-metadata-fetching.mdx b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_manual-metadata-fetching.mdx deleted file mode 100644 index f312967..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_manual-metadata-fetching.mdx +++ /dev/null @@ -1,3 +0,0 @@ -:::note -Si tu proveedor no admite {props.oidc ? 'OpenID Connect Discovery' : 'Metadatos del servidor de autorización OAuth 2.0'}, puedes especificar manualmente la URL de los metadatos o los endpoints. Consulta [Otras formas de inicializar MCP Auth](../../configure-server/mcp-auth.mdx#other-ways) para más detalles. -::: \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oauth.mdx b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oauth.mdx deleted file mode 100644 index 9e67b79..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oauth.mdx +++ /dev/null @@ -1,141 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -Actualiza el archivo `whoami.py` para incluir la configuración de MCP Auth: - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # Reemplaza con tu endpoint de emisor -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OAUTH) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -Actualiza el archivo `whoami.js` para incluir la configuración de MCP Auth: - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // Reemplaza con tu endpoint de emisor -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oauth' }), -}); -``` - - - - - - - -Ahora, necesitamos crear un verificador personalizado de token de acceso (Access token) que obtendrá la información de identidad del usuario desde el servidor de autorización utilizando el token de acceso proporcionado por el inspector MCP. - - - - -```python -import pydantic -import requests -from mcpauth.exceptions import ( - MCPAuthTokenVerificationException, - MCPAuthTokenVerificationExceptionCode, -) -from mcpauth.types import AuthInfo - -def verify_access_token(token: str) -> AuthInfo: - """ - Verifica el token Bearer proporcionado obteniendo la información del usuario desde el servidor de autorización. - Si el token es válido, devuelve un objeto `AuthInfo` que contiene la información del usuario. - - :param token: El token Bearer recibido del inspector MCP. - """ - - try: - # El siguiente código asume que tu servidor de autorización tiene un endpoint para obtener la información del usuario - # usando el token de acceso emitido por el flujo de autorización. - # Ajusta la URL y los encabezados según la API de tu proveedor. - response = requests.get( - "https://your-authorization-server.com/userinfo", - headers={"Authorization": f"Bearer {token}"}, - ) - response.raise_for_status() # Asegúrate de lanzar un error para errores HTTP - json = response.json() # Analiza la respuesta JSON - - # El siguiente código asume que la respuesta de información del usuario es un objeto con un campo 'sub' que - # identifica al usuario. Puede que necesites ajustar esto según la API de tu proveedor. - return AuthInfo( - token=token, - subject=json.get("sub"), - issuer=auth_issuer, # Usa el emisor configurado - claims=json, # Incluye todos los reclamos (claims) (campos JSON) devueltos por el endpoint - ) - # `AuthInfo` es un modelo de Pydantic, por lo que los errores de validación suelen significar que la respuesta no coincide - # con la estructura esperada - except pydantic.ValidationError as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.INVALID_TOKEN, - cause=e, - ) - # Maneja otras excepciones que puedan ocurrir durante la solicitud - except Exception as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.TOKEN_VERIFICATION_FAILED, - cause=e, - ) -``` - - - - -```js -import { MCPAuthTokenVerificationError } from 'mcp-auth'; - -/** - * Verifica el token Bearer proporcionado obteniendo la información del usuario desde el servidor de autorización. - * Si el token es válido, devuelve un objeto `AuthInfo` que contiene la información del usuario. - */ -const verifyToken = async (token) => { - // El siguiente código asume que tu servidor de autorización tiene un endpoint para obtener la información del usuario - // usando el token de acceso emitido por el flujo de autorización. - // Ajusta la URL y los encabezados según la API de tu proveedor. - const response = await fetch('https://your-authorization-server.com/userinfo', { - headers: { Authorization: `Bearer ${token}` }, - }); - - if (!response.ok) { - throw new MCPAuthTokenVerificationError('token_verification_failed', response); - } - - const userInfo = await response.json(); - - // El siguiente código asume que la respuesta de información del usuario es un objeto con un campo 'sub' que - // identifica al usuario. Puede que necesites ajustar esto según la API de tu proveedor. - if (typeof userInfo !== 'object' || userInfo === null || !('sub' in userInfo)) { - throw new MCPAuthTokenVerificationError('invalid_token', response); - } - - return { - token, - issuer: authIssuer, - subject: String(userInfo.sub), // Ajusta esto según el campo de ID de usuario de tu proveedor - clientId: '', // El Client ID no se usa en este ejemplo, pero puede establecerse si es necesario - scopes: [], - claims: userInfo, - }; -}; -``` - - - \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oidc.mdx b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oidc.mdx deleted file mode 100644 index 836d142..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oidc.mdx +++ /dev/null @@ -1,143 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -Actualiza el archivo `whoami.py` para incluir la configuración de MCP Auth: - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # Reemplaza con tu endpoint de emisor -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -Actualiza el archivo `whoami.js` para incluir la configuración de MCP Auth: - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // Reemplaza con tu endpoint de emisor -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oidc' }), -}); -``` - - - - -{props.showAlternative && } -{props.showAlternative && } - -Ahora, necesitamos crear un verificador personalizado de token de acceso (Access token) que obtendrá la información de identidad del usuario desde el servidor de autorización utilizando el token de acceso proporcionado por el inspector MCP. - - - - -```python -import pydantic -import requests -from mcpauth.exceptions import ( - MCPAuthTokenVerificationException, - MCPAuthTokenVerificationExceptionCode, -) -from mcpauth.types import AuthInfo - -def verify_access_token(token: str) -> AuthInfo: - """ - Verifica el token Bearer proporcionado obteniendo la información del usuario desde el servidor de autorización. - Si el token es válido, retorna un objeto `AuthInfo` que contiene la información del usuario. - - :param token: El token Bearer recibido del inspector MCP. - """ - - issuer = auth_server_config.metadata.issuer - endpoint = auth_server_config.metadata.userinfo_endpoint # El proveedor debe soportar el endpoint userinfo - if not endpoint: - raise ValueError( - "El endpoint userinfo no está configurado en los metadatos del servidor de autenticación." - ) - - try: - response = requests.get( - endpoint, - headers={"Authorization": f"Bearer {token}"}, # Encabezado estándar para token Bearer - ) - response.raise_for_status() # Asegura que se lance un error para errores HTTP - json = response.json() # Analiza la respuesta JSON - return AuthInfo( - token=token, - subject=json.get("sub"), # 'sub' es un reclamo estándar para el sujeto (ID del usuario) - issuer=issuer, # Usa el emisor de los metadatos - claims=json, # Incluye todos los reclamos (campos JSON) retornados por el endpoint userinfo - ) - # `AuthInfo` es un modelo de Pydantic, así que los errores de validación usualmente significan que la respuesta no coincide - # con la estructura esperada - except pydantic.ValidationError as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.INVALID_TOKEN, - cause=e, - ) - # Maneja otras excepciones que puedan ocurrir durante la solicitud - except Exception as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.TOKEN_VERIFICATION_FAILED, - cause=e, - ) -``` - - - - -```js -import { MCPAuthTokenVerificationError } from 'mcp-auth'; - -/** - * Verifica el token Bearer proporcionado obteniendo la información del usuario desde el servidor de autorización. - * Si el token es válido, retorna un objeto `AuthInfo` que contiene la información del usuario. - */ -const verifyToken = async (token) => { - const { issuer, userinfoEndpoint } = mcpAuth.config.server.metadata; - - if (!userinfoEndpoint) { - throw new Error('El endpoint userinfo no está configurado en los metadatos del servidor'); - } - - const response = await fetch(userinfoEndpoint, { - headers: { Authorization: `Bearer ${token}` }, - }); - - if (!response.ok) { - throw new MCPAuthTokenVerificationError('token_verification_failed', response); - } - - const userInfo = await response.json(); - - if (typeof userInfo !== 'object' || userInfo === null || !('sub' in userInfo)) { - throw new MCPAuthTokenVerificationError('invalid_token', response); - } - - return { - token, - issuer, - subject: String(userInfo.sub), // 'sub' es un reclamo estándar para el sujeto (ID del usuario) - clientId: '', // El Client ID no se usa en este ejemplo, pero puede establecerse si es necesario - scopes: [], - claims: userInfo, - }; -}; -``` - - - \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_transpile-metadata.mdx b/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_transpile-metadata.mdx deleted file mode 100644 index 396dab9..0000000 --- a/i18n/es/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_transpile-metadata.mdx +++ /dev/null @@ -1,31 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -En algunos casos, la respuesta del proveedor puede estar malformada o no ajustarse al formato de metadatos esperado. Si estás seguro de que el proveedor es compatible, puedes transpilar los metadatos mediante la opción de configuración: - - - - -```python -mcp_auth = MCPAuth( - server=fetch_server_config( - # ...other options - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { - // ...other options - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1.json b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1.json deleted file mode 100644 index 71c3f74..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1.json +++ /dev/null @@ -1,50 +0,0 @@ -{ - "sidebar.docsSidebar.category.Tutorials": { - "message": "Tutoriels", - "description": "The label for category Tutorials in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.Tutorials.link.generated-index.title": { - "message": "Tutoriels", - "description": "The generated-index page title for category Tutorials in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.Configure MCP server": { - "message": "Configurer le serveur MCP", - "description": "The label for category Configure MCP server in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.Configure MCP server.link.generated-index.title": { - "message": "Configurer le serveur MCP", - "description": "The generated-index page title for category Configure MCP server in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.SDK references": { - "message": "Références SDK", - "description": "The label for category SDK references in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.SDK references.link.generated-index.title": { - "message": "Références SDK de MCP Auth", - "description": "The generated-index page title for category SDK references in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.SDK references.link.generated-index.description": { - "message": "Informations sur les classes, méthodes et propriétés extraites des SDK MCP Auth.\n", - "description": "The generated-index page description for category SDK references in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.Node.js SDK": { - "message": "SDK Node.js", - "description": "The label for category Node.js SDK in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.classes": { - "message": "classes", - "description": "The label for category classes in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.functions": { - "message": "fonctions", - "description": "The label for category functions in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.type-aliases": { - "message": "alias de types", - "description": "The label for category type-aliases in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.variables": { - "message": "variables", - "description": "The label for category variables in sidebar docsSidebar" - } -} diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/README.mdx b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/README.mdx deleted file mode 100644 index 967af08..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/README.mdx +++ /dev/null @@ -1,242 +0,0 @@ ---- -sidebar_position: 1 -sidebar_label: Commencer ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -# Commencer - -## Choisir un fournisseur compatible OAuth 2.1 ou OpenID Connect \{#choose-a-compatible-oauth-2-1-or-openid-connect-provider} - -La spécification MCP comporte certaines [exigences spécifiques](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization#1-3-standards-compliance) pour l'autorisation : - -- [OAuth 2.1 IETF DRAFT](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12) -- Métadonnées du serveur d'autorisation OAuth 2.0 ([RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)) -- Protocole d'enregistrement dynamique du client OAuth 2.0 ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) - -Bien que les deux derniers ne soient pas obligatoires, le premier est nécessaire pour garantir une implémentation sécurisée et conforme. - -:::note -Dans le nouveau projet de spécification MCP, la RFC 8414 sera obligatoire pour les serveurs d'autorisation (fournisseurs). Nous mettrons à jour la documentation une fois le nouveau projet finalisé. -::: - -Vous pouvez consulter la [liste des fournisseurs compatibles MCP](/provider-list) pour vérifier si votre fournisseur est pris en charge. - -## Installer MCP Auth SDK \{#install-mcp-auth-sdk} - -MCP Auth est disponible pour Python et TypeScript. Faites-nous savoir si vous avez besoin d'un support pour un autre langage ou framework ! - - - - -```bash -pip install mcpauth -``` - -Ou tout autre gestionnaire de paquets que vous préférez, comme pipenv ou poetry. - - - - -```bash -npm install mcp-auth -``` - -Ou tout autre gestionnaire de paquets que vous préférez, comme pnpm ou yarn. - - - - -## Initialiser MCP Auth \{#init-mcp-auth} - -La première étape consiste à initialiser l'instance MCP Auth avec les métadonnées du serveur d'autorisation de votre fournisseur. Si votre fournisseur est conforme à l'une des spécifications suivantes : - -- [Métadonnées du serveur d'autorisation OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8414) -- [Découverte OpenID Connect](https://openid.net/specs/openid-connect-discovery-1_0.html) - -Vous pouvez utiliser la fonction intégrée pour récupérer les métadonnées et initialiser l'instance MCP Auth : - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -mcp_auth = MCPAuth( - server=fetch_server_config( - '', - type=AuthServerType.OIDC # ou AuthServerType.OAUTH - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { type: 'oidc' }), // ou 'oauth' -}); -``` - - - - -Si vous devez spécifier manuellement l'URL des métadonnées ou les points de terminaison, consultez [Autres façons d'initialiser MCP Auth](./configure-server/mcp-auth.mdx#other-ways). - -## Monter le point de terminaison des métadonnées \{#mount-the-metadata-endpoint} - -Pour se conformer à la spécification MCP actuelle, MCP Auth monte le point de terminaison des métadonnées du serveur d'autorisation OAuth 2.0 (`/.well-known/oauth-authorization-server`) sur votre serveur MCP : - - - - -```python -from starlette.applications import Starlette - -app = Starlette(routes=[ - mcp_auth.metadata_route(), -]) -``` - - - - -```ts -import express from 'express'; - -const app = express(); -app.use(mcpAuth.delegatedRouter()); -``` - - - - -Les URLs dans les métadonnées sont conservées telles quelles, de sorte que le rôle de serveur d'autorisation est entièrement délégué au fournisseur. Vous pouvez tester le point de terminaison des métadonnées en visitant `/.well-known/oauth-authorization-server` sur votre serveur MCP. - -### Pourquoi uniquement le point de terminaison des métadonnées ? \{#why-only-the-metadata-endpoint} - -Vous pouvez voir que les SDK officiels fournissent un routeur d'authentification qui monte des points de terminaison d'autorisation comme `/authorize`, `/token`, etc. Voici pourquoi nous ne faisons pas cela : - -1. Monter uniquement le point de terminaison des métadonnées vous permet de tirer parti de toutes les capacités de votre fournisseur sans "réinventer la roue" et sans injecter de complexité inutile dans votre serveur MCP. -2. Il y a également un effort en cours pour faire évoluer [le rôle du serveur MCP vers un serveur de ressources](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/205) et exiger les métadonnées des ressources protégées OAuth 2.0 ([RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728)). Ce qui signifie que le serveur MCP **ne gérera plus aucune logique d'autorisation** (y compris le point de terminaison des métadonnées), mais servira uniquement de serveur de ressources qui s'appuie sur le fournisseur pour l'authentification et l'autorisation. - -:::note -Nous mettrons à jour MCP Auth pour prendre en charge la nouvelle spécification MCP lorsqu'elle sera finalisée. En attendant, vous pouvez utiliser la version actuelle qui est compatible avec la spécification en vigueur. -::: - -## Utiliser le middleware Bearer auth \{#use-the-bearer-auth-middleware} - -Une fois l'instance MCP Auth initialisée, vous pouvez appliquer le middleware Bearer auth pour protéger vos routes MCP : - - - - -```python -from starlette.applications import Starlette -from starlette.middleware import Middleware -from starlette.routing import Mount -from mcpauth import MCPAuth -from mcp.server.fastmcp import FastMCP - -mcp = FastMCP() -mcp_auth = MCPAuth( - # Initialiser avec la configuration de votre serveur d'authentification -) -bearer_auth = mcp_auth.bearer_auth_middleware( - "jwt", required_scopes=["read", "write"] -) - -app = Starlette(routes=[ - mcp_auth.metadata_route(), - Mount( - "/", - app=mcp.sse_app(), - middleware=[Middleware(bearer_auth)], - ), -]) -``` - - - - -```ts -import express from 'express'; -import { MCPAuth } from 'mcp-auth'; - -const app = express(); -const server = new McpServer(/* ... */); -const mcpAuth = new MCPAuth({ - /* ... */ -}); - -app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] })); -``` - - - - -Dans l'exemple ci-dessus, nous avons spécifié le type de jeton `jwt` et requis les portées `read` et `write`. Cela validera automatiquement le JWT (JSON Web Token) et remplira un objet avec les informations de l'utilisateur authentifié. - -:::info -Vous n'avez jamais entendu parler de JWT (JSON Web Token) ? Pas d'inquiétude, vous pouvez continuer à lire la documentation et nous l'expliquerons en temps voulu. Vous pouvez également consulter [Auth Wiki](https://auth.wiki/jwt) pour une introduction rapide. -::: - -Pour plus d'informations sur la configuration de Bearer auth, consultez [Configurer Bearer auth](./configure-server/bearer-auth.mdx). - -## Récupérer les informations d'authentification dans votre implémentation MCP \{#retrieve-the-auth-info-in-your-mcp-implementation} - -Une fois le middleware Bearer auth appliqué, vous pouvez accéder aux informations de l'utilisateur (ou de l'identité) authentifié dans votre implémentation MCP : - - - - -MCP Auth stockera les informations de l'utilisateur authentifié dans une variable de contexte après une authentification réussie une fois le middleware Bearer auth appliqué. Vous pouvez y accéder dans vos gestionnaires d'outils MCP comme ceci : - -```python -from mcp.server.fastmcp import FastMCP - -mcp = FastMCP() -mcp_auth = MCPAuth( - # Initialiser avec la configuration de votre serveur d'authentification -) - -@mcp.tool() -def add(a: int, b: int): - """ - Un outil qui additionne deux nombres. - Les informations de l'utilisateur authentifié seront disponibles dans le contexte. - """ - auth_info = mcp_auth.auth_info # Accéder aux informations d'authentification dans le contexte actuel - if auth_info: - print(f"Utilisateur authentifié : {auth_info.claims}") - return a + b -``` - - - - -Le deuxième argument du gestionnaire d'outil contiendra l'objet `authInfo`, qui inclut les informations de l'utilisateur authentifié : - -```ts -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; -import { z } from 'zod'; - -const server = new McpServer(/* ... */); -server.tool('add', { a: z.number(), b: z.number() }, async ({ a, b }, { authInfo }) => { - // Vous pouvez maintenant utiliser l'objet `authInfo` pour accéder aux informations authentifiées -}); -``` - - - - -## Prochaines étapes \{#next-steps} - -Continuez la lecture pour découvrir un exemple de bout en bout sur la façon d'intégrer MCP Auth à votre serveur MCP, et comment gérer le flux d'authentification dans les clients MCP. diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/comparison.mdx b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/comparison.mdx deleted file mode 100644 index 77bef6e..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/comparison.mdx +++ /dev/null @@ -1,80 +0,0 @@ ---- -sidebar_position: 101 -sidebar_label: Comparaison ---- - -# Choisir entre MCP Auth et d'autres solutions - -L'écosystème MCP évolue. À mesure que la spécification Model Context Protocol (MCP) passe de l’approche « serveur d’autorisation » au nouveau modèle « serveur de ressources + IdP tiers », il est important de comprendre comment les différentes solutions d’intégration s’inscrivent, aujourd’hui et à l’avenir. - -Cette page présente les principales différences entre mcp-auth et d’autres solutions populaires, afin de vous aider à choisir la meilleure approche pour votre projet. - -## Contexte : Approche proxy vs. intégration IdP \{#background-proxy-approach-vs-idp-integration} - -La plupart des solutions d’auth MCP existantes utilisent une « approche proxy ». Dans ce modèle, le serveur MCP relaie les requêtes d’autorisation à un fournisseur d’identité (IdP) tiers, agissant ainsi comme un intermédiaire entre le client et l’IdP. - -**Approche proxy ([spécification 03-26](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization))** - -```mermaid -sequenceDiagram - participant Client - participant MCP_Server as Serveur MCP - participant ThirdParty_IdP as IdP tiers - - Client->>MCP_Server: Requête d’autorisation - MCP_Server->>ThirdParty_IdP: Relais de la requête - ThirdParty_IdP->>MCP_Server: Réponse - MCP_Server->>Client: Réponse - Client->>MCP_Server: Accès à la ressource - alt Validation à distance - MCP_Server->>ThirdParty_IdP: Validation du jeton - ThirdParty_IdP->>MCP_Server: Jeton valide - else Validation locale - MCP_Server->>MCP_Server: Validation locale du jeton (ex. : JWK en cache) - end - MCP_Server->>Client: Données de la ressource -``` - -Bien que cela fonctionne avec la spécification MCP actuelle (2025-03-26), il s’agit essentiellement d’un contournement. Cela suppose que le serveur MCP agira également comme serveur d’autorisation, ce qui n’est pas la direction de la dernière version du projet de spécification. - -**MCP Auth / future spec (serveur de ressources + IdP tiers)** - -```mermaid -sequenceDiagram - participant Client - participant MCP_Server as Serveur MCP - participant ThirdParty_IdP as IdP tiers - - Client->>ThirdParty_IdP: Requête d’autorisation - ThirdParty_IdP->>Client: Jeton - Client->>MCP_Server: Accès à la ressource (avec jeton) - alt Validation à distance - MCP_Server->>ThirdParty_IdP: Validation du jeton - ThirdParty_IdP->>MCP_Server: Jeton valide - else Validation locale - MCP_Server->>MCP_Server: Validation locale du jeton (ex. : JWK en cache) - end - MCP_Server->>Client: Données de la ressource -``` - -La prochaine spécification MCP [transfère la responsabilité de l’autorisation à un IdP tiers dédié](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/205). Dans ce modèle, le serveur MCP agit uniquement comme serveur de ressources, et tous les points de terminaison d’autorisation proviennent directement de l’IdP tiers. - -## Pourquoi choisir MCP Auth ? \{#why-choose-mcp-auth} - -- Alignement sur la spécification : MCP Auth suit directement la direction du dernier projet de spécification, ce qui en fait la seule solution compatible à la fois avec la spécification 03-26 et la future spécification. -- Plus de contournements : Au lieu d’agir comme un proxy de serveur d’autorisation, MCP Auth laisse l’IdP tiers gérer toute l’autorisation, comme prévu dans la nouvelle spécification. -- Indépendant du fournisseur : MCP Auth fonctionne avec tout fournisseur OAuth 2.0 / OIDC conforme aux standards. -- Transition en douceur : MCP Auth retourne tous les points de terminaison tiers tels quels via les métadonnées du serveur d’autorisation OAuth 2.0. Cela simplifie l’intégration aujourd’hui et la prépare aux évolutions futures. -- Expérience développeur : Propose des tutoriels, des utilitaires et des fonctionnalités à venir comme [OAuth 2.0 Protected Resource Metadata](https://auth.wiki/protected-resource-metadata) pour faciliter la vie des développeurs de serveurs MCP. - -| Fonctionnalité | Solutions proxy | MCP Auth | -| ----------------------------------- | -------------------- | -------- | -| Fonctionne avec la spécification 03-26 | ✅ | ✅ | -| Fonctionne avec la future spécification | ❌ | ✅ | -| Prend en charge les IdP tiers directement | ❌ (contournement uniquement) | ✅ | -| Indépendant du fournisseur | Limité[^1] | Oui | -| Prêt pour la transition | ❌ | ✅ | - -Si vous devez prendre en charge des IdP tiers dès maintenant et souhaitez être prêt pour la future spécification, MCP Auth est la solution recommandée. Les approches basées sur un proxy pourraient bientôt être dépréciées ou nécessiter une refonte importante. - -[^1]: Certaines solutions proxy peuvent coder en dur des paramètres ou points de terminaison spécifiques, limitant ainsi la flexibilité. diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/configure-server/bearer-auth.mdx b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/configure-server/bearer-auth.mdx deleted file mode 100644 index c06fe8e..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/configure-server/bearer-auth.mdx +++ /dev/null @@ -1,250 +0,0 @@ ---- -sidebar_position: 2 -sidebar_label: Auth Bearer ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -# Configurer l’auth Bearer dans le serveur MCP - -MCP Auth propose différentes façons de configurer l’Autorisation Bearer dans votre serveur MCP : - -- Mode [JWT (JSON Web Token)](https://auth.wiki/jwt) : Une méthode d’autorisation intégrée qui vérifie les JWT avec des assertions de revendications (claims). -- Mode personnalisé : Vous permet d’implémenter votre propre logique d’autorisation. - -## Configurer l’auth Bearer avec le mode JWT \{#configure-bearer-auth-with-jwt-mode} - -Si votre fournisseur OAuth / OIDC émet des JWT pour l’autorisation, vous pouvez utiliser le mode JWT intégré dans MCP Auth. Il vérifie la signature du JWT, l’expiration et d’autres revendications que vous spécifiez ; puis il renseigne les informations d’authentification dans le contexte de la requête pour un traitement ultérieur dans votre implémentation MCP. - -### Validation de la portée (Scope) \{#scope-validation} - -Voici un exemple de validation de portée de base : - - - - -```python -from mcpauth import MCPAuth -from starlette.applications import Starlette -from starlette.middleware import Middleware -from starlette.routing import Mount -from mcp.server.fastmcp import FastMCP - -mcp = FastMCP("MyMCPServer") -mcp_auth = MCPAuth( - # Initialize with your auth server config -) -bearer_auth = mcp_auth.bearer_auth_middleware("jwt", required_scopes=["read", "write"]) # [!code highlight] - -app = Starlette( - routes=[Mount('/', app=mcp.sse_app(), middleware=[Middleware(bearer_auth)])] -) -``` - - - - -```ts -import express from 'express'; -import { MCPAuth } from 'mcp-auth'; - -const app = express(); -const mcpAuth = new MCPAuth({ - /* ... */ -}); -const bearerAuth = mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }); // [!code highlight] - -app.use('/mcp', bearerAuth, (req, res) => { - // Now `req.auth` contains the auth info - console.log(req.auth); -}); -``` - - - - -Dans l’exemple ci-dessus, nous avons spécifié que le JWT nécessite les portées (scopes) `read` et `write`. Si le JWT ne contient **aucune** de ces portées, la requête sera rejetée avec une erreur 403 Forbidden. - -### Validation de l’indicateur de ressource (RFC 8707) \{#resource-indicator-validation-rfc-8707} - -Si votre fournisseur est basé sur OIDC, ou prend en charge l’extension [Indicateur de ressource (Resource Indicator)](https://datatracker.ietf.org/doc/html/rfc8707), vous pouvez également spécifier l’option `audience` pour valider la revendication `aud` (audience) dans le JWT. Ceci est utile pour s’assurer que le JWT est destiné à votre serveur MCP. - -Consultez la documentation de votre fournisseur pour vérifier s’il prend en charge l’extension Indicateur de ressource et comment la configurer. Certains fournisseurs peuvent utiliser d’autres termes comme "audience", "ressource API" ou "indicateur API" pour désigner le même concept. - -Une fois l’indicateur de ressource configuré, vous pouvez le spécifier dans le middleware `bearerAuth` : - - - - -```python -bearer_auth = mcp_auth.bearer_auth_middleware( - "jwt", - audience="https://api.example.com/mcp", # L’audience attendue pour le JWT [!code highlight] - required_scopes=["read", "write"] -) -``` - - - - -```ts -const bearerAuth = mcpAuth.bearerAuth('jwt', { - audience: 'https://api.example.com/mcp', // L’audience attendue pour le JWT [!code highlight] - requiredScopes: ['read', 'write'], -}); -``` - - - - -Dans l’exemple ci-dessus, MCP Auth validera **à la fois** la revendication `aud` dans le JWT et les portées requises. - -### Fournir des options personnalisées à la vérification du JWT \{#provide-custom-options-to-the-jwt-verification} - -Vous pouvez également fournir des options personnalisées à la bibliothèque de vérification JWT sous-jacente : - - - - -Dans le SDK Python, nous utilisons [PyJWT](https://pyjwt.readthedocs.io/en/stable/) pour la vérification des JWT. Vous pouvez utiliser les options suivantes : - -- `leeway` : Autorise une certaine marge lors de la vérification de l’expiration du JWT (en secondes). La valeur par défaut est de 60 secondes. - -```python -bearer_auth = mcp_auth.bearer_auth_middleware( - "jwt", - audience="https://api.example.com/mcp", - required_scopes=["read", "write"] - leeway=10, # Réduit le décalage d’horloge en autorisant 10 secondes de marge [!code highlight] -) -``` - - - - -Dans le SDK Node.js, nous utilisons la bibliothèque [jose](https://github.com/panva/jose) pour la vérification des JWT. Vous pouvez fournir les options suivantes : - -- `jwtVerify` : Options pour le processus de vérification JWT (fonction `jwtVerify` de `jose`). -- `remoteJwtSet` : Options pour la récupération du jeu JWT distant (fonction `createRemoteJWKSet` de `jose`). - -```ts {4-9} -const bearerAuth = mcpAuth.bearerAuth('jwt', { - audience: 'https://api.example.com/mcp', - requiredScopes: ['read', 'write'], - jwtVerify: { - clockTolerance: 60, // Autorise un décalage d’horloge de 60 secondes - }, - remoteJwtSet: { - timeoutDuration: 10 * 1000, // Délai de 10 secondes pour la récupération du jeu JWT distant - }, -}); -``` - - - - -## Configurer l’auth Bearer avec une vérification personnalisée \{#configure-bearer-auth-with-custom-verification} - -Si votre fournisseur OAuth / OIDC n’émet pas de JWT, ou si vous souhaitez implémenter votre propre logique d’autorisation, MCP Auth vous permet de créer une fonction de vérification personnalisée : - -:::info -Étant donné que le middleware d’auth Bearer vérifiera l’émetteur (`iss`), l’audience (`aud`) et les portées requises (`scope`) avec le résultat de la vérification fourni, il n’est pas nécessaire d’implémenter ces vérifications dans votre fonction de vérification personnalisée. Vous pouvez vous concentrer sur la vérification de la validité du jeton (par exemple, signature, expiration, etc.) et le retour de l’objet d’informations d’authentification. -::: - - - - -```python -from mcpauth.exceptions import MCPAuthJwtVerificationException, MCPAuthJwtVerificationExceptionCode -from mcpauth.types import AuthInfo - -async def custom_verification(token: str) -> AuthInfo: - # Implémentez ici votre logique de vérification personnalisée - info = await verify_token(token) - if not info: - raise MCPAuthJwtVerificationException( - MCPAuthJwtVerificationExceptionCode.JWT_VERIFICATION_FAILED - ) - return info # Retournez l’objet d’informations d’authentification - -bearer_auth = mcp_auth.bearer_auth_middleware( - custom_verification, - required_scopes=["read", "write"] -) -``` - - - - -```ts -const bearerAuth = mcpAuth.bearerAuth( - async (token) => { - // Implémentez ici votre logique de vérification personnalisée - const info = await verifyToken(token); - if (!info) { - throw new MCPAuthJwtVerificationError('jwt_verification_failed'); - } - return info; // Retournez l’objet d’informations d’authentification - }, - { requiredScopes: ['read', 'write'] } -); -``` - - - - -## Appliquer l’auth Bearer dans votre serveur MCP \{#apply-bearer-auth-in-your-mcp-server} - -Pour protéger votre serveur MCP avec l’auth Bearer, vous devez appliquer le middleware d’auth Bearer à votre instance de serveur MCP. - - - - -```python -bearer_auth = mcp_auth.bearer_auth_middleware("jwt", required_scopes=["read", "write"]) -app = Starlette( - routes=[Mount('/', app=mcp.sse_app(), middleware=[Middleware(bearer_auth)])] -) -``` - - - - -```js -const app = express(); -app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] })); -``` - - - - -Cela garantira que toutes les requêtes entrantes sont authentifiées et autorisées selon les paramètres d’auth Bearer configurés, et que les informations d’authentification seront disponibles dans le contexte de la requête. - -Vous pouvez ensuite accéder à ces informations dans votre implémentation du serveur MCP : - - - - -```python -@mcp.tool() -async def whoami() -> dict: - # `mcp_auth.auth_info` est l’objet de contexte pour la requête en cours - auth_info = mcp_auth.auth_info - print(f"Utilisateur authentifié : {auth_info.subject}") - return {"subject": auth_info.subject} -``` - - - - -```js -// `authInfo` sera transmis depuis l’objet `req.auth` -server.tool('whoami', ({ authInfo }) => { - console.log(`Utilisateur authentifié : ${authInfo.subject}`); - return { subject: authInfo.subject }; -}); -``` - - - diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/configure-server/mcp-auth.mdx b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/configure-server/mcp-auth.mdx deleted file mode 100644 index 3a8f5ba..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/configure-server/mcp-auth.mdx +++ /dev/null @@ -1,208 +0,0 @@ ---- -sidebar_position: 1 -sidebar_label: MCP Auth ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -# Configurer MCP Auth sur le serveur MCP - -Pour connecter votre serveur MCP à un fournisseur OAuth 2.1 ou OpenID Connect, vous devez configurer l’instance MCP Auth. Cela implique d’initialiser l’instance avec les métadonnées du serveur d’autorisation de votre fournisseur et de mettre en place les flux d’autorisation nécessaires. - -## Initialiser MCP Auth \{#init-mcp-auth} - -### Récupération automatique des métadonnées \{#automatic-metadata-fetching} - -La façon la plus simple d’initialiser l’instance MCP Auth est d’utiliser les fonctions intégrées qui récupèrent les métadonnées à partir d’une URL bien connue. Si votre fournisseur est conforme à l’une des normes suivantes : - -- [Métadonnées du serveur d’autorisation OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8414) -- [Découverte OpenID Connect](https://openid.net/specs/openid-connect-discovery-1_0.html) - -Vous pouvez utiliser `fetchServerConfig` pour récupérer automatiquement les métadonnées en fournissant l’URL de l’`issuer` : - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType, fetch_server_config - -mcp_auth = MCPAuth( - server=fetch_server_config( - '', - type=AuthServerType.OIDC # ou AuthServerType.OAUTH - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { type: 'oidc' }), // ou 'oauth' -}); -``` - - - - -Si votre issuer inclut un chemin, le comportement diffère légèrement entre OAuth 2.0 et OpenID Connect : - -- **OAuth 2.0** : L’URL bien connue est ajoutée au **domaine** de l’issuer. Par exemple, si votre issuer est `https://my-project.logto.app/oauth`, l’URL bien connue sera `https://auth.logto.io/.well-known/oauth-authorization-server/oauth`. -- **OpenID Connect** : L’URL bien connue est ajoutée directement à l’**issuer**. Par exemple, si votre issuer est `https://my-project.logto.app/oidc`, l’URL bien connue sera `https://auth.logto.io/oidc/.well-known/openid-configuration`. - -### Autres méthodes d’initialisation de MCP Auth \{#other-ways} - -#### Transpilation personnalisée des données \{#custom-data-transpilation} - -Dans certains cas, les métadonnées renvoyées par le fournisseur peuvent ne pas être conformes au format attendu. Si vous êtes certain que le fournisseur est conforme, vous pouvez utiliser l’option `transpile_data` pour modifier les métadonnées avant leur utilisation : - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -mcp_auth = MCPAuth( - server=fetch_server_config( - '', - type=AuthServerType.OIDC, - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { - type: 'oidc', - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - - -Cela vous permet de modifier l’objet de métadonnées avant qu’il ne soit utilisé par MCP Auth. Par exemple, vous pouvez ajouter ou supprimer des champs, modifier leurs valeurs ou les convertir dans un autre format. - -#### Récupérer les métadonnées depuis une URL spécifique \{#fetch-metadata-from-a-specific-url} - -Si votre fournisseur dispose d’une URL de métadonnées spécifique plutôt que des URLs standard, vous pouvez l’utiliser de manière similaire : - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config_by_well_known_url - -mcp_auth = MCPAuth( - server=fetch_server_config_by_well_known_url( - '', - type=AuthServerType.OIDC # ou AuthServerType.OAUTH - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfigByWellKnownUrl } from 'mcp-auth'; - -const mcpAuth = new MCPAuth({ - server: await fetchServerConfigByWellKnownUrl('', { type: 'oidc' }), // ou 'oauth' -}); -``` - - - - -#### Récupérer les métadonnées depuis une URL spécifique avec transpilation personnalisée \{#fetch-metadata-from-a-specific-url-with-custom-data-transpilation} - -Dans certains cas, la réponse du fournisseur peut être mal formée ou non conforme au format de métadonnées attendu. Si vous êtes certain que le fournisseur est conforme, vous pouvez transpiler les métadonnées via l’option de configuration : - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType, fetch_server_config_by_well_known_url - -mcp_auth = MCPAuth( - server=fetch_server_config_by_well_known_url( - '', - type=AuthServerType.OIDC, - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: await fetchServerConfigByWellKnownUrl('', { - type: 'oidc', - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - - -#### Fournir manuellement les métadonnées \{#manually-provide-metadata} - -Si votre fournisseur ne prend pas en charge la récupération des métadonnées, vous pouvez fournir manuellement l’objet de métadonnées : - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerConfig, AuthServerType, AuthorizationServerMetadata - -mcp_auth = MCPAuth( - server=AuthServerConfig( - type=AuthServerType.OIDC, # ou AuthServerType.OAUTH - metadata=AuthorizationServerMetadata( - issuer='', - authorization_endpoint='', - # ... autres champs de métadonnées - ), - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: { - metadata: { - issuer: '', - // Les champs de métadonnées doivent être en camelCase - authorizationEndpoint: '', - // ... autres champs de métadonnées - }, - type: 'oidc', // ou 'oauth' - }, -}); -``` - - - diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/README.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/README.md deleted file mode 100644 index 8ec1c38..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/README.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -sidebar_label: SDK Node.js ---- - -# Référence du SDK MCP Auth Node.js - -## Classes {#classes} - -- [MCPAuth](/references/js/classes/MCPAuth.md) -- [MCPAuthAuthServerError](/references/js/classes/MCPAuthAuthServerError.md) -- [MCPAuthBearerAuthError](/references/js/classes/MCPAuthBearerAuthError.md) -- [MCPAuthConfigError](/references/js/classes/MCPAuthConfigError.md) -- [MCPAuthError](/references/js/classes/MCPAuthError.md) -- [MCPAuthTokenVerificationError](/references/js/classes/MCPAuthTokenVerificationError.md) - -## Alias de types {#type-aliases} - -- [AuthorizationServerMetadata](/references/js/type-aliases/AuthorizationServerMetadata.md) -- [AuthServerConfig](/references/js/type-aliases/AuthServerConfig.md) -- [AuthServerConfigError](/references/js/type-aliases/AuthServerConfigError.md) -- [AuthServerConfigErrorCode](/references/js/type-aliases/AuthServerConfigErrorCode.md) -- [AuthServerConfigWarning](/references/js/type-aliases/AuthServerConfigWarning.md) -- [AuthServerConfigWarningCode](/references/js/type-aliases/AuthServerConfigWarningCode.md) -- [AuthServerErrorCode](/references/js/type-aliases/AuthServerErrorCode.md) -- [AuthServerSuccessCode](/references/js/type-aliases/AuthServerSuccessCode.md) -- [AuthServerType](/references/js/type-aliases/AuthServerType.md) -- [BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) -- [BearerAuthErrorCode](/references/js/type-aliases/BearerAuthErrorCode.md) -- [BearerAuthJwtConfig](/references/js/type-aliases/BearerAuthJwtConfig.md) -- [CamelCaseAuthorizationServerMetadata](/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md) -- [MCPAuthBearerAuthErrorDetails](/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md) -- [MCPAuthConfig](/references/js/type-aliases/MCPAuthConfig.md) -- [MCPAuthTokenVerificationErrorCode](/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md) -- [VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) -- [VerifyAccessTokenMode](/references/js/type-aliases/VerifyAccessTokenMode.md) - -## Variables {#variables} - -- [authorizationServerMetadataSchema](/references/js/variables/authorizationServerMetadataSchema.md) -- [authServerErrorDescription](/references/js/variables/authServerErrorDescription.md) -- [bearerAuthErrorDescription](/references/js/variables/bearerAuthErrorDescription.md) -- [camelCaseAuthorizationServerMetadataSchema](/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md) -- [serverMetadataPaths](/references/js/variables/serverMetadataPaths.md) -- [tokenVerificationErrorDescription](/references/js/variables/tokenVerificationErrorDescription.md) -- [validateServerConfig](/references/js/variables/validateServerConfig.md) - -## Fonctions {#functions} - -- [createVerifyJwt](/references/js/functions/createVerifyJwt.md) -- [fetchServerConfig](/references/js/functions/fetchServerConfig.md) -- [fetchServerConfigByWellKnownUrl](/references/js/functions/fetchServerConfigByWellKnownUrl.md) -- [handleBearerAuth](/references/js/functions/handleBearerAuth.md) diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuth.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuth.md deleted file mode 100644 index 3aa7805..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuth.md +++ /dev/null @@ -1,195 +0,0 @@ ---- -sidebar_label: MCPAuth ---- - -# Classe : MCPAuth - -La classe principale de la bibliothèque mcp-auth, qui fournit des méthodes pour créer des routeurs et des gestionnaires utiles pour l’authentification (Authentification) et l’autorisation (Autorisation) sur les serveurs MCP. - -## Voir {#see} - -[MCP Auth](https://mcp-auth.dev) pour plus d’informations sur la bibliothèque et son utilisation. - -## Exemple {#example} - -Un exemple d’intégration avec un fournisseur OIDC distant : - -```ts -import express from 'express'; -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const app = express(); -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig( - 'https://auth.logto.io/oidc', - { type: 'oidc' } - ), -}); - -// Monter le routeur pour gérer les métadonnées du serveur d’autorisation OAuth 2.0 -app.use(mcpAuth.delegatedRouter()); - -// Utiliser le gestionnaire d’authentification Bearer sur la route MCP -app.get( - '/mcp', - mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }), - (req, res) => { - console.log('Auth info:', req.auth); - // Traiter la requête MCP ici - }, -); - -// Utiliser les informations d’authentification dans le callback MCP -server.tool( - 'add', - { a: z.number(), b: z.number() }, - async ({ a, b }, { authInfo }) => { - console.log('Auth Info:', authInfo); - // ... - }, -); -``` - -## Constructeurs {#constructors} - -### Constructeur {#constructor} - -```ts -new MCPAuth(config: MCPAuthConfig): MCPAuth; -``` - -#### Paramètres {#parameters} - -##### config {#config} - -[`MCPAuthConfig`](/references/js/type-aliases/MCPAuthConfig.md) - -#### Retourne {#returns} - -`MCPAuth` - -## Propriétés {#properties} - -### config {#config} - -```ts -readonly config: MCPAuthConfig; -``` - -## Méthodes {#methods} - -### bearerAuth() {#bearerauth} - -#### Signature d’appel {#call-signature} - -```ts -bearerAuth(verifyAccessToken: VerifyAccessTokenFunction, config?: Omit): RequestHandler; -``` - -Crée un gestionnaire d’authentification Bearer (middleware Express) qui vérifie le jeton d’accès (Jeton d’accès) dans l’en-tête `Authorization` de la requête. - -##### Paramètres {#parameters} - -###### verifyAccessToken {#verifyaccesstoken} - -[`VerifyAccessTokenFunction`](/references/js/type-aliases/VerifyAccessTokenFunction.md) - -Une fonction qui vérifie le jeton d’accès (Jeton d’accès). Elle doit accepter le jeton d’accès sous forme de chaîne de caractères et retourner une promesse (ou une valeur) qui se résout avec le résultat de la vérification. - -**Voir** - -[VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) pour la définition du type de la fonction `verifyAccessToken`. - -###### config? {#config} - -`Omit`\<[`BearerAuthConfig`](/references/js/type-aliases/BearerAuthConfig.md), `"verifyAccessToken"` \| `"issuer"`\> - -Configuration optionnelle pour le gestionnaire d’authentification Bearer. - -**Voir** - -[BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) pour les options de configuration disponibles (à l’exception de `verifyAccessToken` et `issuer`). - -##### Retourne {#returns} - -`RequestHandler` - -Une fonction middleware Express qui vérifie le jeton d’accès (Jeton d’accès) et ajoute le résultat de la vérification à l’objet requête (`req.auth`). - -##### Voir {#see} - -[handleBearerAuth](/references/js/functions/handleBearerAuth.md) pour les détails d’implémentation et les types étendus de l’objet `req.auth` (`AuthInfo`). - -#### Signature d’appel {#call-signature} - -```ts -bearerAuth(mode: "jwt", config?: Omit & BearerAuthJwtConfig): RequestHandler; -``` - -Crée un gestionnaire d’authentification Bearer (middleware Express) qui vérifie le jeton d’accès (Jeton d’accès) dans l’en-tête `Authorization` de la requête en utilisant un mode de vérification prédéfini. - -En mode `'jwt'`, le gestionnaire créera une fonction de vérification JWT à l’aide du JWK Set provenant de l’URI JWKS du serveur d’autorisation (Émetteur). - -##### Paramètres {#parameters} - -###### mode {#mode} - -`"jwt"` - -Le mode de vérification pour le jeton d’accès (Jeton d’accès). Actuellement, seul 'jwt' est pris en charge. - -**Voir** - -[VerifyAccessTokenMode](/references/js/type-aliases/VerifyAccessTokenMode.md) pour les modes disponibles. - -###### config? {#config} - -`Omit`\<[`BearerAuthConfig`](/references/js/type-aliases/BearerAuthConfig.md), `"verifyAccessToken"` \| `"issuer"`\> & [`BearerAuthJwtConfig`](/references/js/type-aliases/BearerAuthJwtConfig.md) - -Configuration optionnelle pour le gestionnaire d’authentification Bearer, incluant les options de vérification JWT et les options du JWK Set distant. - -**Voir** - - - [BearerAuthJwtConfig](/references/js/type-aliases/BearerAuthJwtConfig.md) pour les options de configuration disponibles pour la vérification JWT. - - [BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) pour les options de configuration disponibles (à l’exception de `verifyAccessToken` et `issuer`). - -##### Retourne {#returns} - -`RequestHandler` - -Une fonction middleware Express qui vérifie le jeton d’accès (Jeton d’accès) et ajoute le résultat de la vérification à l’objet requête (`req.auth`). - -##### Voir {#see} - -[handleBearerAuth](/references/js/functions/handleBearerAuth.md) pour les détails d’implémentation et les types étendus de l’objet `req.auth` (`AuthInfo`). - -##### Lève {#throws} - -si l’URI JWKS n’est pas fourni dans les métadonnées du serveur lors de l’utilisation du mode `'jwt'`. - -*** - -### delegatedRouter() {#delegatedrouter} - -```ts -delegatedRouter(): Router; -``` - -Crée un routeur délégué qui sert le point de terminaison des métadonnées du serveur d’autorisation OAuth 2.0 (`/.well-known/oauth-authorization-server`) avec les métadonnées fournies à l’instance. - -#### Retourne {#returns} - -`Router` - -Un routeur qui sert le point de terminaison des métadonnées du serveur d’autorisation OAuth 2.0 avec les métadonnées fournies à l’instance. - -#### Exemple {#example} - -```ts -import express from 'express'; -import { MCPAuth } from 'mcp-auth'; - -const app = express(); -const mcpAuth: MCPAuth; // Supposons qu’il est initialisé -app.use(mcpAuth.delegatedRouter()); -``` diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthAuthServerError.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthAuthServerError.md deleted file mode 100644 index 23a1808..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthAuthServerError.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -sidebar_label: MCPAuthAuthServerError ---- - -# Classe : MCPAuthAuthServerError - -Erreur levée lorsqu'il y a un problème avec le serveur d'autorisation distant. - -## Hérite de {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## Constructeurs {#constructors} - -### Constructeur {#constructor} - -```ts -new MCPAuthAuthServerError(code: AuthServerErrorCode, cause?: unknown): MCPAuthAuthServerError; -``` - -#### Paramètres {#parameters} - -##### code {#code} - -[`AuthServerErrorCode`](/references/js/type-aliases/AuthServerErrorCode.md) - -##### cause? {#cause} - -`unknown` - -#### Retourne {#returns} - -`MCPAuthAuthServerError` - -#### Redéfinit {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## Propriétés {#properties} - -### cause? {#cause} - -```ts -readonly optional cause: unknown; -``` - -#### Hérité de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: AuthServerErrorCode; -``` - -Le code d'erreur au format snake_case. - -#### Hérité de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### Hérité de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthAuthServerError'; -``` - -#### Redéfinit {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### Hérité de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -Surcharge optionnelle pour le formatage des traces de pile - -#### Paramètres {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### Retourne {#returns} - -`any` - -#### Voir {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### Hérité de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### Hérité de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## Méthodes {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -Convertit l'erreur en un format JSON adapté à une réponse HTTP. - -#### Paramètres {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -Indique s'il faut inclure la cause de l'erreur dans la réponse JSON. -La valeur par défaut est `false`. - -#### Retourne {#returns} - -`Record`\<`string`, `unknown`\> - -#### Hérité de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -Crée la propriété .stack sur un objet cible - -#### Paramètres {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### Retourne {#returns} - -`void` - -#### Hérité de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthBearerAuthError.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthBearerAuthError.md deleted file mode 100644 index d79595c..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthBearerAuthError.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -sidebar_label: MCPAuthBearerAuthError ---- - -# Classe : MCPAuthBearerAuthError - -Erreur levée lorsqu'il y a un problème lors de l'authentification avec des jetons Bearer. - -## Hérite de {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## Constructeurs {#constructors} - -### Constructeur {#constructor} - -```ts -new MCPAuthBearerAuthError(code: BearerAuthErrorCode, cause?: MCPAuthBearerAuthErrorDetails): MCPAuthBearerAuthError; -``` - -#### Paramètres {#parameters} - -##### code {#code} - -[`BearerAuthErrorCode`](/references/js/type-aliases/BearerAuthErrorCode.md) - -##### cause? {#cause} - -[`MCPAuthBearerAuthErrorDetails`](/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md) - -#### Retourne {#returns} - -`MCPAuthBearerAuthError` - -#### Redéfinit {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## Propriétés {#properties} - -### cause? {#cause} - -```ts -readonly optional cause: MCPAuthBearerAuthErrorDetails; -``` - -#### Hérité de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: BearerAuthErrorCode; -``` - -Le code d'erreur au format snake_case. - -#### Hérité de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### Hérité de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthBearerAuthError'; -``` - -#### Redéfinit {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### Hérité de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -Surcharge optionnelle pour formater les traces de pile - -#### Paramètres {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### Retourne {#returns} - -`any` - -#### Voir {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### Hérité de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### Hérité de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## Méthodes {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -Convertit l'erreur en un format JSON adapté à une réponse HTTP. - -#### Paramètres {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -Indique s'il faut inclure la cause de l'erreur dans la réponse JSON. -Par défaut à `false`. - -#### Retourne {#returns} - -`Record`\<`string`, `unknown`\> - -#### Redéfinit {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -Crée la propriété .stack sur un objet cible - -#### Paramètres {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### Retourne {#returns} - -`void` - -#### Hérité de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthConfigError.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthConfigError.md deleted file mode 100644 index fa4d3e5..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthConfigError.md +++ /dev/null @@ -1,202 +0,0 @@ ---- -sidebar_label: MCPAuthConfigError ---- - -# Classe : MCPAuthConfigError - -Erreur levée lorsqu'il y a un problème de configuration avec mcp-auth. - -## Hérite de {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## Constructeurs {#constructors} - -### Constructeur {#constructor} - -```ts -new MCPAuthConfigError(code: string, message: string): MCPAuthConfigError; -``` - -#### Paramètres {#parameters} - -##### code {#code} - -`string` - -Le code d'erreur au format snake_case. - -##### message {#message} - -`string` - -Une description lisible par l'humain de l'erreur. - -#### Retourne {#returns} - -`MCPAuthConfigError` - -#### Hérité de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## Propriétés {#properties} - -### cause? {#cause} - -```ts -optional cause: unknown; -``` - -#### Hérité de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: string; -``` - -Le code d'erreur au format snake_case. - -#### Hérité de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### Hérité de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthConfigError'; -``` - -#### Redéfini depuis {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### Hérité de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -Surcharge optionnelle pour formater les traces de pile - -#### Paramètres {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### Retourne {#returns} - -`any` - -#### Voir {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### Hérité de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### Hérité de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## Méthodes {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -Convertit l'erreur en un format JSON adapté à une réponse HTTP. - -#### Paramètres {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -Indique s'il faut inclure la cause de l'erreur dans la réponse JSON. -Par défaut à `false`. - -#### Retourne {#returns} - -`Record`\<`string`, `unknown`\> - -#### Hérité de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -Crée la propriété .stack sur un objet cible - -#### Paramètres {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### Retourne {#returns} - -`void` - -#### Hérité de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthError.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthError.md deleted file mode 100644 index 6e73245..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthError.md +++ /dev/null @@ -1,219 +0,0 @@ ---- -sidebar_label: MCPAuthError ---- - -# Classe : MCPAuthError - -Classe de base pour toutes les erreurs mcp-auth. - -Elle fournit un moyen standardisé de gérer les erreurs liées à l’authentification (Authentication) et à l’autorisation (Authorization) MCP. - -## Hérite de {#extends} - -- `Error` - -## Étendue par {#extended-by} - -- [`MCPAuthConfigError`](/references/js/classes/MCPAuthConfigError.md) -- [`MCPAuthAuthServerError`](/references/js/classes/MCPAuthAuthServerError.md) -- [`MCPAuthBearerAuthError`](/references/js/classes/MCPAuthBearerAuthError.md) -- [`MCPAuthTokenVerificationError`](/references/js/classes/MCPAuthTokenVerificationError.md) - -## Constructeurs {#constructors} - -### Constructeur {#constructor} - -```ts -new MCPAuthError(code: string, message: string): MCPAuthError; -``` - -#### Paramètres {#parameters} - -##### code {#code} - -`string` - -Le code d’erreur au format snake_case. - -##### message {#message} - -`string` - -Une description lisible par l’humain de l’erreur. - -#### Retourne {#returns} - -`MCPAuthError` - -#### Redéfinit {#overrides} - -```ts -Error.constructor -``` - -## Propriétés {#properties} - -### cause? {#cause} - -```ts -optional cause: unknown; -``` - -#### Hérité de {#inherited-from} - -```ts -Error.cause -``` - -*** - -### code {#code} - -```ts -readonly code: string; -``` - -Le code d’erreur au format snake_case. - -*** - -### message {#message} - -```ts -message: string; -``` - -#### Hérité de {#inherited-from} - -```ts -Error.message -``` - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthError'; -``` - -#### Redéfinit {#overrides} - -```ts -Error.name -``` - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### Hérité de {#inherited-from} - -```ts -Error.stack -``` - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -Surcharge optionnelle pour le formatage des traces de pile - -#### Paramètres {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### Retourne {#returns} - -`any` - -#### Voir {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### Hérité de {#inherited-from} - -```ts -Error.prepareStackTrace -``` - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### Hérité de {#inherited-from} - -```ts -Error.stackTraceLimit -``` - -## Méthodes {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -Convertit l’erreur au format JSON adapté à une réponse HTTP. - -#### Paramètres {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -Indique s’il faut inclure la cause de l’erreur dans la réponse JSON. -Par défaut à `false`. - -#### Retourne {#returns} - -`Record`\<`string`, `unknown`\> - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -Crée la propriété .stack sur un objet cible - -#### Paramètres {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### Retourne {#returns} - -`void` - -#### Hérité de {#inherited-from} - -```ts -Error.captureStackTrace -``` diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthTokenVerificationError.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthTokenVerificationError.md deleted file mode 100644 index b65c69a..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthTokenVerificationError.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -sidebar_label: MCPAuthTokenVerificationError ---- - -# Classe : MCPAuthTokenVerificationError - -Erreur levée lorsqu'il y a un problème lors de la vérification des jetons. - -## Hérite de {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## Constructeurs {#constructors} - -### Constructeur {#constructor} - -```ts -new MCPAuthTokenVerificationError(code: MCPAuthTokenVerificationErrorCode, cause?: unknown): MCPAuthTokenVerificationError; -``` - -#### Paramètres {#parameters} - -##### code {#code} - -[`MCPAuthTokenVerificationErrorCode`](/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md) - -##### cause? {#cause} - -`unknown` - -#### Retourne {#returns} - -`MCPAuthTokenVerificationError` - -#### Redéfinit {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## Propriétés {#properties} - -### cause? {#cause} - -```ts -readonly optional cause: unknown; -``` - -#### Hérité de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: MCPAuthTokenVerificationErrorCode; -``` - -Le code d'erreur au format snake_case. - -#### Hérité de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### Hérité de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthTokenVerificationError'; -``` - -#### Redéfinit {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### Hérité de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -Surcharge optionnelle pour formater les traces de pile - -#### Paramètres {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### Retourne {#returns} - -`any` - -#### Voir {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### Hérité de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### Hérité de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## Méthodes {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -Convertit l'erreur au format JSON compatible avec une réponse HTTP. - -#### Paramètres {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -Indique s'il faut inclure la cause de l'erreur dans la réponse JSON. -Par défaut à `false`. - -#### Retourne {#returns} - -`Record`\<`string`, `unknown`\> - -#### Hérité de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -Crée la propriété .stack sur un objet cible - -#### Paramètres {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### Retourne {#returns} - -`void` - -#### Hérité de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/createVerifyJwt.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/createVerifyJwt.md deleted file mode 100644 index 1b01722..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/createVerifyJwt.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -sidebar_label: createVerifyJwt ---- - -# Fonction : createVerifyJwt() - -```ts -function createVerifyJwt(getKey: JWTVerifyGetKey, options?: JWTVerifyOptions): VerifyAccessTokenFunction; -``` - -Crée une fonction pour vérifier les jetons d’accès JWT (Access token) en utilisant la fonction de récupération de clé fournie et les options. - -## Paramètres {#parameters} - -### getKey {#getkey} - -`JWTVerifyGetKey` - -La fonction permettant de récupérer la clé utilisée pour vérifier le JWT. - -**Voir** - -JWTVerifyGetKey pour la définition du type de la fonction de récupération de clé. - -### options? {#options} - -`JWTVerifyOptions` - -Options facultatives de vérification du JWT. - -**Voir** - -JWTVerifyOptions pour la définition du type des options. - -## Retourne {#returns} - -[`VerifyAccessTokenFunction`](/references/js/type-aliases/VerifyAccessTokenFunction.md) - -Une fonction qui vérifie les jetons d’accès JWT (Access token) et retourne un objet AuthInfo si le jeton est valide. Elle exige que le JWT contienne les champs `iss`, `client_id` et `sub` dans sa charge utile, et peut éventuellement contenir les champs `scope` ou `scopes`. La fonction utilise la bibliothèque `jose` en interne pour effectuer la vérification du JWT. - -## Voir {#see} - -[VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) pour la définition du type de la fonction retournée. diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfig.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfig.md deleted file mode 100644 index 65b0745..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfig.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -sidebar_label: fetchServerConfig ---- - -# Fonction : fetchServerConfig() - -```ts -function fetchServerConfig(issuer: string, config: ServerMetadataConfig): Promise; -``` - -Récupère la configuration du serveur selon l’émetteur (Issuer) et le type de serveur d’autorisation (Authorization). - -Cette fonction détermine automatiquement l’URL well-known en fonction du type de serveur, car les serveurs OAuth et OpenID Connect ont des conventions différentes pour leurs points de terminaison de métadonnées. - -## Paramètres {#parameters} - -### issuer {#issuer} - -`string` - -L’URL de l’émetteur (Issuer) du serveur d’autorisation (Authorization). - -### config {#config} - -`ServerMetadataConfig` - -L’objet de configuration contenant le type de serveur et une fonction de transpilation optionnelle. - -## Retourne {#returns} - -`Promise`\<[`AuthServerConfig`](/references/js/type-aliases/AuthServerConfig.md)\> - -Une promesse qui se résout avec la configuration du serveur. - -## Voir aussi {#see} - - - [fetchServerConfigByWellKnownUrl](/references/js/functions/fetchServerConfigByWellKnownUrl.md) pour l’implémentation sous-jacente. - - [https://www.rfc-editor.org/rfc/rfc8414](https://www.rfc-editor.org/rfc/rfc8414) pour la spécification OAuth 2.0 Authorization Server Metadata. - - [https://openid.net/specs/openid-connect-discovery-1\_0.html](https://openid.net/specs/openid-connect-discovery-1_0.html) pour la spécification OpenID Connect Discovery. - -## Exemple {#example} - -```ts -import { fetchServerConfig } from 'mcp-auth'; -// Récupération de la configuration du serveur OAuth -// Cela va récupérer les métadonnées depuis `https://auth.logto.io/.well-known/oauth-authorization-server/oauth` -const oauthConfig = await fetchServerConfig('https://auth.logto.io/oauth', { type: 'oauth' }); - -// Récupération de la configuration du serveur OpenID Connect -// Cela va récupérer les métadonnées depuis `https://auth.logto.io/oidc/.well-known/openid-configuration` -const oidcConfig = await fetchServerConfig('https://auth.logto.io/oidc', { type: 'oidc' }); -``` - -## Exceptions {#throws} - -si l’opération de récupération échoue. - -## Exceptions {#throws} - -si les métadonnées du serveur sont invalides ou ne correspondent pas à la spécification MCP. \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfigByWellKnownUrl.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfigByWellKnownUrl.md deleted file mode 100644 index a6ee715..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfigByWellKnownUrl.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -sidebar_label: fetchServerConfigByWellKnownUrl ---- - -# Fonction : fetchServerConfigByWellKnownUrl() - -```ts -function fetchServerConfigByWellKnownUrl(wellKnownUrl: string | URL, config: ServerMetadataConfig): Promise; -``` - -Récupère la configuration du serveur à partir de l’URL bien connue fournie et la valide par rapport à la spécification MCP. - -Si les métadonnées du serveur ne sont pas conformes au schéma attendu, mais que vous êtes certain qu’elles sont compatibles, vous pouvez définir une fonction `transpileData` pour transformer les métadonnées dans le format attendu. - -## Paramètres {#parameters} - -### wellKnownUrl {#wellknownurl} - -L’URL bien connue à partir de laquelle récupérer la configuration du serveur. Cela peut être une chaîne de caractères ou un objet URL. - -`string` | `URL` - -### config {#config} - -`ServerMetadataConfig` - -L’objet de configuration contenant le type de serveur et éventuellement la fonction de transpilation. - -## Retourne {#returns} - -`Promise`\<[`AuthServerConfig`](/references/js/type-aliases/AuthServerConfig.md)\> - -Une promesse qui se résout avec la configuration du serveur. - -## Lève une exception {#throws} - -si l’opération de récupération échoue. - -## Lève une exception {#throws} - -si les métadonnées du serveur sont invalides ou ne correspondent pas à la spécification MCP. diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/handleBearerAuth.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/handleBearerAuth.md deleted file mode 100644 index 3780786..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/handleBearerAuth.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -sidebar_label: handleBearerAuth ---- - -# Fonction : handleBearerAuth() - -```ts -function handleBearerAuth(param0: BearerAuthConfig): RequestHandler; -``` - -Crée une fonction middleware pour gérer l’authentification Bearer dans une application Express. - -Ce middleware extrait le jeton Bearer de l’en-tête `Authorization`, le vérifie à l’aide de la fonction -`verifyAccessToken` fournie, et contrôle l’Émetteur (Issuer), l’Audience (Audience) et les Portées (Scopes) requises. - -- Si le jeton est valide, il ajoute les informations d’authentification à la propriété `request.auth` ; -sinon, il répond avec un message d’erreur approprié. -- Si la vérification du jeton d’accès (Access token) échoue, il répond avec une erreur 401 Non autorisé. -- Si le jeton ne possède pas les Portées (Scopes) requises, il répond avec une erreur 403 Interdit. -- Si des erreurs inattendues surviennent lors du processus d’authentification, le middleware les relancera. - -**Remarque :** L’objet `request.auth` contiendra des champs étendus par rapport à l’interface standard -AuthInfo définie dans le module `@modelcontextprotocol/sdk`. Voir l’interface étendue dans ce fichier pour plus de détails. - -## Paramètres {#parameters} - -### param0 {#param0} - -[`BearerAuthConfig`](/references/js/type-aliases/BearerAuthConfig.md) - -Configuration pour le gestionnaire d’authentification Bearer. - -## Retourne {#returns} - -`RequestHandler` - -Une fonction middleware pour Express qui gère l’authentification Bearer. - -## Voir aussi {#see} - -[BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) pour les options de configuration. diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfig.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfig.md deleted file mode 100644 index 000e7b0..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfig.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -sidebar_label: AuthServerConfig ---- - -# Alias de type : AuthServerConfig - -```ts -type AuthServerConfig = { - metadata: CamelCaseAuthorizationServerMetadata; - type: AuthServerType; -}; -``` - -Configuration pour le serveur d'autorisation distant intégré avec le serveur MCP. - -## Propriétés {#properties} - -### metadata {#metadata} - -```ts -metadata: CamelCaseAuthorizationServerMetadata; -``` - -Les métadonnées du serveur d’autorisation (Authorization Server), qui doivent être conformes à la spécification MCP -(basée sur les métadonnées du serveur d’autorisation OAuth 2.0). - -Ces métadonnées sont généralement récupérées à partir du point de terminaison well-known du serveur (OAuth 2.0 -Authorization Server Metadata ou OpenID Connect Discovery) ; elles peuvent également être fournies -directement dans la configuration si le serveur ne prend pas en charge de tels points de terminaison. - -**Remarque :** Les métadonnées doivent être au format camelCase comme préféré par la bibliothèque mcp-auth. - -#### Voir {#see} - - - [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) - - [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) - -*** - -### type {#type} - -```ts -type: AuthServerType; -``` - -Le type du serveur d’autorisation (Authorization Server). - -#### Voir {#see} - -[AuthServerType](/references/js/type-aliases/AuthServerType.md) pour les valeurs possibles. diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigError.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigError.md deleted file mode 100644 index d19b6f5..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigError.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -sidebar_label: AuthServerConfigError ---- - -# Alias de type : AuthServerConfigError - -```ts -type AuthServerConfigError = { - cause?: Error; - code: AuthServerConfigErrorCode; - description: string; -}; -``` - -Représente une erreur qui se produit lors de la validation des métadonnées du serveur d’autorisation. - -## Propriétés {#properties} - -### cause ? {#cause} - -```ts -optional cause: Error; -``` - -Une cause optionnelle de l’erreur, généralement une instance de `Error` qui fournit plus de contexte. - -*** - -### code {#code} - -```ts -code: AuthServerConfigErrorCode; -``` - -Le code représentant l’erreur de validation spécifique. - -*** - -### description {#description} - -```ts -description: string; -``` - -Une description lisible par l’humain de l’erreur. diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigErrorCode.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigErrorCode.md deleted file mode 100644 index 06ada65..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigErrorCode.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_label: AuthServerConfigErrorCode ---- - -# Alias de type : AuthServerConfigErrorCode - -```ts -type AuthServerConfigErrorCode = - | "invalid_server_metadata" - | "code_response_type_not_supported" - | "authorization_code_grant_not_supported" - | "pkce_not_supported" - | "s256_code_challenge_method_not_supported"; -``` - -Les codes des erreurs pouvant survenir lors de la validation des métadonnées du serveur d’autorisation. \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarning.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarning.md deleted file mode 100644 index 6677393..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarning.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -sidebar_label: AuthServerConfigWarning ---- - -# Alias de type : AuthServerConfigWarning - -```ts -type AuthServerConfigWarning = { - code: AuthServerConfigWarningCode; - description: string; -}; -``` - -Représente un avertissement qui se produit lors de la validation des métadonnées du serveur d’autorisation. - -## Propriétés {#properties} - -### code {#code} - -```ts -code: AuthServerConfigWarningCode; -``` - -Le code représentant l’avertissement de validation spécifique. - -*** - -### description {#description} - -```ts -description: string; -``` - -Une description lisible par l’humain de l’avertissement. diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarningCode.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarningCode.md deleted file mode 100644 index 375439b..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarningCode.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -sidebar_label: AuthServerConfigWarningCode ---- - -# Alias de type : AuthServerConfigWarningCode - -```ts -type AuthServerConfigWarningCode = "dynamic_registration_not_supported"; -``` - -Les codes des avertissements pouvant survenir lors de la validation des métadonnées du serveur d’autorisation. \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerErrorCode.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerErrorCode.md deleted file mode 100644 index 64c30a9..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerErrorCode.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_label: AuthServerErrorCode ---- - -# Alias de type : AuthServerErrorCode - -```ts -type AuthServerErrorCode = - | "invalid_server_metadata" - | "invalid_server_config" - | "missing_jwks_uri"; -``` diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerSuccessCode.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerSuccessCode.md deleted file mode 100644 index f1bcc6c..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerSuccessCode.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -sidebar_label: AuthServerSuccessCode ---- - -# Alias de type : AuthServerSuccessCode - -```ts -type AuthServerSuccessCode = - | "server_metadata_valid" - | "dynamic_registration_supported" - | "pkce_supported" - | "s256_code_challenge_method_supported" - | "authorization_code_grant_supported" - | "code_response_type_supported"; -``` - -Les codes pour la validation réussie des métadonnées du serveur d’autorisation. \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerType.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerType.md deleted file mode 100644 index 794cfae..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerType.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -sidebar_label: AuthServerType ---- - -# Alias de type : AuthServerType - -```ts -type AuthServerType = "oauth" | "oidc"; -``` - -Le type du serveur d’autorisation (authorization server). Cette information doit être fournie par la configuration du serveur et indique si le serveur est un serveur d’autorisation OAuth 2.0 ou OpenID Connect (OIDC). diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthorizationServerMetadata.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthorizationServerMetadata.md deleted file mode 100644 index 290eea4..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthorizationServerMetadata.md +++ /dev/null @@ -1,224 +0,0 @@ ---- -sidebar_label: AuthorizationServerMetadata ---- - -# Alias de type : AuthorizationServerMetadata - -```ts -type AuthorizationServerMetadata = { - authorization_endpoint: string; - code_challenge_methods_supported?: string[]; - grant_types_supported?: string[]; - introspection_endpoint?: string; - introspection_endpoint_auth_methods_supported?: string[]; - introspection_endpoint_auth_signing_alg_values_supported?: string[]; - issuer: string; - jwks_uri?: string; - op_policy_uri?: string; - op_tos_uri?: string; - registration_endpoint?: string; - response_modes_supported?: string[]; - response_types_supported: string[]; - revocation_endpoint?: string; - revocation_endpoint_auth_methods_supported?: string[]; - revocation_endpoint_auth_signing_alg_values_supported?: string[]; - scope_supported?: string[]; - service_documentation?: string; - token_endpoint: string; - token_endpoint_auth_methods_supported?: string[]; - token_endpoint_auth_signing_alg_values_supported?: string[]; - ui_locales_supported?: string[]; - userinfo_endpoint?: string; -}; -``` - -Schéma pour les métadonnées du serveur d’autorisation OAuth 2.0 tel que défini dans la RFC 8414. - -## Déclaration de type {#type-declaration} - -### authorization\_endpoint {#authorization-endpoint} - -```ts -authorization_endpoint: string; -``` - -URL du point de terminaison d’autorisation du serveur d’autorisation [[RFC6749](https://rfc-editor.org/rfc/rfc6749)]. -Ceci est OBLIGATOIRE sauf si aucun type de flux n’est pris en charge utilisant le point de terminaison d’autorisation. - -#### Voir {#see} - -https://rfc-editor.org/rfc/rfc6749#section-3.1 - -### code\_challenge\_methods\_supported? {#code-challenge-methods-supported} - -```ts -optional code_challenge_methods_supported: string[]; -``` - -Tableau JSON contenant une liste des méthodes de challenge PKCE (Proof Key for Code Exchange) -[[RFC7636](https://www.rfc-editor.org/rfc/rfc7636)] prises en charge par ce serveur d’autorisation. - -### grant\_types\_supported? {#grant-types-supported} - -```ts -optional grant_types_supported: string[]; -``` - -Tableau JSON contenant une liste des valeurs de type de flux OAuth 2.0 que ce serveur d’autorisation prend en charge. Les valeurs du tableau sont les mêmes que celles utilisées avec le paramètre `grant_types` défini par le "Protocole d’enregistrement dynamique des clients OAuth 2.0" [[RFC7591](https://www.rfc-editor.org/rfc/rfc7591)]. -Si omis, la valeur par défaut est `["authorization_code", "implicit"]`. - -### introspection\_endpoint? {#introspection-endpoint} - -```ts -optional introspection_endpoint: string; -``` - -URL du point de terminaison d’introspection OAuth 2.0 du serveur d’autorisation -[[RFC7662](https://www.rfc-editor.org/rfc/rfc7662)]. - -### introspection\_endpoint\_auth\_methods\_supported? {#introspection-endpoint-auth-methods-supported} - -```ts -optional introspection_endpoint_auth_methods_supported: string[]; -``` - -### introspection\_endpoint\_auth\_signing\_alg\_values\_supported? {#introspection-endpoint-auth-signing-alg-values-supported} - -```ts -optional introspection_endpoint_auth_signing_alg_values_supported: string[]; -``` - -### issuer {#issuer} - -```ts -issuer: string; -``` - -Identifiant de l’émetteur (Issuer) du serveur d’autorisation, qui est une URL utilisant le schéma `https` et ne comportant ni composant de requête ni fragment. - -### jwks\_uri? {#jwks-uri} - -```ts -optional jwks_uri: string; -``` - -URL du document JWK Set [[JWK](https://www.rfc-editor.org/rfc/rfc8414.html#ref-JWK)] du serveur d’autorisation. Le document référencé contient la ou les clés de signature que le client utilise pour valider les signatures du serveur d’autorisation. Cette URL DOIT utiliser le schéma `https`. - -### op\_policy\_uri? {#op-policy-uri} - -```ts -optional op_policy_uri: string; -``` - -### op\_tos\_uri? {#op-tos-uri} - -```ts -optional op_tos_uri: string; -``` - -### registration\_endpoint? {#registration-endpoint} - -```ts -optional registration_endpoint: string; -``` - -URL du point de terminaison d’enregistrement dynamique des clients OAuth 2.0 du serveur d’autorisation -[[RFC7591](https://www.rfc-editor.org/rfc/rfc7591)]. - -### response\_modes\_supported? {#response-modes-supported} - -```ts -optional response_modes_supported: string[]; -``` - -Tableau JSON contenant une liste des valeurs `response_mode` OAuth 2.0 que ce serveur d’autorisation prend en charge, comme spécifié dans "OAuth 2.0 Multiple Response Type Encoding Practices" -[[OAuth.Responses](https://datatracker.ietf.org/doc/html/rfc8414#ref-OAuth.Responses)]. - -Si omis, la valeur par défaut est `["query", "fragment"]`. La valeur de mode de réponse `"form_post"` est également définie dans "OAuth 2.0 Form Post Response Mode" -[[OAuth.FormPost](https://datatracker.ietf.org/doc/html/rfc8414#ref-OAuth.Post)]. - -### response\_types\_supported {#response-types-supported} - -```ts -response_types_supported: string[]; -``` - -Tableau JSON contenant une liste des valeurs `response_type` OAuth 2.0 que ce serveur d’autorisation prend en charge. Les valeurs du tableau sont les mêmes que celles utilisées avec le paramètre `response_types` défini par le "Protocole d’enregistrement dynamique des clients OAuth 2.0" -[[RFC7591](https://www.rfc-editor.org/rfc/rfc7591)]. - -### revocation\_endpoint? {#revocation-endpoint} - -```ts -optional revocation_endpoint: string; -``` - -URL du point de terminaison de révocation OAuth 2.0 du serveur d’autorisation -[[RFC7009](https://www.rfc-editor.org/rfc/rfc7009)]. - -### revocation\_endpoint\_auth\_methods\_supported? {#revocation-endpoint-auth-methods-supported} - -```ts -optional revocation_endpoint_auth_methods_supported: string[]; -``` - -### revocation\_endpoint\_auth\_signing\_alg\_values\_supported? {#revocation-endpoint-auth-signing-alg-values-supported} - -```ts -optional revocation_endpoint_auth_signing_alg_values_supported: string[]; -``` - -### scope\_supported? {#scope-supported} - -```ts -optional scope_supported: string[]; -``` - -### service\_documentation? {#service-documentation} - -```ts -optional service_documentation: string; -``` - -### token\_endpoint {#token-endpoint} - -```ts -token_endpoint: string; -``` - -URL du point de terminaison de jeton du serveur d’autorisation [[RFC6749](https://rfc-editor.org/rfc/rfc6749)]. -Ceci est OBLIGATOIRE sauf si seul le type de flux implicite est pris en charge. - -#### Voir {#see} - -https://rfc-editor.org/rfc/rfc6749#section-3.2 - -### token\_endpoint\_auth\_methods\_supported? {#token-endpoint-auth-methods-supported} - -```ts -optional token_endpoint_auth_methods_supported: string[]; -``` - -### token\_endpoint\_auth\_signing\_alg\_values\_supported? {#token-endpoint-auth-signing-alg-values-supported} - -```ts -optional token_endpoint_auth_signing_alg_values_supported: string[]; -``` - -### ui\_locales\_supported? {#ui-locales-supported} - -```ts -optional ui_locales_supported: string[]; -``` - -### userinfo\_endpoint? {#userinfo-endpoint} - -```ts -optional userinfo_endpoint: string; -``` - -URL du [point de terminaison userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) OpenID Connect. -Ce point de terminaison est utilisé pour récupérer des informations sur l’utilisateur authentifié. - -## Voir {#see} - -https://datatracker.ietf.org/doc/html/rfc8414 \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthConfig.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthConfig.md deleted file mode 100644 index b7745ee..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthConfig.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -sidebar_label: BearerAuthConfig ---- - -# Alias de type : BearerAuthConfig - -```ts -type BearerAuthConfig = { - audience?: string; - issuer: string; - requiredScopes?: string[]; - showErrorDetails?: boolean; - verifyAccessToken: VerifyAccessTokenFunction; -}; -``` - -## Propriétés {#properties} - -### audience? {#audience} - -```ts -optional audience: string; -``` - -L’audience attendue du jeton d’accès (Jeton d’accès (Access token)) (`aud` revendication (claim)). Il s’agit généralement du serveur de ressources -(API) auquel le jeton est destiné. Si ce champ n’est pas renseigné, la vérification de l’audience sera ignorée. - -**Remarque :** Si votre serveur d’autorisation ne prend pas en charge les indicateurs de ressource (Indicateurs de ressource (Resource indicators)) (RFC 8707), -vous pouvez omettre ce champ car l’audience peut ne pas être pertinente. - -#### Voir {#see} - -https://datatracker.ietf.org/doc/html/rfc8707 - -*** - -### issuer {#issuer} - -```ts -issuer: string; -``` - -L’émetteur attendu du jeton d’accès (Jeton d’accès (Access token)) (`iss` revendication (claim)). Il doit s’agir de l’URL du -serveur d’autorisation qui a émis le jeton. - -*** - -### requiredScopes? {#requiredscopes} - -```ts -optional requiredScopes: string[]; -``` - -Un tableau des portées (Portées (Scopes)) requises que le jeton d’accès (Jeton d’accès (Access token)) doit posséder. Si le jeton ne contient pas -toutes ces portées, une erreur sera levée. - -**Remarque :** Le gestionnaire vérifiera la revendication (claim) `scope` dans le jeton, qui peut être une chaîne séparée par des espaces -ou un tableau de chaînes, selon l’implémentation du serveur d’autorisation. Si la revendication `scope` n’est pas présente, le gestionnaire vérifiera la revendication `scopes` -si elle est disponible. - -*** - -### showErrorDetails? {#showerrordetails} - -```ts -optional showErrorDetails: boolean; -``` - -Indique s’il faut afficher des informations d’erreur détaillées dans la réponse. Ceci est utile pour le débogage -pendant le développement, mais doit être désactivé en production pour éviter de divulguer des informations sensibles. - -#### Valeur par défaut {#default} - -```ts -false -``` - -*** - -### verifyAccessToken {#verifyaccesstoken} - -```ts -verifyAccessToken: VerifyAccessTokenFunction; -``` - -Type de fonction pour vérifier un jeton d’accès (Jeton d’accès (Access token)). - -Cette fonction doit lever une [MCPAuthTokenVerificationError](/references/js/classes/MCPAuthTokenVerificationError.md) si le jeton est invalide, -ou retourner un objet AuthInfo si le jeton est valide. - -#### Voir {#see} - -[VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) pour plus de détails. diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthErrorCode.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthErrorCode.md deleted file mode 100644 index 5a5207c..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthErrorCode.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_label: BearerAuthErrorCode ---- - -# Alias de type : BearerAuthErrorCode - -```ts -type BearerAuthErrorCode = - | "missing_auth_header" - | "invalid_auth_header_format" - | "missing_bearer_token" - | "invalid_issuer" - | "invalid_audience" - | "missing_required_scopes" - | "invalid_token"; -``` diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthJwtConfig.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthJwtConfig.md deleted file mode 100644 index 8369974..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthJwtConfig.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -sidebar_label: BearerAuthJwtConfig ---- - -# Alias de type : BearerAuthJwtConfig - -```ts -type BearerAuthJwtConfig = { - jwtVerify?: JWTVerifyOptions; - remoteJwkSet?: RemoteJWKSetOptions; -}; -``` - -Configuration pour le gestionnaire d'authentification Bearer lors de l'utilisation de la vérification JWT. - -## Propriétés {#properties} - -### jwtVerify ? {#jwtverify} - -```ts -optional jwtVerify: JWTVerifyOptions; -``` - -Options à transmettre à la fonction `jwtVerify` de la bibliothèque `jose`. - -#### Voir {#see} - -JWTVerifyOptions pour la définition du type des options. - -*** - -### remoteJwkSet ? {#remotejwkset} - -```ts -optional remoteJwkSet: RemoteJWKSetOptions; -``` - -Options à transmettre à la fonction `createRemoteJWKSet` de la bibliothèque `jose`. - -#### Voir {#see} - -RemoteJWKSetOptions pour la définition du type des options. diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md deleted file mode 100644 index e33c706..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -sidebar_label: CamelCaseAuthorizationServerMetadata ---- - -# Alias de type : CamelCaseAuthorizationServerMetadata - -```ts -type CamelCaseAuthorizationServerMetadata = { - authorizationEndpoint: string; - codeChallengeMethodsSupported?: string[]; - grantTypesSupported?: string[]; - introspectionEndpoint?: string; - introspectionEndpointAuthMethodsSupported?: string[]; - introspectionEndpointAuthSigningAlgValuesSupported?: string[]; - issuer: string; - jwksUri?: string; - opPolicyUri?: string; - opTosUri?: string; - registrationEndpoint?: string; - responseModesSupported?: string[]; - responseTypesSupported: string[]; - revocationEndpoint?: string; - revocationEndpointAuthMethodsSupported?: string[]; - revocationEndpointAuthSigningAlgValuesSupported?: string[]; - scopeSupported?: string[]; - serviceDocumentation?: string; - tokenEndpoint: string; - tokenEndpointAuthMethodsSupported?: string[]; - tokenEndpointAuthSigningAlgValuesSupported?: string[]; - uiLocalesSupported?: string[]; - userinfoEndpoint?: string; -}; -``` - -La version camelCase du type OAuth 2.0 Authorization Server Metadata. - -## Déclaration du type {#type-declaration} - -### authorizationEndpoint {#authorizationendpoint} - -```ts -authorizationEndpoint: string; -``` - -### codeChallengeMethodsSupported? {#codechallengemethodssupported} - -```ts -optional codeChallengeMethodsSupported: string[]; -``` - -### grantTypesSupported? {#granttypessupported} - -```ts -optional grantTypesSupported: string[]; -``` - -### introspectionEndpoint? {#introspectionendpoint} - -```ts -optional introspectionEndpoint: string; -``` - -### introspectionEndpointAuthMethodsSupported? {#introspectionendpointauthmethodssupported} - -```ts -optional introspectionEndpointAuthMethodsSupported: string[]; -``` - -### introspectionEndpointAuthSigningAlgValuesSupported? {#introspectionendpointauthsigningalgvaluessupported} - -```ts -optional introspectionEndpointAuthSigningAlgValuesSupported: string[]; -``` - -### issuer {#issuer} - -```ts -issuer: string; -``` - -### jwksUri? {#jwksuri} - -```ts -optional jwksUri: string; -``` - -### opPolicyUri? {#oppolicyuri} - -```ts -optional opPolicyUri: string; -``` - -### opTosUri? {#optosuri} - -```ts -optional opTosUri: string; -``` - -### registrationEndpoint? {#registrationendpoint} - -```ts -optional registrationEndpoint: string; -``` - -### responseModesSupported? {#responsemodessupported} - -```ts -optional responseModesSupported: string[]; -``` - -### responseTypesSupported {#responsetypessupported} - -```ts -responseTypesSupported: string[]; -``` - -### revocationEndpoint? {#revocationendpoint} - -```ts -optional revocationEndpoint: string; -``` - -### revocationEndpointAuthMethodsSupported? {#revocationendpointauthmethodssupported} - -```ts -optional revocationEndpointAuthMethodsSupported: string[]; -``` - -### revocationEndpointAuthSigningAlgValuesSupported? {#revocationendpointauthsigningalgvaluessupported} - -```ts -optional revocationEndpointAuthSigningAlgValuesSupported: string[]; -``` - -### scopeSupported? {#scopesupported} - -```ts -optional scopeSupported: string[]; -``` - -### serviceDocumentation? {#servicedocumentation} - -```ts -optional serviceDocumentation: string; -``` - -### tokenEndpoint {#tokenendpoint} - -```ts -tokenEndpoint: string; -``` - -### tokenEndpointAuthMethodsSupported? {#tokenendpointauthmethodssupported} - -```ts -optional tokenEndpointAuthMethodsSupported: string[]; -``` - -### tokenEndpointAuthSigningAlgValuesSupported? {#tokenendpointauthsigningalgvaluessupported} - -```ts -optional tokenEndpointAuthSigningAlgValuesSupported: string[]; -``` - -### uiLocalesSupported? {#uilocalessupported} - -```ts -optional uiLocalesSupported: string[]; -``` - -### userinfoEndpoint? {#userinfoendpoint} - -```ts -optional userinfoEndpoint: string; -``` - -## Voir aussi {#see} - -[AuthorizationServerMetadata](/references/js/type-aliases/AuthorizationServerMetadata.md) pour le type original et les informations sur les champs. diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md deleted file mode 100644 index 74bb257..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -sidebar_label: MCPAuthBearerAuthErrorDetails ---- - -# Alias de type : MCPAuthBearerAuthErrorDetails - -```ts -type MCPAuthBearerAuthErrorDetails = { - actual?: unknown; - cause?: unknown; - expected?: unknown; - missingScopes?: string[]; - uri?: URL; -}; -``` - -## Propriétés {#properties} - -### actual? {#actual} - -```ts -optional actual: unknown; -``` - -*** - -### cause? {#cause} - -```ts -optional cause: unknown; -``` - -*** - -### expected? {#expected} - -```ts -optional expected: unknown; -``` - -*** - -### missingScopes? {#missingscopes} - -```ts -optional missingScopes: string[]; -``` - -*** - -### uri? {#uri} - -```ts -optional uri: URL; -``` diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthConfig.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthConfig.md deleted file mode 100644 index 55fb37a..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthConfig.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -sidebar_label: MCPAuthConfig ---- - -# Alias de type : MCPAuthConfig - -```ts -type MCPAuthConfig = { - server: AuthServerConfig; -}; -``` - -Configuration pour la classe [MCPAuth](/references/js/classes/MCPAuth.md). - -## Propriétés {#properties} - -### server {#server} - -```ts -server: AuthServerConfig; -``` - -Configuration pour le serveur d’autorisation distant. diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md deleted file mode 100644 index 083a31d..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: MCPAuthTokenVerificationErrorCode ---- - -# Alias de type : MCPAuthTokenVerificationErrorCode - -```ts -type MCPAuthTokenVerificationErrorCode = "invalid_token" | "token_verification_failed"; -``` diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenFunction.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenFunction.md deleted file mode 100644 index 4a43c15..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenFunction.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -sidebar_label: VerifyAccessTokenFunction ---- - -# Alias de type : VerifyAccessTokenFunction() - -```ts -type VerifyAccessTokenFunction = (token: string) => MaybePromise; -``` - -Type de fonction pour vérifier un jeton d’accès (Access token). - -Cette fonction doit lever une [MCPAuthTokenVerificationError](/references/js/classes/MCPAuthTokenVerificationError.md) si le jeton est invalide, -ou retourner un objet AuthInfo si le jeton est valide. - -Par exemple, si vous disposez d'une fonction de vérification JWT, elle doit au minimum vérifier la signature du jeton, -valider son expiration et extraire les revendications (Claims) nécessaires pour retourner un objet `AuthInfo`. - -**Remarque :** Il n'est pas nécessaire de vérifier les champs suivants dans le jeton, car ils seront contrôlés -par le gestionnaire : - -- `iss` (Émetteur / Issuer) -- `aud` (Audience) -- `scope` (Portées / Scopes) - -## Paramètres {#parameters} - -### token {#token} - -`string` - -La chaîne du jeton d’accès (Access token) à vérifier. - -## Retourne {#returns} - -`MaybePromise`\<`AuthInfo`\> - -Une promesse qui se résout en un objet AuthInfo ou une valeur synchrone si le -jeton est valide. diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenMode.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenMode.md deleted file mode 100644 index 70e1606..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenMode.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: VérifierAccessTokenMode ---- - -# Alias de type : VérifierAccessTokenMode - -```ts -type VerifyAccessTokenMode = "jwt"; -``` diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authServerErrorDescription.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authServerErrorDescription.md deleted file mode 100644 index 9001d1d..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authServerErrorDescription.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: authServerErrorDescription ---- - -# Variable : authServerErrorDescription - -```ts -const authServerErrorDescription: Readonly>; -``` diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authorizationServerMetadataSchema.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authorizationServerMetadataSchema.md deleted file mode 100644 index 156d25e..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authorizationServerMetadataSchema.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: authorizationServerMetadataSchema ---- - -# Variable : authorizationServerMetadataSchema - -```ts -const authorizationServerMetadataSchema: ZodObject; -``` - -Schéma Zod pour les métadonnées du serveur d’autorisation OAuth 2.0 telles que définies dans la RFC 8414. - -## Voir {#see} - -https://datatracker.ietf.org/doc/html/rfc8414 \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/bearerAuthErrorDescription.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/bearerAuthErrorDescription.md deleted file mode 100644 index 2a5bbc0..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/bearerAuthErrorDescription.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: bearerAuthErrorDescription ---- - -# Variable : bearerAuthErrorDescription - -```ts -const bearerAuthErrorDescription: Readonly>; -``` diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md deleted file mode 100644 index 1090c9c..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: camelCaseAuthorizationServerMetadataSchema ---- - -# Variable : camelCaseAuthorizationServerMetadataSchema - -```ts -const camelCaseAuthorizationServerMetadataSchema: ZodObject; -``` - -La version camelCase du schéma Zod des métadonnées du serveur d’autorisation OAuth 2.0. - -## Voir {#see} - -[authorizationServerMetadataSchema](/references/js/variables/authorizationServerMetadataSchema.md) pour le schéma original et les informations sur les champs. diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/serverMetadataPaths.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/serverMetadataPaths.md deleted file mode 100644 index 33d94c8..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/serverMetadataPaths.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_label: serverMetadataPaths ---- - -# Variable : serverMetadataPaths - -```ts -const serverMetadataPaths: Readonly<{ - oauth: "/.well-known/oauth-authorization-server"; - oidc: "/.well-known/openid-configuration"; -}>; -``` diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/tokenVerificationErrorDescription.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/tokenVerificationErrorDescription.md deleted file mode 100644 index b614049..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/tokenVerificationErrorDescription.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: tokenVerificationErrorDescription ---- - -# Variable : tokenVerificationErrorDescription - -```ts -const tokenVerificationErrorDescription: Readonly>; -``` diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/validateServerConfig.md b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/validateServerConfig.md deleted file mode 100644 index a307d3a..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/validateServerConfig.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: validateServerConfig ---- - -# Variable : validateServerConfig - -```ts -const validateServerConfig: ValidateServerConfig; -``` diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/snippets/_get-started-code.mdx b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/snippets/_get-started-code.mdx deleted file mode 100644 index 4f1f572..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/snippets/_get-started-code.mdx +++ /dev/null @@ -1,41 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - - - - - -```python -mcp = FastMCP("MyMCPServer") -mcp_auth = MCPAuth(server=fetch_server_config('', type=AuthServerType.OIDC)) -app = Starlette( - # ... votre configuration du serveur MCP - middleware=[Middleware( - mcp_auth.bearer_auth_middleware("jwt", required_scopes=["read", "write"]) - )] -) - -# Utilisez `mcp_auth.auth_info` pour accéder aux informations d'authentification pour la requête en cours -@mcp.tool() -def whoami() -> dict[str, Any]: - return mcp_auth.auth_info.claims -``` - - - - -```ts -const server = new McpServer(/* ... */); -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { type: 'oidc' }), -}); -const app = express(); - -app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] })); -server.tool('whoami', ({ authInfo }) => { - // Utilisez `authInfo` pour accéder aux informations d'authentification transmises depuis `req.auth` -}); -``` - - - diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/README.mdx b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/README.mdx deleted file mode 100644 index 1efa1ab..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/README.mdx +++ /dev/null @@ -1,1149 +0,0 @@ ---- -sidebar_position: 2 -sidebar_label: 'Tutoriel : Créer un gestionnaire de tâches' ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import SetupOauthOrOidc from './_setup-oauth-or-oidc.mdx'; -import SetupOidc from './_setup-oidc.mdx'; - -# Tutoriel : Créer un gestionnaire de tâches - -Dans ce tutoriel, nous allons construire un serveur MCP de gestionnaire de tâches avec authentification et autorisation des utilisateurs. - -Après avoir terminé ce tutoriel, vous aurez : - -- ✅ Une compréhension de base de la configuration du contrôle d’accès basé sur les rôles (RBAC) dans votre serveur MCP. -- ✅ Un serveur MCP capable de gérer des listes de tâches personnelles. - -:::note -Avant de commencer, nous vous recommandons fortement de suivre d'abord le [tutoriel Who am I](./whoami) si vous n'êtes pas familier avec le serveur MCP et OAuth 2. -::: - -## Aperçu \{#overview} - -Le tutoriel impliquera les composants suivants : - -- **Serveur MCP** : Un serveur MCP simple qui utilise les SDK officiels MCP pour gérer les requêtes, avec un service Todo intégré pour gérer les tâches de l'utilisateur. -- **Inspecteur MCP** : Un outil de test visuel pour les serveurs MCP. Il agit également comme un client OAuth / OIDC pour initier le flux d’autorisation et récupérer les jetons d’accès. -- **Serveur d’autorisation** : Un fournisseur OAuth 2.1 ou OpenID Connect qui gère les identités des utilisateurs et délivre les jetons d’accès. - -Voici un schéma de haut niveau de l’interaction entre ces composants : - -```mermaid -sequenceDiagram - participant Client as Inspecteur MCP - participant Server as Serveur MCP - participant Auth as Serveur d’autorisation - - Client->>Server: Demander une opération todo - Server->>Client: Retourner 401 Non autorisé - Client->>Auth: Initier le flux d’autorisation - Auth->>Auth: Compléter le flux d’autorisation - Auth->>Client: Rediriger avec le code d’autorisation - Client->>Auth: Échanger le code contre un jeton d’accès - Auth->>Client: Retourner le jeton d’accès - Client->>Server: Demander une opération todo avec le jeton d’accès - Server->>Server: Valider le jeton d’accès et obtenir les portées utilisateur depuis le jeton d’accès - Note over Server: Exécuter l’opération todo - Server->>Client: Retourner le résultat de l’opération todo -``` - -## Comprendre votre serveur d’autorisation \{#understand-your-authorization-server} - -### Jetons d’accès avec portées \{#access-tokens-with-scopes} - -Pour mettre en œuvre le [contrôle d’accès basé sur les rôles (RBAC)](https://auth.wiki/rbac) dans votre serveur MCP, votre serveur d’autorisation doit prendre en charge l’émission de jetons d’accès avec des portées. Les portées représentent les permissions accordées à un utilisateur. - - - - -[Logto](https://logto.io) fournit la prise en charge du RBAC via ses ressources API (conformes à [RFC 8707 : Indicateurs de ressource pour OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)) et ses fonctionnalités de rôles. Voici comment le configurer : - -1. Connectez-vous à [Logto Console](https://cloud.logto.io) (ou à votre propre instance Logto Console) - -2. Créez une ressource API et des portées : - - - Allez dans "Ressources API" - - Créez une nouvelle ressource API nommée "Todo Manager" - - Ajoutez les portées suivantes : - - `create:todos` : "Créer de nouvelles tâches" - - `read:todos` : "Lire toutes les tâches" - - `delete:todos` : "Supprimer n’importe quelle tâche" - -3. Créez des rôles (recommandé pour une gestion plus simple) : - - - Allez dans "Rôles" - - Créez un rôle "Admin" et assignez toutes les portées (`create:todos`, `read:todos`, `delete:todos`) - - Créez un rôle "User" et assignez uniquement la portée `create:todos` - -4. Assignez les permissions : - - Allez dans "Utilisateurs" - - Sélectionnez un utilisateur - - Vous pouvez soit : - - Assigner des rôles dans l’onglet "Rôles" (recommandé) - - Ou assigner directement des portées dans l’onglet "Permissions" - -Les portées seront incluses dans la revendication `scope` du jeton d’accès JWT sous forme de chaîne séparée par des espaces. - - - - -Les fournisseurs OAuth 2.0 / OIDC prennent généralement en charge le contrôle d’accès basé sur les portées. Lors de la mise en œuvre du RBAC : - -1. Définissez les portées requises dans votre serveur d’autorisation -2. Configurez votre client pour demander ces portées lors du flux d’autorisation -3. Assurez-vous que votre serveur d’autorisation inclut les portées accordées dans le jeton d’accès -4. Les portées sont généralement incluses dans la revendication `scope` du jeton d’accès JWT - -Consultez la documentation de votre fournisseur pour les détails spécifiques sur : - -- Comment définir et gérer les portées -- Comment les portées sont incluses dans le jeton d’accès -- Toute fonctionnalité RBAC supplémentaire comme la gestion des rôles - - - - -### Validation des jetons et vérification des permissions \{#validating-tokens-and-checking-permissions} - -Lorsque votre serveur MCP reçoit une requête, il doit : - -1. Valider la signature et l’expiration du jeton d’accès -2. Extraire les portées du jeton validé -3. Vérifier si le jeton possède les portées requises pour l’opération demandée - -Par exemple, si un utilisateur souhaite créer une nouvelle tâche, son jeton d’accès doit inclure la portée `create:todos`. Voici comment fonctionne le flux : - -```mermaid -sequenceDiagram - participant Client - participant MCP Server - participant Auth Server - - Client->>MCP Server: Requête avec jeton d’accès - - alt Validation JWT - MCP Server->>Auth Server: Récupérer JWKS - Auth Server-->>MCP Server: Retourner JWKS - MCP Server->>MCP Server: Valider le JWT localement - else Introspection du jeton - MCP Server->>Auth Server: POST /introspect
(token=access_token) - Auth Server-->>MCP Server: Retourner les infos du jeton
(active, scope, etc.) - end - - MCP Server->>MCP Server: Extraire & vérifier les portées - - alt Possède les portées requises - MCP Server->>Client: Autoriser l’opération - else Portées manquantes - MCP Server->>Client: Retourner 403 Interdit - end -``` - -### Enregistrement dynamique de client \{#dynamic-client-registration} - -L’enregistrement dynamique de client n’est pas requis pour ce tutoriel, mais il peut être utile si vous souhaitez automatiser le processus d’enregistrement du client MCP auprès de votre serveur d’autorisation. Consultez [L’enregistrement dynamique de client est-il requis ?](/provider-list#is-dcr-required) pour plus de détails. - -## Comprendre le RBAC dans le gestionnaire de tâches \{#understand-rbac-in-todo-manager} - -À des fins de démonstration, nous allons mettre en œuvre un système simple de contrôle d’accès basé sur les rôles (RBAC) dans notre serveur MCP gestionnaire de tâches. Cela vous montrera les principes de base du RBAC tout en gardant l’implémentation simple. - -:::note -Bien que ce tutoriel démontre la gestion des portées basée sur le RBAC, il est important de noter que tous les fournisseurs d’authentification n’implémentent pas la gestion des portées via les rôles. Certains fournisseurs peuvent avoir leurs propres mécanismes uniques pour gérer le contrôle d’accès et les permissions. -::: - -### Outils et portées \{#tools-and-scopes} - -Notre serveur MCP gestionnaire de tâches fournit trois outils principaux : - -- `create-todo` : Créer une nouvelle tâche -- `get-todos` : Lister toutes les tâches -- `delete-todo` : Supprimer une tâche par ID - -Pour contrôler l’accès à ces outils, nous définissons les portées suivantes : - -- `create:todos` : Autorise la création de nouvelles tâches -- `delete:todos` : Autorise la suppression de tâches existantes -- `read:todos` : Autorise la consultation et la récupération de la liste de toutes les tâches - -### Rôles et permissions \{#roles-and-permissions} - -Nous allons définir deux rôles avec différents niveaux d’accès : - -| Rôle | create:todos | read:todos | delete:todos | -| ----- | ------------ | ---------- | ------------ | -| Admin | ✅ | ✅ | ✅ | -| User | ✅ | | | - -- **User** : Un utilisateur régulier qui peut créer des tâches et voir ou supprimer uniquement ses propres tâches -- **Admin** : Un administrateur qui peut créer, voir et supprimer toutes les tâches, quel que soit le propriétaire - -### Propriété des ressources \{#resource-ownership} - -Bien que le tableau des permissions ci-dessus montre les portées explicites attribuées à chaque rôle, il y a un principe important de propriété des ressources à considérer : - -- **Les utilisateurs** n’ont pas les portées `read:todos` ou `delete:todos`, mais ils peuvent quand même : - - Lire leurs propres tâches - - Supprimer leurs propres tâches -- **Les admins** ont toutes les permissions (`read:todos` et `delete:todos`), ce qui leur permet de : - - Voir toutes les tâches du système - - Supprimer n’importe quelle tâche, quel que soit le propriétaire - -Cela illustre un schéma courant dans les systèmes RBAC où la propriété d’une ressource accorde des permissions implicites aux utilisateurs pour leurs propres ressources, tandis que les rôles administratifs reçoivent des permissions explicites pour toutes les ressources. - -:::tip En savoir plus -Pour approfondir les concepts et bonnes pratiques du RBAC, consultez [Maîtriser le RBAC : Un exemple complet du monde réel](https://blog.logto.io/mastering-rbac). -::: - -## Configurer l’autorisation dans votre fournisseur \{#configure-authorization-in-your-provider} - -Pour mettre en œuvre le système de contrôle d’accès décrit précédemment, vous devrez configurer votre serveur d’autorisation pour prendre en charge les portées requises. Voici comment faire avec différents fournisseurs : - - - - -[Logto](https://logto.io) fournit la prise en charge du RBAC via ses ressources API et ses fonctionnalités de rôles. Voici comment le configurer : - -1. Connectez-vous à [Logto Console](https://cloud.logto.io) (ou à votre propre instance Logto Console) - -2. Créez une ressource API et des portées : - - - Allez dans "Ressources API" - - Créez une nouvelle ressource API nommée "Todo Manager" et utilisez `https://todo.mcp-server.app` (à des fins de démonstration) comme indicateur. - - Créez les portées suivantes : - - `create:todos` : "Créer de nouvelles tâches" - - `read:todos` : "Lire toutes les tâches" - - `delete:todos` : "Supprimer n’importe quelle tâche" - -3. Créez des rôles (recommandé pour une gestion plus simple) : - - - Allez dans "Rôles" - - Créez un rôle "Admin" et assignez toutes les portées (`create:todos`, `read:todos`, `delete:todos`) - - Créez un rôle "User" et assignez uniquement la portée `create:todos` - - Dans la page de détails du rôle "User", passez à l’onglet "Général" et définissez le rôle "User" comme "Rôle par défaut". - -4. Gérez les rôles et permissions des utilisateurs : - - Pour les nouveaux utilisateurs : - - Ils recevront automatiquement le rôle "User" puisque nous l’avons défini comme rôle par défaut - - Pour les utilisateurs existants : - - Allez dans "Gestion des utilisateurs" - - Sélectionnez un utilisateur - - Assignez des rôles à l’utilisateur dans l’onglet "Rôles" - -:::tip Gestion programmatique des rôles -Vous pouvez également utiliser la [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api) de Logto pour gérer les rôles des utilisateurs de manière programmatique. Ceci est particulièrement utile pour la gestion automatisée des utilisateurs ou lors de la création de panneaux d’administration. -::: - -Lors de la demande d’un jeton d’accès, Logto inclura les portées dans la revendication `scope` du jeton en fonction des permissions de rôle de l’utilisateur. - - - - -Dans [Keycloak](https://www.keycloak.org), vous pouvez configurer les permissions requises à l’aide des portées client : - -1. Créez des portées client : - - - Dans votre realm, allez dans "Client scopes" - - Créez trois nouvelles portées client : - - `create:todos` - - `read:todos` - - `delete:todos` - -2. Configurez le client : - - - Allez dans les paramètres de votre client - - Dans l’onglet "Client scopes", ajoutez toutes les portées que vous avez créées - - Assurez-vous que le mappage du jeton est configuré pour inclure les portées - -3. Optionnel : Utilisez les rôles pour une gestion plus simple - - Si vous préférez la gestion basée sur les rôles : - - Créez des rôles de realm pour différents niveaux d’accès - - Mappez les portées aux rôles - - Assignez les rôles aux utilisateurs - - Sinon, vous pouvez assigner directement les portées aux utilisateurs ou via les permissions au niveau du client - -Keycloak inclura les portées accordées dans la revendication `scope` du jeton d’accès. - - - - -Pour les fournisseurs OAuth 2.0 ou OpenID Connect, vous devrez configurer les portées qui représentent différentes permissions. Les étapes exactes dépendront de votre fournisseur, mais généralement : - -1. Définissez les portées : - - - Configurez votre serveur d’autorisation pour prendre en charge : - - `create:todos` - - `read:todos` - - `delete:todos` - -2. Configurez le client : - - - Enregistrez ou mettez à jour votre client pour demander ces portées - - Assurez-vous que les portées sont incluses dans le jeton d’accès - -3. Assignez les permissions : - - Utilisez l’interface de votre fournisseur pour accorder les portées appropriées aux utilisateurs - - Certains fournisseurs peuvent prendre en charge la gestion basée sur les rôles, tandis que d’autres utilisent des attributions directes de portées - - Consultez la documentation de votre fournisseur pour l’approche recommandée - -:::tip -La plupart des fournisseurs incluront les portées accordées dans la revendication `scope` du jeton d’accès. Le format est généralement une chaîne de valeurs de portées séparées par des espaces. -::: - - - - -Après avoir configuré votre serveur d’autorisation, les utilisateurs recevront des jetons d’accès contenant leurs portées accordées. Le serveur MCP utilisera ces portées pour déterminer : - -- Si un utilisateur peut créer de nouvelles tâches (`create:todos`) -- Si un utilisateur peut voir toutes les tâches (`read:todos`) ou seulement les siennes -- Si un utilisateur peut supprimer n’importe quelle tâche (`delete:todos`) ou seulement les siennes - -## Mettre en place le serveur MCP \{#set-up-the-mcp-server} - -Nous allons utiliser les [SDK officiels MCP](https://github.com/modelcontextprotocol) pour créer notre serveur MCP gestionnaire de tâches. - -### Créer un nouveau projet \{#create-a-new-project} - - - - -```bash -mkdir mcp-server -cd mcp-server -uv init # Ou utilisez `pipenv` ou `poetry` pour créer un nouvel environnement virtuel -``` - - - - -Créez un nouveau projet Node.js : - -```bash -mkdir mcp-server -cd mcp-server -npm init -y # Ou utilisez `pnpm init` -npm pkg set type="module" -npm pkg set main="todo-manager.ts" -npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts" -``` - -:::note -Nous utilisons TypeScript dans nos exemples car Node.js v22.6.0+ prend en charge l’exécution native de TypeScript avec l’option `--experimental-strip-types`. Si vous utilisez JavaScript, le code sera similaire – assurez-vous simplement d’utiliser Node.js v22.6.0 ou ultérieur. Voir la documentation Node.js pour plus de détails. -::: - - - - -### Installer le SDK MCP et les dépendances \{#install-the-mcp-sdk-and-dependencies} - - - - -```bash -pip install "mcp[cli]" starlette uvicorn -``` - -Ou tout autre gestionnaire de paquets que vous préférez, comme `uv` ou `poetry`. - - - - -```bash -npm install @modelcontextprotocol/sdk express zod -``` - -Ou tout autre gestionnaire de paquets que vous préférez, comme `pnpm` ou `yarn`. - - - - -### Créer le serveur MCP \{#create-the-mcp-server} - -Commençons par créer un serveur MCP de base avec la définition des outils : - - - - -Créez un fichier nommé `todo-manager.py` et ajoutez le code suivant : - -```python -from typing import Any -from mcp.server.fastmcp import FastMCP -from starlette.applications import Starlette -from starlette.routing import Mount - -mcp = FastMCP("Todo Manager") - -@mcp.tool() -def create_todo(content: str) -> dict[str, Any]: - """Créer une nouvelle tâche.""" - return {"error": "Non implémenté"} - -@mcp.tool() -def get_todos() -> dict[str, Any]: - """Lister toutes les tâches.""" - return {"error": "Non implémenté"} - -@mcp.tool() -def delete_todo(id: str) -> dict[str, Any]: - """Supprimer une tâche par id.""" - return {"error": "Non implémenté"} - -app = Starlette( - routes=[Mount('/', app=mcp.sse_app())] -) -``` - -Lancez le serveur avec : - -```bash -uvicorn todo_manager:app --host 0.0.0.0 --port 3001 -``` - - - - -:::note -Comme l’implémentation actuelle de l’inspecteur MCP ne gère pas les flux d’autorisation, nous utiliserons l’approche SSE pour mettre en place le serveur MCP. Nous mettrons à jour le code ici dès que l’inspecteur MCP prendra en charge les flux d’autorisation. -::: - -Vous pouvez également utiliser `pnpm` ou `yarn` si vous préférez. - -Créez un fichier nommé `todo-manager.ts` et ajoutez le code suivant : - -```ts -// todo-manager.ts - -import { z } from 'zod'; -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; -import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'; -import express from 'express'; - -// Créer un serveur MCP -const server = new McpServer({ - name: 'Todo Manager', - version: '0.0.0', -}); - -server.tool('create-todo', 'Créer une nouvelle tâche', { content: z.string() }, async ({ content }) => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Non implémenté' }) }], - }; -}); - -server.tool('get-todos', 'Lister toutes les tâches', async () => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Non implémenté' }) }], - }; -}); - -server.tool('delete-todo', 'Supprimer une tâche par id', { id: z.string() }, async ({ id }) => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Non implémenté' }) }], - }; -}); - -// Ci-dessous le code standard issu de la documentation du SDK MCP -const PORT = 3001; -const app = express(); - -const transports = {}; - -app.get('/sse', async (_req, res) => { - const transport = new SSEServerTransport('/messages', res); - transports[transport.sessionId] = transport; - - res.on('close', () => { - delete transports[transport.sessionId]; - }); - - await server.connect(transport); -}); - -app.post('/messages', async (req, res) => { - const sessionId = String(req.query.sessionId); - const transport = transports[sessionId]; - if (transport) { - await transport.handlePostMessage(req, res, req.body); - } else { - res.status(400).send('Aucun transport trouvé pour ce sessionId'); - } -}); - -app.listen(PORT); -``` - -Lancez le serveur avec : - -```bash -npm start -``` - - - - -## Inspecter le serveur MCP \{#inspect-the-mcp-server} - -### Cloner et lancer l’inspecteur MCP \{#clone-and-run-mcp-inspector} - -Maintenant que nous avons le serveur MCP en fonctionnement, nous pouvons utiliser l’inspecteur MCP pour vérifier si l’outil `whoami` est disponible. - -En raison des limitations de l’implémentation actuelle, nous avons forké l’[inspecteur MCP](https://github.com/mcp-auth/inspector) pour le rendre plus flexible et évolutif pour l’authentification et l’autorisation. Nous avons également soumis une pull request au dépôt original pour inclure nos modifications. - -Pour lancer l’inspecteur MCP, vous pouvez utiliser la commande suivante (Node.js requis) : - -```bash -git clone https://github.com/mcp-auth/inspector.git -cd inspector -npm install -npm run dev -``` - -Ensuite, ouvrez votre navigateur et allez sur `http://localhost:6274/` (ou l’URL affichée dans le terminal) pour accéder à l’inspecteur MCP. - -### Connecter l’inspecteur MCP au serveur MCP \{#connect-mcp-inspector-to-the-mcp-server} - -Avant de continuer, vérifiez la configuration suivante dans l’inspecteur MCP : - -- **Type de transport** : Réglez sur `SSE`. -- **URL** : Réglez sur l’URL de votre serveur MCP. Dans notre cas, cela devrait être `http://localhost:3001/sse`. - -Vous pouvez maintenant cliquer sur le bouton "Connecter" pour voir si l’inspecteur MCP peut se connecter au serveur MCP. Si tout est correct, vous devriez voir le statut "Connecté" dans l’inspecteur MCP. - -### Point de contrôle : Exécuter les outils du gestionnaire de tâches \{#checkpoint-run-todo-manager-tools} - -1. Dans le menu supérieur de l’inspecteur MCP, cliquez sur l’onglet "Outils". -2. Cliquez sur le bouton "Lister les outils". -3. Vous devriez voir les outils `create-todo`, `get-todos` et `delete-todo` listés sur la page. Cliquez dessus pour ouvrir les détails de l’outil. -4. Vous devriez voir le bouton "Exécuter l’outil" à droite. Cliquez dessus et saisissez les paramètres requis pour exécuter l’outil. -5. Vous devriez voir le résultat de l’outil avec la réponse JSON `{"error": "Non implémenté"}`. - -![Première exécution de l’inspecteur MCP](/docs-assets/images/tutorials/todo-manager/inspector-first-run.png) - -## Intégrer avec votre serveur d’autorisation \{#integrate-with-your-authorization-server} - -Pour compléter cette section, plusieurs points sont à prendre en compte : - -
-**L’URL de l’émetteur de votre serveur d’autorisation** - -Il s’agit généralement de l’URL de base de votre serveur d’autorisation, comme `https://auth.example.com`. Certains fournisseurs peuvent avoir un chemin comme `https://example.logto.app/oidc`, alors assurez-vous de vérifier la documentation de votre fournisseur. - -
- -
-**Comment récupérer les métadonnées du serveur d’autorisation** - -- Si votre serveur d’autorisation est conforme à [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) ou [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html), vous pouvez utiliser les utilitaires intégrés de MCP Auth pour récupérer automatiquement les métadonnées. -- Si votre serveur d’autorisation n’est pas conforme à ces standards, vous devrez spécifier manuellement l’URL des métadonnées ou les points de terminaison dans la configuration du serveur MCP. Consultez la documentation de votre fournisseur pour les points de terminaison spécifiques. - -
- -
-**Comment enregistrer l’inspecteur MCP comme client dans votre serveur d’autorisation** - -- Si votre serveur d’autorisation prend en charge [l’enregistrement dynamique de client](https://datatracker.ietf.org/doc/html/rfc7591), vous pouvez passer cette étape car l’inspecteur MCP s’enregistrera automatiquement comme client. -- Si votre serveur d’autorisation ne prend pas en charge l’enregistrement dynamique de client, vous devrez enregistrer manuellement l’inspecteur MCP comme client dans votre serveur d’autorisation. - -
- -
-**Comprendre les paramètres de la requête de jeton** - -Lorsque vous demandez des jetons d’accès à différents serveurs d’autorisation, vous rencontrerez diverses approches pour spécifier la ressource cible et les permissions. Voici les principaux schémas : - -- **Basé sur l’indicateur de ressource** : - - - Utilise le paramètre `resource` pour spécifier l’API cible (voir [RFC 8707 : Indicateurs de ressource pour OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)) - - Courant dans les implémentations OAuth 2.0 modernes - - Exemple de requête : - ```json - { - "resource": "https://todo.mcp-server.app", - "scope": "create:todos read:todos" - } - ``` - - Le serveur délivre des jetons liés spécifiquement à la ressource demandée - -- **Basé sur l’audience** : - - - Utilise le paramètre `audience` pour spécifier le destinataire du jeton - - Semblable aux indicateurs de ressource mais avec une sémantique différente - - Exemple de requête : - ```json - { - "audience": "todo-api", - "scope": "create:todos read:todos" - } - ``` - -- **Basé uniquement sur les portées** : - - S’appuie uniquement sur les portées sans paramètres de ressource / audience - - Approche OAuth 2.0 traditionnelle - - Exemple de requête : - ```json - { - "scope": "todo-api:create todo-api:read openid profile" - } - ``` - - Utilise souvent des portées préfixées pour nommer les permissions - - Courant dans les implémentations OAuth 2.0 plus simples - -:::tip Bonnes pratiques - -- Consultez la documentation de votre fournisseur pour les paramètres pris en charge -- Certains fournisseurs prennent en charge plusieurs approches simultanément -- Les indicateurs de ressource offrent une meilleure sécurité via la restriction d’audience -- Privilégiez les indicateurs de ressource lorsque disponibles pour un meilleur contrôle d’accès - ::: - -
- -Bien que chaque fournisseur puisse avoir ses propres exigences spécifiques, les étapes suivantes vous guideront dans l’intégration de l’inspecteur MCP et du serveur MCP avec des configurations spécifiques au fournisseur. - -### Enregistrer l’inspecteur MCP comme client \{#register-mcp-inspector-as-a-client} - - - - -L’intégration du gestionnaire de tâches avec [Logto](https://logto.io) est simple car il s’agit d’un fournisseur OpenID Connect qui prend en charge les indicateurs de ressource et les portées, vous permettant de sécuriser votre API todo avec `https://todo.mcp-server.app` comme indicateur de ressource. - -Comme Logto ne prend pas encore en charge l’enregistrement dynamique de client, vous devrez enregistrer manuellement l’inspecteur MCP comme client dans votre tenant Logto : - -1. Ouvrez votre inspecteur MCP, cliquez sur le bouton "Configuration OAuth". Copiez la valeur **Redirect URL (auto-populated)**, qui devrait ressembler à `http://localhost:6274/oauth/callback`. -2. Connectez-vous à [Logto Console](https://cloud.logto.io) (ou à votre propre instance Logto Console). -3. Accédez à l’onglet "Applications", cliquez sur "Créer une application". En bas de la page, cliquez sur "Créer une application sans framework". -4. Remplissez les détails de l’application, puis cliquez sur "Créer l’application" : - - **Sélectionnez un type d’application** : Choisissez "Application monopage". - - **Nom de l’application** : Saisissez un nom pour votre application, par exemple "MCP Inspector". -5. Dans la section "Paramètres / URI de redirection", collez la valeur **Redirect URL (auto-populated)** que vous avez copiée depuis l’inspecteur MCP. Cliquez ensuite sur "Enregistrer les modifications" dans la barre du bas. -6. Dans la carte du haut, vous verrez la valeur "App ID". Copiez-la. -7. Retournez dans l’inspecteur MCP et collez la valeur "App ID" dans la section "Configuration OAuth" sous "Client ID". -8. Saisissez la valeur `{"scope": "create:todos read:todos delete:todos", "resource": "https://todo.mcp-server.app"}` dans le champ "Auth Params". Cela garantira que le jeton d’accès retourné par Logto contient les portées nécessaires pour accéder au gestionnaire de tâches. - - - - -:::note -Ceci est un guide générique d’intégration pour les fournisseurs OAuth 2.0 / OpenID Connect. Les deux suivent des étapes similaires car OIDC est construit sur OAuth 2.0. Consultez la documentation de votre fournisseur pour les détails spécifiques. -::: - -Si votre fournisseur prend en charge l’enregistrement dynamique de client, vous pouvez passer directement à l’étape 8 ci-dessous pour configurer l’inspecteur MCP ; sinon, vous devrez enregistrer manuellement l’inspecteur MCP comme client : - -1. Ouvrez votre inspecteur MCP, cliquez sur le bouton "Configuration OAuth". Copiez la valeur **Redirect URL (auto-populated)**, qui devrait ressembler à `http://localhost:6274/oauth/callback`. - -2. Connectez-vous à la console de votre fournisseur. - -3. Accédez à la section "Applications" ou "Clients", puis créez une nouvelle application ou client. - -4. Si votre fournisseur demande un type de client, sélectionnez "Application monopage" ou "Client public". - -5. Après avoir créé l’application, vous devrez configurer l’URI de redirection. Collez la valeur **Redirect URL (auto-populated)** que vous avez copiée depuis l’inspecteur MCP. - -6. Trouvez le "Client ID" ou "Application ID" de la nouvelle application et copiez-le. - -7. Retournez dans l’inspecteur MCP et collez la valeur "Client ID" dans la section "Configuration OAuth" sous "Client ID". - -8. Saisissez la valeur suivante dans le champ "Auth Params" pour demander les portées nécessaires aux opérations todo : - -```json -{ "scope": "create:todos read:todos delete:todos" } -``` - - - - -### Configurer MCP Auth \{#set-up-mcp-auth} - -Dans votre projet serveur MCP, vous devez installer le SDK MCP Auth et le configurer pour utiliser les métadonnées de votre serveur d’autorisation. - - - - -D’abord, installez le paquet `mcpauth` : - -```bash -pip install mcpauth -``` - -Ou tout autre gestionnaire de paquets que vous préférez, comme `uv` ou `poetry`. - - - - -D’abord, installez le paquet `mcp-auth` : - -```bash -npm install mcp-auth -``` - - - - -MCP Auth nécessite les métadonnées du serveur d’autorisation pour pouvoir s’initialiser. Selon votre fournisseur : - - - - - -L’URL de l’émetteur peut être trouvée dans la page de détails de votre application dans Logto Console, dans la section "Endpoints & Credentials / Issuer endpoint". Elle devrait ressembler à `https://my-project.logto.app/oidc`. - - - - - - - -Pour les fournisseurs OAuth 2.0, vous devrez : - -1. Vérifier la documentation de votre fournisseur pour l’URL du serveur d’autorisation (souvent appelée issuer URL ou base URL) -2. Certains fournisseurs exposent cela à `https://{your-domain}/.well-known/oauth-authorization-server` -3. Cherchez dans la console d’administration de votre fournisseur sous les paramètres OAuth/API - - - - - - - - - - - -Mettez à jour le fichier `todo-manager.py` pour inclure la configuration MCP Auth : - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # Remplacez par votre endpoint issuer -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -Mettez à jour le fichier `todo-manager.ts` pour inclure la configuration MCP Auth : - -```ts -// todo-manager.ts - -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // Remplacez par votre endpoint issuer -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oidc' }), -}); -``` - - - - -### Mettre à jour le serveur MCP \{#update-mcp-server} - -Nous y sommes presque ! Il est temps de mettre à jour le serveur MCP pour appliquer la route et le middleware MCP Auth, puis d’implémenter le contrôle d’accès basé sur les permissions pour les outils du gestionnaire de tâches en fonction des portées de l’utilisateur. - - - - -```python -@mcp.tool() -def create_todo(content: str) -> dict[str, Any]: - """Créer une nouvelle tâche.""" - return ( - mcp_auth.auth_info.scopes - if mcp_auth.auth_info # Ceci sera renseigné par le middleware Bearer auth - else {"error": "Non authentifié"} - ) - -# ... - -bearer_auth = Middleware(mcp_auth.bearer_auth_middleware("jwt")) -app = Starlette( - routes=[ - # Ajouter la route metadata (`/.well-known/oauth-authorization-server`) - mcp_auth.metadata_route(), - # Protéger le serveur MCP avec le middleware Bearer auth - Mount('/', app=mcp.sse_app(), middleware=[bearer_auth]), - ], -) -``` - - - - -```js -server.tool( - 'create-todo', - 'Créer une nouvelle tâche', - { content: z.string() }, - async ({ content, authInfo }) => { - return { - content: [ - { type: 'text', text: JSON.stringify(authInfo?.scopes ?? { error: 'Non authentifié' }) }, - ], - }; - } -); - -// ... - -app.use(mcpAuth.delegatedRouter()); -app.use(mcpAuth.bearerAuth('jwt')); -``` - - - - -Ensuite, implémentons les outils spécifiques. - -Commençons par créer un service de tâches simple pour fournir des opérations CRUD de base pour la gestion des tâches en mémoire. - - - -```python -# service.py - -""" -Un service Todo simple à des fins de démonstration. -Utilise une liste en mémoire pour stocker les tâches. -""" - -from datetime import datetime -from typing import List, Optional, Dict, Any -import random -import string - -class Todo: -"""Représente une tâche.""" - - def __init__(self, id: str, content: str, owner_id: str, created_at: str): - self.id = id - self.content = content - self.owner_id = owner_id - self.created_at = created_at - - def to_dict(self) -> Dict[str, Any]: - """Convertir la tâche en dictionnaire pour la sérialisation JSON.""" - return { - "id": self.id, - "content": self.content, - "ownerId": self.owner_id, - "createdAt": self.created_at - } - -class TodoService: -"""Un service Todo simple à des fins de démonstration.""" - - def __init__(self): - self._todos: List[Todo] = [] - - def get_all_todos(self, owner_id: Optional[str] = None) -> List[Dict[str, Any]]: - """ - Obtenir toutes les tâches, éventuellement filtrées par owner_id. - - Args: - owner_id: Si fourni, ne retourne que les tâches appartenant à cet utilisateur - - Returns: - Liste de dictionnaires de tâches - """ - if owner_id: - filtered_todos = [todo for todo in self._todos if todo.owner_id == owner_id] - return [todo.to_dict() for todo in filtered_todos] - return [todo.to_dict() for todo in self._todos] - - def get_todo_by_id(self, todo_id: str) -> Optional[Todo]: - """ - Obtenir une tâche par son ID. - - Args: - todo_id: L’ID de la tâche à récupérer - - Returns: - Objet Todo si trouvé, None sinon - """ - for todo in self._todos: - if todo.id == todo_id: - return todo - return None - - def create_todo(self, content: str, owner_id: str) -> Dict[str, Any]: - """ - Créer une nouvelle tâche. - - Args: - content: Le contenu de la tâche - owner_id: L’ID de l’utilisateur propriétaire de cette tâche - - Returns: - Dictionnaire représentant la tâche créée - """ - todo = Todo( - id=self._generate_id(), - content=content, - owner_id=owner_id, - created_at=datetime.now().isoformat() - ) - self._todos.append(todo) - return todo.to_dict() - - def delete_todo(self, todo_id: str) -> Optional[Dict[str, Any]]: - """ - Supprimer une tâche par son ID. - - Args: - todo_id: L’ID de la tâche à supprimer - - Returns: - Dictionnaire représentant la tâche supprimée si trouvée, None sinon - """ - for i, todo in enumerate(self._todos): - if todo.id == todo_id: - deleted_todo = self._todos.pop(i) - return deleted_todo.to_dict() - return None - - def _generate_id(self) -> str: - """Générer un ID aléatoire pour une tâche.""" - return ''.join(random.choices(string.ascii_lowercase + string.digits, k=8)) - -```` - - - - - -```ts -// todo-service.ts - -type Todo = { - id: string; - content: string; - ownerId: string; - createdAt: string; -}; - -/** - * Un service Todo simple à des fins de démonstration. - * Utilise un tableau en mémoire pour stocker les tâches - */ -export class TodoService { - private readonly todos: Todo[] = []; - - getAllTodos(ownerId?: string): Todo[] { - if (ownerId) { - return this.todos.filter((todo) => todo.ownerId === ownerId); - } - return this.todos; - } - - getTodoById(id: string): Todo | undefined { - return this.todos.find((todo) => todo.id === id); - } - - createTodo({ content, ownerId }: { content: string; ownerId: string }): Todo { - const todo: Todo = { - id: this.genId(), - content, - ownerId, - createdAt: new Date().toISOString(), - }; - - // eslint-disable-next-line @silverhand/fp/no-mutating-methods - this.todos.push(todo); - return todo; - } - - deleteTodo(id: string): Todo | undefined { - const index = this.todos.findIndex((todo) => todo.id === id); - - if (index === -1) { - return undefined; - } - - // eslint-disable-next-line @silverhand/fp/no-mutating-methods - const [deleted] = this.todos.splice(index, 1); - return deleted; - } - - private genId(): string { - return Math.random().toString(36).slice(2, 10); - } -} -```` - - - - -puis dans la couche outils, nous déterminerons si les opérations sont autorisées en fonction des portées de l’utilisateur : - - - - -```python -# todo-manager.py - -from typing import Any, Optional -from mcpauth.errors import MCPAuthBearerAuthError - -def assert_user_id(auth_info: Optional[dict]) -> str: - """Extraire et valider l’ID utilisateur depuis les infos d’auth.""" - subject = auth_info.get('subject') if auth_info else None - if not subject: - raise ValueError('Invalid auth info') - return subject - -def has_required_scopes(user_scopes: list[str], required_scopes: list[str]) -> bool: - """Vérifier si l’utilisateur possède toutes les portées requises.""" - return all(scope in user_scopes for scope in required_scopes) - -# Créer une instance de TodoService -todo_service = TodoService() - -@mcp.tool() -def create_todo(content: str) -> dict[str, Any]: - """Créer une nouvelle tâche. - - Seuls les utilisateurs avec la portée 'create:todos' peuvent créer des tâches. - """ - # Obtenir les infos d’authentification - auth_info = mcp_auth.auth_info - - # Valider l’ID utilisateur - try: - user_id = assert_user_id(auth_info) - except ValueError as e: - return {"error": str(e)} - - # Vérifier si l’utilisateur a les permissions requises - if not has_required_scopes(auth_info.scopes if auth_info else [], ['create:todos']): - raise MCPAuthBearerAuthError('missing_required_scopes') - - # Créer la nouvelle tâche - created_todo = todo_service.create_todo(content=content, owner_id=user_id) - - # Retourner la tâche créée - return created_todo.__dict__ - -# ... -``` - -Vous pouvez consulter notre [code d’exemple](https://github.com/mcp-auth/python/tree/master/samples/server) pour toutes les autres implémentations détaillées. - - - - -```ts -// todo-manager.ts - -// ... autres imports -import assert from 'node:assert'; -import { type AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js'; -import { TodoService } from './todo-service.js'; - -const todoService = new TodoService(); - -const assertUserId = (authInfo?: AuthInfo) => { - const { subject } = authInfo ?? {}; - assert(subject, 'Invalid auth info'); - return subject; -}; - -/** - * Vérifie si l’utilisateur possède toutes les portées requises pour une opération - */ -const hasRequiredScopes = (userScopes: string[], requiredScopes: string[]): boolean => { - return requiredScopes.every((scope) => userScopes.includes(scope)); -}; - -server.tool( - 'create-todo', - 'Créer une nouvelle tâche', - { content: z.string() }, - ({ content }: { content: string }, { authInfo }) => { - const userId = assertUserId(authInfo); - - /** - * Seuls les utilisateurs avec la portée 'create:todos' peuvent créer des tâches - */ - if (!hasRequiredScopes(authInfo?.scopes ?? [], ['create:todos'])) { - throw new MCPAuthBearerAuthError('missing_required_scopes'); - } - - const createdTodo = todoService.createTodo({ content, ownerId: userId }); - - return { - content: [{ type: 'text', text: JSON.stringify(createdTodo) }], - }; - } -); - -// ... -``` - -Vous pouvez consulter notre [code d’exemple](https://github.com/mcp-auth/js/tree/master/packages/sample-servers/src/todo-manager) pour toutes les autres implémentations détaillées. - - - - -## Point de contrôle : Exécuter les outils `todo-manager` \{#checkpoint-run-the-todo-manager-tools} - -Redémarrez votre serveur MCP et ouvrez l’inspecteur MCP dans votre navigateur. Lorsque vous cliquez sur le bouton "Connecter", vous devriez être redirigé vers la page de connexion de votre serveur d’autorisation. - -Une fois connecté et de retour dans l’inspecteur MCP, répétez les actions du point de contrôle précédent pour exécuter les outils du gestionnaire de tâches. Cette fois, vous pouvez utiliser ces outils avec votre identité utilisateur authentifiée. Le comportement des outils dépendra des rôles et permissions attribués à votre utilisateur : - -- Si vous êtes connecté en tant que **User** (avec uniquement la portée `create:todos`) : - - - Vous pouvez créer de nouvelles tâches avec l’outil `create-todo` - - Vous ne pouvez voir et supprimer que vos propres tâches - - Vous ne pourrez pas voir ou supprimer les tâches des autres utilisateurs - -- Si vous êtes connecté en tant qu’**Admin** (avec toutes les portées : `create:todos`, `read:todos`, `delete:todos`) : - - Vous pouvez créer de nouvelles tâches - - Vous pouvez voir toutes les tâches du système avec l’outil `get-todos` - - Vous pouvez supprimer n’importe quelle tâche avec l’outil `delete-todo`, quel que soit le créateur - -Vous pouvez tester ces différents niveaux de permission en : - -1. Vous déconnectant de la session en cours (cliquez sur le bouton "Déconnecter" dans l’inspecteur MCP) -2. Vous connectant avec un autre compte utilisateur ayant des rôles / permissions différents -3. Essayant à nouveau les mêmes outils pour observer comment le comportement change selon les permissions de l’utilisateur - -Cela démontre comment le contrôle d’accès basé sur les rôles (RBAC) fonctionne en pratique, où différents utilisateurs ont différents niveaux d’accès aux fonctionnalités du système. - -![Résultat de l’outil todo manager dans l’inspecteur MCP](/docs-assets/images/tutorials/todo-manager/result.png) - - - - -:::info -Consultez le [dépôt du SDK MCP Auth Python](https://github.com/mcp-auth/python/blob/master/samples/server/todo-manager/server.py) pour le code complet du serveur MCP (version OIDC). -::: - - - - -:::info -Consultez le [dépôt du SDK MCP Auth Node.js](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) pour le code complet du serveur MCP (version OIDC). -::: - - - - -## Notes de clôture \{#closing-notes} - -🎊 Félicitations ! Vous avez terminé avec succès le tutoriel. Récapitulons ce que nous avons fait : - -- Mise en place d’un serveur MCP de base avec des outils de gestion de tâches (`create-todo`, `get-todos`, `delete-todo`) -- Implémentation du contrôle d’accès basé sur les rôles (RBAC) avec différents niveaux de permission pour les utilisateurs et les administrateurs -- Intégration du serveur MCP avec un serveur d’autorisation en utilisant MCP Auth -- Configuration de l’inspecteur MCP pour authentifier les utilisateurs et utiliser des jetons d’accès avec des portées pour appeler les outils - -N’hésitez pas à consulter d’autres tutoriels et la documentation pour tirer le meilleur parti de MCP Auth. diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_manual-metadata-fetching.mdx b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_manual-metadata-fetching.mdx deleted file mode 100644 index 5d038a6..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_manual-metadata-fetching.mdx +++ /dev/null @@ -1,3 +0,0 @@ -:::note -Si votre fournisseur ne prend pas en charge {props.oidc ? 'OpenID Connect Discovery' : 'Métadonnées du serveur d’autorisation OAuth 2.0'}, vous pouvez spécifier manuellement l’URL des métadonnées ou les points de terminaison. Consultez [Autres méthodes pour initialiser MCP Auth](../../configure-server/mcp-auth.mdx#other-ways) pour plus de détails. -::: \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oauth-or-oidc.mdx b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oauth-or-oidc.mdx deleted file mode 100644 index a668cac..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oauth-or-oidc.mdx +++ /dev/null @@ -1,41 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -Mettez à jour le fichier `todo-manager.py` pour inclure la configuration MCP Auth : - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # Remplacez par votre endpoint d’émetteur -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OAUTH) # ou AuthServerType.OIDC -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -Mettez à jour le fichier `todo-manager.ts` pour inclure la configuration MCP Auth : - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // Remplacez par votre endpoint d’émetteur -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oauth' }), // ou { type: 'oidc' } -}); -``` - - - - - - \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oidc.mdx b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oidc.mdx deleted file mode 100644 index df0eba4..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oidc.mdx +++ /dev/null @@ -1,41 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -Mettez à jour le fichier `todo-manager.py` pour inclure la configuration MCP Auth : - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # Remplacez par votre endpoint d’émetteur -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -Mettez à jour le fichier `todo-manager.ts` pour inclure la configuration MCP Auth : - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // Remplacez par votre endpoint d’émetteur -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oidc' }), -}); -``` - - - - -{props.showAlternative && } -{props.showAlternative && } \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_transpile-metadata.mdx b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_transpile-metadata.mdx deleted file mode 100644 index bf721d9..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_transpile-metadata.mdx +++ /dev/null @@ -1,31 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -Dans certains cas, la réponse du fournisseur peut être mal formée ou ne pas être conforme au format de métadonnées attendu. Si vous êtes certain que le fournisseur est conforme, vous pouvez transpiler les métadonnées via l’option de configuration : - - - - -```python -mcp_auth = MCPAuth( - server=fetch_server_config( - # ...autres options - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { - // ...autres options - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/README.mdx b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/README.mdx deleted file mode 100644 index 23ce33a..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/README.mdx +++ /dev/null @@ -1,611 +0,0 @@ ---- -sidebar_position: 1 -sidebar_label: 'Tutoriel : Qui suis-je ?' ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import SetupOauth from './_setup-oauth.mdx'; -import SetupOidc from './_setup-oidc.mdx'; - -# Tutoriel : Qui suis-je ? (Tutorial: Who am I?) - -Ce tutoriel vous guidera à travers le processus de configuration de MCP Auth pour authentifier les utilisateurs et récupérer leurs informations d'identité depuis le serveur d’autorisation (Authorization Server). - -Après avoir terminé ce tutoriel, vous aurez : - -- ✅ Une compréhension de base de l’utilisation de MCP Auth pour authentifier les utilisateurs. -- ✅ Un serveur MCP qui offre un outil pour récupérer les informations d'identité utilisateur. - -## Vue d’ensemble \{#overview} - -Le tutoriel impliquera les composants suivants : - -- **Serveur MCP** : Un serveur MCP simple qui utilise les SDK officiels MCP pour gérer les requêtes. -- **Inspecteur MCP** : Un outil de test visuel pour les serveurs MCP. Il agit également comme un client OAuth / OIDC pour initier le flux d’autorisation et récupérer les jetons d’accès (Access tokens). -- **Serveur d’autorisation (Authorization server)** : Un fournisseur OAuth 2.1 ou OpenID Connect qui gère les identités utilisateur et émet les jetons d’accès (Access tokens). - -Voici un schéma de haut niveau de l’interaction entre ces composants : - -```mermaid -sequenceDiagram - participant Client as Inspecteur MCP - participant Server as Serveur MCP - participant Auth as Serveur d’autorisation - - Client->>Server: Demande de l’outil `whoami` - Server->>Client: Retourne 401 Non autorisé - Client->>Auth: Initie le flux d’autorisation - Auth->>Auth: Complète le flux d’autorisation - Auth->>Client: Redirige avec le code d’autorisation - Client->>Auth: Échange le code contre un jeton d’accès - Auth->>Client: Retourne le jeton d’accès - Client->>Server: Demande `whoami` avec le jeton d’accès - Server->>Auth: Récupère l’identité utilisateur avec le jeton d’accès - Auth->>Server: Retourne l’identité utilisateur - Server->>Client: Retourne l’identité utilisateur -``` - -## Comprendre votre serveur d’autorisation \{#understand-your-authorization-server} - -### Récupérer les informations d'identité utilisateur \{#retrieving-user-identity-information} - -Pour compléter ce tutoriel, votre serveur d’autorisation doit offrir une API pour récupérer les informations d'identité utilisateur : - - - - -[Logto](https://logto.io) est un fournisseur OpenID Connect qui prend en charge l’[endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) standard pour récupérer les informations d'identité utilisateur. - -Pour obtenir un jeton d’accès (Access token) utilisable sur l’endpoint userinfo, au moins deux portées (Scopes) sont requises : `openid` et `profile`. Vous pouvez continuer à lire, car nous aborderons la configuration des portées plus loin. - - - - -[Keycloak](https://www.keycloak.org) est une solution open-source de gestion des identités et des accès qui prend en charge plusieurs protocoles, dont OpenID Connect (OIDC). En tant que fournisseur OIDC, il implémente l’[endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) standard pour récupérer les informations d'identité utilisateur. - -Pour obtenir un jeton d’accès (Access token) utilisable sur l’endpoint userinfo, au moins deux portées (Scopes) sont requises : `openid` et `profile`. Vous pouvez continuer à lire, car nous aborderons la configuration des portées plus loin. - - - - -La plupart des fournisseurs OpenID Connect prennent en charge l’[endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) pour récupérer les informations d'identité utilisateur. - -Consultez la documentation de votre fournisseur pour vérifier s’il prend en charge cet endpoint. Si votre fournisseur prend en charge [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html), vous pouvez également vérifier si le `userinfo_endpoint` est inclus dans le document de découverte (réponse de l’endpoint `.well-known/openid-configuration`). - -Pour obtenir un jeton d’accès (Access token) utilisable sur l’endpoint userinfo, au moins deux portées (Scopes) sont requises : `openid` et `profile`. Consultez la documentation de votre fournisseur pour voir la correspondance des portées avec les revendications d'identité utilisateur. - - - - -Bien que OAuth 2.0 ne définisse pas de méthode standard pour récupérer les informations d'identité utilisateur, de nombreux fournisseurs implémentent leurs propres endpoints à cet effet. Consultez la documentation de votre fournisseur pour savoir comment récupérer les informations d'identité utilisateur à l’aide d’un jeton d’accès (Access token) et quels paramètres sont requis pour obtenir ce jeton lors de l’appel du flux d’autorisation. - - - - -### Enregistrement dynamique du client \{#dynamic-client-registration} - -L’enregistrement dynamique du client n’est pas requis pour ce tutoriel, mais il peut être utile si vous souhaitez automatiser le processus d’enregistrement du client MCP auprès de votre serveur d’autorisation. Consultez [L’enregistrement dynamique du client est-il requis ?](/provider-list#is-dcr-required) pour plus de détails. - -## Configurer le serveur MCP \{#set-up-the-mcp-server} - -Nous allons utiliser les [SDK officiels MCP](https://github.com/modelcontextprotocol) pour créer un serveur MCP avec un outil `whoami` qui récupère les informations d'identité utilisateur depuis le serveur d’autorisation. - -### Créer un nouveau projet \{#create-a-new-project} - - - - -```bash -mkdir mcp-server -cd mcp-server -uv init # Ou utilisez `pipenv` ou `poetry` pour créer un nouvel environnement virtuel -``` - - - - -Créez un nouveau projet Node.js : - -```bash -mkdir mcp-server -cd mcp-server -npm init -y # Ou utilisez `pnpm init` -npm pkg set type="module" -npm pkg set main="whoami.js" -npm pkg set scripts.start="node whoami.js" -``` - - - - -### Installer le SDK MCP et les dépendances \{#install-the-mcp-sdk-and-dependencies} - - - - -```bash -pip install "mcp[cli]" starlette uvicorn -``` - -Ou tout autre gestionnaire de paquets que vous préférez, comme `uv` ou `poetry`. - - - - -```bash -npm install @modelcontextprotocol/sdk express -``` - -Ou tout autre gestionnaire de paquets que vous préférez, comme `pnpm` ou `yarn`. - - - - -### Créer le serveur MCP \{#create-the-mcp-server} - -Commençons par créer un serveur MCP qui implémente un outil `whoami`. - - - - -Créez un fichier nommé `whoami.py` et ajoutez le code suivant : - -```python -from mcp.server.fastmcp import FastMCP -from starlette.applications import Starlette -from starlette.routing import Mount -from typing import Any - -mcp = FastMCP("WhoAmI") - -@mcp.tool() -def whoami() -> dict[str, Any]: - """Un outil qui retourne les informations de l’utilisateur courant.""" - return {"error": "Not authenticated"} - -app = Starlette( - routes=[Mount('/', app=mcp.sse_app())] -) -``` - -Lancez le serveur avec : - -```bash -uvicorn whoami:app --host 0.0.0.0 --port 3001 -``` - - - - -:::note -Comme l’implémentation actuelle de l’inspecteur MCP ne gère pas les flux d’autorisation, nous utiliserons l’approche SSE pour configurer le serveur MCP. Nous mettrons à jour le code ici dès que l’inspecteur MCP prendra en charge les flux d’autorisation. -::: - -Vous pouvez également utiliser `pnpm` ou `yarn` si vous préférez. - -Créez un fichier nommé `whoami.js` et ajoutez le code suivant : - -```js -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; -import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'; -import express from 'express'; - -// Créez un serveur MCP -const server = new McpServer({ - name: 'WhoAmI', - version: '0.0.0', -}); - -// Ajoutez un outil au serveur qui retourne les informations de l’utilisateur courant -server.tool('whoami', async () => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Not authenticated' }) }], - }; -}); - -// Ci-dessous, le code standard issu de la documentation du SDK MCP -const PORT = 3001; -const app = express(); - -const transports = {}; - -app.get('/sse', async (_req, res) => { - const transport = new SSEServerTransport('/messages', res); - transports[transport.sessionId] = transport; - - res.on('close', () => { - delete transports[transport.sessionId]; - }); - - await server.connect(transport); -}); - -app.post('/messages', async (req, res) => { - const sessionId = String(req.query.sessionId); - const transport = transports[sessionId]; - if (transport) { - await transport.handlePostMessage(req, res, req.body); - } else { - res.status(400).send('No transport found for sessionId'); - } -}); - -app.listen(PORT); -``` - -Lancez le serveur avec : - -```bash -npm start -``` - - - - -## Inspecter le serveur MCP \{#inspect-the-mcp-server} - -### Cloner et lancer l’inspecteur MCP \{#clone-and-run-mcp-inspector} - -Maintenant que le serveur MCP fonctionne, nous pouvons utiliser l’inspecteur MCP pour vérifier si l’outil `whoami` est disponible. - -En raison des limites de l’implémentation actuelle, nous avons forké l’[inspecteur MCP](https://github.com/mcp-auth/inspector) pour le rendre plus flexible et évolutif pour l’authentification (Authentication) et l’autorisation (Authorization). Nous avons également soumis une pull request au dépôt original pour inclure nos modifications. - -Pour lancer l’inspecteur MCP, vous pouvez utiliser la commande suivante (Node.js est requis) : - -```bash -git clone https://github.com/mcp-auth/inspector.git -cd inspector -npm install -npm run dev -``` - -Ensuite, ouvrez votre navigateur et accédez à `http://localhost:6274/` (ou à l’URL affichée dans le terminal) pour accéder à l’inspecteur MCP. - -### Connecter l’inspecteur MCP au serveur MCP \{#connect-mcp-inspector-to-the-mcp-server} - -Avant de continuer, vérifiez la configuration suivante dans l’inspecteur MCP : - -- **Type de transport** : Réglez sur `SSE`. -- **URL** : Réglez sur l’URL de votre serveur MCP. Dans notre cas, il s’agit de `http://localhost:3001/sse`. - -Vous pouvez maintenant cliquer sur le bouton "Connecter" pour voir si l’inspecteur MCP peut se connecter au serveur MCP. Si tout est correct, vous devriez voir le statut "Connecté" dans l’inspecteur MCP. - -### Point de contrôle : Exécuter l’outil `whoami` \{#checkpoint-run-the-whoami-tool} - -1. Dans le menu supérieur de l’inspecteur MCP, cliquez sur l’onglet "Outils". -2. Cliquez sur le bouton "Lister les outils". -3. Vous devriez voir l’outil `whoami` listé sur la page. Cliquez dessus pour ouvrir les détails de l’outil. -4. Vous devriez voir le bouton "Exécuter l’outil" à droite. Cliquez dessus pour exécuter l’outil. -5. Vous devriez voir le résultat de l’outil avec la réponse JSON `{"error": "Not authenticated"}`. - -![Première exécution de l’inspecteur MCP](/docs-assets/images/tutorials/whoami/inspector-first-run.png) - -## Intégrer avec votre serveur d’autorisation \{#integrate-with-your-authorization-server} - -Pour compléter cette section, plusieurs points sont à prendre en compte : - -
-**L’URL de l’émetteur (Issuer) de votre serveur d’autorisation** - -Il s’agit généralement de l’URL de base de votre serveur d’autorisation, comme `https://auth.example.com`. Certains fournisseurs peuvent avoir un chemin comme `https://example.logto.app/oidc`, alors assurez-vous de vérifier la documentation de votre fournisseur. - -
- -
-**Comment récupérer les métadonnées du serveur d’autorisation** - -- Si votre serveur d’autorisation est conforme à la [spécification OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) ou à [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html), vous pouvez utiliser les utilitaires intégrés de MCP Auth pour récupérer automatiquement les métadonnées. -- Si votre serveur d’autorisation n’est pas conforme à ces standards, vous devrez spécifier manuellement l’URL des métadonnées ou les endpoints dans la configuration du serveur MCP. Consultez la documentation de votre fournisseur pour les endpoints spécifiques. - -
- -
-**Comment enregistrer l’inspecteur MCP comme client dans votre serveur d’autorisation** - -- Si votre serveur d’autorisation prend en charge [l’enregistrement dynamique du client](https://datatracker.ietf.org/doc/html/rfc7591), vous pouvez ignorer cette étape car l’inspecteur MCP s’enregistrera automatiquement comme client. -- Si votre serveur d’autorisation ne prend pas en charge l’enregistrement dynamique du client, vous devrez enregistrer manuellement l’inspecteur MCP comme client dans votre serveur d’autorisation. - -
- -
-**Comment récupérer les informations d'identité utilisateur et comment configurer les paramètres de la requête d’autorisation** - -- Pour les fournisseurs OpenID Connect : généralement, vous devez demander au moins les portées (Scopes) `openid` et `profile` lors de l’initiation du flux d’autorisation. Cela garantira que le jeton d’accès (Access token) retourné par le serveur d’autorisation contient les portées nécessaires pour accéder à l’[endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) et récupérer les informations d'identité utilisateur. - - Remarque : certains fournisseurs peuvent ne pas prendre en charge l’endpoint userinfo. - -- Pour les fournisseurs OAuth 2.0 / OAuth 2.1 : consultez la documentation de votre fournisseur pour savoir comment récupérer les informations d'identité utilisateur à l’aide d’un jeton d’accès (Access token) et quels paramètres sont requis pour obtenir ce jeton lors de l’appel du flux d’autorisation. - -
- -Bien que chaque fournisseur puisse avoir ses propres exigences spécifiques, les étapes suivantes vous guideront dans le processus d’intégration de l’inspecteur MCP et du serveur MCP avec des configurations spécifiques au fournisseur. - -### Enregistrer l’inspecteur MCP comme client \{#register-mcp-inspector-as-a-client} - - - - -L’intégration avec [Logto](https://logto.io) est simple puisqu’il s’agit d’un fournisseur OpenID Connect qui prend en charge l’[endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) standard pour récupérer les informations d'identité utilisateur. - -Comme Logto ne prend pas encore en charge l’enregistrement dynamique du client, vous devrez enregistrer manuellement l’inspecteur MCP comme client dans votre tenant Logto : - -1. Ouvrez votre inspecteur MCP, cliquez sur le bouton "Configuration OAuth". Copiez la valeur **Redirect URL (auto-populated)**, qui devrait ressembler à `http://localhost:6274/oauth/callback`. -2. Connectez-vous à [Logto Console](https://cloud.logto.io) (ou à votre Logto Console auto-hébergée). -3. Accédez à l’onglet "Applications", cliquez sur "Créer une application". En bas de la page, cliquez sur "Créer une application sans framework". -4. Remplissez les détails de l’application, puis cliquez sur "Créer l’application" : - - **Sélectionnez un type d’application** : Choisissez "Application monopage". - - **Nom de l’application** : Entrez un nom pour votre application, par exemple "MCP Inspector". -5. Dans la section "Paramètres / URI de redirection", collez la valeur **Redirect URL (auto-populated)** copiée depuis l’inspecteur MCP. Cliquez ensuite sur "Enregistrer les modifications" dans la barre du bas. -6. Dans la carte du haut, vous verrez la valeur "App ID". Copiez-la. -7. Retournez dans l’inspecteur MCP et collez la valeur "App ID" dans la section "Configuration OAuth" sous "Client ID". -8. Entrez la valeur `{"scope": "openid profile email"}` dans le champ "Auth Params". Cela garantira que le jeton d’accès (Access token) retourné par Logto contient les portées nécessaires pour accéder à l’endpoint userinfo. - - - - -[Keycloak](https://www.keycloak.org) est une solution open-source de gestion des identités et des accès qui prend en charge le protocole OpenID Connect. - -Bien que Keycloak prenne en charge l’enregistrement dynamique du client, son endpoint d’enregistrement ne prend pas en charge CORS, ce qui empêche la plupart des clients MCP de s’enregistrer directement. Nous devrons donc enregistrer notre client manuellement. - -:::note -Bien que Keycloak puisse être installé de [différentes manières](https://www.keycloak.org/guides#getting-started) (bare metal, kubernetes, etc.), pour ce tutoriel, nous utiliserons Docker pour une configuration rapide et simple. -::: - -Configurons une instance Keycloak et adaptons-la à nos besoins : - -1. Lancez une instance Keycloak avec Docker en suivant la [documentation officielle](https://www.keycloak.org/getting-started/getting-started-docker) : - -```bash -docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.2.4 start-dev -``` - -2. Accédez à la console d’administration Keycloak (http://localhost:8080/admin) et connectez-vous avec ces identifiants : - - - Nom d’utilisateur : `admin` - - Mot de passe : `admin` - -3. Créez un nouveau Realm : - - - Cliquez sur "Create Realm" en haut à gauche - - Entrez `mcp-realm` dans le champ "Realm name" - - Cliquez sur "Create" - -4. Créez un utilisateur de test : - - - Cliquez sur "Users" dans le menu de gauche - - Cliquez sur "Create new user" - - Remplissez les informations utilisateur : - - Nom d’utilisateur : `testuser` - - Prénom et nom peuvent être quelconques - - Cliquez sur "Create" - - Dans l’onglet "Credentials", définissez un mot de passe et décochez "Temporary" - -5. Enregistrez l’inspecteur MCP comme client : - - - Ouvrez votre inspecteur MCP, cliquez sur le bouton "Configuration OAuth". Copiez la valeur **Redirect URL (auto-populated)**, qui devrait ressembler à `http://localhost:6274/oauth/callback`. - - Dans la console d’administration Keycloak, cliquez sur "Clients" dans le menu de gauche - - Cliquez sur "Create client" - - Remplissez les détails du client : - - Type de client : Sélectionnez "OpenID Connect" - - Client ID : Entrez `mcp-inspector` - - Cliquez sur "Next" - - Sur la page "Capability config" : - - Assurez-vous que "Standard flow" est activé - - Cliquez sur "Next" - - Sur la page "Login settings" : - - Collez l’URL de rappel de l’inspecteur MCP précédemment copiée dans "Valid redirect URIs" - - Entrez `http://localhost:6274` dans "Web origins" - - Cliquez sur "Save" - - Copiez le "Client ID" (qui est `mcp-inspector`) - -6. De retour dans l’inspecteur MCP : - - Collez le Client ID copié dans le champ "Client ID" de la section "Configuration OAuth" - - Entrez la valeur suivante dans le champ "Auth Params" pour demander les portées nécessaires : - -```json -{ "scope": "openid profile email" } -``` - - - - -:::note -Ceci est un guide générique d’intégration avec un fournisseur OpenID Connect. Consultez la documentation de votre fournisseur pour les détails spécifiques. -::: - -Si votre fournisseur OpenID Connect prend en charge l’enregistrement dynamique du client, vous pouvez passer directement à l’étape 8 ci-dessous pour configurer l’inspecteur MCP ; sinon, vous devrez enregistrer manuellement l’inspecteur MCP comme client dans votre fournisseur OpenID Connect : - -1. Ouvrez votre inspecteur MCP, cliquez sur le bouton "Configuration OAuth". Copiez la valeur **Redirect URL (auto-populated)**, qui devrait ressembler à `http://localhost:6274/oauth/callback`. -2. Connectez-vous à la console de votre fournisseur OpenID Connect. -3. Accédez à la section "Applications" ou "Clients", puis créez une nouvelle application ou un nouveau client. -4. Si votre fournisseur demande un type de client, sélectionnez "Application monopage" ou "Client public". -5. Après avoir créé l’application, vous devrez configurer l’URI de redirection. Collez la valeur **Redirect URL (auto-populated)** copiée depuis l’inspecteur MCP. -6. Trouvez le "Client ID" ou "Application ID" de la nouvelle application et copiez-le. -7. Retournez dans l’inspecteur MCP et collez la valeur "Client ID" dans la section "Configuration OAuth" sous "Client ID". -8. Pour les fournisseurs OpenID Connect standards, vous pouvez entrer la valeur suivante dans le champ "Auth Params" pour demander les portées nécessaires à l’accès à l’endpoint userinfo : - -```json -{ "scope": "openid profile email" } -``` - - - - -:::note -Ceci est un guide générique d’intégration avec un fournisseur OAuth 2.0 / OAuth 2.1. Consultez la documentation de votre fournisseur pour les détails spécifiques. -::: - -Si votre fournisseur OAuth 2.0 / OAuth 2.1 prend en charge l’enregistrement dynamique du client, vous pouvez passer directement à l’étape 8 ci-dessous pour configurer l’inspecteur MCP ; sinon, vous devrez enregistrer manuellement l’inspecteur MCP comme client dans votre fournisseur OAuth 2.0 / OAuth 2.1 : - -1. Ouvrez votre inspecteur MCP, cliquez sur le bouton "Configuration OAuth". Copiez la valeur **Redirect URL (auto-populated)**, qui devrait ressembler à `http://localhost:6274/oauth/callback`. -2. Connectez-vous à la console de votre fournisseur OAuth 2.0 / OAuth 2.1. -3. Accédez à la section "Applications" ou "Clients", puis créez une nouvelle application ou un nouveau client. -4. Si votre fournisseur demande un type de client, sélectionnez "Application monopage" ou "Client public". -5. Après avoir créé l’application, vous devrez configurer l’URI de redirection. Collez la valeur **Redirect URL (auto-populated)** copiée depuis l’inspecteur MCP. -6. Trouvez le "Client ID" ou "Application ID" de la nouvelle application et copiez-le. -7. Retournez dans l’inspecteur MCP et collez la valeur "Client ID" dans la section "Configuration OAuth" sous "Client ID". -8. Consultez la documentation de votre fournisseur pour savoir comment obtenir des jetons d’accès pour les informations d'identité utilisateur. Vous devrez peut-être spécifier les portées ou paramètres requis pour obtenir le jeton d’accès. Par exemple, si votre fournisseur exige la portée `profile` pour accéder aux informations d'identité utilisateur, vous pouvez entrer la valeur suivante dans le champ "Auth Params" : - -```json -{ "scope": "profile" } -``` - - - - -### Configurer MCP Auth \{#set-up-mcp-auth} - -Dans votre projet serveur MCP, vous devez installer le SDK MCP Auth et le configurer pour utiliser les métadonnées de votre serveur d’autorisation. - - - - -D’abord, installez le paquet `mcpauth` : - -```bash -pip install mcpauth -``` - -Ou tout autre gestionnaire de paquets que vous préférez, comme `uv` ou `poetry`. - - - - -D’abord, installez le paquet `mcp-auth` : - -```bash -npm install mcp-auth -``` - - - - -MCP Auth nécessite les métadonnées du serveur d’autorisation pour pouvoir s’initialiser. Selon votre fournisseur : - - - - - -L’URL de l’émetteur (Issuer) se trouve sur la page de détails de votre application dans Logto Console, dans la section "Endpoints & Credentials / Issuer endpoint". Elle devrait ressembler à `https://my-project.logto.app/oidc`. - - - - - - - -L’URL de l’émetteur (Issuer) se trouve dans votre console d’administration Keycloak. Dans votre 'mcp-realm', accédez à la section "Realm settings / Endpoints" et cliquez sur le lien "OpenID Endpoint Configuration". Le champ `issuer` dans le document JSON contiendra votre URL d’émetteur, qui devrait ressembler à `http://localhost:8080/realms/mcp-realm`. - - - - - - - -Le code suivant suppose également que le serveur d’autorisation prend en charge l’[endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) pour récupérer les informations d'identité utilisateur. Si votre fournisseur ne prend pas en charge cet endpoint, vous devrez consulter la documentation de votre fournisseur pour l’endpoint spécifique et remplacer la variable userinfo endpoint par la bonne URL. - - - - - - -Comme mentionné précédemment, OAuth 2.0 ne définit pas de méthode standard pour récupérer les informations d'identité utilisateur. Le code suivant suppose que votre fournisseur dispose d’un endpoint spécifique pour récupérer les informations d'identité utilisateur à l’aide d’un jeton d’accès (Access token). Vous devrez consulter la documentation de votre fournisseur pour l’endpoint spécifique et remplacer la variable userinfo endpoint par la bonne URL. - - - - - - -### Mettre à jour le serveur MCP \{#update-mcp-server} - -Nous y sommes presque ! Il est temps de mettre à jour le serveur MCP pour appliquer la route MCP Auth et la fonction middleware, puis faire en sorte que l’outil `whoami` retourne les véritables informations d'identité utilisateur. - - - - -```python -@mcp.tool() -def whoami() -> dict[str, Any]: - """Un outil qui retourne les informations de l’utilisateur courant.""" - return ( - mcp_auth.auth_info.claims - if mcp_auth.auth_info # Ceci sera renseigné par le middleware Bearer auth - else {"error": "Not authenticated"} - ) - -# ... - -bearer_auth = Middleware(mcp_auth.bearer_auth_middleware(verify_access_token)) -app = Starlette( - routes=[ - # Ajoutez la route des métadonnées (`/.well-known/oauth-authorization-server`) - mcp_auth.metadata_route(), - # Protégez le serveur MCP avec le middleware Bearer auth - Mount('/', app=mcp.sse_app(), middleware=[bearer_auth]), - ], -) -``` - - - - -```js -server.tool('whoami', ({ authInfo }) => { - return { - content: [ - { type: 'text', text: JSON.stringify(authInfo?.claims ?? { error: 'Not authenticated' }) }, - ], - }; -}); - -// ... - -app.use(mcpAuth.delegatedRouter()); -app.use(mcpAuth.bearerAuth(verifyToken)); -``` - - - - -## Point de contrôle : Exécuter l’outil `whoami` avec authentification \{#checkpoint-run-the-whoami-tool-with-authentication} - -Redémarrez votre serveur MCP et ouvrez l’inspecteur MCP dans votre navigateur. Lorsque vous cliquez sur le bouton "Connecter", vous devriez être redirigé vers la page de connexion de votre serveur d’autorisation. - -Une fois connecté et de retour dans l’inspecteur MCP, répétez les actions du point de contrôle précédent pour exécuter l’outil `whoami`. Cette fois, vous devriez voir les informations d'identité utilisateur retournées par le serveur d’autorisation. - -![Résultat de l’outil whoami dans l’inspecteur MCP](/docs-assets/images/tutorials/whoami/result.png) - - - - -:::info -Consultez le [dépôt du SDK MCP Auth Python](https://github.com/mcp-auth/python/blob/master/samples/server/whoami.py) pour le code complet du serveur MCP (version OIDC). -::: - - - - -:::info -Consultez le [dépôt du SDK MCP Auth Node.js](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) pour le code complet du serveur MCP (version OIDC). Ce répertoire contient les versions TypeScript et JavaScript du code. -::: - - - - -## Notes de clôture \{#closing-notes} - -🎊 Félicitations ! Vous avez terminé avec succès le tutoriel. Récapitulons ce que nous avons fait : - -- Mise en place d’un serveur MCP basique avec l’outil `whoami` -- Intégration du serveur MCP avec un serveur d’autorisation via MCP Auth -- Configuration de l’inspecteur MCP pour authentifier les utilisateurs et récupérer leurs informations d'identité - -Vous pouvez également explorer des sujets avancés, notamment : - -- Utiliser [JWT (JSON Web Token)](https://auth.wiki/jwt) pour l’authentification (Authentication) et l’autorisation (Authorization) -- Exploiter les [indicateurs de ressource (RFC 8707)](https://auth-wiki.logto.io/resource-indicator) pour spécifier les ressources accédées -- Implémenter des mécanismes de contrôle d’accès personnalisés, tels que le [contrôle d’accès basé sur les rôles (RBAC)](https://auth.wiki/rbac) ou le [contrôle d’accès basé sur les attributs (ABAC)](https://auth.wiki/abac) - -N’hésitez pas à consulter d’autres tutoriels et la documentation pour tirer le meilleur parti de MCP Auth. \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_manual-metadata-fetching.mdx b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_manual-metadata-fetching.mdx deleted file mode 100644 index 5d038a6..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_manual-metadata-fetching.mdx +++ /dev/null @@ -1,3 +0,0 @@ -:::note -Si votre fournisseur ne prend pas en charge {props.oidc ? 'OpenID Connect Discovery' : 'Métadonnées du serveur d’autorisation OAuth 2.0'}, vous pouvez spécifier manuellement l’URL des métadonnées ou les points de terminaison. Consultez [Autres méthodes pour initialiser MCP Auth](../../configure-server/mcp-auth.mdx#other-ways) pour plus de détails. -::: \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oauth.mdx b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oauth.mdx deleted file mode 100644 index 95331e8..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oauth.mdx +++ /dev/null @@ -1,141 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -Mettez à jour le fichier `whoami.py` pour inclure la configuration MCP Auth : - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # Remplacez par votre endpoint d’émetteur -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OAUTH) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -Mettez à jour le fichier `whoami.js` pour inclure la configuration MCP Auth : - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // Remplacez par votre endpoint d’émetteur -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oauth' }), -}); -``` - - - - - - - -Nous devons maintenant créer un vérificateur personnalisé de jeton d’accès (Access token) qui ira chercher les informations d'identité de l'utilisateur auprès du serveur d'autorisation en utilisant le jeton d’accès fourni par l’inspecteur MCP. - - - - -```python -import pydantic -import requests -from mcpauth.exceptions import ( - MCPAuthTokenVerificationException, - MCPAuthTokenVerificationExceptionCode, -) -from mcpauth.types import AuthInfo - -def verify_access_token(token: str) -> AuthInfo: - """ - Vérifie le jeton Bearer fourni en récupérant les informations utilisateur auprès du serveur d'autorisation. - Si le jeton est valide, retourne un objet `AuthInfo` contenant les informations de l'utilisateur. - - :param token: Le jeton Bearer reçu de l’inspecteur MCP. - """ - - try: - # Le code suivant suppose que votre serveur d'autorisation dispose d'un endpoint pour récupérer les infos utilisateur - # en utilisant le jeton d’accès émis par le flux d'autorisation. - # Adaptez l’URL et les en-têtes selon l’API de votre fournisseur. - response = requests.get( - "https://your-authorization-server.com/userinfo", - headers={"Authorization": f"Bearer {token}"}, - ) - response.raise_for_status() # S'assurer qu'une erreur est levée pour les erreurs HTTP - json = response.json() # Analyse la réponse JSON - - # Le code suivant suppose que la réponse contient un champ 'sub' qui identifie l'utilisateur. - # Vous devrez peut-être l’adapter selon l’API de votre fournisseur. - return AuthInfo( - token=token, - subject=json.get("sub"), - issuer=auth_issuer, # Utilisez l’émetteur configuré - claims=json, # Inclut toutes les revendications (champs JSON) retournées par l’endpoint - ) - # `AuthInfo` est un modèle Pydantic, donc les erreurs de validation signifient généralement que la réponse ne correspond pas - # à la structure attendue - except pydantic.ValidationError as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.INVALID_TOKEN, - cause=e, - ) - # Gérer les autres exceptions pouvant survenir lors de la requête - except Exception as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.TOKEN_VERIFICATION_FAILED, - cause=e, - ) -``` - - - - -```js -import { MCPAuthTokenVerificationError } from 'mcp-auth'; - -/** - * Vérifie le jeton Bearer fourni en récupérant les informations utilisateur auprès du serveur d'autorisation. - * Si le jeton est valide, retourne un objet `AuthInfo` contenant les informations de l'utilisateur. - */ -const verifyToken = async (token) => { - // Le code suivant suppose que votre serveur d'autorisation dispose d'un endpoint pour récupérer les infos utilisateur - // en utilisant le jeton d’accès émis par le flux d'autorisation. - // Adaptez l’URL et les en-têtes selon l’API de votre fournisseur. - const response = await fetch('https://your-authorization-server.com/userinfo', { - headers: { Authorization: `Bearer ${token}` }, - }); - - if (!response.ok) { - throw new MCPAuthTokenVerificationError('token_verification_failed', response); - } - - const userInfo = await response.json(); - - // Le code suivant suppose que la réponse contient un champ 'sub' qui identifie l'utilisateur. - // Vous devrez peut-être l’adapter selon l’API de votre fournisseur. - if (typeof userInfo !== 'object' || userInfo === null || !('sub' in userInfo)) { - throw new MCPAuthTokenVerificationError('invalid_token', response); - } - - return { - token, - issuer: authIssuer, - subject: String(userInfo.sub), // Adaptez ceci selon le champ d’ID utilisateur de votre fournisseur - clientId: '', // L’ID client n’est pas utilisé dans cet exemple, mais peut être défini si besoin - scopes: [], - claims: userInfo, - }; -}; -``` - - - diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oidc.mdx b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oidc.mdx deleted file mode 100644 index 16a71c7..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oidc.mdx +++ /dev/null @@ -1,143 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -Mettez à jour le fichier `whoami.py` pour inclure la configuration MCP Auth : - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # Remplacez par votre endpoint d’émetteur -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -Mettez à jour le fichier `whoami.js` pour inclure la configuration MCP Auth : - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // Remplacez par votre endpoint d’émetteur -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oidc' }), -}); -``` - - - - -{props.showAlternative && } -{props.showAlternative && } - -Nous devons maintenant créer un vérificateur personnalisé de jeton d’accès (Access token) qui ira chercher les informations d'identité de l'utilisateur auprès du serveur d'autorisation en utilisant le jeton d’accès fourni par l’inspecteur MCP. - - - - -```python -import pydantic -import requests -from mcpauth.exceptions import ( - MCPAuthTokenVerificationException, - MCPAuthTokenVerificationExceptionCode, -) -from mcpauth.types import AuthInfo - -def verify_access_token(token: str) -> AuthInfo: - """ - Vérifie le jeton Bearer fourni en récupérant les informations utilisateur depuis le serveur d'autorisation. - Si le jeton est valide, retourne un objet `AuthInfo` contenant les informations de l'utilisateur. - - :param token: Le jeton Bearer reçu de l’inspecteur MCP. - """ - - issuer = auth_server_config.metadata.issuer - endpoint = auth_server_config.metadata.userinfo_endpoint # Le fournisseur doit supporter l’endpoint userinfo - if not endpoint: - raise ValueError( - "L’endpoint userinfo n’est pas configuré dans les métadonnées du serveur d’authentification." - ) - - try: - response = requests.get( - endpoint, - headers={"Authorization": f"Bearer {token}"}, # En-tête standard Bearer token - ) - response.raise_for_status() # S’assurer de lever une erreur pour les erreurs HTTP - json = response.json() # Analyse la réponse JSON - return AuthInfo( - token=token, - subject=json.get("sub"), # 'sub' est une revendication standard pour le sujet (ID utilisateur) - issuer=issuer, # Utilise l’émetteur issu des métadonnées - claims=json, # Inclut toutes les revendications (champs JSON) retournées par l’endpoint userinfo - ) - # `AuthInfo` est un modèle Pydantic, donc les erreurs de validation signifient généralement que la réponse ne correspond pas - # à la structure attendue - except pydantic.ValidationError as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.INVALID_TOKEN, - cause=e, - ) - # Gérer les autres exceptions pouvant survenir lors de la requête - except Exception as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.TOKEN_VERIFICATION_FAILED, - cause=e, - ) -``` - - - - -```js -import { MCPAuthTokenVerificationError } from 'mcp-auth'; - -/** - * Vérifie le jeton Bearer fourni en récupérant les informations utilisateur depuis le serveur d'autorisation. - * Si le jeton est valide, retourne un objet `AuthInfo` contenant les informations de l'utilisateur. - */ -const verifyToken = async (token) => { - const { issuer, userinfoEndpoint } = mcpAuth.config.server.metadata; - - if (!userinfoEndpoint) { - throw new Error('L’endpoint userinfo n’est pas configuré dans les métadonnées du serveur'); - } - - const response = await fetch(userinfoEndpoint, { - headers: { Authorization: `Bearer ${token}` }, - }); - - if (!response.ok) { - throw new MCPAuthTokenVerificationError('token_verification_failed', response); - } - - const userInfo = await response.json(); - - if (typeof userInfo !== 'object' || userInfo === null || !('sub' in userInfo)) { - throw new MCPAuthTokenVerificationError('invalid_token', response); - } - - return { - token, - issuer, - subject: String(userInfo.sub), // 'sub' est une revendication standard pour le sujet (ID utilisateur) - clientId: '', // L’ID client n’est pas utilisé dans cet exemple, mais peut être défini si besoin - scopes: [], - claims: userInfo, - }; -}; -``` - - - diff --git a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_transpile-metadata.mdx b/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_transpile-metadata.mdx deleted file mode 100644 index bf721d9..0000000 --- a/i18n/fr/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_transpile-metadata.mdx +++ /dev/null @@ -1,31 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -Dans certains cas, la réponse du fournisseur peut être mal formée ou ne pas être conforme au format de métadonnées attendu. Si vous êtes certain que le fournisseur est conforme, vous pouvez transpiler les métadonnées via l’option de configuration : - - - - -```python -mcp_auth = MCPAuth( - server=fetch_server_config( - # ...autres options - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { - // ...autres options - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1.json b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1.json deleted file mode 100644 index cb8187e..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1.json +++ /dev/null @@ -1,50 +0,0 @@ -{ - "sidebar.docsSidebar.category.Tutorials": { - "message": "チュートリアル", - "description": "The label for category Tutorials in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.Tutorials.link.generated-index.title": { - "message": "チュートリアル", - "description": "The generated-index page title for category Tutorials in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.Configure MCP server": { - "message": "MCPサーバーの設定", - "description": "The label for category Configure MCP server in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.Configure MCP server.link.generated-index.title": { - "message": "MCPサーバーの設定", - "description": "The generated-index page title for category Configure MCP server in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.SDK references": { - "message": "SDKリファレンス", - "description": "The label for category SDK references in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.SDK references.link.generated-index.title": { - "message": "MCP Auth SDKリファレンス", - "description": "The generated-index page title for category SDK references in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.SDK references.link.generated-index.description": { - "message": "MCP Auth SDKから抽出されたクラス、メソッド、プロパティに関する情報。\n", - "description": "The generated-index page description for category SDK references in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.Node.js SDK": { - "message": "Node.js SDK", - "description": "The label for category Node.js SDK in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.classes": { - "message": "クラス", - "description": "The label for category classes in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.functions": { - "message": "関数", - "description": "The label for category functions in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.type-aliases": { - "message": "型エイリアス", - "description": "The label for category type-aliases in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.variables": { - "message": "変数", - "description": "The label for category variables in sidebar docsSidebar" - } -} diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/README.mdx b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/README.mdx deleted file mode 100644 index c8a5ba0..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/README.mdx +++ /dev/null @@ -1,242 +0,0 @@ ---- -sidebar_position: 1 -sidebar_label: はじめに ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -# はじめに - -## 互換性のある OAuth 2.1 または OpenID Connect プロバイダーを選択する \{#choose-a-compatible-oauth-2-1-or-openid-connect-provider} - -MCP 仕様では、認可 (Authorization) に関していくつかの [特定の要件](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization#1-3-standards-compliance) があります： - -- [OAuth 2.1 IETF DRAFT](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12) -- OAuth 2.0 認可サーバーメタデータ ([RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)) -- OAuth 2.0 動的クライアント登録プロトコル ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) - -最後の 2 つは必須ではありませんが、最初のものは安全かつ準拠した実装を確保するために必要です。 - -:::note -新しい MCP ドラフトでは、RFC 8414 が認可サーバー（プロバイダー）に必須となります。新しいドラフトが確定次第、ドキュメントを更新します。 -::: - -[互換性のある MCP プロバイダーリスト](/provider-list) で、プロバイダーがサポートされているか確認できます。 - -## MCP Auth SDK をインストールする \{#install-mcp-auth-sdk} - -MCP Auth は Python と TypeScript の両方で利用可能です。他の言語やフレームワークのサポートが必要な場合はお知らせください！ - - - - -```bash -pip install mcpauth -``` - -または、pipenv や poetry などお好みのパッケージマネージャーを利用できます。 - - - - -```bash -npm install mcp-auth -``` - -または、pnpm や yarn などお好みのパッケージマネージャーを利用できます。 - - - - -## MCP Auth を初期化する \{#init-mcp-auth} - -最初のステップは、プロバイダーの認可サーバーメタデータで MCP Auth インスタンスを初期化することです。プロバイダーが次のいずれかに準拠している場合： - -- [OAuth 2.0 認可サーバーメタデータ](https://datatracker.ietf.org/doc/html/rfc8414) -- [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) - -組み込み関数を使ってメタデータを取得し、MCP Auth インスタンスを初期化できます： - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -mcp_auth = MCPAuth( - server=fetch_server_config( - '', - type=AuthServerType.OIDC # または AuthServerType.OAUTH - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { type: 'oidc' }), // または 'oauth' -}); -``` - - - - -メタデータ URL やエンドポイントを手動で指定する必要がある場合は、[他の MCP Auth 初期化方法](./configure-server/mcp-auth.mdx#other-ways) をご覧ください。 - -## メタデータエンドポイントをマウントする \{#mount-the-metadata-endpoint} - -現在の MCP 仕様に準拠するため、MCP Auth は OAuth 2.0 認可サーバーメタデータエンドポイント (`/.well-known/oauth-authorization-server`) を MCP サーバーにマウントします： - - - - -```python -from starlette.applications import Starlette - -app = Starlette(routes=[ - mcp_auth.metadata_route(), -]) -``` - - - - -```ts -import express from 'express'; - -const app = express(); -app.use(mcpAuth.delegatedRouter()); -``` - - - - -メタデータ内の URL はそのまま保持されるため、認可サーバーの役割は完全にプロバイダーに委譲されます。`/.well-known/oauth-authorization-server` にアクセスして MCP サーバーでメタデータエンドポイントをテストできます。 - -### なぜメタデータエンドポイントだけなのか？ \{#why-only-the-metadata-endpoint} - -公式 SDK では `/authorize` や `/token` などの認可エンドポイントをマウントする認証ルーターが提供されている場合がありますが、私たちがそうしない理由は次の通りです： - -1. メタデータエンドポイントのみをマウントすることで、プロバイダーの機能を最大限活用でき、「車輪の再発明」を避け、MCP サーバーに不要な複雑さを持ち込まずに済みます。 -2. [MCP サーバーの役割をリソースサーバーへ移行する](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/205) 取り組みも進行中であり、OAuth 2.0 保護リソースメタデータ ([RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728)) が必要となります。つまり、MCP サーバーは **今後は認可ロジックを一切処理せず**（メタデータエンドポイントも含む）、プロバイダーに認証 (Authentication) と認可 (Authorization) を委ねるリソースサーバーとしてのみ機能します。 - -:::note -新しい MCP 仕様が確定次第、MCP Auth も対応予定です。それまでは現行仕様に対応したバージョンをご利用いただけます。 -::: - -## Bearer 認証ミドルウェアを利用する \{#use-the-bearer-auth-middleware} - -MCP Auth インスタンスを初期化したら、Bearer 認証ミドルウェアを適用して MCP ルートを保護できます： - - - - -```python -from starlette.applications import Starlette -from starlette.middleware import Middleware -from starlette.routing import Mount -from mcpauth import MCPAuth -from mcp.server.fastmcp import FastMCP - -mcp = FastMCP() -mcp_auth = MCPAuth( - # 認証サーバー設定で初期化 -) -bearer_auth = mcp_auth.bearer_auth_middleware( - "jwt", required_scopes=["read", "write"] -) - -app = Starlette(routes=[ - mcp_auth.metadata_route(), - Mount( - "/", - app=mcp.sse_app(), - middleware=[Middleware(bearer_auth)], - ), -]) -``` - - - - -```ts -import express from 'express'; -import { MCPAuth } from 'mcp-auth'; - -const app = express(); -const server = new McpServer(/* ... */); -const mcpAuth = new MCPAuth({ - /* ... */ -}); - -app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] })); -``` - - - - -上記の例では、`jwt` トークンタイプを指定し、`read` と `write` のスコープを必須としています。これにより JWT (JSON Web Token) を自動的に検証し、認証済みユーザー情報を含むオブジェクトが生成されます。 - -:::info -JWT (JSON Web Token) について初めて聞いた方もご安心ください。ドキュメント内で必要に応じて説明します。簡単な紹介は [Auth Wiki](https://auth.wiki/jwt) もご覧いただけます。 -::: - -Bearer 認証の設定について詳しくは、[Bearer 認証の設定](./configure-server/bearer-auth.mdx) をご覧ください。 - -## MCP 実装で認証情報を取得する \{#retrieve-the-auth-info-in-your-mcp-implementation} - -Bearer 認証ミドルウェアを適用すると、MCP 実装内で認証済みユーザー（またはアイデンティティ）の情報にアクセスできます： - - - - -Bearer 認証ミドルウェアが適用されると、MCP Auth は認証済みユーザー情報をコンテキスト変数に保存します。MCP ツールハンドラー内で次のようにアクセスできます： - -```python -from mcp.server.fastmcp import FastMCP - -mcp = FastMCP() -mcp_auth = MCPAuth( - # 認証サーバー設定で初期化 -) - -@mcp.tool() -def add(a: int, b: int): - """ - 2 つの数値を加算するツール。 - 認証済みユーザー情報はコンテキストで利用可能です。 - """ - auth_info = mcp_auth.auth_info # 現在のコンテキストで認証情報にアクセス - if auth_info: - print(f"Authenticated user: {auth_info.claims}") - return a + b -``` - - - - -ツールハンドラーの第 2 引数に `authInfo` オブジェクトが含まれ、認証済みユーザー情報を利用できます： - -```ts -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; -import { z } from 'zod'; - -const server = new McpServer(/* ... */); -server.tool('add', { a: z.number(), b: z.number() }, async ({ a, b }, { authInfo }) => { - // ここで `authInfo` オブジェクトを使って認証情報にアクセスできます -}); -``` - - - - -## 次のステップ \{#next-steps} - -引き続き、MCP Auth を MCP サーバーと統合するエンドツーエンドの例や、MCP クライアントでの認証フローの扱い方について学んでいきましょう。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/comparison.mdx b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/comparison.mdx deleted file mode 100644 index c6a0b3a..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/comparison.mdx +++ /dev/null @@ -1,80 +0,0 @@ ---- -sidebar_position: 101 -sidebar_label: 比較 ---- - -# MCP Auth と他のソリューションの比較・選択 - -MCP エコシステムは進化し続けています。Model Context Protocol (MCP) 仕様が「認可サーバー」方式から新しい「リソースサーバー + サードパーティ IdP」モデルへ移行する中で、さまざまな統合ソリューションが現在および将来どのように適合するかを理解することが重要です。 - -このページでは、mcp-auth と他の一般的なソリューションの主な違いをまとめ、プロジェクトに最適なアプローチを選択するための参考情報を提供します。 - -## 背景：プロキシ方式 vs. IdP 連携 \{#background-proxy-approach-vs-idp-integration} - -現在の多くの MCP 認証 (Authentication) ソリューションは「プロキシ方式」を採用しています。このモデルでは、MCP サーバーが認可 (Authorization) リクエストをサードパーティのアイデンティティプロバイダー (IdP) にプロキシし、クライアントと IdP の間の仲介役として機能します。 - -**プロキシ方式 ([03-26 仕様](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization))** - -```mermaid -sequenceDiagram - participant Client - participant MCP_Server as MCP サーバー - participant ThirdParty_IdP as サードパーティ IdP - - Client->>MCP_Server: 認可リクエスト - MCP_Server->>ThirdParty_IdP: リクエストをプロキシ - ThirdParty_IdP->>MCP_Server: レスポンス - MCP_Server->>Client: レスポンス - Client->>MCP_Server: リソースへアクセス - alt リモート検証 - MCP_Server->>ThirdParty_IdP: トークンを検証 - ThirdParty_IdP->>MCP_Server: トークン有効 - else ローカル検証 - MCP_Server->>MCP_Server: ローカルでトークンを検証（例：キャッシュされた JWK） - end - MCP_Server->>Client: リソースデータ -``` - -この方式は現行（2025-03-26）MCP 仕様で動作しますが、本質的には回避策です。MCP サーバーが認可サーバーとしても動作することを前提としており、最新のドラフト仕様の方向性とは異なります。 - -**MCP Auth / 将来仕様（リソースサーバー + サードパーティ IdP）** - -```mermaid -sequenceDiagram - participant Client - participant MCP_Server as MCP サーバー - participant ThirdParty_IdP as サードパーティ IdP - - Client->>ThirdParty_IdP: 認可リクエスト - ThirdParty_IdP->>Client: トークン - Client->>MCP_Server: リソースへアクセス（トークン付き） - alt リモート検証 - MCP_Server->>ThirdParty_IdP: トークンを検証 - ThirdParty_IdP->>MCP_Server: トークン有効 - else ローカル検証 - MCP_Server->>MCP_Server: ローカルでトークンを検証（例：キャッシュされた JWK） - end - MCP_Server->>Client: リソースデータ -``` - -今後の MCP 仕様では、[認可 (Authorization) の責任を専用のサードパーティ IdP に移す](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/205) 形にシフトします。このモデルでは、MCP サーバーはリソースサーバーとしてのみ機能し、すべての認可 (Authorization) エンドポイントはサードパーティ IdP から直接提供されます。 - -## なぜ MCP Auth を選ぶのか？ \{#why-choose-mcp-auth} - -- 仕様との整合性：MCP Auth は最新ドラフトの方向性に直接従っており、03-26 仕様と今後の仕様の両方に対応できる唯一のソリューションです。 -- 回避策不要：認可サーバープロキシとして動作する代わりに、MCP Auth では新仕様の意図通り、すべての認可 (Authorization) をサードパーティ IdP に任せます。 -- プロバイダー非依存：MCP Auth は、標準準拠の OAuth 2.0 / OIDC プロバイダーならどれでも利用できます。 -- スムーズな移行：MCP Auth は OAuth 2.0 認可サーバーメタデータ経由ですべてのサードパーティエンドポイントをそのまま返します。これにより、現時点での統合も将来の変更にも柔軟に対応できます。 -- 開発者体験：チュートリアルやユーティリティ、[OAuth 2.0 Protected Resource Metadata](https://auth.wiki/protected-resource-metadata) など今後の機能も提供し、MCP サーバー開発者の負担を軽減します。 - -| 機能 | プロキシソリューション | MCP Auth | -| ------------------------------------ | ------------------------- | -------- | -| 03-26 仕様に対応 | ✅ | ✅ | -| 将来仕様に対応 | ❌ | ✅ | -| サードパーティ IdP を直接サポート | ❌（回避策のみ） | ✅ | -| プロバイダー非依存 | 制限あり[^1] | はい | -| 移行準備完了 | ❌ | ✅ | - -今すぐサードパーティ IdP をサポートし、将来の仕様にも備えたい場合は、MCP Auth が推奨ソリューションです。プロキシベースのアプローチは、近い将来非推奨となるか、大幅な再設計が必要になる可能性があります。 - -[^1]: 一部のプロキシソリューションは特定のパラメーターやエンドポイントをハードコーディングしており、柔軟性が制限されます。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/configure-server/bearer-auth.mdx b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/configure-server/bearer-auth.mdx deleted file mode 100644 index b6500d0..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/configure-server/bearer-auth.mdx +++ /dev/null @@ -1,250 +0,0 @@ ---- -sidebar_position: 2 -sidebar_label: Bearer 認証 ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -# MCP サーバーで Bearer 認証を設定する - -MCP Auth では、MCP サーバーで Bearer 認可 (Authorization) を設定するためのさまざまな方法を提供しています： - -- [JWT (JSON Web Token)](https://auth.wiki/jwt) モード：クレーム (Claims) アサーションで JWT を検証する組み込みの認可 (Authorization) 方法。 -- カスタムモード：独自の認可 (Authorization) ロジックを実装できます。 - -## JWT モードで Bearer 認証を設定する \{#configure-bearer-auth-with-jwt-mode} - -OAuth / OIDC プロバイダーが認可 (Authorization) 用に JWT を発行する場合、MCP Auth の組み込み JWT モードを利用できます。JWT の署名、有効期限、および指定した他のクレーム (Claims) を検証し、その後、認証 (Authentication) 情報をリクエストコンテキストに格納して MCP 実装で利用できるようにします。 - -### スコープ (Scope) 検証 \{#scope-validation} - -基本的なスコープ (Scope) 検証の例は以下の通りです： - - - - -```python -from mcpauth import MCPAuth -from starlette.applications import Starlette -from starlette.middleware import Middleware -from starlette.routing import Mount -from mcp.server.fastmcp import FastMCP - -mcp = FastMCP("MyMCPServer") -mcp_auth = MCPAuth( - # Initialize with your auth server config -) -bearer_auth = mcp_auth.bearer_auth_middleware("jwt", required_scopes=["read", "write"]) # [!code highlight] - -app = Starlette( - routes=[Mount('/', app=mcp.sse_app(), middleware=[Middleware(bearer_auth)])] -) -``` - - - - -```ts -import express from 'express'; -import { MCPAuth } from 'mcp-auth'; - -const app = express(); -const mcpAuth = new MCPAuth({ - /* ... */ -}); -const bearerAuth = mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }); // [!code highlight] - -app.use('/mcp', bearerAuth, (req, res) => { - // Now `req.auth` contains the auth info - console.log(req.auth); -}); -``` - - - - -上記の例では、JWT に `read` および `write` スコープ (Scope) が必要であることを指定しています。JWT にこれらのスコープ (Scope) の **いずれか** が含まれていない場合、リクエストは 403 Forbidden エラーで拒否されます。 - -### リソースインジケーター (Resource indicator) 検証 (RFC 8707) \{#resource-indicator-validation-rfc-8707} - -プロバイダーが OIDC ベース、または [Resource Indicator](https://datatracker.ietf.org/doc/html/rfc8707) 拡張をサポートしている場合、`audience` オプションを指定して JWT の `aud`（オーディエンス (Audience)）クレーム (Claim) を検証できます。これは、JWT が MCP サーバー向けであることを保証するのに役立ちます。 - -プロバイダーのドキュメントを確認し、Resource Indicator 拡張をサポートしているか、またその設定方法を確認してください。一部のプロバイダーでは「audience」「API リソース」「API indicator」など、同じ概念を指す他の用語を使用する場合があります。 - -リソースインジケーター (Resource indicator) を設定したら、`bearerAuth` ミドルウェアで指定できます： - - - - -```python -bearer_auth = mcp_auth.bearer_auth_middleware( - "jwt", - audience="https://api.example.com/mcp", # JWT の期待されるオーディエンス (Audience) [!code highlight] - required_scopes=["read", "write"] -) -``` - - - - -```ts -const bearerAuth = mcpAuth.bearerAuth('jwt', { - audience: 'https://api.example.com/mcp', // JWT の期待されるオーディエンス (Audience) [!code highlight] - requiredScopes: ['read', 'write'], -}); -``` - - - - -上記の例では、MCP Auth は JWT の `aud` クレーム (Claim) と必要なスコープ (Scope) の **両方** を検証します。 - -### JWT 検証へのカスタムオプションの指定 \{#provide-custom-options-to-the-jwt-verification} - -基盤となる JWT 検証ライブラリにカスタムオプションを指定することもできます： - - - - -Python SDK では、JWT 検証に [PyJWT](https://pyjwt.readthedocs.io/en/stable/) を使用しています。次のオプションが利用できます： - -- `leeway`: JWT の有効期限検証時に許容する猶予時間（秒単位）。デフォルトは 60 秒です。 - -```python -bearer_auth = mcp_auth.bearer_auth_middleware( - "jwt", - audience="https://api.example.com/mcp", - required_scopes=["read", "write"] - leeway=10, # 10 秒の猶予で時計のずれを許容 [!code highlight] -) -``` - - - - -Node.js SDK では、JWT 検証に [jose](https://github.com/panva/jose) ライブラリを使用しています。次のオプションが利用できます： - -- `jwtVerify`: JWT 検証プロセスのオプション（`jose` の `jwtVerify` 関数）。 -- `remoteJwtSet`: リモート JWT セット取得のオプション（`jose` の `createRemoteJWKSet` 関数）。 - -```ts {4-9} -const bearerAuth = mcpAuth.bearerAuth('jwt', { - audience: 'https://api.example.com/mcp', - requiredScopes: ['read', 'write'], - jwtVerify: { - clockTolerance: 60, // 60 秒の時計のずれを許容 - }, - remoteJwtSet: { - timeoutDuration: 10 * 1000, // リモート JWT セット取得のタイムアウト 10 秒 - }, -}); -``` - - - - -## カスタム検証による Bearer 認証の設定 \{#configure-bearer-auth-with-custom-verification} - -OAuth / OIDC プロバイダーが JWT を発行しない場合や、独自の認可 (Authorization) ロジックを実装したい場合、MCP Auth ではカスタム検証関数を作成できます： - -:::info -Bearer 認証ミドルウェアは、発行者 (`iss`)、オーディエンス (`aud`)、必要なスコープ (`scope`) を検証結果と照合するため、これらのチェックをカスタム検証関数で実装する必要はありません。トークンの有効性（例：署名、有効期限など）の検証と認証 (Authentication) 情報オブジェクトの返却に集中できます。 -::: - - - - -```python -from mcpauth.exceptions import MCPAuthJwtVerificationException, MCPAuthJwtVerificationExceptionCode -from mcpauth.types import AuthInfo - -async def custom_verification(token: str) -> AuthInfo: - # ここでカスタム検証ロジックを実装 - info = await verify_token(token) - if not info: - raise MCPAuthJwtVerificationException( - MCPAuthJwtVerificationExceptionCode.JWT_VERIFICATION_FAILED - ) - return info # 認証 (Authentication) 情報オブジェクトを返却 - -bearer_auth = mcp_auth.bearer_auth_middleware( - custom_verification, - required_scopes=["read", "write"] -) -``` - - - - -```ts -const bearerAuth = mcpAuth.bearerAuth( - async (token) => { - // ここでカスタム検証ロジックを実装 - const info = await verifyToken(token); - if (!info) { - throw new MCPAuthJwtVerificationError('jwt_verification_failed'); - } - return info; // 認証 (Authentication) 情報オブジェクトを返却 - }, - { requiredScopes: ['read', 'write'] } -); -``` - - - - -## MCP サーバーで Bearer 認証を適用する \{#apply-bearer-auth-in-your-mcp-server} - -MCP サーバーを Bearer 認証で保護するには、MCP サーバーインスタンスに Bearer 認証ミドルウェアを適用する必要があります。 - - - - -```python -bearer_auth = mcp_auth.bearer_auth_middleware("jwt", required_scopes=["read", "write"]) -app = Starlette( - routes=[Mount('/', app=mcp.sse_app(), middleware=[Middleware(bearer_auth)])] -) -``` - - - - -```js -const app = express(); -app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] })); -``` - - - - -これにより、すべての受信リクエストが設定された Bearer 認証に従って認証 (Authentication) および認可 (Authorization) され、認証 (Authentication) 情報がリクエストコンテキストで利用できるようになります。 - -その後、MCP サーバー実装内で情報にアクセスできます： - - - - -```python -@mcp.tool() -async def whoami() -> dict: - # `mcp_auth.auth_info` は現在のリクエストのコンテキストオブジェクト - auth_info = mcp_auth.auth_info - print(f"Authenticated user: {auth_info.subject}") - return {"subject": auth_info.subject} -``` - - - - -```js -// `authInfo` は `req.auth` オブジェクトから渡されます -server.tool('whoami', ({ authInfo }) => { - console.log(`Authenticated user: ${authInfo.subject}`); - return { subject: authInfo.subject }; -}); -``` - - - diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/configure-server/mcp-auth.mdx b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/configure-server/mcp-auth.mdx deleted file mode 100644 index c9a07b6..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/configure-server/mcp-auth.mdx +++ /dev/null @@ -1,208 +0,0 @@ ---- -sidebar_position: 1 -sidebar_label: MCP Auth ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -# MCP サーバーでの MCP Auth の設定 - -MCP サーバーを OAuth 2.1 または OpenID Connect プロバイダーに接続するには、MCP Auth インスタンスの設定が必要です。これには、プロバイダーの認可サーバーメタデータでインスタンスを初期化し、必要な認可フローをセットアップする作業が含まれます。 - -## MCP Auth の初期化 \{#init-mcp-auth} - -### メタデータの自動取得 \{#automatic-metadata-fetching} - -MCP Auth インスタンスを初期化する最も簡単な方法は、well-known URL からメタデータを取得する組み込み関数を利用することです。プロバイダーが次のいずれかの標準に準拠している場合： - -- [OAuth 2.0 認可サーバーメタデータ](https://datatracker.ietf.org/doc/html/rfc8414) -- [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) - -`fetchServerConfig` を使い、`issuer` の URL を指定することでメタデータを自動取得できます： - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType, fetch_server_config - -mcp_auth = MCPAuth( - server=fetch_server_config( - '', - type=AuthServerType.OIDC # または AuthServerType.OAUTH - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { type: 'oidc' }), // または 'oauth' -}); -``` - - - - -issuer にパスが含まれている場合、OAuth 2.0 と OpenID Connect で挙動が少し異なります： - -- **OAuth 2.0**：well-known URL は issuer の **ドメイン** に追加されます。例：issuer が `https://my-project.logto.app/oauth` の場合、well-known URL は `https://auth.logto.io/.well-known/oauth-authorization-server/oauth` となります。 -- **OpenID Connect**：well-known URL は **issuer** に直接追加されます。例：issuer が `https://my-project.logto.app/oidc` の場合、well-known URL は `https://auth.logto.io/oidc/.well-known/openid-configuration` となります。 - -### その他の MCP Auth 初期化方法 \{#other-ways} - -#### カスタムデータ変換 \{#custom-data-transpilation} - -場合によっては、プロバイダーから返されるメタデータが期待される形式に準拠していないことがあります。プロバイダーが準拠していると確信できる場合は、`transpile_data` オプションを使ってメタデータを使用前に修正できます： - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -mcp_auth = MCPAuth( - server=fetch_server_config( - '', - type=AuthServerType.OIDC, - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { - type: 'oidc', - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - - -これにより、MCP Auth で使用する前にメタデータオブジェクトを修正できます。たとえば、フィールドの追加や削除、値の変更、別の形式への変換などが可能です。 - -#### 特定の URL からメタデータを取得 \{#fetch-metadata-from-a-specific-url} - -プロバイダーが標準以外の特定のメタデータ URL を持っている場合も、同様に利用できます： - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config_by_well_known_url - -mcp_auth = MCPAuth( - server=fetch_server_config_by_well_known_url( - '', - type=AuthServerType.OIDC # または AuthServerType.OAUTH - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfigByWellKnownUrl } from 'mcp-auth'; - -const mcpAuth = new MCPAuth({ - server: await fetchServerConfigByWellKnownUrl('', { type: 'oidc' }), // または 'oauth' -}); -``` - - - - -#### 特定の URL からカスタムデータ変換付きでメタデータを取得 \{#fetch-metadata-from-a-specific-url-with-custom-data-transpilation} - -場合によっては、プロバイダーのレスポンスが不正または期待されるメタデータ形式に準拠していないことがあります。プロバイダーが準拠していると確信できる場合は、設定オプションでメタデータを変換できます： - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType, fetch_server_config_by_well_known_url - -mcp_auth = MCPAuth( - server=fetch_server_config_by_well_known_url( - '', - type=AuthServerType.OIDC, - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: await fetchServerConfigByWellKnownUrl('', { - type: 'oidc', - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - - -#### メタデータを手動で指定 \{#manually-provide-metadata} - -プロバイダーがメタデータの取得をサポートしていない場合は、メタデータオブジェクトを手動で指定できます： - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerConfig, AuthServerType, AuthorizationServerMetadata - -mcp_auth = MCPAuth( - server=AuthServerConfig( - type=AuthServerType.OIDC, # または AuthServerType.OAUTH - metadata=AuthorizationServerMetadata( - issuer='', - authorization_endpoint='', - # ... 他のメタデータフィールド - ), - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: { - metadata: { - issuer: '', - // メタデータフィールドは camelCase で記述 - authorizationEndpoint: '', - // ... 他のメタデータフィールド - }, - type: 'oidc', // または 'oauth' - }, -}); -``` - - - diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/README.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/README.md deleted file mode 100644 index 90c10c4..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/README.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -sidebar_label: Node.js SDK ---- - -# MCP Auth Node.js SDK リファレンス - -## クラス {#classes} - -- [MCPAuth](/references/js/classes/MCPAuth.md) -- [MCPAuthAuthServerError](/references/js/classes/MCPAuthAuthServerError.md) -- [MCPAuthBearerAuthError](/references/js/classes/MCPAuthBearerAuthError.md) -- [MCPAuthConfigError](/references/js/classes/MCPAuthConfigError.md) -- [MCPAuthError](/references/js/classes/MCPAuthError.md) -- [MCPAuthTokenVerificationError](/references/js/classes/MCPAuthTokenVerificationError.md) - -## 型エイリアス {#type-aliases} - -- [AuthorizationServerMetadata](/references/js/type-aliases/AuthorizationServerMetadata.md) -- [AuthServerConfig](/references/js/type-aliases/AuthServerConfig.md) -- [AuthServerConfigError](/references/js/type-aliases/AuthServerConfigError.md) -- [AuthServerConfigErrorCode](/references/js/type-aliases/AuthServerConfigErrorCode.md) -- [AuthServerConfigWarning](/references/js/type-aliases/AuthServerConfigWarning.md) -- [AuthServerConfigWarningCode](/references/js/type-aliases/AuthServerConfigWarningCode.md) -- [AuthServerErrorCode](/references/js/type-aliases/AuthServerErrorCode.md) -- [AuthServerSuccessCode](/references/js/type-aliases/AuthServerSuccessCode.md) -- [AuthServerType](/references/js/type-aliases/AuthServerType.md) -- [BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) -- [BearerAuthErrorCode](/references/js/type-aliases/BearerAuthErrorCode.md) -- [BearerAuthJwtConfig](/references/js/type-aliases/BearerAuthJwtConfig.md) -- [CamelCaseAuthorizationServerMetadata](/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md) -- [MCPAuthBearerAuthErrorDetails](/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md) -- [MCPAuthConfig](/references/js/type-aliases/MCPAuthConfig.md) -- [MCPAuthTokenVerificationErrorCode](/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md) -- [VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) -- [VerifyAccessTokenMode](/references/js/type-aliases/VerifyAccessTokenMode.md) - -## 変数 {#variables} - -- [authorizationServerMetadataSchema](/references/js/variables/authorizationServerMetadataSchema.md) -- [authServerErrorDescription](/references/js/variables/authServerErrorDescription.md) -- [bearerAuthErrorDescription](/references/js/variables/bearerAuthErrorDescription.md) -- [camelCaseAuthorizationServerMetadataSchema](/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md) -- [serverMetadataPaths](/references/js/variables/serverMetadataPaths.md) -- [tokenVerificationErrorDescription](/references/js/variables/tokenVerificationErrorDescription.md) -- [validateServerConfig](/references/js/variables/validateServerConfig.md) - -## 関数 {#functions} - -- [createVerifyJwt](/references/js/functions/createVerifyJwt.md) -- [fetchServerConfig](/references/js/functions/fetchServerConfig.md) -- [fetchServerConfigByWellKnownUrl](/references/js/functions/fetchServerConfigByWellKnownUrl.md) -- [handleBearerAuth](/references/js/functions/handleBearerAuth.md) diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuth.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuth.md deleted file mode 100644 index 3e3ba82..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuth.md +++ /dev/null @@ -1,195 +0,0 @@ ---- -sidebar_label: MCPAuth ---- - -# クラス: MCPAuth - -mcp-auth ライブラリのメインクラスであり、MCP サーバーにおける認証 (Authentication) と認可 (Authorization) のためのルーターや便利なハンドラーを作成するメソッドを提供します。 - -## 参照 {#see} - -ライブラリやその使い方の詳細は [MCP Auth](https://mcp-auth.dev) をご覧ください。 - -## 例 {#example} - -リモート OIDC プロバイダーとの統合例： - -```ts -import express from 'express'; -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const app = express(); -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig( - 'https://auth.logto.io/oidc', - { type: 'oidc' } - ), -}); - -// OAuth 2.0 認可サーバーメタデータを処理するルーターをマウント -app.use(mcpAuth.delegatedRouter()); - -// MCP ルートで Bearer 認証 (Authentication) ハンドラーを使用 -app.get( - '/mcp', - mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }), - (req, res) => { - console.log('Auth info:', req.auth); - // ここで MCP リクエストを処理 - }, -); - -// MCP コールバックで認証 (Authentication) 情報を利用 -server.tool( - 'add', - { a: z.number(), b: z.number() }, - async ({ a, b }, { authInfo }) => { - console.log('Auth Info:', authInfo); - // ... - }, -); -``` - -## コンストラクター {#constructors} - -### コンストラクター {#constructor} - -```ts -new MCPAuth(config: MCPAuthConfig): MCPAuth; -``` - -#### パラメーター {#parameters} - -##### config {#config} - -[`MCPAuthConfig`](/references/js/type-aliases/MCPAuthConfig.md) - -#### 戻り値 {#returns} - -`MCPAuth` - -## プロパティ {#properties} - -### config {#config} - -```ts -readonly config: MCPAuthConfig; -``` - -## メソッド {#methods} - -### bearerAuth() {#bearerauth} - -#### 呼び出しシグネチャ {#call-signature} - -```ts -bearerAuth(verifyAccessToken: VerifyAccessTokenFunction, config?: Omit): RequestHandler; -``` - -リクエストの `Authorization` ヘッダー内のアクセス トークン (Access token) を検証する Bearer 認証 (Authentication) ハンドラー（Express ミドルウェア）を作成します。 - -##### パラメーター {#parameters} - -###### verifyAccessToken {#verifyaccesstoken} - -[`VerifyAccessTokenFunction`](/references/js/type-aliases/VerifyAccessTokenFunction.md) - -アクセス トークン (Access token) を検証する関数です。文字列としてアクセス トークン (Access token) を受け取り、検証結果に解決する promise（または値）を返す必要があります。 - -**参照** - -`verifyAccessToken` 関数の型定義については [VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) をご覧ください。 - -###### config? {#config} - -`Omit`\<[`BearerAuthConfig`](/references/js/type-aliases/BearerAuthConfig.md), `"verifyAccessToken"` \| `"issuer"`\> - -Bearer 認証 (Authentication) ハンドラーのためのオプション設定です。 - -**参照** - -利用可能な設定オプション（`verifyAccessToken` と `issuer` を除く）については [BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) をご覧ください。 - -##### 戻り値 {#returns} - -`RequestHandler` - -アクセス トークン (Access token) を検証し、検証結果をリクエストオブジェクト（`req.auth`）に追加する Express ミドルウェア関数です。 - -##### 参照 {#see} - -`req.auth`（`AuthInfo`）オブジェクトの実装詳細や拡張型については [handleBearerAuth](/references/js/functions/handleBearerAuth.md) をご覧ください。 - -#### 呼び出しシグネチャ {#call-signature} - -```ts -bearerAuth(mode: "jwt", config?: Omit & BearerAuthJwtConfig): RequestHandler; -``` - -リクエストの `Authorization` ヘッダー内のアクセス トークン (Access token) を、事前定義された検証モードで検証する Bearer 認証 (Authentication) ハンドラー（Express ミドルウェア）を作成します。 - -`'jwt'` モードでは、認可サーバーの JWKS URI から JWK セットを使用して JWT 検証関数を作成します。 - -##### パラメーター {#parameters} - -###### mode {#mode} - -`"jwt"` - -アクセス トークン (Access token) の検証モードです。現在は 'jwt' のみサポートされています。 - -**参照** - -利用可能なモードについては [VerifyAccessTokenMode](/references/js/type-aliases/VerifyAccessTokenMode.md) をご覧ください。 - -###### config? {#config} - -`Omit`\<[`BearerAuthConfig`](/references/js/type-aliases/BearerAuthConfig.md), `"verifyAccessToken"` \| `"issuer"`\> & [`BearerAuthJwtConfig`](/references/js/type-aliases/BearerAuthJwtConfig.md) - -JWT 検証オプションやリモート JWK セットオプションを含む、Bearer 認証 (Authentication) ハンドラーのためのオプション設定です。 - -**参照** - - - JWT 検証のための設定オプションについては [BearerAuthJwtConfig](/references/js/type-aliases/BearerAuthJwtConfig.md) をご覧ください。 - - 設定オプション（`verifyAccessToken` と `issuer` を除く）については [BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) をご覧ください。 - -##### 戻り値 {#returns} - -`RequestHandler` - -アクセス トークン (Access token) を検証し、検証結果をリクエストオブジェクト（`req.auth`）に追加する Express ミドルウェア関数です。 - -##### 参照 {#see} - -`req.auth`（`AuthInfo`）オブジェクトの実装詳細や拡張型については [handleBearerAuth](/references/js/functions/handleBearerAuth.md) をご覧ください。 - -##### 例外 {#throws} - -`'jwt'` モード使用時にサーバーメタデータに JWKS URI が提供されていない場合、例外がスローされます。 - -*** - -### delegatedRouter() {#delegatedrouter} - -```ts -delegatedRouter(): Router; -``` - -OAuth 2.0 認可サーバーメタデータエンドポイント（`/.well-known/oauth-authorization-server`）を、インスタンスに提供されたメタデータで提供する委譲ルーターを作成します。 - -#### 戻り値 {#returns} - -`Router` - -インスタンスに提供されたメタデータで OAuth 2.0 認可サーバーメタデータエンドポイントを提供するルーターです。 - -#### 例 {#example} - -```ts -import express from 'express'; -import { MCPAuth } from 'mcp-auth'; - -const app = express(); -const mcpAuth: MCPAuth; // 初期化済みと仮定 -app.use(mcpAuth.delegatedRouter()); -``` diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthAuthServerError.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthAuthServerError.md deleted file mode 100644 index 015eb65..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthAuthServerError.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -sidebar_label: MCPAuthAuthServerError ---- - -# クラス: MCPAuthAuthServerError - -リモート認可 (Authorization) サーバーで問題が発生した場合にスローされるエラーです。 - -## 継承 {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## コンストラクター {#constructors} - -### コンストラクター {#constructor} - -```ts -new MCPAuthAuthServerError(code: AuthServerErrorCode, cause?: unknown): MCPAuthAuthServerError; -``` - -#### パラメーター {#parameters} - -##### code {#code} - -[`AuthServerErrorCode`](/references/js/type-aliases/AuthServerErrorCode.md) - -##### cause? {#cause} - -`unknown` - -#### 戻り値 {#returns} - -`MCPAuthAuthServerError` - -#### オーバーライド {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## プロパティ {#properties} - -### cause? {#cause} - -```ts -readonly optional cause: unknown; -``` - -#### 継承元 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: AuthServerErrorCode; -``` - -スネークケース形式のエラーコードです。 - -#### 継承元 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### 継承元 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthAuthServerError'; -``` - -#### オーバーライド {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### 継承元 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -スタックトレースのフォーマットをカスタマイズするためのオプションのオーバーライド - -#### パラメーター {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### 戻り値 {#returns} - -`any` - -#### 参照 {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### 継承元 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### 継承元 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## メソッド {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -エラーを HTTP レスポンスに適した JSON 形式に変換します。 - -#### パラメーター {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -JSON レスポンスにエラーの原因を含めるかどうかを指定します。 -デフォルトは `false` です。 - -#### 戻り値 {#returns} - -`Record`\<`string`, `unknown`\> - -#### 継承元 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -ターゲットオブジェクトに .stack プロパティを作成します - -#### パラメーター {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### 戻り値 {#returns} - -`void` - -#### 継承元 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthBearerAuthError.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthBearerAuthError.md deleted file mode 100644 index 0a88685..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthBearerAuthError.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -sidebar_label: MCPAuthBearerAuthError ---- - -# クラス: MCPAuthBearerAuthError - -Bearer トークンによる認証 (Authentication) 時に問題が発生した場合にスローされるエラーです。 - -## 継承 {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## コンストラクター {#constructors} - -### コンストラクター {#constructor} - -```ts -new MCPAuthBearerAuthError(code: BearerAuthErrorCode, cause?: MCPAuthBearerAuthErrorDetails): MCPAuthBearerAuthError; -``` - -#### パラメーター {#parameters} - -##### code {#code} - -[`BearerAuthErrorCode`](/references/js/type-aliases/BearerAuthErrorCode.md) - -##### cause? {#cause} - -[`MCPAuthBearerAuthErrorDetails`](/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md) - -#### 戻り値 {#returns} - -`MCPAuthBearerAuthError` - -#### オーバーライド {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## プロパティ {#properties} - -### cause? {#cause} - -```ts -readonly optional cause: MCPAuthBearerAuthErrorDetails; -``` - -#### 継承元 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: BearerAuthErrorCode; -``` - -スネークケース形式のエラーコードです。 - -#### 継承元 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### 継承元 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthBearerAuthError'; -``` - -#### オーバーライド {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### 継承元 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -スタックトレースのフォーマットをカスタマイズするためのオプションのオーバーライド - -#### パラメーター {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### 戻り値 {#returns} - -`any` - -#### 参照 {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### 継承元 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### 継承元 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## メソッド {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -エラーを HTTP レスポンスに適した JSON 形式に変換します。 - -#### パラメーター {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -JSON レスポンスにエラーの原因を含めるかどうかを指定します。 -デフォルトは `false` です。 - -#### 戻り値 {#returns} - -`Record`\<`string`, `unknown`\> - -#### オーバーライド {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -ターゲットオブジェクトに .stack プロパティを作成します - -#### パラメーター {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### 戻り値 {#returns} - -`void` - -#### 継承元 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthConfigError.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthConfigError.md deleted file mode 100644 index 9d1ba1e..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthConfigError.md +++ /dev/null @@ -1,202 +0,0 @@ ---- -sidebar_label: MCPAuthConfigError ---- - -# クラス: MCPAuthConfigError - -mcp-auth の設定に問題がある場合にスローされるエラーです。 - -## 継承元 {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## コンストラクター {#constructors} - -### コンストラクター {#constructor} - -```ts -new MCPAuthConfigError(code: string, message: string): MCPAuthConfigError; -``` - -#### パラメーター {#parameters} - -##### code {#code} - -`string` - -スネークケース形式のエラーコードです。 - -##### message {#message} - -`string` - -エラーの人間が読める説明です。 - -#### 戻り値 {#returns} - -`MCPAuthConfigError` - -#### 継承元 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## プロパティ {#properties} - -### cause? {#cause} - -```ts -optional cause: unknown; -``` - -#### 継承元 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: string; -``` - -スネークケース形式のエラーコードです。 - -#### 継承元 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### 継承元 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthConfigError'; -``` - -#### オーバーライド {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### 継承元 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -スタックトレースのフォーマットをカスタマイズするためのオプションのオーバーライド - -#### パラメーター {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### 戻り値 {#returns} - -`any` - -#### 参照 {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### 継承元 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### 継承元 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## メソッド {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -エラーを HTTP レスポンスに適した JSON 形式に変換します。 - -#### パラメーター {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -JSON レスポンスにエラーの原因を含めるかどうか。 -デフォルトは `false` です。 - -#### 戻り値 {#returns} - -`Record`\<`string`, `unknown`\> - -#### 継承元 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -ターゲットオブジェクトに .stack プロパティを作成します - -#### パラメーター {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### 戻り値 {#returns} - -`void` - -#### 継承元 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthError.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthError.md deleted file mode 100644 index 0eeedde..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthError.md +++ /dev/null @@ -1,219 +0,0 @@ ---- -sidebar_label: MCPAuthError ---- - -# クラス: MCPAuthError - -すべての mcp-auth エラーの基底クラスです。 - -MCP の認証 (Authentication) および認可 (Authorization) に関連するエラーを標準化された方法で処理するためのものです。 - -## 継承元 {#extends} - -- `Error` - -## 継承先 {#extended-by} - -- [`MCPAuthConfigError`](/references/js/classes/MCPAuthConfigError.md) -- [`MCPAuthAuthServerError`](/references/js/classes/MCPAuthAuthServerError.md) -- [`MCPAuthBearerAuthError`](/references/js/classes/MCPAuthBearerAuthError.md) -- [`MCPAuthTokenVerificationError`](/references/js/classes/MCPAuthTokenVerificationError.md) - -## コンストラクター {#constructors} - -### コンストラクター {#constructor} - -```ts -new MCPAuthError(code: string, message: string): MCPAuthError; -``` - -#### パラメーター {#parameters} - -##### code {#code} - -`string` - -スネークケース形式のエラーコード。 - -##### message {#message} - -`string` - -エラーの人間が読める説明。 - -#### 戻り値 {#returns} - -`MCPAuthError` - -#### オーバーライド {#overrides} - -```ts -Error.constructor -``` - -## プロパティ {#properties} - -### cause? {#cause} - -```ts -optional cause: unknown; -``` - -#### 継承元 {#inherited-from} - -```ts -Error.cause -``` - -*** - -### code {#code} - -```ts -readonly code: string; -``` - -スネークケース形式のエラーコード。 - -*** - -### message {#message} - -```ts -message: string; -``` - -#### 継承元 {#inherited-from} - -```ts -Error.message -``` - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthError'; -``` - -#### オーバーライド {#overrides} - -```ts -Error.name -``` - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### 継承元 {#inherited-from} - -```ts -Error.stack -``` - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -スタックトレースのフォーマットをカスタマイズするためのオプションのオーバーライド - -#### パラメーター {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### 戻り値 {#returns} - -`any` - -#### 参考 {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### 継承元 {#inherited-from} - -```ts -Error.prepareStackTrace -``` - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### 継承元 {#inherited-from} - -```ts -Error.stackTraceLimit -``` - -## メソッド {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -エラーを HTTP レスポンスに適した JSON 形式に変換します。 - -#### パラメーター {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -JSON レスポンスにエラーの原因を含めるかどうか。 -デフォルトは `false` です。 - -#### 戻り値 {#returns} - -`Record`\<`string`, `unknown`\> - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -ターゲットオブジェクトに .stack プロパティを作成します - -#### パラメーター {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### 戻り値 {#returns} - -`void` - -#### 継承元 {#inherited-from} - -```ts -Error.captureStackTrace -``` diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthTokenVerificationError.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthTokenVerificationError.md deleted file mode 100644 index dcaaa0c..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthTokenVerificationError.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -sidebar_label: MCPAuthTokenVerificationError ---- - -# クラス: MCPAuthTokenVerificationError - -トークンの検証時に問題が発生した場合にスローされるエラーです。 - -## 継承 {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## コンストラクター {#constructors} - -### コンストラクター {#constructor} - -```ts -new MCPAuthTokenVerificationError(code: MCPAuthTokenVerificationErrorCode, cause?: unknown): MCPAuthTokenVerificationError; -``` - -#### パラメーター {#parameters} - -##### code {#code} - -[`MCPAuthTokenVerificationErrorCode`](/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md) - -##### cause? {#cause} - -`unknown` - -#### 戻り値 {#returns} - -`MCPAuthTokenVerificationError` - -#### オーバーライド {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## プロパティ {#properties} - -### cause? {#cause} - -```ts -readonly optional cause: unknown; -``` - -#### 継承元 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: MCPAuthTokenVerificationErrorCode; -``` - -スネークケース形式のエラーコードです。 - -#### 継承元 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### 継承元 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthTokenVerificationError'; -``` - -#### オーバーライド {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### 継承元 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -スタックトレースのフォーマットをカスタマイズするためのオプションのオーバーライド - -#### パラメーター {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### 戻り値 {#returns} - -`any` - -#### 参照 {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### 継承元 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### 継承元 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## メソッド {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -エラーを HTTP レスポンスに適した JSON 形式に変換します。 - -#### パラメーター {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -JSON レスポンスにエラーの原因を含めるかどうかを指定します。 -デフォルトは `false` です。 - -#### 戻り値 {#returns} - -`Record`\<`string`, `unknown`\> - -#### 継承元 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -ターゲットオブジェクトに .stack プロパティを作成します - -#### パラメーター {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### 戻り値 {#returns} - -`void` - -#### 継承元 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/createVerifyJwt.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/createVerifyJwt.md deleted file mode 100644 index 4d7380d..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/createVerifyJwt.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -sidebar_label: createVerifyJwt ---- - -# 関数: createVerifyJwt() - -```ts -function createVerifyJwt(getKey: JWTVerifyGetKey, options?: JWTVerifyOptions): VerifyAccessTokenFunction; -``` - -指定されたキー取得関数とオプションを使用して、JWT アクセス トークン (Access token) を検証する関数を作成します。 - -## パラメーター {#parameters} - -### getKey {#getkey} - -`JWTVerifyGetKey` - -JWT を検証するために使用されるキーを取得する関数です。 - -**参照** - -キー取得関数の型定義については JWTVerifyGetKey を参照してください。 - -### options? {#options} - -`JWTVerifyOptions` - -オプションの JWT 検証オプションです。 - -**参照** - -オプションの型定義については JWTVerifyOptions を参照してください。 - -## 戻り値 {#returns} - -[`VerifyAccessTokenFunction`](/references/js/type-aliases/VerifyAccessTokenFunction.md) - -JWT アクセス トークン (Access token) を検証し、トークンが有効な場合は AuthInfo オブジェクトを返す関数です。この関数は、JWT のペイロードに `iss`、`client_id`、`sub` フィールドが含まれている必要があり、オプションで `scope` または `scopes` フィールドを含めることができます。内部的には `jose` ライブラリを使用して JWT の検証を行います。 - -## 参照 {#see} - -返される関数の型定義については [VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) を参照してください。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfig.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfig.md deleted file mode 100644 index 525b71a..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfig.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -sidebar_label: fetchServerConfig ---- - -# 関数: fetchServerConfig() - -```ts -function fetchServerConfig(issuer: string, config: ServerMetadataConfig): Promise; -``` - -発行者 (Issuer) と認可サーバーの種類に基づいてサーバー設定を取得します。 - -この関数は、サーバーの種類に応じて自動的に well-known URL を判別します。OAuth および OpenID Connect サーバーは、メタデータエンドポイントの規約が異なります。 - -## パラメーター {#parameters} - -### issuer {#issuer} - -`string` - -認可サーバーの発行者 (Issuer) URL。 - -### config {#config} - -`ServerMetadataConfig` - -サーバーの種類およびオプションのトランスパイル関数を含む設定オブジェクト。 - -## 戻り値 {#returns} - -`Promise`\<[`AuthServerConfig`](/references/js/type-aliases/AuthServerConfig.md)\> - -サーバー設定を解決する Promise。 - -## 参照 {#see} - - - 基本実装については [fetchServerConfigByWellKnownUrl](/references/js/functions/fetchServerConfigByWellKnownUrl.md) を参照してください。 - - OAuth 2.0 認可サーバーメタデータ仕様については [https://www.rfc-editor.org/rfc/rfc8414](https://www.rfc-editor.org/rfc/rfc8414) を参照してください。 - - OpenID Connect Discovery 仕様については [https://openid.net/specs/openid-connect-discovery-1\_0.html](https://openid.net/specs/openid-connect-discovery-1_0.html) を参照してください。 - -## 例 {#example} - -```ts -import { fetchServerConfig } from 'mcp-auth'; -// OAuth サーバー設定の取得 -// これは `https://auth.logto.io/.well-known/oauth-authorization-server/oauth` からメタデータを取得します -const oauthConfig = await fetchServerConfig('https://auth.logto.io/oauth', { type: 'oauth' }); - -// OpenID Connect サーバー設定の取得 -// これは `https://auth.logto.io/oidc/.well-known/openid-configuration` からメタデータを取得します -const oidcConfig = await fetchServerConfig('https://auth.logto.io/oidc', { type: 'oidc' }); -``` - -## 例外 {#throws} - -フェッチ操作に失敗した場合にスローされます。 - -## 例外 {#throws} - -サーバーメタデータが無効、または MCP 仕様と一致しない場合にスローされます。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfigByWellKnownUrl.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfigByWellKnownUrl.md deleted file mode 100644 index 1c331d6..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfigByWellKnownUrl.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -sidebar_label: fetchServerConfigByWellKnownUrl ---- - -# 関数: fetchServerConfigByWellKnownUrl() - -```ts -function fetchServerConfigByWellKnownUrl(wellKnownUrl: string | URL, config: ServerMetadataConfig): Promise; -``` - -指定された well-known URL からサーバー構成を取得し、MCP 仕様に対して検証します。 - -サーバーメタデータが期待されるスキーマに準拠していない場合でも、互換性があると確信している場合は、`transpileData` 関数を定義してメタデータを期待される形式に変換できます。 - -## パラメーター {#parameters} - -### wellKnownUrl {#wellknownurl} - -サーバー構成を取得するための well-known URL。これは文字列または URL オブジェクトです。 - -`string` | `URL` - -### config {#config} - -`ServerMetadataConfig` - -サーバータイプおよびオプションのトランスパイル関数を含む構成オブジェクト。 - -## 戻り値 {#returns} - -`Promise`\<[`AuthServerConfig`](/references/js/type-aliases/AuthServerConfig.md)\> - -サーバー構成を解決する Promise。 - -## 例外 {#throws} - -フェッチ操作が失敗した場合にスローされます。 - -## 例外 {#throws} - -サーバーメタデータが無効、または MCP 仕様と一致しない場合にスローされます。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/handleBearerAuth.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/handleBearerAuth.md deleted file mode 100644 index 4a6ed50..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/handleBearerAuth.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -sidebar_label: handleBearerAuth ---- - -# 関数: handleBearerAuth() - -```ts -function handleBearerAuth(param0: BearerAuthConfig): RequestHandler; -``` - -Express アプリケーションで Bearer 認証を処理するためのミドルウェア関数を作成します。 - -このミドルウェアは、`Authorization` ヘッダーから Bearer トークンを抽出し、指定された `verifyAccessToken` 関数を使用して検証し、発行者、オーディエンス、必要なスコープをチェックします。 - -- トークンが有効な場合、認証情報を `request.auth` プロパティに追加します。有効でない場合は、適切なエラーメッセージで応答します。 -- アクセス トークン (Access token) の検証に失敗した場合、401 Unauthorized エラーで応答します。 -- トークンに必要なスコープ (Scope) が含まれていない場合、403 Forbidden エラーで応答します。 -- 認証 (Authentication) プロセス中に予期しないエラーが発生した場合、ミドルウェアはそれらを再スローします。 - -**注意:** `request.auth` オブジェクトには、`@modelcontextprotocol/sdk` モジュールで定義されている標準の AuthInfo インターフェースよりも拡張されたフィールドが含まれます。詳細はこのファイル内の拡張インターフェースを参照してください。 - -## パラメーター {#parameters} - -### param0 {#param0} - -[`BearerAuthConfig`](/references/js/type-aliases/BearerAuthConfig.md) - -Bearer 認証 (Authentication) ハンドラーの設定。 - -## 戻り値 {#returns} - -`RequestHandler` - -Bearer 認証 (Authentication) を処理する Express 用ミドルウェア関数。 - -## 参照 {#see} - -設定オプションについては [BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) を参照してください。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfig.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfig.md deleted file mode 100644 index f7f6f4b..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfig.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -sidebar_label: AuthServerConfig ---- - -# 型エイリアス: AuthServerConfig - -```ts -type AuthServerConfig = { - metadata: CamelCaseAuthorizationServerMetadata; - type: AuthServerType; -}; -``` - -MCP サーバーと統合されたリモート認可サーバー (Authorization server) の設定。 - -## プロパティ {#properties} - -### metadata {#metadata} - -```ts -metadata: CamelCaseAuthorizationServerMetadata; -``` - -認可サーバー (Authorization server) のメタデータであり、MCP 仕様（OAuth 2.0 認可サーバーメタデータに基づく）に準拠している必要があります。 - -このメタデータは通常、サーバーの well-known エンドポイント（OAuth 2.0 認可サーバーメタデータまたは OpenID Connect Discovery）から取得されますが、サーバーがそのようなエンドポイントをサポートしていない場合は、設定内で直接指定することもできます。 - -**注意:** メタデータは mcp-auth ライブラリの推奨に従い、camelCase 形式である必要があります。 - -#### 参照 {#see} - - - [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) - - [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) - -*** - -### type {#type} - -```ts -type: AuthServerType; -``` - -認可サーバー (Authorization server) のタイプ。 - -#### 参照 {#see} - -[AuthServerType](/references/js/type-aliases/AuthServerType.md) で利用可能な値を確認できます。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigError.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigError.md deleted file mode 100644 index 5cb99a2..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigError.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -sidebar_label: AuthServerConfigError ---- - -# 型エイリアス: AuthServerConfigError - -```ts -type AuthServerConfigError = { - cause?: Error; - code: AuthServerConfigErrorCode; - description: string; -}; -``` - -認可サーバーメタデータの検証中に発生するエラーを表します。 - -## プロパティ {#properties} - -### cause? {#cause} - -```ts -optional cause: Error; -``` - -エラーの任意の原因。通常は、より多くのコンテキストを提供する `Error` のインスタンスです。 - -*** - -### code {#code} - -```ts -code: AuthServerConfigErrorCode; -``` - -特定の検証エラーを表すコードです。 - -*** - -### description {#description} - -```ts -description: string; -``` - -エラーの人間が読める説明です。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigErrorCode.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigErrorCode.md deleted file mode 100644 index 81df4a9..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigErrorCode.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_label: AuthServerConfigErrorCode ---- - -# 型エイリアス: AuthServerConfigErrorCode - -```ts -type AuthServerConfigErrorCode = - | "invalid_server_metadata" - | "code_response_type_not_supported" - | "authorization_code_grant_not_supported" - | "pkce_not_supported" - | "s256_code_challenge_method_not_supported"; -``` - -認可サーバーメタデータの検証時に発生する可能性があるエラーのコードです。 \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarning.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarning.md deleted file mode 100644 index 5a3c435..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarning.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -sidebar_label: AuthServerConfigWarning ---- - -# 型エイリアス: AuthServerConfigWarning - -```ts -type AuthServerConfigWarning = { - code: AuthServerConfigWarningCode; - description: string; -}; -``` - -認可サーバーメタデータの検証中に発生する警告を表します。 - -## プロパティ {#properties} - -### code {#code} - -```ts -code: AuthServerConfigWarningCode; -``` - -特定の検証警告を表すコードです。 - -*** - -### description {#description} - -```ts -description: string; -``` - -警告の人間が読める説明です。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarningCode.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarningCode.md deleted file mode 100644 index a11e5a4..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarningCode.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -sidebar_label: AuthServerConfigWarningCode ---- - -# 型エイリアス: AuthServerConfigWarningCode - -```ts -type AuthServerConfigWarningCode = "dynamic_registration_not_supported"; -``` - -認可サーバーメタデータの検証時に発生する可能性がある警告のコードです。 \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerErrorCode.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerErrorCode.md deleted file mode 100644 index bfa1379..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerErrorCode.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_label: AuthServerErrorCode ---- - -# 型エイリアス: AuthServerErrorCode - -```ts -type AuthServerErrorCode = - | "invalid_server_metadata" - | "invalid_server_config" - | "missing_jwks_uri"; -``` diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerSuccessCode.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerSuccessCode.md deleted file mode 100644 index e9db26d..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerSuccessCode.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -sidebar_label: AuthServerSuccessCode ---- - -# 型エイリアス: AuthServerSuccessCode - -```ts -type AuthServerSuccessCode = - | "server_metadata_valid" - | "dynamic_registration_supported" - | "pkce_supported" - | "s256_code_challenge_method_supported" - | "authorization_code_grant_supported" - | "code_response_type_supported"; -``` - -認可サーバーメタデータの検証が成功した場合のコードです。 \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerType.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerType.md deleted file mode 100644 index 1712c56..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerType.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -sidebar_label: AuthServerType ---- - -# 型エイリアス: AuthServerType - -```ts -type AuthServerType = "oauth" | "oidc"; -``` - -認可サーバー (Authorization server) の種類です。この情報はサーバー設定によって提供され、サーバーが OAuth 2.0 または OpenID Connect (OIDC) 認可サーバー (Authorization server) であるかを示します。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthorizationServerMetadata.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthorizationServerMetadata.md deleted file mode 100644 index 760d5bb..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthorizationServerMetadata.md +++ /dev/null @@ -1,228 +0,0 @@ ---- -sidebar_label: AuthorizationServerMetadata ---- - -# 型エイリアス: AuthorizationServerMetadata - -```ts -type AuthorizationServerMetadata = { - authorization_endpoint: string; - code_challenge_methods_supported?: string[]; - grant_types_supported?: string[]; - introspection_endpoint?: string; - introspection_endpoint_auth_methods_supported?: string[]; - introspection_endpoint_auth_signing_alg_values_supported?: string[]; - issuer: string; - jwks_uri?: string; - op_policy_uri?: string; - op_tos_uri?: string; - registration_endpoint?: string; - response_modes_supported?: string[]; - response_types_supported: string[]; - revocation_endpoint?: string; - revocation_endpoint_auth_methods_supported?: string[]; - revocation_endpoint_auth_signing_alg_values_supported?: string[]; - scope_supported?: string[]; - service_documentation?: string; - token_endpoint: string; - token_endpoint_auth_methods_supported?: string[]; - token_endpoint_auth_signing_alg_values_supported?: string[]; - ui_locales_supported?: string[]; - userinfo_endpoint?: string; -}; -``` - -RFC 8414 で定義されている OAuth 2.0 認可サーバーメタデータのスキーマです。 - -## 型宣言 {#type-declaration} - -### authorization\_endpoint {#authorization-endpoint} - -```ts -authorization_endpoint: string; -``` - -認可サーバーの認可エンドポイントの URL [[RFC6749](https://rfc-editor.org/rfc/rfc6749)]。 -認可エンドポイントを使用する grant type がサポートされていない場合を除き、これは必須です。 - -#### 参照 {#see} - -https://rfc-editor.org/rfc/rfc6749#section-3.1 - -### code\_challenge\_methods\_supported? {#code-challenge-methods-supported} - -```ts -optional code_challenge_methods_supported: string[]; -``` - -この認可サーバーがサポートする Proof Key for Code Exchange (PKCE) -[[RFC7636](https://www.rfc-editor.org/rfc/rfc7636)] の code challenge メソッドのリストを含む JSON 配列。 - -### grant\_types\_supported? {#grant-types-supported} - -```ts -optional grant_types_supported: string[]; -``` - -この認可サーバーがサポートする OAuth 2.0 grant type 値のリストを含む JSON 配列。 -配列の値は "OAuth 2.0 Dynamic Client Registration Protocol" [[RFC7591](https://www.rfc-editor.org/rfc/rfc7591)] で定義された `grant_types` パラメーターで使用されるものと同じです。 -省略された場合、デフォルト値は `["authorization_code", "implicit"]` です。 - -### introspection\_endpoint? {#introspection-endpoint} - -```ts -optional introspection_endpoint: string; -``` - -認可サーバーの OAuth 2.0 インスペクションエンドポイントの URL -[[RFC7662](https://www.rfc-editor.org/rfc/rfc7662)]。 - -### introspection\_endpoint\_auth\_methods\_supported? {#introspection-endpoint-auth-methods-supported} - -```ts -optional introspection_endpoint_auth_methods_supported: string[]; -``` - -### introspection\_endpoint\_auth\_signing\_alg\_values\_supported? {#introspection-endpoint-auth-signing-alg-values-supported} - -```ts -optional introspection_endpoint_auth_signing_alg_values_supported: string[]; -``` - -### issuer {#issuer} - -```ts -issuer: string; -``` - -認可サーバーの発行者 (Issuer) 識別子であり、`https` スキームを使用し、クエリやフラグメントコンポーネントを持たない URL です。 - -### jwks\_uri? {#jwks-uri} - -```ts -optional jwks_uri: string; -``` - -認可サーバーの JWK Set [[JWK](https://www.rfc-editor.org/rfc/rfc8414.html#ref-JWK)] -ドキュメントの URL。参照されるドキュメントには、クライアントが認可サーバーからの署名を検証するために使用する署名鍵が含まれます。この URL は `https` スキームを使用しなければなりません。 - -### op\_policy\_uri? {#op-policy-uri} - -```ts -optional op_policy_uri: string; -``` - -### op\_tos\_uri? {#op-tos-uri} - -```ts -optional op_tos_uri: string; -``` - -### registration\_endpoint? {#registration-endpoint} - -```ts -optional registration_endpoint: string; -``` - -認可サーバーの OAuth 2.0 Dynamic Client Registration エンドポイントの URL -[[RFC7591](https://www.rfc-editor.org/rfc/rfc7591)]。 - -### response\_modes\_supported? {#response-modes-supported} - -```ts -optional response_modes_supported: string[]; -``` - -この認可サーバーがサポートする OAuth 2.0 `response_mode` 値のリストを含む JSON 配列。 -"OAuth 2.0 Multiple Response Type Encoding Practices" -[[OAuth.Responses](https://datatracker.ietf.org/doc/html/rfc8414#ref-OAuth.Responses)] で規定されています。 - -省略された場合、デフォルトは `["query", "fragment"]` です。レスポンスモード値 `"form_post"` も "OAuth 2.0 Form Post Response Mode" -[[OAuth.FormPost](https://datatracker.ietf.org/doc/html/rfc8414#ref-OAuth.Post)] で定義されています。 - -### response\_types\_supported {#response-types-supported} - -```ts -response_types_supported: string[]; -``` - -この認可サーバーがサポートする OAuth 2.0 `response_type` 値のリストを含む JSON 配列。 -配列の値は "OAuth 2.0 Dynamic Client Registration Protocol" -[[RFC7591](https://www.rfc-editor.org/rfc/rfc7591)] で定義された `response_types` パラメーターで使用されるものと同じです。 - -### revocation\_endpoint? {#revocation-endpoint} - -```ts -optional revocation_endpoint: string; -``` - -認可サーバーの OAuth 2.0 取り消しエンドポイントの URL -[[RFC7009](https://www.rfc-editor.org/rfc/rfc7009)]。 - -### revocation\_endpoint\_auth\_methods\_supported? {#revocation-endpoint-auth-methods-supported} - -```ts -optional revocation_endpoint_auth_methods_supported: string[]; -``` - -### revocation\_endpoint\_auth\_signing\_alg\_values\_supported? {#revocation-endpoint-auth-signing-alg-values-supported} - -```ts -optional revocation_endpoint_auth_signing_alg_values_supported: string[]; -``` - -### scope\_supported? {#scope-supported} - -```ts -optional scope_supported: string[]; -``` - -### service\_documentation? {#service-documentation} - -```ts -optional service_documentation: string; -``` - -### token\_endpoint {#token-endpoint} - -```ts -token_endpoint: string; -``` - -認可サーバーのトークンエンドポイントの URL [[RFC6749](https://rfc-editor.org/rfc/rfc6749)]。 -暗黙的な grant type のみがサポートされている場合を除き、これは必須です。 - -#### 参照 {#see} - -https://rfc-editor.org/rfc/rfc6749#section-3.2 - -### token\_endpoint\_auth\_methods\_supported? {#token-endpoint-auth-methods-supported} - -```ts -optional token_endpoint_auth_methods_supported: string[]; -``` - -### token\_endpoint\_auth\_signing\_alg\_values\_supported? {#token-endpoint-auth-signing-alg-values-supported} - -```ts -optional token_endpoint_auth_signing_alg_values_supported: string[]; -``` - -### ui\_locales\_supported? {#ui-locales-supported} - -```ts -optional ui_locales_supported: string[]; -``` - -### userinfo\_endpoint? {#userinfo-endpoint} - -```ts -optional userinfo_endpoint: string; -``` - -OpenID Connect の [userinfo エンドポイント](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) の URL。 -このエンドポイントは認証済みユーザーに関する情報を取得するために使用されます。 - -## 参照 {#see} - -https://datatracker.ietf.org/doc/html/rfc8414 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthConfig.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthConfig.md deleted file mode 100644 index 3f98df1..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthConfig.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -sidebar_label: BearerAuthConfig ---- - -# 型エイリアス: BearerAuthConfig - -```ts -type BearerAuthConfig = { - audience?: string; - issuer: string; - requiredScopes?: string[]; - showErrorDetails?: boolean; - verifyAccessToken: VerifyAccessTokenFunction; -}; -``` - -## プロパティ {#properties} - -### audience? {#audience} - -```ts -optional audience: string; -``` - -アクセス トークン (アクセス トークン) の期待されるオーディエンス (`aud` クレーム)。これは通常、トークンが意図されているリソースサーバー（API）です。指定しない場合、オーディエンスのチェックはスキップされます。 - -**注意:** 認可サーバーがリソースインジケーター (RFC 8707) をサポートしていない場合、このフィールドは省略できます。なぜなら、オーディエンスが関連しない場合があるためです。 - -#### 参照 {#see} - -https://datatracker.ietf.org/doc/html/rfc8707 - -*** - -### issuer {#issuer} - -```ts -issuer: string; -``` - -アクセス トークン (アクセス トークン) の期待される発行者 (`iss` クレーム)。これはトークンを発行した認可サーバーの URL である必要があります。 - -*** - -### requiredScopes? {#requiredscopes} - -```ts -optional requiredScopes: string[]; -``` - -アクセス トークン (アクセス トークン) に必要なスコープ (スコープ) の配列。トークンにこれらすべてのスコープが含まれていない場合、エラーがスローされます。 - -**注意:** ハンドラーはトークン内の `scope` クレームをチェックします。これは認可サーバーの実装によって、スペース区切りの文字列または文字列の配列である場合があります。`scope` クレームが存在しない場合、ハンドラーは `scopes` クレームがあればそれをチェックします。 - -*** - -### showErrorDetails? {#showerrordetails} - -```ts -optional showErrorDetails: boolean; -``` - -レスポンスに詳細なエラー情報を表示するかどうか。これは開発中のデバッグに便利ですが、本番環境では機密情報漏洩を防ぐため無効にするべきです。 - -#### デフォルト {#default} - -```ts -false -``` - -*** - -### verifyAccessToken {#verifyaccesstoken} - -```ts -verifyAccessToken: VerifyAccessTokenFunction; -``` - -アクセス トークン (アクセス トークン) を検証するための関数型。 - -この関数は、トークンが無効な場合は [MCPAuthTokenVerificationError](/references/js/classes/MCPAuthTokenVerificationError.md) をスローし、有効な場合は AuthInfo オブジェクトを返す必要があります。 - -#### 参照 {#see} - -[VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) を参照してください。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthErrorCode.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthErrorCode.md deleted file mode 100644 index 908bb65..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthErrorCode.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_label: BearerAuthErrorCode ---- - -# 型エイリアス: BearerAuthErrorCode - -```ts -type BearerAuthErrorCode = - | "missing_auth_header" - | "invalid_auth_header_format" - | "missing_bearer_token" - | "invalid_issuer" - | "invalid_audience" - | "missing_required_scopes" - | "invalid_token"; -``` diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthJwtConfig.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthJwtConfig.md deleted file mode 100644 index 9b2632a..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthJwtConfig.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -sidebar_label: BearerAuthJwtConfig ---- - -# 型エイリアス: BearerAuthJwtConfig - -```ts -type BearerAuthJwtConfig = { - jwtVerify?: JWTVerifyOptions; - remoteJwkSet?: RemoteJWKSetOptions; -}; -``` - -JWT 検証を使用する場合の Bearer 認証ハンドラーの設定。 - -## プロパティ {#properties} - -### jwtVerify? {#jwtverify} - -```ts -optional jwtVerify: JWTVerifyOptions; -``` - -`jose` ライブラリの `jwtVerify` 関数に渡すオプション。 - -#### 参照 {#see} - -JWTVerifyOptions の型定義を参照してください。 - -*** - -### remoteJwkSet? {#remotejwkset} - -```ts -optional remoteJwkSet: RemoteJWKSetOptions; -``` - -`jose` ライブラリの `createRemoteJWKSet` 関数に渡すオプション。 - -#### 参照 {#see} - -RemoteJWKSetOptions の型定義を参照してください。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md deleted file mode 100644 index a0aeffb..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -sidebar_label: CamelCaseAuthorizationServerMetadata ---- - -# 型エイリアス: CamelCaseAuthorizationServerMetadata - -```ts -type CamelCaseAuthorizationServerMetadata = { - authorizationEndpoint: string; - codeChallengeMethodsSupported?: string[]; - grantTypesSupported?: string[]; - introspectionEndpoint?: string; - introspectionEndpointAuthMethodsSupported?: string[]; - introspectionEndpointAuthSigningAlgValuesSupported?: string[]; - issuer: string; - jwksUri?: string; - opPolicyUri?: string; - opTosUri?: string; - registrationEndpoint?: string; - responseModesSupported?: string[]; - responseTypesSupported: string[]; - revocationEndpoint?: string; - revocationEndpointAuthMethodsSupported?: string[]; - revocationEndpointAuthSigningAlgValuesSupported?: string[]; - scopeSupported?: string[]; - serviceDocumentation?: string; - tokenEndpoint: string; - tokenEndpointAuthMethodsSupported?: string[]; - tokenEndpointAuthSigningAlgValuesSupported?: string[]; - uiLocalesSupported?: string[]; - userinfoEndpoint?: string; -}; -``` - -OAuth 2.0 認可サーバーメタデータ (Authorization Server Metadata) 型の camelCase バージョンです。 - -## 型定義 {#type-declaration} - -### authorizationEndpoint {#authorizationendpoint} - -```ts -authorizationEndpoint: string; -``` - -### codeChallengeMethodsSupported? {#codechallengemethodssupported} - -```ts -optional codeChallengeMethodsSupported: string[]; -``` - -### grantTypesSupported? {#granttypessupported} - -```ts -optional grantTypesSupported: string[]; -``` - -### introspectionEndpoint? {#introspectionendpoint} - -```ts -optional introspectionEndpoint: string; -``` - -### introspectionEndpointAuthMethodsSupported? {#introspectionendpointauthmethodssupported} - -```ts -optional introspectionEndpointAuthMethodsSupported: string[]; -``` - -### introspectionEndpointAuthSigningAlgValuesSupported? {#introspectionendpointauthsigningalgvaluessupported} - -```ts -optional introspectionEndpointAuthSigningAlgValuesSupported: string[]; -``` - -### issuer {#issuer} - -```ts -issuer: string; -``` - -### jwksUri? {#jwksuri} - -```ts -optional jwksUri: string; -``` - -### opPolicyUri? {#oppolicyuri} - -```ts -optional opPolicyUri: string; -``` - -### opTosUri? {#optosuri} - -```ts -optional opTosUri: string; -``` - -### registrationEndpoint? {#registrationendpoint} - -```ts -optional registrationEndpoint: string; -``` - -### responseModesSupported? {#responsemodessupported} - -```ts -optional responseModesSupported: string[]; -``` - -### responseTypesSupported {#responsetypessupported} - -```ts -responseTypesSupported: string[]; -``` - -### revocationEndpoint? {#revocationendpoint} - -```ts -optional revocationEndpoint: string; -``` - -### revocationEndpointAuthMethodsSupported? {#revocationendpointauthmethodssupported} - -```ts -optional revocationEndpointAuthMethodsSupported: string[]; -``` - -### revocationEndpointAuthSigningAlgValuesSupported? {#revocationendpointauthsigningalgvaluessupported} - -```ts -optional revocationEndpointAuthSigningAlgValuesSupported: string[]; -``` - -### scopeSupported? {#scopesupported} - -```ts -optional scopeSupported: string[]; -``` - -### serviceDocumentation? {#servicedocumentation} - -```ts -optional serviceDocumentation: string; -``` - -### tokenEndpoint {#tokenendpoint} - -```ts -tokenEndpoint: string; -``` - -### tokenEndpointAuthMethodsSupported? {#tokenendpointauthmethodssupported} - -```ts -optional tokenEndpointAuthMethodsSupported: string[]; -``` - -### tokenEndpointAuthSigningAlgValuesSupported? {#tokenendpointauthsigningalgvaluessupported} - -```ts -optional tokenEndpointAuthSigningAlgValuesSupported: string[]; -``` - -### uiLocalesSupported? {#uilocalessupported} - -```ts -optional uiLocalesSupported: string[]; -``` - -### userinfoEndpoint? {#userinfoendpoint} - -```ts -optional userinfoEndpoint: string; -``` - -## 参照 {#see} - -元の型およびフィールド情報については、 [AuthorizationServerMetadata](/references/js/type-aliases/AuthorizationServerMetadata.md) を参照してください。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md deleted file mode 100644 index 4012d4c..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -sidebar_label: MCPAuthBearerAuthErrorDetails ---- - -# 型エイリアス: MCPAuthBearerAuthErrorDetails - -```ts -type MCPAuthBearerAuthErrorDetails = { - actual?: unknown; - cause?: unknown; - expected?: unknown; - missingScopes?: string[]; - uri?: URL; -}; -``` - -## プロパティ {#properties} - -### actual? {#actual} - -```ts -optional actual: unknown; -``` - -*** - -### cause? {#cause} - -```ts -optional cause: unknown; -``` - -*** - -### expected? {#expected} - -```ts -optional expected: unknown; -``` - -*** - -### missingScopes? {#missingscopes} - -```ts -optional missingScopes: string[]; -``` - -*** - -### uri? {#uri} - -```ts -optional uri: URL; -``` diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthConfig.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthConfig.md deleted file mode 100644 index a612cd9..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthConfig.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -sidebar_label: MCPAuthConfig ---- - -# 型エイリアス: MCPAuthConfig - -```ts -type MCPAuthConfig = { - server: AuthServerConfig; -}; -``` - -[MCPAuth](/references/js/classes/MCPAuth.md) クラスの設定。 - -## プロパティ {#properties} - -### server {#server} - -```ts -server: AuthServerConfig; -``` - -リモート認可 (Authorization) サーバーの設定。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md deleted file mode 100644 index 36e1f1a..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: MCPAuthTokenVerificationErrorCode ---- - -# 型エイリアス: MCPAuthTokenVerificationErrorCode - -```ts -type MCPAuthTokenVerificationErrorCode = "invalid_token" | "token_verification_failed"; -``` diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenFunction.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenFunction.md deleted file mode 100644 index 5672b90..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenFunction.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -sidebar_label: VerifyAccessTokenFunction ---- - -# 型エイリアス: VerifyAccessTokenFunction() - -```ts -type VerifyAccessTokenFunction = (token: string) => MaybePromise; -``` - -アクセス トークン (Access token) を検証するための関数型です。 - -この関数は、トークンが無効な場合は [MCPAuthTokenVerificationError](/references/js/classes/MCPAuthTokenVerificationError.md) をスローし、有効な場合は AuthInfo オブジェクトを返す必要があります。 - -例えば、JWT 検証関数がある場合、少なくともトークンの署名を確認し、有効期限を検証し、必要なクレーム (Claims) を抽出して `AuthInfo` オブジェクトを返す必要があります。 - -**注意:** 次のフィールドについては、ハンドラーによって確認されるため、トークン内で検証する必要はありません： - -- `iss`（発行者 (Issuer)） -- `aud`（オーディエンス (Audience)） -- `scope`（スコープ (Scopes)） - -## パラメーター {#parameters} - -### token {#token} - -`string` - -検証するアクセス トークン (Access token) の文字列。 - -## 戻り値 {#returns} - -`MaybePromise`\<`AuthInfo`\> - -トークンが有効な場合、AuthInfo オブジェクトを解決する Promise または同期値。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenMode.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenMode.md deleted file mode 100644 index 9367b1f..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenMode.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: VerifyAccessTokenMode ---- - -# 型エイリアス: VerifyAccessTokenMode - -```ts -type VerifyAccessTokenMode = "jwt"; -``` diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authServerErrorDescription.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authServerErrorDescription.md deleted file mode 100644 index fec4bec..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authServerErrorDescription.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: authServerErrorDescription ---- - -# 変数: authServerErrorDescription - -```ts -const authServerErrorDescription: Readonly>; -``` diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authorizationServerMetadataSchema.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authorizationServerMetadataSchema.md deleted file mode 100644 index f7f0567..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authorizationServerMetadataSchema.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: authorizationServerMetadataSchema ---- - -# 変数: authorizationServerMetadataSchema - -```ts -const authorizationServerMetadataSchema: ZodObject; -``` - -RFC 8414 で定義されている OAuth 2.0 認可サーバーメタデータのための Zod スキーマです。 - -## 参照 {#see} - -https://datatracker.ietf.org/doc/html/rfc8414 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/bearerAuthErrorDescription.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/bearerAuthErrorDescription.md deleted file mode 100644 index e459784..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/bearerAuthErrorDescription.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: bearerAuthErrorDescription ---- - -# 変数: bearerAuthErrorDescription (bearerAuthErrorDescription) - -```ts -const bearerAuthErrorDescription: Readonly>; -``` diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md deleted file mode 100644 index 138647a..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: camelCaseAuthorizationServerMetadataSchema ---- - -# 変数: camelCaseAuthorizationServerMetadataSchema - -```ts -const camelCaseAuthorizationServerMetadataSchema: ZodObject; -``` - -OAuth 2.0 認可サーバーメタデータ (Authorization Server Metadata) の Zod スキーマの camelCase バージョンです。 - -## 参照 {#see} - -元のスキーマおよびフィールド情報については、 [authorizationServerMetadataSchema](/references/js/variables/authorizationServerMetadataSchema.md) を参照してください。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/serverMetadataPaths.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/serverMetadataPaths.md deleted file mode 100644 index 698258c..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/serverMetadataPaths.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_label: serverMetadataPaths ---- - -# 変数: serverMetadataPaths - -```ts -const serverMetadataPaths: Readonly<{ - oauth: "/.well-known/oauth-authorization-server"; - oidc: "/.well-known/openid-configuration"; -}>; -``` diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/tokenVerificationErrorDescription.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/tokenVerificationErrorDescription.md deleted file mode 100644 index b3659b0..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/tokenVerificationErrorDescription.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: トークン検証エラーの説明 (tokenVerificationErrorDescription) ---- - -# 変数: トークン検証エラーの説明 (tokenVerificationErrorDescription) - -```ts -const tokenVerificationErrorDescription: Readonly>; -``` diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/validateServerConfig.md b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/validateServerConfig.md deleted file mode 100644 index 3725276..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/validateServerConfig.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: validateServerConfig ---- - -# 変数: validateServerConfig - -```ts -const validateServerConfig: ValidateServerConfig; -``` diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/snippets/_get-started-code.mdx b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/snippets/_get-started-code.mdx deleted file mode 100644 index 4673030..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/snippets/_get-started-code.mdx +++ /dev/null @@ -1,41 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - - - - - -```python -mcp = FastMCP("MyMCPServer") -mcp_auth = MCPAuth(server=fetch_server_config('', type=AuthServerType.OIDC)) -app = Starlette( - # ... MCP サーバーのセットアップ - middleware=[Middleware( - mcp_auth.bearer_auth_middleware("jwt", required_scopes=["read", "write"]) - )] -) - -# 現在のリクエストの認証情報 (auth information) へアクセスするには `mcp_auth.auth_info` を使用 -@mcp.tool() -def whoami() -> dict[str, Any]: - return mcp_auth.auth_info.claims -``` - - - - -```ts -const server = new McpServer(/* ... */); -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { type: 'oidc' }), -}); -const app = express(); - -app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] })); -server.tool('whoami', ({ authInfo }) => { - // `authInfo` を使って `req.auth` から渡された認証情報 (auth information) へアクセス -}); -``` - - - diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/README.mdx b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/README.mdx deleted file mode 100644 index 976dadf..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/README.mdx +++ /dev/null @@ -1,1145 +0,0 @@ ---- -sidebar_position: 2 -sidebar_label: 'チュートリアル: Todo マネージャーを構築する' ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import SetupOauthOrOidc from './_setup-oauth-or-oidc.mdx'; -import SetupOidc from './_setup-oidc.mdx'; - -# チュートリアル: Todo マネージャーを構築する - -このチュートリアルでは、ユーザー認証 (Authentication) と認可 (Authorization) を備えた todo マネージャー MCP サーバーを構築します。 - -このチュートリアルを完了すると、次のことができるようになります： - -- ✅ MCP サーバーでロールベースのアクセス制御 (RBAC) を設定する方法の基本的な理解 -- ✅ 個人の todo リストを管理できる MCP サーバー - -:::note -始める前に、MCP サーバーや OAuth 2 に不慣れな場合は、[Who am I チュートリアル](./whoami) を先にご覧いただくことを強くおすすめします。 -::: - -## 概要 \{#overview} - -このチュートリアルでは、以下のコンポーネントが登場します： - -- **MCP サーバー**：MCP 公式 SDK を利用してリクエストを処理し、ユーザーの todo アイテムを管理する Todo サービスを統合したシンプルな MCP サーバー -- **MCP inspector**：MCP サーバーのためのビジュアルテストツール。OAuth / OIDC クライアントとして認可フローを開始し、アクセス トークンを取得する役割も担います。 -- **認可サーバー (Authorization server)**：ユーザーのアイデンティティを管理し、アクセス トークンを発行する OAuth 2.1 または OpenID Connect プロバイダー - -これらのコンポーネント間のやり取りを示すハイレベルな図です： - -```mermaid -sequenceDiagram - participant Client as MCP Inspector - participant Server as MCP Server - participant Auth as 認可サーバー - - Client->>Server: Todo 操作をリクエスト - Server->>Client: 401 Unauthorized を返す - Client->>Auth: 認可フローを開始 - Auth->>Auth: 認可フローを完了 - Auth->>Client: 認可コードでリダイレクト - Client->>Auth: コードをアクセストークンに交換 - Auth->>Client: アクセストークンを返す - Client->>Server: アクセストークン付きで Todo 操作をリクエスト - Server->>Server: アクセストークンを検証し、ユーザースコープを取得 - Note over Server: Todo 操作を実行 - Server->>Client: Todo 操作結果を返す -``` - -## 認可サーバーを理解する \{#understand-your-authorization-server} - -### スコープ付きアクセス トークン \{#access-tokens-with-scopes} - -MCP サーバーで [ロールベースのアクセス制御 (RBAC)](https://auth.wiki/rbac) を実装するには、認可サーバーがスコープ付きのアクセス トークンを発行できる必要があります。スコープは、ユーザーに付与された権限を表します。 - - - - -[Logto](https://logto.io) は、API リソース（[RFC 8707: OAuth 2.0 のリソースインジケーター](https://datatracker.ietf.org/doc/html/rfc8707) に準拠）とロール機能を通じて RBAC をサポートしています。設定方法は以下の通りです： - -1. [Logto Console](https://cloud.logto.io)（またはセルフホストの Logto Console）にサインイン - -2. API リソースとスコープを作成： - - - 「API リソース」に移動 - - 「Todo Manager」という名前で新しい API リソースを作成 - - 以下のスコープを追加： - - `create:todos`: 「新しい todo アイテムを作成」 - - `read:todos`: 「すべての todo アイテムを取得」 - - `delete:todos`: 「任意の todo アイテムを削除」 - -3. ロールを作成（管理を簡単にするため推奨）： - - - 「ロール」に移動 - - 「Admin」ロールを作成し、すべてのスコープ（`create:todos`, `read:todos`, `delete:todos`）を割り当て - - 「User」ロールを作成し、`create:todos` スコープのみを割り当て - -4. 権限を割り当てる： - - 「ユーザー」に移動 - - ユーザーを選択 - - 以下のいずれかを実施： - - 「ロール」タブでロールを割り当て（推奨） - - または「権限」タブで直接スコープを割り当て - -スコープは JWT アクセス トークンの `scope` クレームにスペース区切りの文字列として含まれます。 - - - - -OAuth 2.0 / OIDC プロバイダーは通常、スコープベースのアクセス制御をサポートしています。RBAC を実装する場合： - -1. 認可サーバーで必要なスコープを定義 -2. クライアントが認可フロー中にこれらのスコープをリクエストするよう設定 -3. 認可サーバーが付与したスコープをアクセス トークンに含めることを確認 -4. スコープは通常、JWT アクセス トークンの `scope` クレームに含まれます - -スコープの定義・管理方法や、アクセス トークンへのスコープの含め方、ロール管理などの追加 RBAC 機能については、プロバイダーのドキュメントを参照してください。 - - - - -### トークンの検証と権限チェック \{#validating-tokens-and-checking-permissions} - -MCP サーバーがリクエストを受け取った際に行うべきこと： - -1. アクセス トークンの署名と有効期限を検証 -2. 検証済みトークンからスコープを抽出 -3. リクエストされた操作に必要なスコープがトークンに含まれているか確認 - -例えば、ユーザーが新しい todo アイテムを作成したい場合、そのアクセス トークンには `create:todos` スコープが含まれている必要があります。フローは以下の通りです： - -```mermaid -sequenceDiagram - participant Client - participant MCP Server - participant Auth Server - - Client->>MCP Server: アクセス トークン付きでリクエスト - - alt JWT 検証 - MCP Server->>Auth Server: JWKS を取得 - Auth Server-->>MCP Server: JWKS を返す - MCP Server->>MCP Server: JWT をローカルで検証 - else トークンインスペクション - MCP Server->>Auth Server: POST /introspect
(token=access_token) - Auth Server-->>MCP Server: トークン情報を返す
(active, scope など) - end - - MCP Server->>MCP Server: スコープを抽出・チェック - - alt 必要なスコープあり - MCP Server->>Client: 操作を許可 - else スコープ不足 - MCP Server->>Client: 403 Forbidden を返す - end -``` - -### Dynamic Client Registration \{#dynamic-client-registration} - -このチュートリアルでは Dynamic Client Registration は必須ではありませんが、認可サーバーへの MCP クライアント登録を自動化したい場合に便利です。詳細は [Dynamic Client Registration は必要ですか？](/provider-list#is-dcr-required) をご覧ください。 - -## Todo マネージャーにおける RBAC を理解する \{#understand-rbac-in-todo-manager} - -デモ目的で、todo マネージャー MCP サーバーにシンプルなロールベースのアクセス制御 (RBAC) システムを実装します。これにより、RBAC の基本原則をシンプルな実装で体験できます。 - -:::note -このチュートリアルでは RBAC ベースのスコープ管理を紹介していますが、すべての認証 (Authentication) プロバイダーがロールによるスコープ管理を実装しているわけではありません。プロバイダーによっては独自のアクセス制御や権限管理の仕組みを持っている場合があります。 -::: - -### ツールとスコープ \{#tools-and-scopes} - -todo マネージャー MCP サーバーは、主に次の 3 つのツールを提供します： - -- `create-todo`: 新しい todo アイテムを作成 -- `get-todos`: すべての todo を一覧表示 -- `delete-todo`: ID で todo を削除 - -これらのツールへのアクセスを制御するため、以下のスコープを定義します： - -- `create:todos`: 新しい todo アイテムの作成を許可 -- `delete:todos`: 既存の todo アイテムの削除を許可 -- `read:todos`: すべての todo アイテムの取得を許可 - -### ロールと権限 \{#roles-and-permissions} - -異なるアクセスレベルを持つ 2 つのロールを定義します： - -| ロール | create:todos | read:todos | delete:todos | -| ------- | ------------ | ---------- | ------------ | -| Admin | ✅ | ✅ | ✅ | -| User | ✅ | | | - -- **User**：自分の todo の作成・閲覧・削除のみ可能な一般ユーザー -- **Admin**：すべての todo の作成・閲覧・削除が可能な管理者 - -### リソース所有権 \{#resource-ownership} - -上記の権限テーブルは各ロールに明示的に割り当てられたスコープを示していますが、リソース所有権の重要な原則も考慮する必要があります： - -- **User** は `read:todos` や `delete:todos` スコープを持っていませんが、次のことが可能です： - - 自分の todo アイテムの閲覧 - - 自分の todo アイテムの削除 -- **Admin** は `read:todos` および `delete:todos` のフル権限を持ち、次のことが可能です： - - システム内のすべての todo アイテムの閲覧 - - 所有者に関係なく任意の todo アイテムの削除 - -これは、RBAC システムでよく見られるパターンで、リソース所有者には自分のリソースに対する暗黙的な権限が与えられ、管理者ロールにはすべてのリソースに対する明示的な権限が付与されることを示しています。 - -:::tip 詳しく学ぶ -RBAC の概念やベストプラクティスについてさらに深く知りたい場合は、[Mastering RBAC: A Comprehensive Real-World Example](https://blog.logto.io/mastering-rbac) をご覧ください。 -::: - -## プロバイダーで認可を設定する \{#configure-authorization-in-your-provider} - -前述のアクセス制御システムを実装するには、認可サーバーで必要なスコープをサポートするよう設定する必要があります。プロバイダーごとの設定方法は以下の通りです： - - - - -[Logto](https://logto.io) は、API リソースとロール機能を通じて RBAC をサポートしています。設定方法は以下の通りです： - -1. [Logto Console](https://cloud.logto.io)（またはセルフホストの Logto Console）にサインイン - -2. API リソースとスコープを作成： - - - 「API リソース」に移動 - - 「Todo Manager」という名前で新しい API リソースを作成し、インジケーターとして `https://todo.mcp-server.app`（デモ用）を使用 - - 以下のスコープを作成： - - `create:todos`: 「新しい todo アイテムを作成」 - - `read:todos`: 「すべての todo アイテムを取得」 - - `delete:todos`: 「任意の todo アイテムを削除」 - -3. ロールを作成（管理を簡単にするため推奨）： - - - 「ロール」に移動 - - 「Admin」ロールを作成し、すべてのスコープ（`create:todos`, `read:todos`, `delete:todos`）を割り当て - - 「User」ロールを作成し、`create:todos` スコープのみを割り当て - - 「User」ロールの詳細ページで「一般」タブに切り替え、「User」ロールを「デフォルトロール」に設定 - -4. ユーザーロールと権限を管理： - - 新規ユーザーの場合： - - デフォルトロールとして「User」を設定したため、自動的に「User」ロールが付与されます - - 既存ユーザーの場合： - - 「ユーザー管理」に移動 - - ユーザーを選択 - - 「ロール」タブでユーザーにロールを割り当て - -:::tip プログラムによるロール管理 -Logto の [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api) を使って、ユーザーロールをプログラムで管理することも可能です。自動ユーザー管理や管理画面の構築時に特に便利です。 -::: - -アクセストークンをリクエストすると、Logto はユーザーロールの権限に基づいてトークンの `scope` クレームにスコープを含めます。 - - - - -[Keycloak](https://www.keycloak.org) では、クライアントスコープを使って必要な権限を設定できます： - -1. クライアントスコープを作成： - - - レルム内で「クライアントスコープ」に移動 - - 以下の 3 つのクライアントスコープを作成： - - `create:todos` - - `read:todos` - - `delete:todos` - -2. クライアントを設定： - - - クライアント設定に移動 - - 「クライアントスコープ」タブで作成したすべてのスコープを追加 - - トークンマッパーがスコープを含めるように設定されていることを確認 - -3. オプション：ロールによる管理を利用 - - ロールベースの管理を希望する場合： - - 異なるアクセスレベル用のレルムロールを作成 - - スコープをロールにマッピング - - ユーザーにロールを割り当て - - それ以外の場合は、ユーザーやクライアントレベルの権限で直接スコープを割り当てることも可能 - -Keycloak は付与されたスコープをアクセス トークンの `scope` クレームに含めます。 - - - - -OAuth 2.0 または OpenID Connect プロバイダーの場合、異なる権限を表すスコープを設定する必要があります。具体的な手順はプロバイダーによって異なりますが、一般的には： - -1. スコープを定義： - - - 認可サーバーで以下をサポートするよう設定： - - `create:todos` - - `read:todos` - - `delete:todos` - -2. クライアントを設定： - - - クライアントを登録または更新し、これらのスコープをリクエストするように設定 - - スコープがアクセス トークンに含まれることを確認 - -3. 権限を割り当てる： - - プロバイダーのインターフェースでユーザーに適切なスコープを付与 - - 一部のプロバイダーはロールベース管理をサポートし、他は直接スコープ割り当てを使用 - - 推奨される方法はプロバイダーのドキュメントを参照 - -:::tip -ほとんどのプロバイダーは、付与されたスコープをアクセス トークンの `scope` クレームに含めます。形式は通常、スペース区切りのスコープ値の文字列です。 -::: - - - - -認可サーバーの設定後、ユーザーは付与されたスコープを含むアクセス トークンを受け取ります。MCP サーバーはこれらのスコープを使って次のことを判断します： - -- 新しい todo を作成できるか（`create:todos`） -- すべての todo を閲覧できるか（`read:todos`）または自分のものだけか -- 任意の todo を削除できるか（`delete:todos`）または自分のものだけか - -## MCP サーバーをセットアップする \{#set-up-the-mcp-server} - -[公式 MCP SDK](https://github.com/modelcontextprotocol) を使って todo マネージャー MCP サーバーを作成します。 - -### 新しいプロジェクトを作成 \{#create-a-new-project} - - - - -```bash -mkdir mcp-server -cd mcp-server -uv init # または `pipenv` や `poetry` で仮想環境を作成 -``` - - - - -新しい Node.js プロジェクトをセットアップ： - -```bash -mkdir mcp-server -cd mcp-server -npm init -y # または `pnpm init` -npm pkg set type="module" -npm pkg set main="todo-manager.ts" -npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts" -``` - -:::note -サンプルでは TypeScript を使用しています。Node.js v22.6.0 以降では `--experimental-strip-types` フラグで TypeScript をネイティブ実行できます。JavaScript を使う場合もほぼ同様ですが、Node.js v22.6.0 以降を使用してください。詳細は Node.js ドキュメントを参照してください。 -::: - - - - -### MCP SDK と依存パッケージのインストール \{#install-the-mcp-sdk-and-dependencies} - - - - -```bash -pip install "mcp[cli]" starlette uvicorn -``` - -または `uv` や `poetry` などお好みのパッケージマネージャーを利用できます。 - - - - -```bash -npm install @modelcontextprotocol/sdk express zod -``` - -または `pnpm` や `yarn` などお好みのパッケージマネージャーを利用できます。 - - - - -### MCP サーバーを作成 \{#create-the-mcp-server} - -まず、ツール定義を含む基本的な MCP サーバーを作成します： - - - - -`todo-manager.py` というファイルを作成し、次のコードを追加します： - -```python -from typing import Any -from mcp.server.fastmcp import FastMCP -from starlette.applications import Starlette -from starlette.routing import Mount - -mcp = FastMCP("Todo Manager") - -@mcp.tool() -def create_todo(content: str) -> dict[str, Any]: - """新しい todo を作成""" - return {"error": "Not implemented"} - -@mcp.tool() -def get_todos() -> dict[str, Any]: - """すべての todo を一覧表示""" - return {"error": "Not implemented"} - -@mcp.tool() -def delete_todo(id: str) -> dict[str, Any]: - """ID で todo を削除""" - return {"error": "Not implemented"} - -app = Starlette( - routes=[Mount('/', app=mcp.sse_app())] -) -``` - -サーバーを起動： - -```bash -uvicorn todo_manager:app --host 0.0.0.0 --port 3001 -``` - - - - -:::note -現時点の MCP inspector 実装では認可フローに対応していないため、SSE アプローチで MCP サーバーをセットアップします。MCP inspector が認可フローに対応した際にはコードを更新します。 -::: - -`pnpm` や `yarn` も利用可能です。 - -`todo-manager.ts` というファイルを作成し、次のコードを追加します： - -```ts -// todo-manager.ts - -import { z } from 'zod'; -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; -import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'; -import express from 'express'; - -// MCP サーバーを作成 -const server = new McpServer({ - name: 'Todo Manager', - version: '0.0.0', -}); - -server.tool('create-todo', '新しい todo を作成', { content: z.string() }, async ({ content }) => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }], - }; -}); - -server.tool('get-todos', 'すべての todo を一覧表示', async () => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }], - }; -}); - -server.tool('delete-todo', 'ID で todo を削除', { id: z.string() }, async ({ id }) => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }], - }; -}); - -// 以下は MCP SDK ドキュメントのボイラープレートコード -const PORT = 3001; -const app = express(); - -const transports = {}; - -app.get('/sse', async (_req, res) => { - const transport = new SSEServerTransport('/messages', res); - transports[transport.sessionId] = transport; - - res.on('close', () => { - delete transports[transport.sessionId]; - }); - - await server.connect(transport); -}); - -app.post('/messages', async (req, res) => { - const sessionId = String(req.query.sessionId); - const transport = transports[sessionId]; - if (transport) { - await transport.handlePostMessage(req, res, req.body); - } else { - res.status(400).send('No transport found for sessionId'); - } -}); - -app.listen(PORT); -``` - -サーバーを起動： - -```bash -npm start -``` - - - - -## MCP サーバーを検証する \{#inspect-the-mcp-server} - -### MCP inspector をクローンして起動 \{#clone-and-run-mcp-inspector} - -MCP サーバーが起動したので、MCP inspector を使って `whoami` ツールが利用可能か確認します。 - -現状の実装制限のため、[MCP inspector](https://github.com/mcp-auth/inspector) をフォークし、認証 (Authentication)・認可 (Authorization) に柔軟かつ拡張可能にしました。オリジナルリポジトリにもプルリクエストを提出済みです。 - -MCP inspector を起動するには（Node.js が必要です）： - -```bash -git clone https://github.com/mcp-auth/inspector.git -cd inspector -npm install -npm run dev -``` - -その後、ブラウザで `http://localhost:6274/`（またはターミナルに表示された URL）にアクセスしてください。 - -### MCP inspector を MCP サーバーに接続 \{#connect-mcp-inspector-to-the-mcp-server} - -進める前に、MCP inspector の設定を確認してください： - -- **Transport Type**：`SSE` に設定 -- **URL**：MCP サーバーの URL を設定（例：`http://localhost:3001/sse`） - -「Connect」ボタンをクリックし、MCP inspector が MCP サーバーに接続できるか確認します。問題なければ MCP inspector に「Connected」ステータスが表示されます。 - -### チェックポイント: Todo マネージャーツールを実行 \{#checkpoint-run-todo-manager-tools} - -1. MCP inspector の上部メニューで「Tools」タブをクリック -2. 「List Tools」ボタンをクリック -3. `create-todo`, `get-todos`, `delete-todo` ツールが一覧に表示されるはずです。クリックして詳細を開きます。 -4. 右側に「Run Tool」ボタンが表示されます。クリックして必要なパラメータを入力し、ツールを実行します。 -5. ツールの結果として `{"error": "Not implemented"}` という JSON レスポンスが表示されます。 - -![MCP inspector first run](/docs-assets/images/tutorials/todo-manager/inspector-first-run.png) - -## 認可サーバーと連携する \{#integrate-with-your-authorization-server} - -このセクションを完了するには、いくつかの考慮事項があります： - -
-**認可サーバーの発行者 (Issuer) URL** - -通常は認可サーバーのベース URL です（例：`https://auth.example.com`）。プロバイダーによっては `https://example.logto.app/oidc` のようなパスが付く場合もあるので、ドキュメントを確認してください。 - -
- -
-**認可サーバーメタデータの取得方法** - -- 認可サーバーが [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) または [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) に準拠していれば、MCP Auth の組み込みユーティリティで自動取得できます。 -- 準拠していない場合は、MCP サーバー設定でメタデータ URL やエンドポイントを手動指定する必要があります。詳細はプロバイダーのドキュメントを参照してください。 - -
- -
-**MCP inspector を認可サーバーのクライアントとして登録する方法** - -- 認可サーバーが [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591) をサポートしていれば、このステップは不要です。MCP inspector が自動でクライアント登録します。 -- サポートしていない場合は、MCP inspector を手動でクライアント登録する必要があります。 - -
- -
-**トークンリクエストパラメータの理解** - -認可サーバーからアクセス トークンをリクエストする際、ターゲットリソースや権限指定の方法がいくつかあります。主なパターンは以下の通りです： - -- **リソースインジケーター方式**： - - - `resource` パラメータでターゲット API を指定（[RFC 8707](https://datatracker.ietf.org/doc/html/rfc8707) 参照） - - モダンな OAuth 2.0 実装で一般的 - - 例： - ```json - { - "resource": "https://todo.mcp-server.app", - "scope": "create:todos read:todos" - } - ``` - - サーバーはリソースにバインドされたトークンを発行 - -- **オーディエンス方式**： - - - `audience` パラメータでトークンの受信者を指定 - - リソースインジケーターと似ているが意味が異なる - - 例： - ```json - { - "audience": "todo-api", - "scope": "create:todos read:todos" - } - ``` - -- **純粋なスコープ方式**： - - リソースやオーディエンスパラメータなしでスコープのみを利用 - - 従来の OAuth 2.0 アプローチ - - 例： - ```json - { - "scope": "todo-api:create todo-api:read openid profile" - } - ``` - - 権限の名前空間化のためにプレフィックス付きスコープを使うことが多い - - シンプルな OAuth 2.0 実装で一般的 - -:::tip ベストプラクティス - -- サポートされているパラメータはプロバイダーのドキュメントを確認 -- 複数の方式を同時にサポートするプロバイダーもある -- リソースインジケーターはオーディエンス制限によるセキュリティ向上に有効 -- 利用可能ならリソースインジケーター方式を推奨 - ::: - -
- -プロバイダーごとに固有の要件がある場合もありますが、以下の手順で MCP inspector および MCP サーバーをプロバイダー固有の設定で統合できます。 - -### MCP inspector をクライアントとして登録 \{#register-mcp-inspector-as-a-client} - - - - -[Logto](https://logto.io) との統合は簡単です。OpenID Connect プロバイダーであり、リソースインジケーターとスコープをサポートしているため、`https://todo.mcp-server.app` をリソースインジケーターとして todo API を安全に保護できます。 - -Logto は現時点で Dynamic Client Registration をサポートしていないため、MCP inspector を Logto テナントのクライアントとして手動登録する必要があります： - -1. MCP inspector を開き、「OAuth Configuration」ボタンをクリック。**Redirect URL (auto-populated)** の値（例：`http://localhost:6274/oauth/callback`）をコピー -2. [Logto Console](https://cloud.logto.io)（またはセルフホストの Logto Console）にサインイン -3. 「アプリケーション」タブで「Create application」をクリック。ページ下部で「Create app without framework」をクリック -4. アプリケーション詳細を入力し、「Create application」をクリック： - - **アプリケーションタイプ**：「Single-page application」を選択 - - **アプリケーション名**：例「MCP Inspector」 -5. 「Settings / Redirect URIs」セクションで、先ほどコピーした **Redirect URL (auto-populated)** を貼り付け、「Save changes」をクリック -6. 上部カードに「App ID」が表示されるのでコピー -7. MCP inspector に戻り、「OAuth Configuration」セクションの「Client ID」に「App ID」を貼り付け -8. 「Auth Params」フィールドに `{"scope": "create:todos read:todos delete:todos", "resource": "https://todo.mcp-server.app"}` を入力。これで Logto から返されるアクセストークンに必要なスコープが含まれます。 - - - - -:::note -これは一般的な OAuth 2.0 / OpenID Connect プロバイダー統合ガイドです。OIDC は OAuth 2.0 上に構築されているため、手順はほぼ同じです。詳細はプロバイダーのドキュメントを参照してください。 -::: - -プロバイダーが Dynamic Client Registration をサポートしていれば、下記の 8 番に直接進んで MCP inspector を設定できます。サポートしていない場合は MCP inspector を手動でクライアント登録してください： - -1. MCP inspector を開き、「OAuth Configuration」ボタンをクリック。**Redirect URL (auto-populated)** の値（例：`http://localhost:6274/oauth/callback`）をコピー - -2. プロバイダーのコンソールにサインイン - -3. 「アプリケーション」または「クライアント」セクションで新しいアプリケーションまたはクライアントを作成 - -4. クライアントタイプが必要な場合は「Single-page application」または「Public client」を選択 - -5. アプリケーション作成後、リダイレクト URI を設定。先ほどコピーした **Redirect URL (auto-populated)** を貼り付け - -6. 新規アプリケーションの「Client ID」または「Application ID」をコピー - -7. MCP inspector に戻り、「OAuth Configuration」セクションの「Client ID」に貼り付け - -8. 「Auth Params」フィールドに以下を入力し、todo 操作用の必要なスコープをリクエスト： - -```json -{ "scope": "create:todos read:todos delete:todos" } -``` - - - - -### MCP auth をセットアップ \{#set-up-mcp-auth} - -MCP サーバープロジェクトで MCP Auth SDK をインストールし、認可サーバーメタデータを使って設定します。 - - - - -まず `mcpauth` パッケージをインストール： - -```bash -pip install mcpauth -``` - -または `uv` や `poetry` などお好みのパッケージマネージャーを利用できます。 - - - - -まず `mcp-auth` パッケージをインストール： - -```bash -npm install mcp-auth -``` - - - - -MCP Auth は認可サーバーメタデータが必要です。プロバイダーごとに： - - - - - -発行者 (Issuer) URL は Logto Console のアプリケーション詳細ページ「Endpoints & Credentials / Issuer endpoint」セクションで確認できます（例：`https://my-project.logto.app/oidc`）。 - - - - - - - -OAuth 2.0 プロバイダーの場合： - -1. 認可サーバーの URL（Issuer URL またはベース URL）をドキュメントで確認 -2. 多くの場合 `https://{your-domain}/.well-known/oauth-authorization-server` で公開 -3. 管理コンソールの OAuth/API 設定を確認 - - - - - - - - - - - -`todo-manager.py` を MCP Auth 設定を含むように更新： - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # 発行者エンドポイントに置き換え -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -`todo-manager.ts` を MCP Auth 設定を含むように更新： - -```ts -// todo-manager.ts - -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // 発行者エンドポイントに置き換え -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oidc' }), -}); -``` - - - - -### MCP サーバーを更新 \{#update-mcp-server} - -あと少しです！MCP Auth のルートとミドルウェア関数を適用し、ユーザーのスコープに基づく権限管理を todo マネージャーツールに実装します。 - - - - -```python -@mcp.tool() -def create_todo(content: str) -> dict[str, Any]: - """新しい todo を作成""" - return ( - mcp_auth.auth_info.scopes - if mcp_auth.auth_info # Bearer 認証ミドルウェアでセットされる - else {"error": "Not authenticated"} - ) - -# ... - -bearer_auth = Middleware(mcp_auth.bearer_auth_middleware("jwt")) -app = Starlette( - routes=[ - # メタデータルート（`/.well-known/oauth-authorization-server`）を追加 - mcp_auth.metadata_route(), - # Bearer 認証ミドルウェアで MCP サーバーを保護 - Mount('/', app=mcp.sse_app(), middleware=[bearer_auth]), - ], -) -``` - - - - -```js -server.tool( - 'create-todo', - '新しい todo を作成', - { content: z.string() }, - async ({ content, authInfo }) => { - return { - content: [ - { type: 'text', text: JSON.stringify(authInfo?.scopes ?? { error: 'Not authenticated' }) }, - ], - }; - } -); - -// ... - -app.use(mcpAuth.delegatedRouter()); -app.use(mcpAuth.bearerAuth('jwt')); -``` - - - - -次に、実際のツールを実装します。 - -まず、メモリ上で todo アイテムの基本的な CRUD 操作を提供するシンプルな todo サービスを作成します。 - - - -```python -# service.py - -""" -デモ用のシンプルな Todo サービス。 -メモリ上のリストで todo を管理します。 -""" - -from datetime import datetime -from typing import List, Optional, Dict, Any -import random -import string - -class Todo: -"""Todo アイテムを表します。""" - - def __init__(self, id: str, content: str, owner_id: str, created_at: str): - self.id = id - self.content = content - self.owner_id = owner_id - self.created_at = created_at - - def to_dict(self) -> Dict[str, Any]: - """Todo を辞書に変換（JSON シリアライズ用）""" - return { - "id": self.id, - "content": self.content, - "ownerId": self.owner_id, - "createdAt": self.created_at - } - -class TodoService: -"""デモ用のシンプルな Todo サービス。""" - - def __init__(self): - self._todos: List[Todo] = [] - - def get_all_todos(self, owner_id: Optional[str] = None) -> List[Dict[str, Any]]: - """ - すべての todo を取得。owner_id でフィルタ可能。 - - Args: - owner_id: 指定した場合、そのユーザー所有の todo のみ返す - - Returns: - Todo 辞書のリスト - """ - if owner_id: - filtered_todos = [todo for todo in self._todos if todo.owner_id == owner_id] - return [todo.to_dict() for todo in filtered_todos] - return [todo.to_dict() for todo in self._todos] - - def get_todo_by_id(self, todo_id: str) -> Optional[Todo]: - """ - ID で todo を取得 - - Args: - todo_id: 取得する todo の ID - - Returns: - 見つかれば Todo オブジェクト、なければ None - """ - for todo in self._todos: - if todo.id == todo_id: - return todo - return None - - def create_todo(self, content: str, owner_id: str) -> Dict[str, Any]: - """ - 新しい todo を作成 - - Args: - content: todo の内容 - owner_id: この todo の所有ユーザー ID - - Returns: - 作成した todo の辞書 - """ - todo = Todo( - id=self._generate_id(), - content=content, - owner_id=owner_id, - created_at=datetime.now().isoformat() - ) - self._todos.append(todo) - return todo.to_dict() - - def delete_todo(self, todo_id: str) -> Optional[Dict[str, Any]]: - """ - ID で todo を削除 - - Args: - todo_id: 削除する todo の ID - - Returns: - 削除した todo の辞書（見つかれば）、なければ None - """ - for i, todo in enumerate(self._todos): - if todo.id == todo_id: - deleted_todo = self._todos.pop(i) - return deleted_todo.to_dict() - return None - - def _generate_id(self) -> str: - """Todo 用のランダム ID を生成""" - return ''.join(random.choices(string.ascii_lowercase + string.digits, k=8)) - -```` - - - - - -```ts -// todo-service.ts - -type Todo = { - id: string; - content: string; - ownerId: string; - createdAt: string; -}; - -/** - * デモ用のシンプルな Todo サービス。 - * メモリ上の配列で todo を管理 - */ -export class TodoService { - private readonly todos: Todo[] = []; - - getAllTodos(ownerId?: string): Todo[] { - if (ownerId) { - return this.todos.filter((todo) => todo.ownerId === ownerId); - } - return this.todos; - } - - getTodoById(id: string): Todo | undefined { - return this.todos.find((todo) => todo.id === id); - } - - createTodo({ content, ownerId }: { content: string; ownerId: string }): Todo { - const todo: Todo = { - id: this.genId(), - content, - ownerId, - createdAt: new Date().toISOString(), - }; - - // eslint-disable-next-line @silverhand/fp/no-mutating-methods - this.todos.push(todo); - return todo; - } - - deleteTodo(id: string): Todo | undefined { - const index = this.todos.findIndex((todo) => todo.id === id); - - if (index === -1) { - return undefined; - } - - // eslint-disable-next-line @silverhand/fp/no-mutating-methods - const [deleted] = this.todos.splice(index, 1); - return deleted; - } - - private genId(): string { - return Math.random().toString(36).slice(2, 10); - } -} -```` - - - - -次にツール層で、ユーザーのスコープに基づいて操作が許可されるかどうかを判定します： - - - - -```python -# todo-manager.py - -from typing import Any, Optional -from mcpauth.errors import MCPAuthBearerAuthError - -def assert_user_id(auth_info: Optional[dict]) -> str: - """auth info からユーザー ID を抽出・検証""" - subject = auth_info.get('subject') if auth_info else None - if not subject: - raise ValueError('Invalid auth info') - return subject - -def has_required_scopes(user_scopes: list[str], required_scopes: list[str]) -> bool: - """ユーザーがすべての必要なスコープを持っているかチェック""" - return all(scope in user_scopes for scope in required_scopes) - -# TodoService のインスタンスを作成 -todo_service = TodoService() - -@mcp.tool() -def create_todo(content: str) -> dict[str, Any]: - """新しい todo を作成 - - 'create:todos' スコープを持つユーザーのみ作成可能 - """ - # 認証情報を取得 - auth_info = mcp_auth.auth_info - - # ユーザー ID を検証 - try: - user_id = assert_user_id(auth_info) - except ValueError as e: - return {"error": str(e)} - - # 必要な権限を持っているかチェック - if not has_required_scopes(auth_info.scopes if auth_info else [], ['create:todos']): - raise MCPAuthBearerAuthError('missing_required_scopes') - - # 新しい todo を作成 - created_todo = todo_service.create_todo(content=content, owner_id=user_id) - - # 作成した todo を返す - return created_todo.__dict__ - -# ... -``` - -[サンプルコード](https://github.com/mcp-auth/python/tree/master/samples/server) で他の詳細実装も確認できます。 - - - - -```ts -// todo-manager.ts - -// ... 他のインポート -import assert from 'node:assert'; -import { type AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js'; -import { TodoService } from './todo-service.js'; - -const todoService = new TodoService(); - -const assertUserId = (authInfo?: AuthInfo) => { - const { subject } = authInfo ?? {}; - assert(subject, 'Invalid auth info'); - return subject; -}; - -/** - * 操作に必要なすべてのスコープをユーザーが持っているかチェック - */ -const hasRequiredScopes = (userScopes: string[], requiredScopes: string[]): boolean => { - return requiredScopes.every((scope) => userScopes.includes(scope)); -}; - -server.tool( - 'create-todo', - '新しい todo を作成', - { content: z.string() }, - ({ content }: { content: string }, { authInfo }) => { - const userId = assertUserId(authInfo); - - /** - * 'create:todos' スコープを持つユーザーのみ作成可能 - */ - if (!hasRequiredScopes(authInfo?.scopes ?? [], ['create:todos'])) { - throw new MCPAuthBearerAuthError('missing_required_scopes'); - } - - const createdTodo = todoService.createTodo({ content, ownerId: userId }); - - return { - content: [{ type: 'text', text: JSON.stringify(createdTodo) }], - }; - } -); - -// ... -``` - -[サンプルコード](https://github.com/mcp-auth/js/tree/master/packages/sample-servers/src/todo-manager) で他の詳細実装も確認できます。 - - - - -## チェックポイント: `todo-manager` ツールを実行 \{#checkpoint-run-the-todo-manager-tools} - -MCP サーバーを再起動し、ブラウザで MCP inspector を開きます。「Connect」ボタンをクリックすると、認可サーバーのサインインページにリダイレクトされます。 - -サインインして MCP inspector に戻ったら、前回のチェックポイントと同じ操作で todo マネージャーツールを実行します。今回は認証済みユーザーとしてツールを利用できます。ツールの挙動は、ユーザーに割り当てられたロールと権限によって異なります： - -- **User**（`create:todos` スコープのみ）の場合： - - - `create-todo` ツールで新しい todo を作成可能 - - 自分の todo のみ閲覧・削除可能 - - 他ユーザーの todo は閲覧・削除不可 - -- **Admin**（すべてのスコープ：`create:todos`, `read:todos`, `delete:todos`）の場合： - - 新しい todo を作成可能 - - `get-todos` ツールですべての todo を閲覧可能 - - `delete-todo` ツールで所有者に関係なく任意の todo を削除可能 - -異なる権限レベルをテストするには： - -1. 現在のセッションからサインアウト（MCP inspector の「Disconnect」ボタンをクリック） -2. 別のロール／権限を持つユーザーアカウントでサインイン -3. 同じツールを再度試し、ユーザーの権限による挙動の違いを確認 - -これにより、ロールベースのアクセス制御 (RBAC) が実際にどのように機能するかを体験できます。 - -![MCP inspector todo manager tool result](/docs-assets/images/tutorials/todo-manager/result.png) - - - - -:::info -[MCP Auth Python SDK リポジトリ](https://github.com/mcp-auth/python/blob/master/samples/server/todo-manager/server.py) で MCP サーバー（OIDC 版）の完全なコードを確認できます。 -::: - - - - -:::info -[MCP Auth Node.js SDK リポジトリ](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) で MCP サーバー（OIDC 版）の完全なコードを確認できます。 -::: - - - - -## 締めくくり \{#closing-notes} - -🎊 おめでとうございます！チュートリアルを無事完了しました。ここまでで行ったことを振り返りましょう： - -- Todo 管理ツール（`create-todo`, `get-todos`, `delete-todo`）付きの基本的な MCP サーバーのセットアップ -- ユーザーと管理者で異なる権限レベルを持つロールベースのアクセス制御 (RBAC) の実装 -- MCP サーバーを MCP Auth で認可サーバーと統合 -- MCP Inspector でユーザー認証とスコープ付きアクセストークンを使ったツール呼び出し - -他のチュートリアルやドキュメントもぜひご覧いただき、MCP Auth を最大限に活用してください。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_manual-metadata-fetching.mdx b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_manual-metadata-fetching.mdx deleted file mode 100644 index 340a89b..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_manual-metadata-fetching.mdx +++ /dev/null @@ -1,3 +0,0 @@ -:::note -プロバイダーが {props.oidc ? 'OpenID Connect Discovery' : 'OAuth 2.0 Authorization Server Metadata'} をサポートしていない場合、メタデータ URL またはエンドポイントを手動で指定できます。詳細は [MCP Auth を初期化するその他の方法](../../configure-server/mcp-auth.mdx#other-ways) をご確認ください。 -::: \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oauth-or-oidc.mdx b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oauth-or-oidc.mdx deleted file mode 100644 index 4d1ebc5..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oauth-or-oidc.mdx +++ /dev/null @@ -1,41 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -`todo-manager.py` を更新して、MCP Auth の構成を追加します： - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # 発行者エンドポイントに置き換えてください -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OAUTH) # または AuthServerType.OIDC -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -`todo-manager.ts` を更新して、MCP Auth の構成を追加します： - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // 発行者エンドポイントに置き換えてください -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oauth' }), // または { type: 'oidc' } -}); -``` - - - - - - diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oidc.mdx b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oidc.mdx deleted file mode 100644 index 32b6bf4..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oidc.mdx +++ /dev/null @@ -1,41 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -`todo-manager.py` を更新して MCP Auth の設定を追加します： - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # 発行者エンドポイントに置き換えてください -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -`todo-manager.ts` を更新して MCP Auth の設定を追加します： - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // 発行者エンドポイントに置き換えてください -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oidc' }), -}); -``` - - - - -{props.showAlternative && } -{props.showAlternative && } \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_transpile-metadata.mdx b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_transpile-metadata.mdx deleted file mode 100644 index d081f2d..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_transpile-metadata.mdx +++ /dev/null @@ -1,31 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -場合によっては、プロバイダーのレスポンスが不正であったり、期待されるメタデータ形式に準拠していないことがあります。プロバイダーが準拠していると確信できる場合は、設定オプションを使ってメタデータをトランスパイルできます： - - - - -```python -mcp_auth = MCPAuth( - server=fetch_server_config( - # ...other options - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { - // ...other options - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/README.mdx b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/README.mdx deleted file mode 100644 index 2745ae6..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/README.mdx +++ /dev/null @@ -1,606 +0,0 @@ ---- -sidebar_position: 1 -sidebar_label: 'チュートリアル: 私は誰？' ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import SetupOauth from './_setup-oauth.mdx'; -import SetupOidc from './_setup-oidc.mdx'; - -# チュートリアル: 私は誰？ - -このチュートリアルでは、MCP Auth をセットアップしてユーザーを認証 (Authentication) し、認可 (Authorization) サーバーからアイデンティティ情報を取得する手順を案内します。 - -このチュートリアルを完了すると、次のことができるようになります： - -- ✅ MCP Auth を使ってユーザーを認証 (Authentication) する基本的な理解 -- ✅ ユーザーのアイデンティティ情報を取得するツールを提供する MCP サーバー - -## 概要 \{#overview} - -このチュートリアルでは、以下のコンポーネントを使用します： - -- **MCP サーバー**：MCP 公式 SDK を使ってリクエストを処理するシンプルな MCP サーバー -- **MCP inspector**：MCP サーバーのためのビジュアルテストツール。OAuth / OIDC クライアントとして認可フローを開始し、アクセス トークン (Access token) を取得する役割も担います。 -- **認可 (Authorization) サーバー**：ユーザーのアイデンティティを管理し、アクセス トークン (Access token) を発行する OAuth 2.1 または OpenID Connect プロバイダー - -これらのコンポーネント間のやり取りを高レベルで示した図です： - -```mermaid -sequenceDiagram - participant Client as MCP Inspector - participant Server as MCP Server - participant Auth as 認可サーバー (Authorization Server) - - Client->>Server: ツール `whoami` をリクエスト - Server->>Client: 401 Unauthorized を返す - Client->>Auth: 認可フローを開始 - Auth->>Auth: 認可フローを完了 - Auth->>Client: 認可コード付きでリダイレクト - Client->>Auth: コードをアクセス トークン (Access token) と交換 - Auth->>Client: アクセス トークン (Access token) を返す - Client->>Server: アクセス トークン (Access token) 付きで `whoami` をリクエスト - Server->>Auth: アクセス トークン (Access token) でユーザー情報を取得 - Auth->>Server: ユーザー情報を返す - Server->>Client: ユーザー情報を返す -``` - -## 認可 (Authorization) サーバーを理解する \{#understand-your-authorization-server} - -### ユーザーのアイデンティティ情報の取得 \{#retrieving-user-identity-information} - -このチュートリアルを完了するには、認可 (Authorization) サーバーがユーザーのアイデンティティ情報を取得するための API を提供している必要があります： - - - - -[Logto](https://logto.io) は OpenID Connect プロバイダーであり、標準の [userinfo エンドポイント](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) をサポートしてユーザーのアイデンティティ情報を取得できます。 - -userinfo エンドポイントにアクセスできるアクセス トークン (Access token) を取得するには、少なくとも `openid` と `profile` の 2 つのスコープ (Scope) が必要です。スコープ (Scope) の設定については後述しますので、そのまま読み進めてください。 - - - - -[Keycloak](https://www.keycloak.org) は、OpenID Connect (OIDC) を含む複数のプロトコルをサポートするオープンソースのアイデンティティおよびアクセス管理ソリューションです。OIDC プロバイダーとして、標準の [userinfo エンドポイント](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) を実装してユーザーのアイデンティティ情報を取得できます。 - -userinfo エンドポイントにアクセスできるアクセス トークン (Access token) を取得するには、少なくとも `openid` と `profile` の 2 つのスコープ (Scope) が必要です。スコープ (Scope) の設定については後述しますので、そのまま読み進めてください。 - - - - -ほとんどの OpenID Connect プロバイダーは、[userinfo エンドポイント](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) をサポートしてユーザーのアイデンティティ情報を取得できます。 - -プロバイダーのドキュメントで、このエンドポイントがサポートされているか確認してください。プロバイダーが [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) をサポートしている場合、`.well-known/openid-configuration` エンドポイントのレスポンスに `userinfo_endpoint` が含まれているかも確認できます。 - -userinfo エンドポイントにアクセスできるアクセス トークン (Access token) を取得するには、少なくとも `openid` と `profile` の 2 つのスコープ (Scope) が必要です。スコープ (Scope) とユーザーアイデンティティクレーム (Claim) の対応は、プロバイダーのドキュメントを参照してください。 - - - - -OAuth 2.0 ではユーザーのアイデンティティ情報を取得する標準的な方法は定義されていませんが、多くのプロバイダーは独自のエンドポイントを実装しています。プロバイダーのドキュメントで、アクセス トークン (Access token) を使ってユーザーのアイデンティティ情報をどのように取得するか、また認可フローでどのパラメーターが必要かを確認してください。 - - - - -### Dynamic Client Registration \{#dynamic-client-registration} - -Dynamic Client Registration はこのチュートリアルでは必須ではありませんが、MCP クライアントの登録プロセスを認可 (Authorization) サーバーと自動化したい場合に便利です。詳細は [Dynamic Client Registration は必要ですか？](/provider-list#is-dcr-required) をご覧ください。 - -## MCP サーバーのセットアップ \{#set-up-the-mcp-server} - -[MCP 公式 SDK](https://github.com/modelcontextprotocol) を使って、認可 (Authorization) サーバーからユーザーのアイデンティティ情報を取得する `whoami` ツール付きの MCP サーバーを作成します。 - -### 新しいプロジェクトの作成 \{#create-a-new-project} - - - - -```bash -mkdir mcp-server -cd mcp-server -uv init # または `pipenv` や `poetry` で仮想環境を作成 -``` - - - - -新しい Node.js プロジェクトをセットアップします： - -```bash -mkdir mcp-server -cd mcp-server -npm init -y # または `pnpm init` -npm pkg set type="module" -npm pkg set main="whoami.js" -npm pkg set scripts.start="node whoami.js" -``` - - - - -### MCP SDK と依存パッケージのインストール \{#install-the-mcp-sdk-and-dependencies} - - - - -```bash -pip install "mcp[cli]" starlette uvicorn -``` - -または `uv` や `poetry` など、お好みのパッケージマネージャーを使用してください。 - - - - -```bash -npm install @modelcontextprotocol/sdk express -``` - -または `pnpm` や `yarn` など、お好みのパッケージマネージャーを使用してください。 - - - - -### MCP サーバーの作成 \{#create-the-mcp-server} - -まず、`whoami` ツールを実装した MCP サーバーを作成します。 - - - - -`whoami.py` というファイルを作成し、次のコードを追加します： - -```python -from mcp.server.fastmcp import FastMCP -from starlette.applications import Starlette -from starlette.routing import Mount -from typing import Any - -mcp = FastMCP("WhoAmI") - -@mcp.tool() -def whoami() -> dict[str, Any]: - """現在のユーザー情報を返すツール""" - return {"error": "Not authenticated"} - -app = Starlette( - routes=[Mount('/', app=mcp.sse_app())] -) -``` - -サーバーを起動します： - -```bash -uvicorn whoami:app --host 0.0.0.0 --port 3001 -``` - - - - -:::note -現時点の MCP inspector 実装では認可 (Authorization) フローを扱えないため、SSE アプローチで MCP サーバーをセットアップします。MCP inspector が認可 (Authorization) フローに対応した際には、ここにコードを更新します。 -::: - -`pnpm` や `yarn` も利用可能です。 - -`whoami.js` というファイルを作成し、次のコードを追加します： - -```js -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; -import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'; -import express from 'express'; - -// MCP サーバーを作成 -const server = new McpServer({ - name: 'WhoAmI', - version: '0.0.0', -}); - -// 現在のユーザー情報を返すツールを追加 -server.tool('whoami', async () => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Not authenticated' }) }], - }; -}); - -// 以下は MCP SDK ドキュメントのボイラープレートコード -const PORT = 3001; -const app = express(); - -const transports = {}; - -app.get('/sse', async (_req, res) => { - const transport = new SSEServerTransport('/messages', res); - transports[transport.sessionId] = transport; - - res.on('close', () => { - delete transports[transport.sessionId]; - }); - - await server.connect(transport); -}); - -app.post('/messages', async (req, res) => { - const sessionId = String(req.query.sessionId); - const transport = transports[sessionId]; - if (transport) { - await transport.handlePostMessage(req, res, req.body); - } else { - res.status(400).send('No transport found for sessionId'); - } -}); - -app.listen(PORT); -``` - -サーバーを起動します： - -```bash -npm start -``` - - - - -## MCP サーバーの検証 \{#inspect-the-mcp-server} - -### MCP inspector のクローンと起動 \{#clone-and-run-mcp-inspector} - -MCP サーバーが起動したので、MCP inspector を使って `whoami` ツールが利用できるか確認します。 - -現状の実装制限のため、[MCP inspector](https://github.com/mcp-auth/inspector) をフォークし、認証 (Authentication)・認可 (Authorization) により柔軟かつ拡張可能にしました。オリジナルリポジトリにもプルリクエストを提出済みです。 - -MCP inspector を起動するには、以下のコマンドを使用します（Node.js が必要です）： - -```bash -git clone https://github.com/mcp-auth/inspector.git -cd inspector -npm install -npm run dev -``` - -その後、ブラウザで `http://localhost:6274/`（またはターミナルに表示された他の URL）にアクセスして MCP inspector を開きます。 - -### MCP inspector を MCP サーバーに接続 \{#connect-mcp-inspector-to-the-mcp-server} - -進む前に、MCP inspector で次の設定を確認してください： - -- **Transport Type**：`SSE` に設定 -- **URL**：MCP サーバーの URL を設定（例：`http://localhost:3001/sse`） - -「Connect」ボタンをクリックして、MCP inspector が MCP サーバーに接続できるか確認します。問題なければ MCP inspector に「Connected」ステータスが表示されます。 - -### チェックポイント: `whoami` ツールの実行 \{#checkpoint-run-the-whoami-tool} - -1. MCP inspector の上部メニューで「Tools」タブをクリック -2. 「List Tools」ボタンをクリック -3. ページに `whoami` ツールが表示されているはずです。クリックして詳細を開きます。 -4. 右側に「Run Tool」ボタンが表示されるのでクリック -5. ツールの結果として `{"error": "Not authenticated"}` という JSON レスポンスが表示されます。 - -![MCP inspector first run](/docs-assets/images/tutorials/whoami/inspector-first-run.png) - -## 認可 (Authorization) サーバーとの連携 \{#integrate-with-your-authorization-server} - -このセクションを完了するには、いくつかの考慮事項があります： - -
-**認可 (Authorization) サーバーの発行者 (Issuer) URL** - -通常は認可 (Authorization) サーバーのベース URL です（例：`https://auth.example.com`）。プロバイダーによっては `https://example.logto.app/oidc` のようなパスが付く場合もあるので、ドキュメントを確認してください。 - -
- -
-**認可 (Authorization) サーバーのメタデータ取得方法** - -- 認可 (Authorization) サーバーが [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) または [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) に準拠していれば、MCP Auth の組み込みユーティリティで自動取得できます。 -- 準拠していない場合は、MCP サーバーの設定でメタデータ URL やエンドポイントを手動指定する必要があります。詳細はプロバイダーのドキュメントを参照してください。 - -
- -
-**MCP inspector を認可 (Authorization) サーバーのクライアントとして登録する方法** - -- 認可 (Authorization) サーバーが [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591) をサポートしていれば、このステップはスキップできます。MCP inspector が自動でクライアント登録します。 -- サポートしていない場合は、MCP inspector を手動でクライアント登録する必要があります。 - -
- -
-**ユーザーのアイデンティティ情報の取得方法と認可リクエストパラメーターの設定方法** - -- OpenID Connect プロバイダーの場合：認可フロー開始時に `openid` と `profile` のスコープ (Scope) をリクエストする必要があります。これにより、認可 (Authorization) サーバーから返されるアクセス トークン (Access token) で [userinfo エンドポイント](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) にアクセスできます。 - - ※ 一部プロバイダーは userinfo エンドポイントをサポートしていない場合があります。 - -- OAuth 2.0 / OAuth 2.1 プロバイダーの場合：アクセス トークン (Access token) でユーザーのアイデンティティ情報を取得する方法や必要なパラメーターはプロバイダーのドキュメントを参照してください。 - -
- -プロバイダーごとに要件は異なりますが、以下の手順で MCP inspector と MCP サーバーをプロバイダー固有の設定で連携できます。 - -### MCP inspector をクライアントとして登録 \{#register-mcp-inspector-as-a-client} - - - - -[Logto](https://logto.io) との連携はシンプルです。OpenID Connect プロバイダーであり、標準の [userinfo エンドポイント](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) をサポートしています。 - -Logto は Dynamic Client Registration をまだサポートしていないため、MCP inspector を Logto テナントのクライアントとして手動登録する必要があります： - -1. MCP inspector を開き、「OAuth Configuration」ボタンをクリック。**Redirect URL (auto-populated)** の値（例：`http://localhost:6274/oauth/callback`）をコピー -2. [Logto Console](https://cloud.logto.io)（またはセルフホスト Logto Console）にサインイン -3. 「Applications」タブで「Create application」をクリック。ページ下部で「Create app without framework」をクリック -4. アプリケーション詳細を入力し、「Create application」をクリック： - - **Select an application type**：「Single-page application」を選択 - - **Application name**：例「MCP Inspector」など任意の名前 -5. 「Settings / Redirect URIs」セクションで、先ほどコピーした **Redirect URL (auto-populated)** を貼り付け、「Save changes」をクリック -6. 上部カードに「App ID」が表示されるのでコピー -7. MCP inspector に戻り、「OAuth Configuration」の「Client ID」欄に「App ID」を貼り付け -8. 「Auth Params」欄に `{"scope": "openid profile email"}` を入力。これで Logto から返されるアクセス トークン (Access token) に必要なスコープ (Scope) が含まれます。 - - - - -[Keycloak](https://www.keycloak.org) は OpenID Connect プロトコルをサポートするオープンソースのアイデンティティ・アクセス管理ソリューションです。 - -Keycloak は Dynamic Client Registration をサポートしていますが、クライアント登録エンドポイントが CORS に対応していないため、ほとんどの MCP クライアントは直接登録できません。そのため、手動でクライアント登録が必要です。 - -:::note -Keycloak は [さまざまな方法](https://www.keycloak.org/guides#getting-started)（ベアメタル、kubernetes など）でインストールできますが、このチュートリアルでは Docker を使って簡単にセットアップします。 -::: - -Keycloak インスタンスをセットアップし、必要な設定を行います： - -1. まず、[公式ドキュメント](https://www.keycloak.org/getting-started/getting-started-docker) に従い Docker で Keycloak を起動： - -```bash -docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.2.4 start-dev -``` - -2. Keycloak Admin Console（http://localhost:8080/admin）にアクセスし、以下でログイン： - - - ユーザー名: `admin` - - パスワード: `admin` - -3. 新しい Realm を作成： - - - 左上の「Create Realm」をクリック - - 「Realm name」に `mcp-realm` を入力 - - 「Create」をクリック - -4. テストユーザーを作成： - - - 左メニューの「Users」をクリック - - 「Create new user」をクリック - - ユーザー詳細を入力（ユーザー名: `testuser`、名・姓は任意） - - 「Create」をクリック - - 「Credentials」タブでパスワードを設定し、「Temporary」をオフ - -5. MCP Inspector をクライアントとして登録： - - - MCP inspector を開き、「OAuth Configuration」ボタンをクリック。**Redirect URL (auto-populated)**（例：`http://localhost:6274/oauth/callback`）をコピー - - Keycloak Admin Console で左メニューの「Clients」をクリック - - 「Create client」をクリック - - クライアント詳細を入力： - - Client type: 「OpenID Connect」を選択 - - Client ID: `mcp-inspector` を入力 - - 「Next」をクリック - - 「Capability config」ページで「Standard flow」が有効になっていることを確認し、「Next」 - - 「Login settings」ページで、先ほどコピーした MCP Inspector のコールバック URL を「Valid redirect URIs」に貼り付け - - 「Web origins」に `http://localhost:6274` を入力 - - 「Save」をクリック - - 「Client ID」（`mcp-inspector`）をコピー - -6. MCP Inspector に戻り： - - コピーした Client ID を「OAuth Configuration」の「Client ID」欄に貼り付け - - 「Auth Params」欄に以下を入力して必要なスコープ (Scope) をリクエスト： - -```json -{ "scope": "openid profile email" } -``` - - - - -:::note -これは汎用的な OpenID Connect プロバイダー連携ガイドです。詳細はプロバイダーのドキュメントを参照してください。 -::: - -OpenID Connect プロバイダーが Dynamic Client Registration をサポートしていれば、下記 8 の設定に進んで MCP inspector を設定できます。サポートしていない場合は、手動で MCP inspector をクライアント登録する必要があります： - -1. MCP inspector を開き、「OAuth Configuration」ボタンをクリック。**Redirect URL (auto-populated)**（例：`http://localhost:6274/oauth/callback`）をコピー -2. OpenID Connect プロバイダーのコンソールにサインイン -3. 「Applications」または「Clients」セクションで新しいアプリケーションまたはクライアントを作成 -4. クライアントタイプが必要な場合は「Single-page application」または「Public client」を選択 -5. アプリケーション作成後、リダイレクト URI を設定。コピーした **Redirect URL (auto-populated)** を貼り付け -6. 新規アプリケーションの「Client ID」または「Application ID」をコピー -7. MCP inspector に戻り、「OAuth Configuration」の「Client ID」欄に貼り付け -8. 標準的な OpenID Connect プロバイダーの場合、userinfo エンドポイントにアクセスするために必要なスコープ (Scope) をリクエストするには「Auth Params」欄に以下を入力： - -```json -{ "scope": "openid profile email" } -``` - - - - -:::note -これは汎用的な OAuth 2.0 / OAuth 2.1 プロバイダー連携ガイドです。詳細はプロバイダーのドキュメントを参照してください。 -::: - -OAuth 2.0 / OAuth 2.1 プロバイダーが Dynamic Client Registration をサポートしていれば、下記 8 の設定に進んで MCP inspector を設定できます。サポートしていない場合は、手動で MCP inspector をクライアント登録する必要があります： - -1. MCP inspector を開き、「OAuth Configuration」ボタンをクリック。**Redirect URL (auto-populated)**（例：`http://localhost:6274/oauth/callback`）をコピー -2. OAuth 2.0 / OAuth 2.1 プロバイダーのコンソールにサインイン -3. 「Applications」または「Clients」セクションで新しいアプリケーションまたはクライアントを作成 -4. クライアントタイプが必要な場合は「Single-page application」または「Public client」を選択 -5. アプリケーション作成後、リダイレクト URI を設定。コピーした **Redirect URL (auto-populated)** を貼り付け -6. 新規アプリケーションの「Client ID」または「Application ID」をコピー -7. MCP inspector に戻り、「OAuth Configuration」の「Client ID」欄に貼り付け -8. アクセス トークン (Access token) でユーザーのアイデンティティ情報を取得する方法や必要なスコープ (Scope)・パラメーターはプロバイダーのドキュメントを参照してください。例えば、`profile` スコープ (Scope) が必要な場合は「Auth Params」欄に以下を入力： - -```json -{ "scope": "profile" } -``` - - - - -### MCP auth のセットアップ \{#set-up-mcp-auth} - -MCP サーバープロジェクトで MCP Auth SDK をインストールし、認可 (Authorization) サーバーのメタデータを使うように設定します。 - - - - -まず `mcpauth` パッケージをインストール： - -```bash -pip install mcpauth -``` - -または `uv` や `poetry` など、お好みのパッケージマネージャーを使用してください。 - - - - -まず `mcp-auth` パッケージをインストール： - -```bash -npm install mcp-auth -``` - - - - -MCP Auth は初期化のために認可 (Authorization) サーバーのメタデータが必要です。プロバイダーごとに設定方法が異なります： - - - - - -発行者 (Issuer) URL は Logto Console のアプリケーション詳細ページ「Endpoints & Credentials / Issuer endpoint」セクションで確認できます。例：`https://my-project.logto.app/oidc` - - - - - - - -発行者 (Issuer) URL は Keycloak Admin Console の「mcp-realm」内、「Realm settings / Endpoints」セクションの「OpenID Endpoint Configuration」リンクで確認できます。JSON ドキュメントの `issuer` フィールドが発行者 (Issuer) URL です（例：`http://localhost:8080/realms/mcp-realm`）。 - - - - - - - -以下のコードは、認可 (Authorization) サーバーが [userinfo エンドポイント](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) をサポートしていることを前提としています。サポートしていない場合は、プロバイダーのドキュメントで該当エンドポイントを確認し、userinfo エンドポイント変数を正しい URL に置き換えてください。 - - - - - - -前述の通り、OAuth 2.0 ではユーザーのアイデンティティ情報を取得する標準的な方法は定義されていません。以下のコードは、プロバイダーがアクセス トークン (Access token) でユーザーのアイデンティティ情報を取得できる独自エンドポイントを持っていることを前提としています。プロバイダーのドキュメントで該当エンドポイントを確認し、userinfo エンドポイント変数を正しい URL に置き換えてください。 - - - - - - -### MCP サーバーの更新 \{#update-mcp-server} - -あと少しです！MCP Auth のルートとミドルウェア関数を適用し、`whoami` ツールが実際のユーザーアイデンティティ情報を返すよう MCP サーバーを更新します。 - - - - -```python -@mcp.tool() -def whoami() -> dict[str, Any]: - """現在のユーザー情報を返すツール""" - return ( - mcp_auth.auth_info.claims - if mcp_auth.auth_info # Bearer auth ミドルウェアでセットされます - else {"error": "Not authenticated"} - ) - -# ... - -bearer_auth = Middleware(mcp_auth.bearer_auth_middleware(verify_access_token)) -app = Starlette( - routes=[ - # メタデータルート（`/.well-known/oauth-authorization-server`）を追加 - mcp_auth.metadata_route(), - # Bearer auth ミドルウェアで MCP サーバーを保護 - Mount('/', app=mcp.sse_app(), middleware=[bearer_auth]), - ], -) -``` - - - - -```js -server.tool('whoami', ({ authInfo }) => { - return { - content: [ - { type: 'text', text: JSON.stringify(authInfo?.claims ?? { error: 'Not authenticated' }) }, - ], - }; -}); - -// ... - -app.use(mcpAuth.delegatedRouter()); -app.use(mcpAuth.bearerAuth(verifyToken)); -``` - - - - -## チェックポイント: 認証 (Authentication) 付きで `whoami` ツールを実行 \{#checkpoint-run-the-whoami-tool-with-authentication} - -MCP サーバーを再起動し、ブラウザで MCP inspector を開きます。「Connect」ボタンをクリックすると、認可 (Authorization) サーバーのサインインページにリダイレクトされます。 - -サインイン後 MCP inspector に戻り、前回と同じ手順で `whoami` ツールを実行してください。今回は認可 (Authorization) サーバーから返されたユーザーのアイデンティティ情報が表示されるはずです。 - -![MCP inspector whoami tool result](/docs-assets/images/tutorials/whoami/result.png) - - - - -:::info -[MCP Auth Python SDK リポジトリ](https://github.com/mcp-auth/python/blob/master/samples/server/whoami.py) で MCP サーバー（OIDC 版）の完全なコードを確認できます。 -::: - - - - -:::info -[MCP Auth Node.js SDK リポジトリ](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) で MCP サーバー（OIDC 版）の完全なコードを確認できます。このディレクトリには TypeScript 版と JavaScript 版の両方が含まれています。 -::: - - - - -## 締めくくり \{#closing-notes} - -🎊 おめでとうございます！チュートリアルを無事完了しました。ここまでの内容を振り返りましょう： - -- `whoami` ツール付きの基本的な MCP サーバーのセットアップ -- MCP Auth を使った MCP サーバーと認可 (Authorization) サーバーの連携 -- MCP Inspector でユーザー認証 (Authentication) とアイデンティティ情報の取得 - -さらに発展的なトピックとして、以下もぜひご検討ください： - -- [JWT (JSON Web Token)](https://auth.wiki/jwt) を使った認証 (Authentication)・認可 (Authorization) -- [リソースインジケーター (RFC 8707)](https://auth-wiki.logto.io/resource-indicator) を活用したアクセスリソースの指定 -- [ロールベースのアクセス制御 (RBAC)](https://auth.wiki/rbac) や [属性ベースのアクセス制御 (ABAC)](https://auth.wiki/abac) などのカスタムアクセス制御の実装 - -他のチュートリアルやドキュメントもぜひご覧いただき、MCP Auth を最大限に活用してください。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_manual-metadata-fetching.mdx b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_manual-metadata-fetching.mdx deleted file mode 100644 index 340a89b..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_manual-metadata-fetching.mdx +++ /dev/null @@ -1,3 +0,0 @@ -:::note -プロバイダーが {props.oidc ? 'OpenID Connect Discovery' : 'OAuth 2.0 Authorization Server Metadata'} をサポートしていない場合、メタデータ URL またはエンドポイントを手動で指定できます。詳細は [MCP Auth を初期化するその他の方法](../../configure-server/mcp-auth.mdx#other-ways) をご確認ください。 -::: \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oauth.mdx b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oauth.mdx deleted file mode 100644 index 4bfa978..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oauth.mdx +++ /dev/null @@ -1,141 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -`whoami.py` を更新して MCP Auth の設定を追加します： - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # 発行者エンドポイントに置き換えてください -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OAUTH) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -`whoami.js` を更新して MCP Auth の設定を追加します： - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // 発行者エンドポイントに置き換えてください -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oauth' }), -}); -``` - - - - - - - -次に、MCP インスペクターから提供されたアクセス トークン (Access token) を使用して認可サーバーからユーザーのアイデンティティ情報を取得するカスタム アクセス トークン (Access token) 検証関数を作成する必要があります。 - - - - -```python -import pydantic -import requests -from mcpauth.exceptions import ( - MCPAuthTokenVerificationException, - MCPAuthTokenVerificationExceptionCode, -) -from mcpauth.types import AuthInfo - -def verify_access_token(token: str) -> AuthInfo: - """ - 提供された Bearer トークンを認可サーバーからユーザー情報を取得することで検証します。 - トークンが有効な場合、ユーザー情報を含む `AuthInfo` オブジェクトを返します。 - - :param token: MCP インスペクターから受け取った Bearer トークン。 - """ - - try: - # 以下のコードは、認可サーバーがアクセス トークン (Access token) を使って - # ユーザー情報を取得するエンドポイントを持っていることを前提としています。 - # プロバイダーの API に応じて URL やヘッダーを調整してください。 - response = requests.get( - "https://your-authorization-server.com/userinfo", - headers={"Authorization": f"Bearer {token}"}, - ) - response.raise_for_status() # HTTP エラー時に例外を発生させます - json = response.json() # JSON レスポンスをパースします - - # 以下のコードは、ユーザー情報レスポンスがユーザーを識別する 'sub' フィールドを - # 含むオブジェクトであることを前提としています。プロバイダーの API に応じて調整してください。 - return AuthInfo( - token=token, - subject=json.get("sub"), - issuer=auth_issuer, # 設定済みの発行者 (Issuer) を使用 - claims=json, # エンドポイントから返されたすべてのクレーム (Claims)（JSON フィールド）を含めます - ) - # `AuthInfo` は Pydantic モデルなので、バリデーションエラーは通常レスポンスが - # 期待される構造と一致しなかったことを意味します - except pydantic.ValidationError as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.INVALID_TOKEN, - cause=e, - ) - # リクエスト中に発生するその他の例外を処理します - except Exception as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.TOKEN_VERIFICATION_FAILED, - cause=e, - ) -``` - - - - -```js -import { MCPAuthTokenVerificationError } from 'mcp-auth'; - -/** - * 提供された Bearer トークンを認可サーバーからユーザー情報を取得することで検証します。 - * トークンが有効な場合、ユーザー情報を含む `AuthInfo` オブジェクトを返します。 - */ -const verifyToken = async (token) => { - // 以下のコードは、認可サーバーがアクセス トークン (Access token) を使って - // ユーザー情報を取得するエンドポイントを持っていることを前提としています。 - // プロバイダーの API に応じて URL やヘッダーを調整してください。 - const response = await fetch('https://your-authorization-server.com/userinfo', { - headers: { Authorization: `Bearer ${token}` }, - }); - - if (!response.ok) { - throw new MCPAuthTokenVerificationError('token_verification_failed', response); - } - - const userInfo = await response.json(); - - // 以下のコードは、ユーザー情報レスポンスがユーザーを識別する 'sub' フィールドを - // 含むオブジェクトであることを前提としています。プロバイダーの API に応じて調整してください。 - if (typeof userInfo !== 'object' || userInfo === null || !('sub' in userInfo)) { - throw new MCPAuthTokenVerificationError('invalid_token', response); - } - - return { - token, - issuer: authIssuer, - subject: String(userInfo.sub), // プロバイダーのユーザー ID フィールドに応じて調整してください - clientId: '', // この例ではクライアント ID は使用しませんが、必要に応じて設定可能です - scopes: [], - claims: userInfo, - }; -}; -``` - - - diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oidc.mdx b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oidc.mdx deleted file mode 100644 index 783641a..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oidc.mdx +++ /dev/null @@ -1,142 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -`whoami.py` を更新して MCP Auth の設定を追加します： - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # 発行者エンドポイントに置き換えてください -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -`whoami.js` を更新して MCP Auth の設定を追加します： - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // 発行者エンドポイントに置き換えてください -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oidc' }), -}); -``` - - - - -{props.showAlternative && } -{props.showAlternative && } - -次に、MCP インスペクターから提供されたアクセス トークン (Access token) を使用して認可サーバーからユーザーのアイデンティティ情報を取得するカスタム アクセス トークン (Access token) 検証関数を作成します。 - - - - -```python -import pydantic -import requests -from mcpauth.exceptions import ( - MCPAuthTokenVerificationException, - MCPAuthTokenVerificationExceptionCode, -) -from mcpauth.types import AuthInfo - -def verify_access_token(token: str) -> AuthInfo: - """ - 提供された Bearer トークンを認可サーバーからユーザー情報を取得して検証します。 - トークンが有効な場合、ユーザー情報を含む `AuthInfo` オブジェクトを返します。 - - :param token: MCP インスペクターから受け取った Bearer トークン。 - """ - - issuer = auth_server_config.metadata.issuer - endpoint = auth_server_config.metadata.userinfo_endpoint # プロバイダーは userinfo エンドポイントをサポートしている必要があります - if not endpoint: - raise ValueError( - "Userinfo エンドポイントが認証サーバーメタデータに設定されていません。" - ) - - try: - response = requests.get( - endpoint, - headers={"Authorization": f"Bearer {token}"}, # 標準の Bearer トークンヘッダー - ) - response.raise_for_status() # HTTP エラーの場合は例外を発生させる - json = response.json() # JSON レスポンスをパース - return AuthInfo( - token=token, - subject=json.get("sub"), # 'sub' はサブジェクト（ユーザー ID）の標準クレーム - issuer=issuer, # メタデータから発行者を使用 - claims=json, # userinfo エンドポイントから返されたすべてのクレーム (Claims)（JSON フィールド）を含める - ) - # `AuthInfo` は Pydantic モデルなので、バリデーションエラーは通常レスポンスが期待された構造と一致しない場合に発生します - except pydantic.ValidationError as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.INVALID_TOKEN, - cause=e, - ) - # リクエスト中に発生するその他の例外を処理 - except Exception as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.TOKEN_VERIFICATION_FAILED, - cause=e, - ) -``` - - - - -```js -import { MCPAuthTokenVerificationError } from 'mcp-auth'; - -/** - * 提供された Bearer トークンを認可サーバーからユーザー情報を取得して検証します。 - * トークンが有効な場合、ユーザー情報を含む `AuthInfo` オブジェクトを返します。 - */ -const verifyToken = async (token) => { - const { issuer, userinfoEndpoint } = mcpAuth.config.server.metadata; - - if (!userinfoEndpoint) { - throw new Error('Userinfo エンドポイントがサーバーメタデータに設定されていません'); - } - - const response = await fetch(userinfoEndpoint, { - headers: { Authorization: `Bearer ${token}` }, - }); - - if (!response.ok) { - throw new MCPAuthTokenVerificationError('token_verification_failed', response); - } - - const userInfo = await response.json(); - - if (typeof userInfo !== 'object' || userInfo === null || !('sub' in userInfo)) { - throw new MCPAuthTokenVerificationError('invalid_token', response); - } - - return { - token, - issuer, - subject: String(userInfo.sub), // 'sub' はサブジェクト（ユーザー ID）の標準クレーム - clientId: '', // この例ではクライアント ID は使用しませんが、必要に応じて設定可能 - scopes: [], - claims: userInfo, - }; -}; -``` - - - diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_transpile-metadata.mdx b/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_transpile-metadata.mdx deleted file mode 100644 index c4ff063..0000000 --- a/i18n/ja/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_transpile-metadata.mdx +++ /dev/null @@ -1,31 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -場合によっては、プロバイダーからのレスポンスが不正であったり、期待されるメタデータ形式に準拠していないことがあります。プロバイダーが準拠していると確信できる場合は、設定オプションを使ってメタデータをトランスパイルできます： - - - - -```python -mcp_auth = MCPAuth( - server=fetch_server_config( - # ...other options - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { - // ...other options - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1.json b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1.json deleted file mode 100644 index 47cfa53..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1.json +++ /dev/null @@ -1,50 +0,0 @@ -{ - "sidebar.docsSidebar.category.Tutorials": { - "message": "튜토리얼", - "description": "The label for category Tutorials in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.Tutorials.link.generated-index.title": { - "message": "튜토리얼", - "description": "The generated-index page title for category Tutorials in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.Configure MCP server": { - "message": "MCP 서버 구성", - "description": "The label for category Configure MCP server in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.Configure MCP server.link.generated-index.title": { - "message": "MCP 서버 구성", - "description": "The generated-index page title for category Configure MCP server in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.SDK references": { - "message": "SDK 참조", - "description": "The label for category SDK references in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.SDK references.link.generated-index.title": { - "message": "MCP Auth SDK 참조", - "description": "The generated-index page title for category SDK references in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.SDK references.link.generated-index.description": { - "message": "MCP Auth SDK에서 추출된 클래스, 메서드, 속성에 대한 정보.\n", - "description": "The generated-index page description for category SDK references in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.Node.js SDK": { - "message": "Node.js SDK", - "description": "The label for category Node.js SDK in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.classes": { - "message": "클래스", - "description": "The label for category classes in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.functions": { - "message": "함수", - "description": "The label for category functions in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.type-aliases": { - "message": "타입 별칭", - "description": "The label for category type-aliases in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.variables": { - "message": "변수", - "description": "The label for category variables in sidebar docsSidebar" - } -} diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/README.mdx b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/README.mdx deleted file mode 100644 index a10c9b4..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/README.mdx +++ /dev/null @@ -1,242 +0,0 @@ ---- -sidebar_position: 1 -sidebar_label: 시작하기 ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -# 시작하기 - -## 호환되는 OAuth 2.1 또는 OpenID Connect 공급자 선택하기 \{#choose-a-compatible-oauth-2-1-or-openid-connect-provider} - -MCP 명세는 인가 (Authorization)에 대해 몇 가지 [특정 요구사항](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization#1-3-standards-compliance)이 있습니다: - -- [OAuth 2.1 IETF DRAFT](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12) -- OAuth 2.0 인가 서버 메타데이터 ([RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)) -- OAuth 2.0 동적 클라이언트 등록 프로토콜 ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) - -마지막 두 가지는 필수는 아니지만, 첫 번째는 안전하고 규격에 맞는 구현을 위해 반드시 필요합니다. - -:::note -새로운 MCP 초안에서는 RFC 8414가 인가 서버(공급자)에서 필수로 요구됩니다. 새로운 초안이 확정되면 문서를 업데이트하겠습니다. -::: - -[호환되는 MCP 공급자 목록](/provider-list)을 확인하여 사용 중인 공급자가 지원되는지 확인하세요. - -## MCP Auth SDK 설치하기 \{#install-mcp-auth-sdk} - -MCP Auth는 Python과 TypeScript 모두에서 사용할 수 있습니다. 다른 언어나 프레임워크 지원이 필요하다면 알려주세요! - - - - -```bash -pip install mcpauth -``` - -또는 pipenv, poetry 등 선호하는 패키지 매니저를 사용할 수 있습니다. - - - - -```bash -npm install mcp-auth -``` - -또는 pnpm, yarn 등 선호하는 패키지 매니저를 사용할 수 있습니다. - - - - -## MCP Auth 초기화하기 \{#init-mcp-auth} - -첫 번째 단계는 공급자의 인가 서버 메타데이터로 MCP Auth 인스턴스를 초기화하는 것입니다. 만약 공급자가 다음 중 하나를 준수한다면: - -- [OAuth 2.0 인가 서버 메타데이터](https://datatracker.ietf.org/doc/html/rfc8414) -- [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) - -내장 함수를 사용하여 메타데이터를 가져오고 MCP Auth 인스턴스를 초기화할 수 있습니다: - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -mcp_auth = MCPAuth( - server=fetch_server_config( - '', - type=AuthServerType.OIDC # 또는 AuthServerType.OAUTH - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { type: 'oidc' }), // 또는 'oauth' -}); -``` - - - - -메타데이터 URL 또는 엔드포인트를 수동으로 지정해야 하는 경우, [MCP Auth 초기화의 다른 방법](./configure-server/mcp-auth.mdx#other-ways)을 확인하세요. - -## 메타데이터 엔드포인트 마운트하기 \{#mount-the-metadata-endpoint} - -현재 MCP 명세를 준수하기 위해, MCP Auth는 OAuth 2.0 인가 서버 메타데이터 엔드포인트(`/.well-known/oauth-authorization-server`)를 MCP 서버에 마운트합니다: - - - - -```python -from starlette.applications import Starlette - -app = Starlette(routes=[ - mcp_auth.metadata_route(), -]) -``` - - - - -```ts -import express from 'express'; - -const app = express(); -app.use(mcpAuth.delegatedRouter()); -``` - - - - -메타데이터 내의 URL은 그대로 유지되므로, 인가 서버의 역할은 전적으로 공급자에게 위임됩니다. MCP 서버에서 `/.well-known/oauth-authorization-server`에 접속하여 메타데이터 엔드포인트를 테스트할 수 있습니다. - -### 왜 메타데이터 엔드포인트만 마운트하나요? \{#why-only-the-metadata-endpoint} - -공식 SDK에서는 `/authorize`, `/token` 등 인가 엔드포인트를 마운트하는 인증 라우터를 제공하는 경우가 있습니다. 저희가 그렇게 하지 않는 이유는 다음과 같습니다: - -1. 메타데이터 엔드포인트만 마운트하면, "바퀴를 다시 발명"하지 않고 공급자의 모든 기능을 최대한 활용할 수 있으며, MCP 서버에 불필요한 복잡성을 추가하지 않습니다. -2. 또한 [MCP 서버의 역할을 리소스 서버로 전환](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/205)하고 OAuth 2.0 보호 리소스 메타데이터 ([RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728))를 요구하는 작업이 진행 중입니다. 이는 MCP 서버가 **더 이상 인가 로직(메타데이터 엔드포인트 포함)을 처리하지 않고**, 오직 공급자에 의존하여 인증 (Authentication) 및 인가 (Authorization)를 수행하는 리소스 서버로만 동작하게 됨을 의미합니다. - -:::note -새로운 MCP 명세가 확정되면 MCP Auth도 이에 맞게 업데이트할 예정입니다. 그때까지는 현재 명세와 호환되는 버전을 사용하실 수 있습니다. -::: - -## Bearer 인증 미들웨어 사용하기 \{#use-the-bearer-auth-middleware} - -MCP Auth 인스턴스가 초기화되면, Bearer 인증 미들웨어를 적용하여 MCP 라우트를 보호할 수 있습니다: - - - - -```python -from starlette.applications import Starlette -from starlette.middleware import Middleware -from starlette.routing import Mount -from mcpauth import MCPAuth -from mcp.server.fastmcp import FastMCP - -mcp = FastMCP() -mcp_auth = MCPAuth( - # 인증 서버 설정으로 초기화 -) -bearer_auth = mcp_auth.bearer_auth_middleware( - "jwt", required_scopes=["read", "write"] -) - -app = Starlette(routes=[ - mcp_auth.metadata_route(), - Mount( - "/", - app=mcp.sse_app(), - middleware=[Middleware(bearer_auth)], - ), -]) -``` - - - - -```ts -import express from 'express'; -import { MCPAuth } from 'mcp-auth'; - -const app = express(); -const server = new McpServer(/* ... */); -const mcpAuth = new MCPAuth({ - /* ... */ -}); - -app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] })); -``` - - - - -위 예시에서는 `jwt` 토큰 타입을 지정하고, `read` 및 `write` 스코프를 요구했습니다. JWT (JSON Web Token)를 자동으로 검증하고, 인증된 사용자 정보를 포함한 객체를 채워줍니다. - -:::info -JWT (JSON Web Token)에 대해 처음 들어보시나요? 걱정하지 마세요. 문서를 계속 읽으시면 필요할 때 설명해 드립니다. 빠른 소개가 필요하다면 [Auth Wiki](https://auth.wiki/jwt)를 참고하세요. -::: - -Bearer 인증 설정에 대한 자세한 내용은 [Bearer 인증 구성하기](./configure-server/bearer-auth.mdx)를 참고하세요. - -## MCP 구현에서 인증 정보 가져오기 \{#retrieve-the-auth-info-in-your-mcp-implementation} - -Bearer 인증 미들웨어가 적용되면, MCP 구현 내에서 인증된 사용자(또는 아이덴티티)의 정보를 접근할 수 있습니다: - - - - -Bearer 인증 미들웨어가 적용된 후, MCP Auth는 인증된 사용자 정보를 컨텍스트 변수에 저장합니다. MCP 도구 핸들러에서 다음과 같이 접근할 수 있습니다: - -```python -from mcp.server.fastmcp import FastMCP - -mcp = FastMCP() -mcp_auth = MCPAuth( - # 인증 서버 설정으로 초기화 -) - -@mcp.tool() -def add(a: int, b: int): - """ - 두 숫자를 더하는 도구입니다. - 인증된 사용자 정보는 컨텍스트에서 사용할 수 있습니다. - """ - auth_info = mcp_auth.auth_info # 현재 컨텍스트에서 인증 정보 접근 - if auth_info: - print(f"Authenticated user: {auth_info.claims}") - return a + b -``` - - - - -도구 핸들러의 두 번째 인자는 인증된 사용자 정보를 포함하는 `authInfo` 객체를 포함합니다: - -```ts -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; -import { z } from 'zod'; - -const server = new McpServer(/* ... */); -server.tool('add', { a: z.number(), b: z.number() }, async ({ a, b }, { authInfo }) => { - // 이제 `authInfo` 객체를 사용하여 인증된 정보를 접근할 수 있습니다 -}); -``` - - - - -## 다음 단계 \{#next-steps} - -계속 읽으면서 MCP Auth를 MCP 서버와 통합하는 방법과 MCP 클라이언트에서 인증 플로우를 처리하는 방법에 대한 엔드 투 엔드 예제를 확인하세요. diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/comparison.mdx b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/comparison.mdx deleted file mode 100644 index 1c4f325..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/comparison.mdx +++ /dev/null @@ -1,80 +0,0 @@ ---- -sidebar_position: 101 -sidebar_label: 비교 ---- - -# MCP Auth와 기타 솔루션 중 선택하기 - -MCP 생태계는 진화하고 있습니다. Model Context Protocol (MCP) 명세가 “인가 서버” 방식에서 새로운 “리소스 서버 + 서드파티 아이덴티티 제공자 (IdP)” 모델로 이동함에 따라, 다양한 통합 솔루션이 현재와 미래에 어떻게 적합한지 이해하는 것이 중요합니다. - -이 페이지에서는 mcp-auth와 다른 인기 있는 솔루션 간의 주요 차이점을 정리하여, 프로젝트에 가장 적합한 접근 방식을 선택할 수 있도록 돕습니다. - -## 배경: 프록시 방식 vs. IdP 통합 \{#background-proxy-approach-vs-idp-integration} - -대부분의 기존 MCP 인증 (Authentication) 솔루션은 “프록시 방식”을 사용합니다. 이 모델에서 MCP 서버는 인가 (Authorization) 요청을 서드파티 아이덴티티 제공자 (IdP)로 프록시하여, 클라이언트와 IdP 사이의 중개자 역할을 합니다. - -**프록시 방식 ([03-26 명세](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization))** - -```mermaid -sequenceDiagram - participant Client - participant MCP_Server as MCP 서버 - participant ThirdParty_IdP as 서드파티 IdP - - Client->>MCP_Server: 인가 (Authorization) 요청 - MCP_Server->>ThirdParty_IdP: 요청 프록시 - ThirdParty_IdP->>MCP_Server: 응답 - MCP_Server->>Client: 응답 - Client->>MCP_Server: 리소스 접근 - alt 원격 검증 - MCP_Server->>ThirdParty_IdP: 토큰 검증 - ThirdParty_IdP->>MCP_Server: 토큰 유효 - else 로컬 검증 - MCP_Server->>MCP_Server: 로컬에서 토큰 검증 (예: 캐시된 JWK) - end - MCP_Server->>Client: 리소스 데이터 -``` - -이 방식은 현재 (2025-03-26) MCP 명세와 호환되지만, 본질적으로 우회 방법입니다. MCP 서버가 인가 (Authorization) 서버 역할도 한다는 전제에 기반하며, 이는 최신 초안 명세의 방향과는 다릅니다. - -**MCP Auth / 미래 명세 (리소스 서버 + 서드파티 IdP)** - -```mermaid -sequenceDiagram - participant Client - participant MCP_Server as MCP 서버 - participant ThirdParty_IdP as 서드파티 IdP - - Client->>ThirdParty_IdP: 인가 (Authorization) 요청 - ThirdParty_IdP->>Client: 토큰 - Client->>MCP_Server: 리소스 접근 (토큰 포함) - alt 원격 검증 - MCP_Server->>ThirdParty_IdP: 토큰 검증 - ThirdParty_IdP->>MCP_Server: 토큰 유효 - else 로컬 검증 - MCP_Server->>MCP_Server: 로컬에서 토큰 검증 (예: 캐시된 JWK) - end - MCP_Server->>Client: 리소스 데이터 -``` - -다가오는 MCP 명세는 [인가 (Authorization) 책임을 전담 서드파티 IdP로 이전합니다](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/205). 이 모델에서 MCP 서버는 오직 리소스 서버 역할만 하며, 모든 인가 (Authorization) 엔드포인트는 서드파티 IdP에서 직접 제공합니다. - -## 왜 MCP Auth를 선택해야 할까요? \{#why-choose-mcp-auth} - -- 명세 일치: MCP Auth는 최신 초안의 방향을 직접 따르므로, 03-26 명세와 다가오는 명세 모두와 호환되는 유일한 솔루션입니다. -- 더 이상 우회 없음: 인가 (Authorization) 서버 프록시 역할 대신, MCP Auth는 새로운 명세 의도대로 모든 인가 (Authorization)을 서드파티 IdP가 처리하도록 합니다. -- 공급자 무관: MCP Auth는 표준을 준수하는 모든 OAuth 2.0 / OIDC 공급자와 함께 작동합니다. -- 원활한 전환: MCP Auth는 모든 서드파티 엔드포인트를 OAuth 2.0 인가 (Authorization) 서버 메타데이터를 통해 그대로 반환합니다. 덕분에 현재 통합이 간단하고, 미래 변화에도 준비되어 있습니다. -- 개발자 경험: 튜토리얼, 유틸리티, 그리고 [OAuth 2.0 보호 리소스 메타데이터](https://auth.wiki/protected-resource-metadata)와 같은 향후 기능을 제공하여 MCP 서버 개발자의 삶을 더 쉽게 만듭니다. - -| 기능 | 프록시 솔루션 | MCP Auth | -| ------------------------------------ | --------------------- | -------- | -| 03-26 명세 지원 | ✅ | ✅ | -| 미래 명세 지원 | ❌ | ✅ | -| 서드파티 IdP 직접 지원 | ❌ (우회만 가능) | ✅ | -| 공급자 무관 | 제한적[^1] | 예 | -| 전환 준비 | ❌ | ✅ | - -지금 서드파티 IdP 지원이 필요하고, 다가오는 명세에도 대비하고 싶다면 MCP Auth가 권장 솔루션입니다. 프록시 기반 접근 방식은 곧 사용 중단되거나 대대적인 재작업이 필요할 수 있습니다. - -[^1]: 일부 프록시 솔루션은 특정 파라미터나 엔드포인트를 하드코딩하여 유연성이 제한될 수 있습니다. diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/configure-server/bearer-auth.mdx b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/configure-server/bearer-auth.mdx deleted file mode 100644 index a858a12..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/configure-server/bearer-auth.mdx +++ /dev/null @@ -1,250 +0,0 @@ ---- -sidebar_position: 2 -sidebar_label: Bearer auth ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -# MCP 서버에서 Bearer 인증 (Authentication) 구성하기 - -MCP Auth는 MCP 서버에서 Bearer 인가 (Authorization)를 구성하는 다양한 방법을 제공합니다: - -- [JWT (JSON Web Token)](https://auth.wiki/jwt) 모드: 클레임 (Claim) 검증을 통해 JWT를 검증하는 내장 인가 (Authorization) 방식입니다. -- 커스텀 모드: 직접 인가 (Authorization) 로직을 구현할 수 있습니다. - -## JWT 모드로 Bearer 인증 (Authentication) 구성하기 \{#configure-bearer-auth-with-jwt-mode} - -OAuth / OIDC 제공자가 인가 (Authorization)를 위해 JWT를 발급한다면, MCP Auth의 내장 JWT 모드를 사용할 수 있습니다. 이 모드는 JWT 서명, 만료, 그리고 지정한 기타 클레임 (Claim)을 검증합니다. 이후 인증 (Authentication) 정보를 요청 컨텍스트에 채워 MCP 구현에서 추가 처리를 할 수 있도록 합니다. - -### 스코프 (Scope) 검증 \{#scope-validation} - -다음은 기본적인 스코프 (Scope) 검증 예시입니다: - - - - -```python -from mcpauth import MCPAuth -from starlette.applications import Starlette -from starlette.middleware import Middleware -from starlette.routing import Mount -from mcp.server.fastmcp import FastMCP - -mcp = FastMCP("MyMCPServer") -mcp_auth = MCPAuth( - # Initialize with your auth server config -) -bearer_auth = mcp_auth.bearer_auth_middleware("jwt", required_scopes=["read", "write"]) # [!code highlight] - -app = Starlette( - routes=[Mount('/', app=mcp.sse_app(), middleware=[Middleware(bearer_auth)])] -) -``` - - - - -```ts -import express from 'express'; -import { MCPAuth } from 'mcp-auth'; - -const app = express(); -const mcpAuth = new MCPAuth({ - /* ... */ -}); -const bearerAuth = mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }); // [!code highlight] - -app.use('/mcp', bearerAuth, (req, res) => { - // Now `req.auth` contains the auth info - console.log(req.auth); -}); -``` - - - - -위 예시에서 JWT에 `read`와 `write` 스코프 (Scope)가 필요하다고 지정했습니다. JWT에 이 중 **하나라도** 포함되어 있지 않으면, 요청은 403 Forbidden 오류로 거부됩니다. - -### 리소스 지표 (Resource indicator) 검증 (RFC 8707) \{#resource-indicator-validation-rfc-8707} - -제공자가 OIDC 기반이거나 [Resource Indicator](https://datatracker.ietf.org/doc/html/rfc8707) 확장을 지원한다면, `audience` 옵션을 지정하여 JWT의 `aud` (대상 (Audience)) 클레임 (Claim)을 검증할 수 있습니다. 이는 JWT가 MCP 서버를 대상으로 발급된 것임을 보장하는 데 유용합니다. - -제공자의 문서를 확인하여 Resource Indicator 확장을 지원하는지, 그리고 어떻게 구성하는지 알아보세요. 일부 제공자는 이 개념을 "audience", "API 리소스", "API indicator" 등으로 부를 수 있습니다. - -리소스 지표 (Resource indicator)를 구성한 후, `bearerAuth` 미들웨어에 지정할 수 있습니다: - - - - -```python -bearer_auth = mcp_auth.bearer_auth_middleware( - "jwt", - audience="https://api.example.com/mcp", # JWT의 예상 대상 (Audience) [!code highlight] - required_scopes=["read", "write"] -) -``` - - - - -```ts -const bearerAuth = mcpAuth.bearerAuth('jwt', { - audience: 'https://api.example.com/mcp', // JWT의 예상 대상 (Audience) [!code highlight] - requiredScopes: ['read', 'write'], -}); -``` - - - - -위 예시에서는 MCP Auth가 JWT의 `aud` 클레임 (Claim)과 필요한 스코프 (Scope) **둘 다** 검증합니다. - -### JWT 검증에 커스텀 옵션 제공하기 \{#provide-custom-options-to-the-jwt-verification} - -기본 JWT 검증 라이브러리에 커스텀 옵션을 제공할 수도 있습니다: - - - - -Python SDK에서는 JWT 검증을 위해 [PyJWT](https://pyjwt.readthedocs.io/en/stable/)를 사용합니다. 다음 옵션을 사용할 수 있습니다: - -- `leeway`: JWT 만료 시간 검증 시 허용할 여유 시간 (초 단위). 기본값은 60초입니다. - -```python -bearer_auth = mcp_auth.bearer_auth_middleware( - "jwt", - audience="https://api.example.com/mcp", - required_scopes=["read", "write"] - leeway=10, # 10초의 여유로 클럭 스큐를 줄임 [!code highlight] -) -``` - - - - -Node.js SDK에서는 JWT 검증을 위해 [jose](https://github.com/panva/jose) 라이브러리를 사용합니다. 다음 옵션을 제공할 수 있습니다: - -- `jwtVerify`: JWT 검증 과정의 옵션 (`jose`의 `jwtVerify` 함수). -- `remoteJwtSet`: 원격 JWT 세트 가져오기 옵션 (`jose`의 `createRemoteJWKSet` 함수). - -```ts {4-9} -const bearerAuth = mcpAuth.bearerAuth('jwt', { - audience: 'https://api.example.com/mcp', - requiredScopes: ['read', 'write'], - jwtVerify: { - clockTolerance: 60, // 60초의 클럭 스큐 허용 - }, - remoteJwtSet: { - timeoutDuration: 10 * 1000, // 원격 JWT 세트 가져오기 10초 타임아웃 - }, -}); -``` - - - - -## 커스텀 검증으로 Bearer 인증 (Authentication) 구성하기 \{#configure-bearer-auth-with-custom-verification} - -OAuth / OIDC 제공자가 JWT를 발급하지 않거나, 직접 인가 (Authorization) 로직을 구현하고 싶다면, MCP Auth에서 커스텀 검증 함수를 만들 수 있습니다: - -:::info -Bearer 인증 (Authentication) 미들웨어는 발급자 (`iss`), 대상 (`aud`), 그리고 필요한 스코프 (`scope`)를 주어진 검증 결과와 비교하므로, 커스텀 검증 함수에서 이 검증들을 직접 구현할 필요가 없습니다. 토큰의 유효성 (예: 서명, 만료 등) 검증과 인증 (Authentication) 정보 객체 반환에 집중하면 됩니다. -::: - - - - -```python -from mcpauth.exceptions import MCPAuthJwtVerificationException, MCPAuthJwtVerificationExceptionCode -from mcpauth.types import AuthInfo - -async def custom_verification(token: str) -> AuthInfo: - # 여기에 커스텀 검증 로직을 구현하세요 - info = await verify_token(token) - if not info: - raise MCPAuthJwtVerificationException( - MCPAuthJwtVerificationExceptionCode.JWT_VERIFICATION_FAILED - ) - return info # 인증 (Authentication) 정보 객체 반환 - -bearer_auth = mcp_auth.bearer_auth_middleware( - custom_verification, - required_scopes=["read", "write"] -) -``` - - - - -```ts -const bearerAuth = mcpAuth.bearerAuth( - async (token) => { - // 여기에 커스텀 검증 로직을 구현하세요 - const info = await verifyToken(token); - if (!info) { - throw new MCPAuthJwtVerificationError('jwt_verification_failed'); - } - return info; // 인증 (Authentication) 정보 객체 반환 - }, - { requiredScopes: ['read', 'write'] } -); -``` - - - - -## MCP 서버에 Bearer 인증 (Authentication) 적용하기 \{#apply-bearer-auth-in-your-mcp-server} - -MCP 서버를 Bearer 인증 (Authentication)으로 보호하려면, MCP 서버 인스턴스에 Bearer 인증 (Authentication) 미들웨어를 적용해야 합니다. - - - - -```python -bearer_auth = mcp_auth.bearer_auth_middleware("jwt", required_scopes=["read", "write"]) -app = Starlette( - routes=[Mount('/', app=mcp.sse_app(), middleware=[Middleware(bearer_auth)])] -) -``` - - - - -```js -const app = express(); -app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] })); -``` - - - - -이렇게 하면 모든 들어오는 요청이 구성된 Bearer 인증 (Authentication) 설정에 따라 인증 (Authentication) 및 인가 (Authorization)되고, 인증 (Authentication) 정보가 요청 컨텍스트에서 사용할 수 있게 됩니다. - -이후 MCP 서버 구현에서 해당 정보를 사용할 수 있습니다: - - - - -```python -@mcp.tool() -async def whoami() -> dict: - # `mcp_auth.auth_info`는 현재 요청의 컨텍스트 객체입니다 - auth_info = mcp_auth.auth_info - print(f"Authenticated user: {auth_info.subject}") - return {"subject": auth_info.subject} -``` - - - - -```js -// `authInfo`는 `req.auth` 객체에서 전달됩니다 -server.tool('whoami', ({ authInfo }) => { - console.log(`Authenticated user: ${authInfo.subject}`); - return { subject: authInfo.subject }; -}); -``` - - - diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/configure-server/mcp-auth.mdx b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/configure-server/mcp-auth.mdx deleted file mode 100644 index 2648ed4..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/configure-server/mcp-auth.mdx +++ /dev/null @@ -1,208 +0,0 @@ ---- -sidebar_position: 1 -sidebar_label: MCP Auth ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -# MCP 서버에서 MCP Auth 구성하기 - -MCP 서버를 OAuth 2.1 또는 OpenID Connect 공급자에 연결하려면 MCP Auth 인스턴스를 구성해야 합니다. 이는 공급자의 인가 서버 메타데이터로 인스턴스를 초기화하고 필요한 인가 플로우를 설정하는 과정을 포함합니다. - -## MCP Auth 초기화하기 \{#init-mcp-auth} - -### 메타데이터 자동 가져오기 \{#automatic-metadata-fetching} - -MCP Auth 인스턴스를 초기화하는 가장 쉬운 방법은 well-known URL에서 메타데이터를 가져오는 내장 함수를 사용하는 것입니다. 공급자가 다음 표준 중 하나를 준수하는 경우: - -- [OAuth 2.0 인가 서버 메타데이터](https://datatracker.ietf.org/doc/html/rfc8414) -- [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) - -`fetchServerConfig`를 사용하여 `issuer` URL을 제공하면 메타데이터를 자동으로 가져올 수 있습니다: - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType, fetch_server_config - -mcp_auth = MCPAuth( - server=fetch_server_config( - '', - type=AuthServerType.OIDC # 또는 AuthServerType.OAUTH - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { type: 'oidc' }), // 또는 'oauth' -}); -``` - - - - -issuer에 경로가 포함된 경우, OAuth 2.0과 OpenID Connect에서 동작이 약간 다릅니다: - -- **OAuth 2.0**: well-known URL이 issuer의 **도메인**에 추가됩니다. 예를 들어, issuer가 `https://my-project.logto.app/oauth`라면, well-known URL은 `https://auth.logto.io/.well-known/oauth-authorization-server/oauth`가 됩니다. -- **OpenID Connect**: well-known URL이 **issuer**에 직접 추가됩니다. 예를 들어, issuer가 `https://my-project.logto.app/oidc`라면, well-known URL은 `https://auth.logto.io/oidc/.well-known/openid-configuration`이 됩니다. - -### MCP Auth를 초기화하는 다른 방법 \{#other-ways} - -#### 커스텀 데이터 변환 \{#custom-data-transpilation} - -경우에 따라 공급자가 반환하는 메타데이터가 예상 형식과 다를 수 있습니다. 공급자가 표준을 준수한다고 확신한다면, `transpile_data` 옵션을 사용하여 메타데이터를 사용하기 전에 수정할 수 있습니다: - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -mcp_auth = MCPAuth( - server=fetch_server_config( - '', - type=AuthServerType.OIDC, - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { - type: 'oidc', - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - - -이렇게 하면 MCP Auth에서 메타데이터 객체를 사용하기 전에 수정할 수 있습니다. 예를 들어, 필드를 추가하거나 제거하고, 값을 변경하거나, 다른 형식으로 변환할 수 있습니다. - -#### 특정 URL에서 메타데이터 가져오기 \{#fetch-metadata-from-a-specific-url} - -공급자가 표준이 아닌 특정 메타데이터 URL을 제공하는 경우에도 유사하게 사용할 수 있습니다: - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config_by_well_known_url - -mcp_auth = MCPAuth( - server=fetch_server_config_by_well_known_url( - '', - type=AuthServerType.OIDC # 또는 AuthServerType.OAUTH - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfigByWellKnownUrl } from 'mcp-auth'; - -const mcpAuth = new MCPAuth({ - server: await fetchServerConfigByWellKnownUrl('', { type: 'oidc' }), // 또는 'oauth' -}); -``` - - - - -#### 특정 URL에서 커스텀 데이터 변환과 함께 메타데이터 가져오기 \{#fetch-metadata-from-a-specific-url-with-custom-data-transpilation} - -경우에 따라 공급자의 응답이 잘못되었거나 예상 메타데이터 형식과 다를 수 있습니다. 공급자가 표준을 준수한다고 확신한다면, 설정 옵션을 통해 메타데이터를 변환할 수 있습니다: - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType, fetch_server_config_by_well_known_url - -mcp_auth = MCPAuth( - server=fetch_server_config_by_well_known_url( - '', - type=AuthServerType.OIDC, - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: await fetchServerConfigByWellKnownUrl('', { - type: 'oidc', - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - - -#### 메타데이터를 수동으로 제공하기 \{#manually-provide-metadata} - -공급자가 메타데이터 가져오기를 지원하지 않는 경우, 메타데이터 객체를 수동으로 제공할 수 있습니다: - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerConfig, AuthServerType, AuthorizationServerMetadata - -mcp_auth = MCPAuth( - server=AuthServerConfig( - type=AuthServerType.OIDC, # 또는 AuthServerType.OAUTH - metadata=AuthorizationServerMetadata( - issuer='', - authorization_endpoint='', - # ... 기타 메타데이터 필드 - ), - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: { - metadata: { - issuer: '', - // 메타데이터 필드는 camelCase여야 합니다 - authorizationEndpoint: '', - // ... 기타 메타데이터 필드 - }, - type: 'oidc', // 또는 'oauth' - }, -}); -``` - - - diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/README.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/README.md deleted file mode 100644 index a3b8fa3..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/README.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -sidebar_label: Node.js SDK ---- - -# MCP Auth Node.js SDK 참고 - -## 클래스 {#classes} - -- [MCPAuth](/references/js/classes/MCPAuth.md) -- [MCPAuthAuthServerError](/references/js/classes/MCPAuthAuthServerError.md) -- [MCPAuthBearerAuthError](/references/js/classes/MCPAuthBearerAuthError.md) -- [MCPAuthConfigError](/references/js/classes/MCPAuthConfigError.md) -- [MCPAuthError](/references/js/classes/MCPAuthError.md) -- [MCPAuthTokenVerificationError](/references/js/classes/MCPAuthTokenVerificationError.md) - -## 타입 별칭 {#type-aliases} - -- [AuthorizationServerMetadata](/references/js/type-aliases/AuthorizationServerMetadata.md) -- [AuthServerConfig](/references/js/type-aliases/AuthServerConfig.md) -- [AuthServerConfigError](/references/js/type-aliases/AuthServerConfigError.md) -- [AuthServerConfigErrorCode](/references/js/type-aliases/AuthServerConfigErrorCode.md) -- [AuthServerConfigWarning](/references/js/type-aliases/AuthServerConfigWarning.md) -- [AuthServerConfigWarningCode](/references/js/type-aliases/AuthServerConfigWarningCode.md) -- [AuthServerErrorCode](/references/js/type-aliases/AuthServerErrorCode.md) -- [AuthServerSuccessCode](/references/js/type-aliases/AuthServerSuccessCode.md) -- [AuthServerType](/references/js/type-aliases/AuthServerType.md) -- [BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) -- [BearerAuthErrorCode](/references/js/type-aliases/BearerAuthErrorCode.md) -- [BearerAuthJwtConfig](/references/js/type-aliases/BearerAuthJwtConfig.md) -- [CamelCaseAuthorizationServerMetadata](/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md) -- [MCPAuthBearerAuthErrorDetails](/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md) -- [MCPAuthConfig](/references/js/type-aliases/MCPAuthConfig.md) -- [MCPAuthTokenVerificationErrorCode](/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md) -- [VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) -- [VerifyAccessTokenMode](/references/js/type-aliases/VerifyAccessTokenMode.md) - -## 변수 {#variables} - -- [authorizationServerMetadataSchema](/references/js/variables/authorizationServerMetadataSchema.md) -- [authServerErrorDescription](/references/js/variables/authServerErrorDescription.md) -- [bearerAuthErrorDescription](/references/js/variables/bearerAuthErrorDescription.md) -- [camelCaseAuthorizationServerMetadataSchema](/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md) -- [serverMetadataPaths](/references/js/variables/serverMetadataPaths.md) -- [tokenVerificationErrorDescription](/references/js/variables/tokenVerificationErrorDescription.md) -- [validateServerConfig](/references/js/variables/validateServerConfig.md) - -## 함수 {#functions} - -- [createVerifyJwt](/references/js/functions/createVerifyJwt.md) -- [fetchServerConfig](/references/js/functions/fetchServerConfig.md) -- [fetchServerConfigByWellKnownUrl](/references/js/functions/fetchServerConfigByWellKnownUrl.md) -- [handleBearerAuth](/references/js/functions/handleBearerAuth.md) diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuth.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuth.md deleted file mode 100644 index e5750fe..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuth.md +++ /dev/null @@ -1,195 +0,0 @@ ---- -sidebar_label: MCPAuth ---- - -# 클래스: MCPAuth - -mcp-auth 라이브러리의 주요 클래스이며, MCP 서버에서 인증 (Authentication) 및 인가 (Authorization)를 위한 라우터와 유용한 핸들러를 생성하는 메서드를 제공합니다. - -## 참고 {#see} - -라이브러리 및 사용법에 대한 자세한 내용은 [MCP Auth](https://mcp-auth.dev) 를 참고하세요. - -## 예시 {#example} - -원격 OIDC 제공자와 통합하는 예시: - -```ts -import express from 'express'; -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const app = express(); -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig( - 'https://auth.logto.io/oidc', - { type: 'oidc' } - ), -}); - -// OAuth 2.0 인가 (Authorization) 서버 메타데이터를 처리하는 라우터를 마운트합니다. -app.use(mcpAuth.delegatedRouter()); - -// MCP 경로에서 Bearer 인증 (Authentication) 핸들러를 사용합니다. -app.get( - '/mcp', - mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }), - (req, res) => { - console.log('Auth info:', req.auth); - // 여기서 MCP 요청을 처리합니다. - }, -); - -// MCP 콜백에서 인증 (Authentication) 정보를 사용합니다. -server.tool( - 'add', - { a: z.number(), b: z.number() }, - async ({ a, b }, { authInfo }) => { - console.log('Auth Info:', authInfo); - // ... - }, -); -``` - -## 생성자 {#constructors} - -### 생성자 {#constructor} - -```ts -new MCPAuth(config: MCPAuthConfig): MCPAuth; -``` - -#### 매개변수 {#parameters} - -##### config {#config} - -[`MCPAuthConfig`](/references/js/type-aliases/MCPAuthConfig.md) - -#### 반환값 {#returns} - -`MCPAuth` - -## 속성 {#properties} - -### config {#config} - -```ts -readonly config: MCPAuthConfig; -``` - -## 메서드 {#methods} - -### bearerAuth() {#bearerauth} - -#### 호출 시그니처 {#call-signature} - -```ts -bearerAuth(verifyAccessToken: VerifyAccessTokenFunction, config?: Omit): RequestHandler; -``` - -요청의 `Authorization` 헤더에 있는 액세스 토큰 (Access token)을 검증하는 Bearer 인증 (Authentication) 핸들러 (Express 미들웨어)를 생성합니다. - -##### 매개변수 {#parameters} - -###### verifyAccessToken {#verifyaccesstoken} - -[`VerifyAccessTokenFunction`](/references/js/type-aliases/VerifyAccessTokenFunction.md) - -액세스 토큰 (Access token)을 검증하는 함수입니다. 문자열로 액세스 토큰을 받아, 검증 결과로 resolve되는 promise (또는 값)를 반환해야 합니다. - -**참고** - -`verifyAccessToken` 함수의 타입 정의는 [VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) 를 참고하세요. - -###### config? {#config} - -`Omit`\<[`BearerAuthConfig`](/references/js/type-aliases/BearerAuthConfig.md), `"verifyAccessToken"` \| `"issuer"`\> - -Bearer 인증 (Authentication) 핸들러에 대한 선택적 설정입니다. - -**참고** - -설정 가능한 옵션(단, `verifyAccessToken` 및 `issuer` 제외)은 [BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) 를 참고하세요. - -##### 반환값 {#returns} - -`RequestHandler` - -액세스 토큰 (Access token)을 검증하고, 검증 결과를 요청 객체 (`req.auth`)에 추가하는 Express 미들웨어 함수입니다. - -##### 참고 {#see} - -`req.auth` (`AuthInfo`) 객체의 구현 세부사항 및 확장 타입은 [handleBearerAuth](/references/js/functions/handleBearerAuth.md) 를 참고하세요. - -#### 호출 시그니처 {#call-signature} - -```ts -bearerAuth(mode: "jwt", config?: Omit & BearerAuthJwtConfig): RequestHandler; -``` - -사전 정의된 검증 모드를 사용하여 요청의 `Authorization` 헤더에 있는 액세스 토큰 (Access token)을 검증하는 Bearer 인증 (Authentication) 핸들러 (Express 미들웨어)를 생성합니다. - -'jwt' 모드에서는, 인가 (Authorization) 서버의 JWKS URI에서 JWK Set을 사용하여 JWT 검증 함수를 생성합니다. - -##### 매개변수 {#parameters} - -###### mode {#mode} - -`"jwt"` - -액세스 토큰 (Access token)의 검증 모드입니다. 현재는 'jwt'만 지원됩니다. - -**참고** - -사용 가능한 모드는 [VerifyAccessTokenMode](/references/js/type-aliases/VerifyAccessTokenMode.md) 를 참고하세요. - -###### config? {#config} - -`Omit`\<[`BearerAuthConfig`](/references/js/type-aliases/BearerAuthConfig.md), `"verifyAccessToken"` \| `"issuer"`\> & [`BearerAuthJwtConfig`](/references/js/type-aliases/BearerAuthJwtConfig.md) - -JWT 검증 옵션 및 원격 JWK set 옵션을 포함한 Bearer 인증 (Authentication) 핸들러의 선택적 설정입니다. - -**참고** - - - JWT 검증을 위한 설정 옵션은 [BearerAuthJwtConfig](/references/js/type-aliases/BearerAuthJwtConfig.md) 를 참고하세요. - - 설정 가능한 옵션(단, `verifyAccessToken` 및 `issuer` 제외)은 [BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) 를 참고하세요. - -##### 반환값 {#returns} - -`RequestHandler` - -액세스 토큰 (Access token)을 검증하고, 검증 결과를 요청 객체 (`req.auth`)에 추가하는 Express 미들웨어 함수입니다. - -##### 참고 {#see} - -`req.auth` (`AuthInfo`) 객체의 구현 세부사항 및 확장 타입은 [handleBearerAuth](/references/js/functions/handleBearerAuth.md) 를 참고하세요. - -##### 예외 발생 {#throws} - -'jwt' 모드 사용 시, 서버 메타데이터에 JWKS URI가 제공되지 않은 경우 예외가 발생합니다. - -*** - -### delegatedRouter() {#delegatedrouter} - -```ts -delegatedRouter(): Router; -``` - -OAuth 2.0 인가 (Authorization) 서버 메타데이터 엔드포인트 (`/.well-known/oauth-authorization-server`)를 인스턴스에 제공된 메타데이터로 제공하는 위임 라우터를 생성합니다. - -#### 반환값 {#returns} - -`Router` - -인스턴스에 제공된 메타데이터로 OAuth 2.0 인가 (Authorization) 서버 메타데이터 엔드포인트를 제공하는 라우터입니다. - -#### 예시 {#example} - -```ts -import express from 'express'; -import { MCPAuth } from 'mcp-auth'; - -const app = express(); -const mcpAuth: MCPAuth; // 초기화되어 있다고 가정 -app.use(mcpAuth.delegatedRouter()); -``` diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthAuthServerError.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthAuthServerError.md deleted file mode 100644 index fcadcfd..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthAuthServerError.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -sidebar_label: MCPAuthAuthServerError ---- - -# 클래스: MCPAuthAuthServerError - -원격 인가 (Authorization) 서버에 문제가 발생했을 때 발생하는 오류입니다. - -## 상속 {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## 생성자 {#constructors} - -### 생성자 {#constructor} - -```ts -new MCPAuthAuthServerError(code: AuthServerErrorCode, cause?: unknown): MCPAuthAuthServerError; -``` - -#### 매개변수 {#parameters} - -##### code {#code} - -[`AuthServerErrorCode`](/references/js/type-aliases/AuthServerErrorCode.md) - -##### cause? {#cause} - -`unknown` - -#### 반환값 {#returns} - -`MCPAuthAuthServerError` - -#### 오버라이드 {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## 속성 {#properties} - -### cause? {#cause} - -```ts -readonly optional cause: unknown; -``` - -#### 상속됨 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: AuthServerErrorCode; -``` - -스네이크 케이스 형식의 오류 코드입니다. - -#### 상속됨 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### 상속됨 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthAuthServerError'; -``` - -#### 오버라이드 {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### 상속됨 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -스택 트레이스 포맷팅을 위한 선택적 오버라이드 - -#### 매개변수 {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### 반환값 {#returns} - -`any` - -#### 참고 {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### 상속됨 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### 상속됨 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## 메서드 {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -오류를 HTTP 응답에 적합한 JSON 형식으로 변환합니다. - -#### 매개변수 {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -JSON 응답에 오류의 원인(cause)을 포함할지 여부입니다. -기본값은 `false`입니다. - -#### 반환값 {#returns} - -`Record`\<`string`, `unknown`\> - -#### 상속됨 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -대상 객체에 .stack 속성을 생성합니다 - -#### 매개변수 {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### 반환값 {#returns} - -`void` - -#### 상속됨 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthBearerAuthError.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthBearerAuthError.md deleted file mode 100644 index 92d73c9..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthBearerAuthError.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -sidebar_label: MCPAuthBearerAuthError ---- - -# 클래스: MCPAuthBearerAuthError - -Bearer 액세스 토큰 (Access token) 인증 (Authentication) 과정에서 문제가 발생할 때 발생하는 오류입니다. - -## 상속 {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## 생성자 {#constructors} - -### 생성자 {#constructor} - -```ts -new MCPAuthBearerAuthError(code: BearerAuthErrorCode, cause?: MCPAuthBearerAuthErrorDetails): MCPAuthBearerAuthError; -``` - -#### 매개변수 {#parameters} - -##### code {#code} - -[`BearerAuthErrorCode`](/references/js/type-aliases/BearerAuthErrorCode.md) - -##### cause? {#cause} - -[`MCPAuthBearerAuthErrorDetails`](/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md) - -#### 반환값 {#returns} - -`MCPAuthBearerAuthError` - -#### 오버라이드 {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## 프로퍼티 {#properties} - -### cause? {#cause} - -```ts -readonly optional cause: MCPAuthBearerAuthErrorDetails; -``` - -#### 상속됨 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: BearerAuthErrorCode; -``` - -스네이크 케이스(snake_case) 형식의 오류 코드입니다. - -#### 상속됨 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### 상속됨 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthBearerAuthError'; -``` - -#### 오버라이드 {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### 상속됨 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -스택 트레이스(stack trace) 포맷팅을 위한 선택적 오버라이드 - -#### 매개변수 {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### 반환값 {#returns} - -`any` - -#### 참고 {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### 상속됨 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### 상속됨 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## 메서드 {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -오류를 HTTP 응답에 적합한 JSON 형식으로 변환합니다. - -#### 매개변수 {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -JSON 응답에 오류의 원인(cause)을 포함할지 여부입니다. -기본값은 `false`입니다. - -#### 반환값 {#returns} - -`Record`\<`string`, `unknown`\> - -#### 오버라이드 {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -대상 객체에 .stack 프로퍼티를 생성합니다 - -#### 매개변수 {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### 반환값 {#returns} - -`void` - -#### 상속됨 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthConfigError.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthConfigError.md deleted file mode 100644 index eab0897..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthConfigError.md +++ /dev/null @@ -1,202 +0,0 @@ ---- -sidebar_label: MCPAuthConfigError ---- - -# 클래스: MCPAuthConfigError - -mcp-auth의 구성 문제로 인해 발생하는 오류입니다. - -## 상속 {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## 생성자 {#constructors} - -### 생성자 {#constructor} - -```ts -new MCPAuthConfigError(code: string, message: string): MCPAuthConfigError; -``` - -#### 매개변수 {#parameters} - -##### code {#code} - -`string` - -스네이크 케이스 형식의 오류 코드입니다. - -##### message {#message} - -`string` - -오류에 대한 사람이 읽을 수 있는 설명입니다. - -#### 반환값 {#returns} - -`MCPAuthConfigError` - -#### 상속됨 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## 속성 {#properties} - -### cause? {#cause} - -```ts -optional cause: unknown; -``` - -#### 상속됨 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: string; -``` - -스네이크 케이스 형식의 오류 코드입니다. - -#### 상속됨 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### 상속됨 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthConfigError'; -``` - -#### 오버라이드 {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### 상속됨 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -스택 트레이스 형식을 지정하기 위한 선택적 오버라이드입니다. - -#### 매개변수 {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### 반환값 {#returns} - -`any` - -#### 참고 {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### 상속됨 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### 상속됨 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## 메서드 {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -오류를 HTTP 응답에 적합한 JSON 형식으로 변환합니다. - -#### 매개변수 {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -JSON 응답에 오류의 원인을 포함할지 여부입니다. -기본값은 `false`입니다. - -#### 반환값 {#returns} - -`Record`\<`string`, `unknown`\> - -#### 상속됨 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -대상 객체에 .stack 속성을 생성합니다. - -#### 매개변수 {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### 반환값 {#returns} - -`void` - -#### 상속됨 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthError.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthError.md deleted file mode 100644 index 5dc8faf..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthError.md +++ /dev/null @@ -1,219 +0,0 @@ ---- -sidebar_label: MCPAuthError ---- - -# 클래스: MCPAuthError - -모든 mcp-auth 오류의 기본 클래스입니다. - -MCP 인증 (Authentication) 및 인가 (Authorization)와 관련된 오류를 표준화된 방식으로 처리할 수 있도록 합니다. - -## 상속 {#extends} - -- `Error` - -## 확장 클래스 {#extended-by} - -- [`MCPAuthConfigError`](/references/js/classes/MCPAuthConfigError.md) -- [`MCPAuthAuthServerError`](/references/js/classes/MCPAuthAuthServerError.md) -- [`MCPAuthBearerAuthError`](/references/js/classes/MCPAuthBearerAuthError.md) -- [`MCPAuthTokenVerificationError`](/references/js/classes/MCPAuthTokenVerificationError.md) - -## 생성자 {#constructors} - -### 생성자 {#constructor} - -```ts -new MCPAuthError(code: string, message: string): MCPAuthError; -``` - -#### 매개변수 {#parameters} - -##### code {#code} - -`string` - -스네이크 케이스 형식의 오류 코드입니다. - -##### message {#message} - -`string` - -오류에 대한 사람이 읽을 수 있는 설명입니다. - -#### 반환값 {#returns} - -`MCPAuthError` - -#### 오버라이드 {#overrides} - -```ts -Error.constructor -``` - -## 속성 {#properties} - -### cause? {#cause} - -```ts -optional cause: unknown; -``` - -#### 상속됨 {#inherited-from} - -```ts -Error.cause -``` - -*** - -### code {#code} - -```ts -readonly code: string; -``` - -스네이크 케이스 형식의 오류 코드입니다. - -*** - -### message {#message} - -```ts -message: string; -``` - -#### 상속됨 {#inherited-from} - -```ts -Error.message -``` - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthError'; -``` - -#### 오버라이드 {#overrides} - -```ts -Error.name -``` - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### 상속됨 {#inherited-from} - -```ts -Error.stack -``` - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -스택 트레이스 포맷팅을 위한 선택적 오버라이드 - -#### 매개변수 {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### 반환값 {#returns} - -`any` - -#### 참고 {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### 상속됨 {#inherited-from} - -```ts -Error.prepareStackTrace -``` - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### 상속됨 {#inherited-from} - -```ts -Error.stackTraceLimit -``` - -## 메서드 {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -오류를 HTTP 응답에 적합한 JSON 형식으로 변환합니다. - -#### 매개변수 {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -JSON 응답에 오류의 원인을 포함할지 여부입니다. -기본값은 `false`입니다. - -#### 반환값 {#returns} - -`Record`\<`string`, `unknown`\> - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -대상 객체에 .stack 속성을 생성합니다 - -#### 매개변수 {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### 반환값 {#returns} - -`void` - -#### 상속됨 {#inherited-from} - -```ts -Error.captureStackTrace -``` diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthTokenVerificationError.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthTokenVerificationError.md deleted file mode 100644 index cc31fe8..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthTokenVerificationError.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -sidebar_label: MCPAuthTokenVerificationError ---- - -# 클래스: MCPAuthTokenVerificationError - -토큰을 검증하는 과정에서 문제가 발생했을 때 발생하는 오류입니다. - -## 상속 {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## 생성자 {#constructors} - -### 생성자 {#constructor} - -```ts -new MCPAuthTokenVerificationError(code: MCPAuthTokenVerificationErrorCode, cause?: unknown): MCPAuthTokenVerificationError; -``` - -#### 매개변수 {#parameters} - -##### code {#code} - -[`MCPAuthTokenVerificationErrorCode`](/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md) - -##### cause? {#cause} - -`unknown` - -#### 반환값 {#returns} - -`MCPAuthTokenVerificationError` - -#### 오버라이드 {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## 속성 {#properties} - -### cause? {#cause} - -```ts -readonly optional cause: unknown; -``` - -#### 상속됨 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: MCPAuthTokenVerificationErrorCode; -``` - -스네이크 케이스(snake_case) 형식의 오류 코드입니다. - -#### 상속됨 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### 상속됨 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthTokenVerificationError'; -``` - -#### 오버라이드 {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### 상속됨 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -스택 트레이스 형식을 지정하기 위한 선택적 오버라이드입니다. - -#### 매개변수 {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### 반환값 {#returns} - -`any` - -#### 참고 {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### 상속됨 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### 상속됨 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## 메서드 {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -오류를 HTTP 응답에 적합한 JSON 형식으로 변환합니다. - -#### 매개변수 {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -JSON 응답에 오류의 원인(cause)을 포함할지 여부입니다. -기본값은 `false`입니다. - -#### 반환값 {#returns} - -`Record`\<`string`, `unknown`\> - -#### 상속됨 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -대상 객체에 .stack 속성을 생성합니다. - -#### 매개변수 {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### 반환값 {#returns} - -`void` - -#### 상속됨 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/createVerifyJwt.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/createVerifyJwt.md deleted file mode 100644 index ca14ce0..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/createVerifyJwt.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -sidebar_label: createVerifyJwt ---- - -# 함수: createVerifyJwt() - -```ts -function createVerifyJwt(getKey: JWTVerifyGetKey, options?: JWTVerifyOptions): VerifyAccessTokenFunction; -``` - -제공된 키 조회 함수와 옵션을 사용하여 JWT 액세스 토큰 (Access token)을 검증하는 함수를 생성합니다. - -## 매개변수 {#parameters} - -### getKey {#getkey} - -`JWTVerifyGetKey` - -JWT를 검증하는 데 사용되는 키를 조회하는 함수입니다. - -**참고** - -키 조회 함수의 타입 정의는 JWTVerifyGetKey를 참고하세요. - -### options? {#options} - -`JWTVerifyOptions` - -선택적으로 JWT 검증 옵션을 지정할 수 있습니다. - -**참고** - -옵션의 타입 정의는 JWTVerifyOptions를 참고하세요. - -## 반환값 {#returns} - -[`VerifyAccessTokenFunction`](/references/js/type-aliases/VerifyAccessTokenFunction.md) - -JWT 액세스 토큰 (Access token)을 검증하고, 토큰이 유효한 경우 AuthInfo 객체를 반환하는 함수입니다. 이 함수는 JWT의 페이로드에 `iss`, `client_id`, `sub` 필드가 반드시 포함되어야 하며, 선택적으로 `scope` 또는 `scopes` 필드를 포함할 수 있습니다. JWT 검증은 내부적으로 `jose` 라이브러리를 사용합니다. - -## 참고 {#see} - -반환되는 함수의 타입 정의는 [VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md)에서 확인할 수 있습니다. diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfig.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfig.md deleted file mode 100644 index ae64042..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfig.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -sidebar_label: fetchServerConfig ---- - -# 함수: fetchServerConfig() - -```ts -function fetchServerConfig(issuer: string, config: ServerMetadataConfig): Promise; -``` - -발급자 (Issuer) 및 인가 서버 유형에 따라 서버 구성을 가져옵니다. - -이 함수는 서버 유형에 따라 well-known URL을 자동으로 결정합니다. OAuth 및 OpenID Connect 서버는 메타데이터 엔드포인트에 대해 서로 다른 규칙을 가지고 있기 때문입니다. - -## 매개변수 {#parameters} - -### issuer {#issuer} - -`string` - -인가 (Authorization) 서버의 발급자 (Issuer) URL입니다. - -### config {#config} - -`ServerMetadataConfig` - -서버 유형과 선택적 트랜스파일 함수가 포함된 구성 객체입니다. - -## 반환값 {#returns} - -`Promise`\<[`AuthServerConfig`](/references/js/type-aliases/AuthServerConfig.md)\> - -서버 구성으로 resolve되는 promise입니다. - -## 참고 {#see} - - - 내부 구현에 대해서는 [fetchServerConfigByWellKnownUrl](/references/js/functions/fetchServerConfigByWellKnownUrl.md) 을(를) 참고하세요. - - OAuth 2.0 인가 (Authorization) 서버 메타데이터 명세는 [https://www.rfc-editor.org/rfc/rfc8414](https://www.rfc-editor.org/rfc/rfc8414) 를 참고하세요. - - OpenID Connect Discovery 명세는 [https://openid.net/specs/openid-connect-discovery-1\_0.html](https://openid.net/specs/openid-connect-discovery-1_0.html) 를 참고하세요. - -## 예시 {#example} - -```ts -import { fetchServerConfig } from 'mcp-auth'; -// OAuth 서버 구성을 가져옵니다 -// 이는 `https://auth.logto.io/.well-known/oauth-authorization-server/oauth`에서 메타데이터를 가져옵니다 -const oauthConfig = await fetchServerConfig('https://auth.logto.io/oauth', { type: 'oauth' }); - -// OpenID Connect 서버 구성을 가져옵니다 -// 이는 `https://auth.logto.io/oidc/.well-known/openid-configuration`에서 메타데이터를 가져옵니다 -const oidcConfig = await fetchServerConfig('https://auth.logto.io/oidc', { type: 'oidc' }); -``` - -## 예외 {#throws} - -fetch 작업이 실패할 경우 예외가 발생합니다. - -## 예외 {#throws} - -서버 메타데이터가 유효하지 않거나 MCP 명세와 일치하지 않을 경우 예외가 발생합니다. diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfigByWellKnownUrl.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfigByWellKnownUrl.md deleted file mode 100644 index e8eaa7f..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfigByWellKnownUrl.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -sidebar_label: fetchServerConfigByWellKnownUrl ---- - -# 함수: fetchServerConfigByWellKnownUrl() - -```ts -function fetchServerConfigByWellKnownUrl(wellKnownUrl: string | URL, config: ServerMetadataConfig): Promise; -``` - -제공된 well-known URL에서 서버 구성을 가져오고, 이를 MCP 명세에 따라 검증합니다. - -서버 메타데이터가 예상된 스키마와 일치하지 않지만, 호환된다고 확신하는 경우 `transpileData` 함수를 정의하여 메타데이터를 예상 형식으로 변환할 수 있습니다. - -## 매개변수 {#parameters} - -### wellKnownUrl {#wellknownurl} - -서버 구성을 가져올 well-known URL입니다. 문자열 또는 URL 객체일 수 있습니다. - -`string` | `URL` - -### config {#config} - -`ServerMetadataConfig` - -서버 유형과 선택적 변환 함수(transpile function)를 포함하는 구성 객체입니다. - -## 반환값 {#returns} - -`Promise`\<[`AuthServerConfig`](/references/js/type-aliases/AuthServerConfig.md)\> - -서버 구성으로 해결되는 프로미스입니다. - -## 예외 {#throws} - -가져오기(fetch) 작업이 실패할 경우 예외가 발생합니다. - -## 예외 {#throws} - -서버 메타데이터가 유효하지 않거나 MCP 명세와 일치하지 않을 경우 예외가 발생합니다. diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/handleBearerAuth.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/handleBearerAuth.md deleted file mode 100644 index 21e1641..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/handleBearerAuth.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -sidebar_label: handleBearerAuth ---- - -# 함수: handleBearerAuth() - -```ts -function handleBearerAuth(param0: BearerAuthConfig): RequestHandler; -``` - -Express 애플리케이션에서 Bearer 인증 (Authentication)을 처리하는 미들웨어 함수를 생성합니다. - -이 미들웨어는 `Authorization` 헤더에서 Bearer 액세스 토큰 (Access token)을 추출하고, -제공된 `verifyAccessToken` 함수를 사용해 토큰을 검증하며, 발급자 (Issuer), 대상 (Audience), 그리고 필요한 스코프 (Scope)를 확인합니다. - -- 토큰이 유효하면 인증 (Authentication) 정보를 `request.auth` 속성에 추가합니다. - 유효하지 않으면 적절한 오류 메시지로 응답합니다. -- 액세스 토큰 (Access token) 검증에 실패하면 401 Unauthorized 오류로 응답합니다. -- 토큰에 필요한 스코프 (Scope)가 없으면 403 Forbidden 오류로 응답합니다. -- 인증 (Authentication) 과정에서 예기치 않은 오류가 발생하면, 미들웨어가 해당 오류를 다시 throw합니다. - -**참고:** `request.auth` 객체는 `@modelcontextprotocol/sdk` 모듈에 정의된 표준 AuthInfo 인터페이스보다 확장된 필드를 포함합니다. 자세한 내용은 이 파일의 확장 인터페이스를 참고하세요. - -## 매개변수 {#parameters} - -### param0 {#param0} - -[`BearerAuthConfig`](/references/js/type-aliases/BearerAuthConfig.md) - -Bearer 인증 (Authentication) 핸들러를 위한 구성입니다. - -## 반환값 {#returns} - -`RequestHandler` - -Bearer 인증 (Authentication)을 처리하는 Express용 미들웨어 함수입니다. - -## 참고 {#see} - -구성 옵션에 대해서는 [BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md)를 참고하세요. diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfig.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfig.md deleted file mode 100644 index cdf9aad..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfig.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -sidebar_label: AuthServerConfig ---- - -# 타입 별칭: AuthServerConfig - -```ts -type AuthServerConfig = { - metadata: CamelCaseAuthorizationServerMetadata; - type: AuthServerType; -}; -``` - -MCP 서버와 통합된 원격 인가 서버 (Authorization Server)의 구성입니다. - -## 속성(Properties) {#properties} - -### metadata {#metadata} - -```ts -metadata: CamelCaseAuthorizationServerMetadata; -``` - -인가 서버 (Authorization Server)의 메타데이터로, MCP 명세 (OAuth 2.0 인가 서버 메타데이터 기반)를 따라야 합니다. - -이 메타데이터는 일반적으로 서버의 well-known 엔드포인트 (OAuth 2.0 인가 서버 메타데이터 또는 OpenID Connect Discovery)에서 가져오며, 서버가 해당 엔드포인트를 지원하지 않는 경우 구성에 직접 제공할 수도 있습니다. - -**참고:** 메타데이터는 mcp-auth 라이브러리에서 선호하는 camelCase 형식이어야 합니다. - -#### 참고(See) {#see} - - - [OAuth 2.0 인가 서버 메타데이터](https://datatracker.ietf.org/doc/html/rfc8414) - - [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) - -*** - -### type {#type} - -```ts -type: AuthServerType; -``` - -인가 서버 (Authorization Server)의 유형입니다. - -#### 참고(See) {#see} - -가능한 값은 [AuthServerType](/references/js/type-aliases/AuthServerType.md) 을 참고하세요. diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigError.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigError.md deleted file mode 100644 index a83df84..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigError.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -sidebar_label: AuthServerConfigError ---- - -# 타입 별칭: AuthServerConfigError (Type Alias: AuthServerConfigError) - -```ts -type AuthServerConfigError = { - cause?: Error; - code: AuthServerConfigErrorCode; - description: string; -}; -``` - -인가 서버 메타데이터의 검증 중에 발생하는 오류를 나타냅니다. - -## 속성 (Properties) {#properties} - -### cause? {#cause} - -```ts -optional cause: Error; -``` - -오류의 선택적 원인으로, 일반적으로 더 많은 맥락을 제공하는 `Error` 인스턴스입니다. - -*** - -### code {#code} - -```ts -code: AuthServerConfigErrorCode; -``` - -특정 검증 오류를 나타내는 코드입니다. - -*** - -### description {#description} - -```ts -description: string; -``` - -오류에 대한 사람이 읽을 수 있는 설명입니다. diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigErrorCode.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigErrorCode.md deleted file mode 100644 index b6ecf79..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigErrorCode.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_label: AuthServerConfigErrorCode ---- - -# 타입 별칭: AuthServerConfigErrorCode - -```ts -type AuthServerConfigErrorCode = - | "invalid_server_metadata" - | "code_response_type_not_supported" - | "authorization_code_grant_not_supported" - | "pkce_not_supported" - | "s256_code_challenge_method_not_supported"; -``` - -인가 서버 메타데이터를 검증할 때 발생할 수 있는 오류 코드입니다. \ No newline at end of file diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarning.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarning.md deleted file mode 100644 index e5d4939..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarning.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -sidebar_label: AuthServerConfigWarning ---- - -# 타입 별칭: AuthServerConfigWarning (AuthServerConfigWarning) - -```ts -type AuthServerConfigWarning = { - code: AuthServerConfigWarningCode; - description: string; -}; -``` - -인가 서버 메타데이터의 검증 중에 발생하는 경고를 나타냅니다. - -## 속성(Properties) {#properties} - -### code {#code} - -```ts -code: AuthServerConfigWarningCode; -``` - -특정 검증 경고를 나타내는 코드입니다. - -*** - -### description {#description} - -```ts -description: string; -``` - -경고에 대한 사람이 읽을 수 있는 설명입니다. diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarningCode.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarningCode.md deleted file mode 100644 index 20b1907..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarningCode.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -sidebar_label: AuthServerConfigWarningCode ---- - -# 타입 별칭: AuthServerConfigWarningCode - -```ts -type AuthServerConfigWarningCode = "dynamic_registration_not_supported"; -``` - -인가 서버 메타데이터를 검증할 때 발생할 수 있는 경고 코드입니다. \ No newline at end of file diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerErrorCode.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerErrorCode.md deleted file mode 100644 index 3ad6134..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerErrorCode.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_label: AuthServerErrorCode ---- - -# 타입 별칭: AuthServerErrorCode (Type Alias: AuthServerErrorCode) - -```ts -type AuthServerErrorCode = - | "invalid_server_metadata" - | "invalid_server_config" - | "missing_jwks_uri"; -``` diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerSuccessCode.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerSuccessCode.md deleted file mode 100644 index d1236d8..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerSuccessCode.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -sidebar_label: AuthServerSuccessCode ---- - -# 타입 별칭: AuthServerSuccessCode - -```ts -type AuthServerSuccessCode = - | "server_metadata_valid" - | "dynamic_registration_supported" - | "pkce_supported" - | "s256_code_challenge_method_supported" - | "authorization_code_grant_supported" - | "code_response_type_supported"; -``` - -인가 서버 메타데이터의 성공적인 검증을 나타내는 코드입니다. \ No newline at end of file diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerType.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerType.md deleted file mode 100644 index df7aded..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerType.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -sidebar_label: AuthServerType ---- - -# 타입 별칭: AuthServerType - -```ts -type AuthServerType = "oauth" | "oidc"; -``` - -인가 서버의 타입입니다. 이 정보는 서버 구성에서 제공되어야 하며, 서버가 OAuth 2.0 또는 OpenID Connect (OIDC) 인가 서버인지 나타냅니다. diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthorizationServerMetadata.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthorizationServerMetadata.md deleted file mode 100644 index dd9f939..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthorizationServerMetadata.md +++ /dev/null @@ -1,217 +0,0 @@ ---- -sidebar_label: AuthorizationServerMetadata ---- - -# 타입 별칭: AuthorizationServerMetadata - -```ts -type AuthorizationServerMetadata = { - authorization_endpoint: string; - code_challenge_methods_supported?: string[]; - grant_types_supported?: string[]; - introspection_endpoint?: string; - introspection_endpoint_auth_methods_supported?: string[]; - introspection_endpoint_auth_signing_alg_values_supported?: string[]; - issuer: string; - jwks_uri?: string; - op_policy_uri?: string; - op_tos_uri?: string; - registration_endpoint?: string; - response_modes_supported?: string[]; - response_types_supported: string[]; - revocation_endpoint?: string; - revocation_endpoint_auth_methods_supported?: string[]; - revocation_endpoint_auth_signing_alg_values_supported?: string[]; - scope_supported?: string[]; - service_documentation?: string; - token_endpoint: string; - token_endpoint_auth_methods_supported?: string[]; - token_endpoint_auth_signing_alg_values_supported?: string[]; - ui_locales_supported?: string[]; - userinfo_endpoint?: string; -}; -``` - -RFC 8414에서 정의된 OAuth 2.0 인가 서버 메타데이터 스키마입니다. - -## 타입 선언 {#type-declaration} - -### authorization\_endpoint {#authorization-endpoint} - -```ts -authorization_endpoint: string; -``` - -인가 서버의 인가 엔드포인트 URL [[RFC6749](https://rfc-editor.org/rfc/rfc6749)]. -인가 엔드포인트를 사용하는 grant type이 지원되지 않는 경우를 제외하고 필수입니다. - -#### 참고 {#see} - -https://rfc-editor.org/rfc/rfc6749#section-3.1 - -### code\_challenge\_methods\_supported? {#code-challenge-methods-supported} - -```ts -optional code_challenge_methods_supported: string[]; -``` - -이 인가 서버가 지원하는 Proof Key for Code Exchange (PKCE) [[RFC7636](https://www.rfc-editor.org/rfc/rfc7636)] 코드 챌린지 방식의 목록을 포함하는 JSON 배열입니다. - -### grant\_types\_supported? {#grant-types-supported} - -```ts -optional grant_types_supported: string[]; -``` - -이 인가 서버가 지원하는 OAuth 2.0 grant type 값의 목록을 포함하는 JSON 배열입니다. 배열 값은 "OAuth 2.0 Dynamic Client Registration Protocol" [[RFC7591](https://www.rfc-editor.org/rfc/rfc7591)]에서 정의된 `grant_types` 파라미터와 동일하게 사용됩니다. -생략된 경우 기본값은 `["authorization_code", "implicit"]`입니다. - -### introspection\_endpoint? {#introspection-endpoint} - -```ts -optional introspection_endpoint: string; -``` - -인가 서버의 OAuth 2.0 인트로스펙션 엔드포인트 URL [[RFC7662](https://www.rfc-editor.org/rfc/rfc7662)]. - -### introspection\_endpoint\_auth\_methods\_supported? {#introspection-endpoint-auth-methods-supported} - -```ts -optional introspection_endpoint_auth_methods_supported: string[]; -``` - -### introspection\_endpoint\_auth\_signing\_alg\_values\_supported? {#introspection-endpoint-auth-signing-alg-values-supported} - -```ts -optional introspection_endpoint_auth_signing_alg_values_supported: string[]; -``` - -### issuer {#issuer} - -```ts -issuer: string; -``` - -인가 서버의 발급자 (Issuer) 식별자입니다. `https` 스킴을 사용하며 쿼리 또는 프래그먼트 컴포넌트가 없는 URL입니다. - -### jwks\_uri? {#jwks-uri} - -```ts -optional jwks_uri: string; -``` - -인가 서버의 JWK Set [[JWK](https://www.rfc-editor.org/rfc/rfc8414.html#ref-JWK)] 문서의 URL입니다. 참조된 문서에는 인가 서버의 서명을 검증하기 위해 클라이언트가 사용하는 서명 키가 포함되어 있습니다. 이 URL은 반드시 `https` 스킴을 사용해야 합니다. - -### op\_policy\_uri? {#op-policy-uri} - -```ts -optional op_policy_uri: string; -``` - -### op\_tos\_uri? {#op-tos-uri} - -```ts -optional op_tos_uri: string; -``` - -### registration\_endpoint? {#registration-endpoint} - -```ts -optional registration_endpoint: string; -``` - -인가 서버의 OAuth 2.0 동적 클라이언트 등록 엔드포인트 URL [[RFC7591](https://www.rfc-editor.org/rfc/rfc7591)]. - -### response\_modes\_supported? {#response-modes-supported} - -```ts -optional response_modes_supported: string[]; -``` - -이 인가 서버가 지원하는 OAuth 2.0 `response_mode` 값의 목록을 포함하는 JSON 배열입니다. "OAuth 2.0 Multiple Response Type Encoding Practices" [[OAuth.Responses](https://datatracker.ietf.org/doc/html/rfc8414#ref-OAuth.Responses)]에서 명시되어 있습니다. - -생략된 경우 기본값은 `["query", "fragment"]`입니다. `"form_post"` 응답 모드는 "OAuth 2.0 Form Post Response Mode" [[OAuth.FormPost](https://datatracker.ietf.org/doc/html/rfc8414#ref-OAuth.Post)]에서 정의되어 있습니다. - -### response\_types\_supported {#response-types-supported} - -```ts -response_types_supported: string[]; -``` - -이 인가 서버가 지원하는 OAuth 2.0 `response_type` 값의 목록을 포함하는 JSON 배열입니다. 배열 값은 "OAuth 2.0 Dynamic Client Registration Protocol" [[RFC7591](https://www.rfc-editor.org/rfc/rfc7591)]에서 정의된 `response_types` 파라미터와 동일하게 사용됩니다. - -### revocation\_endpoint? {#revocation-endpoint} - -```ts -optional revocation_endpoint: string; -``` - -인가 서버의 OAuth 2.0 토큰 폐기 엔드포인트 URL [[RFC7009](https://www.rfc-editor.org/rfc/rfc7009)]. - -### revocation\_endpoint\_auth\_methods\_supported? {#revocation-endpoint-auth-methods-supported} - -```ts -optional revocation_endpoint_auth_methods_supported: string[]; -``` - -### revocation\_endpoint\_auth\_signing\_alg\_values\_supported? {#revocation-endpoint-auth-signing-alg-values-supported} - -```ts -optional revocation_endpoint_auth_signing_alg_values_supported: string[]; -``` - -### scope\_supported? {#scope-supported} - -```ts -optional scope_supported: string[]; -``` - -### service\_documentation? {#service-documentation} - -```ts -optional service_documentation: string; -``` - -### token\_endpoint {#token-endpoint} - -```ts -token_endpoint: string; -``` - -인가 서버의 토큰 엔드포인트 URL [[RFC6749](https://rfc-editor.org/rfc/rfc6749)]. -암시적(implicit) grant type만 지원하는 경우를 제외하고 필수입니다. - -#### 참고 {#see} - -https://rfc-editor.org/rfc/rfc6749#section-3.2 - -### token\_endpoint\_auth\_methods\_supported? {#token-endpoint-auth-methods-supported} - -```ts -optional token_endpoint_auth_methods_supported: string[]; -``` - -### token\_endpoint\_auth\_signing\_alg\_values\_supported? {#token-endpoint-auth-signing-alg-values-supported} - -```ts -optional token_endpoint_auth_signing_alg_values_supported: string[]; -``` - -### ui\_locales\_supported? {#ui-locales-supported} - -```ts -optional ui_locales_supported: string[]; -``` - -### userinfo\_endpoint? {#userinfo-endpoint} - -```ts -optional userinfo_endpoint: string; -``` - -OpenID Connect [userinfo 엔드포인트](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)의 URL입니다. -이 엔드포인트는 인증된 사용자에 대한 정보를 가져오는 데 사용됩니다. - -## 참고 {#see} - -https://datatracker.ietf.org/doc/html/rfc8414 \ No newline at end of file diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthConfig.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthConfig.md deleted file mode 100644 index e59958a..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthConfig.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -sidebar_label: BearerAuthConfig ---- - -# 타입 별칭: BearerAuthConfig - -```ts -type BearerAuthConfig = { - audience?: string; - issuer: string; - requiredScopes?: string[]; - showErrorDetails?: boolean; - verifyAccessToken: VerifyAccessTokenFunction; -}; -``` - -## 속성(Properties) {#properties} - -### audience? {#audience} - -```ts -optional audience: string; -``` - -액세스 토큰 (Access token)의 예상 대상 (audience) (`aud` 클레임 (Claim)). 일반적으로 토큰이 사용될 리소스 서버 (API)를 의미합니다. 이 값이 제공되지 않으면 대상 (Audience) 확인이 생략됩니다. - -**참고:** 인가 서버가 리소스 지표 (Resource Indicators, RFC 8707)를 지원하지 않는 경우, 대상 (Audience)이 관련 없을 수 있으므로 이 필드를 생략할 수 있습니다. - -#### 참고(See) {#see} - -https://datatracker.ietf.org/doc/html/rfc8707 - -*** - -### issuer {#issuer} - -```ts -issuer: string; -``` - -액세스 토큰 (Access token)의 예상 발급자 (Issuer) (`iss` 클레임 (Claim)). 토큰을 발급한 인가 서버의 URL이어야 합니다. - -*** - -### requiredScopes? {#requiredscopes} - -```ts -optional requiredScopes: string[]; -``` - -액세스 토큰 (Access token)이 반드시 포함해야 하는 스코프 (Scope) 배열입니다. 토큰에 이 모든 스코프 (Scope)가 없으면 오류가 발생합니다. - -**참고:** 핸들러는 토큰의 `scope` 클레임 (Claim)을 확인합니다. 이 값은 인가 서버의 구현에 따라 공백으로 구분된 문자열이거나 문자열 배열일 수 있습니다. 만약 `scope` 클레임 (Claim)이 없으면, 핸들러는 `scopes` 클레임 (Claim)이 있는지 확인합니다. - -*** - -### showErrorDetails? {#showerrordetails} - -```ts -optional showErrorDetails: boolean; -``` - -응답에 상세 오류 정보를 표시할지 여부입니다. 개발 중 디버깅에 유용하지만, 민감한 정보 노출을 방지하기 위해 운영 환경에서는 비활성화해야 합니다. - -#### 기본값(Default) {#default} - -```ts -false -``` - -*** - -### verifyAccessToken {#verifyaccesstoken} - -```ts -verifyAccessToken: VerifyAccessTokenFunction; -``` - -액세스 토큰 (Access token) 검증을 위한 함수 타입입니다. - -이 함수는 토큰이 유효하지 않은 경우 [MCPAuthTokenVerificationError](/references/js/classes/MCPAuthTokenVerificationError.md)를 throw 하거나, 토큰이 유효한 경우 AuthInfo 객체를 반환해야 합니다. - -#### 참고(See) {#see} - -[VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md)에서 자세한 내용을 확인하세요. diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthErrorCode.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthErrorCode.md deleted file mode 100644 index d536d4d..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthErrorCode.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_label: BearerAuthErrorCode ---- - -# 타입 별칭: BearerAuthErrorCode - -```ts -type BearerAuthErrorCode = - | "missing_auth_header" - | "invalid_auth_header_format" - | "missing_bearer_token" - | "invalid_issuer" - | "invalid_audience" - | "missing_required_scopes" - | "invalid_token"; -``` diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthJwtConfig.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthJwtConfig.md deleted file mode 100644 index 1908bdc..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthJwtConfig.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -sidebar_label: BearerAuthJwtConfig ---- - -# 타입 별칭: BearerAuthJwtConfig - -```ts -type BearerAuthJwtConfig = { - jwtVerify?: JWTVerifyOptions; - remoteJwkSet?: RemoteJWKSetOptions; -}; -``` - -JWT 검증을 사용할 때 Bearer 인증 핸들러를 위한 구성입니다. - -## 속성(Properties) {#properties} - -### jwtVerify? {#jwtverify} - -```ts -optional jwtVerify: JWTVerifyOptions; -``` - -`jose` 라이브러리의 `jwtVerify` 함수에 전달할 옵션입니다. - -#### 참고(See) {#see} - -옵션의 타입 정의는 JWTVerifyOptions를 참고하세요. - -*** - -### remoteJwkSet? {#remotejwkset} - -```ts -optional remoteJwkSet: RemoteJWKSetOptions; -``` - -`jose` 라이브러리의 `createRemoteJWKSet` 함수에 전달할 옵션입니다. - -#### 참고(See) {#see} - -옵션의 타입 정의는 RemoteJWKSetOptions를 참고하세요. diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md deleted file mode 100644 index e85e445..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -sidebar_label: CamelCaseAuthorizationServerMetadata ---- - -# 타입 별칭: CamelCaseAuthorizationServerMetadata - -```ts -type CamelCaseAuthorizationServerMetadata = { - authorizationEndpoint: string; - codeChallengeMethodsSupported?: string[]; - grantTypesSupported?: string[]; - introspectionEndpoint?: string; - introspectionEndpointAuthMethodsSupported?: string[]; - introspectionEndpointAuthSigningAlgValuesSupported?: string[]; - issuer: string; - jwksUri?: string; - opPolicyUri?: string; - opTosUri?: string; - registrationEndpoint?: string; - responseModesSupported?: string[]; - responseTypesSupported: string[]; - revocationEndpoint?: string; - revocationEndpointAuthMethodsSupported?: string[]; - revocationEndpointAuthSigningAlgValuesSupported?: string[]; - scopeSupported?: string[]; - serviceDocumentation?: string; - tokenEndpoint: string; - tokenEndpointAuthMethodsSupported?: string[]; - tokenEndpointAuthSigningAlgValuesSupported?: string[]; - uiLocalesSupported?: string[]; - userinfoEndpoint?: string; -}; -``` - -OAuth 2.0 인가 서버 메타데이터 (Authorization Server Metadata) 타입의 camelCase 버전입니다. - -## 타입 선언 {#type-declaration} - -### authorizationEndpoint {#authorizationendpoint} - -```ts -authorizationEndpoint: string; -``` - -### codeChallengeMethodsSupported? {#codechallengemethodssupported} - -```ts -optional codeChallengeMethodsSupported: string[]; -``` - -### grantTypesSupported? {#granttypessupported} - -```ts -optional grantTypesSupported: string[]; -``` - -### introspectionEndpoint? {#introspectionendpoint} - -```ts -optional introspectionEndpoint: string; -``` - -### introspectionEndpointAuthMethodsSupported? {#introspectionendpointauthmethodssupported} - -```ts -optional introspectionEndpointAuthMethodsSupported: string[]; -``` - -### introspectionEndpointAuthSigningAlgValuesSupported? {#introspectionendpointauthsigningalgvaluessupported} - -```ts -optional introspectionEndpointAuthSigningAlgValuesSupported: string[]; -``` - -### issuer {#issuer} - -```ts -issuer: string; -``` - -### jwksUri? {#jwksuri} - -```ts -optional jwksUri: string; -``` - -### opPolicyUri? {#oppolicyuri} - -```ts -optional opPolicyUri: string; -``` - -### opTosUri? {#optosuri} - -```ts -optional opTosUri: string; -``` - -### registrationEndpoint? {#registrationendpoint} - -```ts -optional registrationEndpoint: string; -``` - -### responseModesSupported? {#responsemodessupported} - -```ts -optional responseModesSupported: string[]; -``` - -### responseTypesSupported {#responsetypessupported} - -```ts -responseTypesSupported: string[]; -``` - -### revocationEndpoint? {#revocationendpoint} - -```ts -optional revocationEndpoint: string; -``` - -### revocationEndpointAuthMethodsSupported? {#revocationendpointauthmethodssupported} - -```ts -optional revocationEndpointAuthMethodsSupported: string[]; -``` - -### revocationEndpointAuthSigningAlgValuesSupported? {#revocationendpointauthsigningalgvaluessupported} - -```ts -optional revocationEndpointAuthSigningAlgValuesSupported: string[]; -``` - -### scopeSupported? {#scopesupported} - -```ts -optional scopeSupported: string[]; -``` - -### serviceDocumentation? {#servicedocumentation} - -```ts -optional serviceDocumentation: string; -``` - -### tokenEndpoint {#tokenendpoint} - -```ts -tokenEndpoint: string; -``` - -### tokenEndpointAuthMethodsSupported? {#tokenendpointauthmethodssupported} - -```ts -optional tokenEndpointAuthMethodsSupported: string[]; -``` - -### tokenEndpointAuthSigningAlgValuesSupported? {#tokenendpointauthsigningalgvaluessupported} - -```ts -optional tokenEndpointAuthSigningAlgValuesSupported: string[]; -``` - -### uiLocalesSupported? {#uilocalessupported} - -```ts -optional uiLocalesSupported: string[]; -``` - -### userinfoEndpoint? {#userinfoendpoint} - -```ts -optional userinfoEndpoint: string; -``` - -## 참고 {#see} - -원본 타입 및 필드 정보는 [AuthorizationServerMetadata](/references/js/type-aliases/AuthorizationServerMetadata.md) 를 참고하세요. diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md deleted file mode 100644 index a1407ff..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -sidebar_label: MCPAuthBearerAuthErrorDetails ---- - -# 타입 별칭: MCPAuthBearerAuthErrorDetails - -```ts -type MCPAuthBearerAuthErrorDetails = { - actual?: unknown; - cause?: unknown; - expected?: unknown; - missingScopes?: string[]; - uri?: URL; -}; -``` - -## 속성 {#properties} - -### actual? {#actual} - -```ts -optional actual: unknown; -``` - -*** - -### cause? {#cause} - -```ts -optional cause: unknown; -``` - -*** - -### expected? {#expected} - -```ts -optional expected: unknown; -``` - -*** - -### missingScopes? {#missingscopes} - -```ts -optional missingScopes: string[]; -``` - -*** - -### uri? {#uri} - -```ts -optional uri: URL; -``` diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthConfig.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthConfig.md deleted file mode 100644 index 10614e5..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthConfig.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -sidebar_label: MCPAuthConfig ---- - -# 타입 별칭: MCPAuthConfig - -```ts -type MCPAuthConfig = { - server: AuthServerConfig; -}; -``` - -[MCPAuth](/references/js/classes/MCPAuth.md) 클래스에 대한 설정입니다. - -## 속성 {#properties} - -### server {#server} - -```ts -server: AuthServerConfig; -``` - -원격 인가 (Authorization) 서버에 대한 설정입니다. diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md deleted file mode 100644 index edaf9a6..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: MCPAuthTokenVerificationErrorCode ---- - -# 타입 별칭: MCPAuthTokenVerificationErrorCode (Type Alias: MCPAuthTokenVerificationErrorCode) - -```ts -type MCPAuthTokenVerificationErrorCode = "invalid_token" | "token_verification_failed"; -``` diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenFunction.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenFunction.md deleted file mode 100644 index 9d84296..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenFunction.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -sidebar_label: VerifyAccessTokenFunction ---- - -# 타입 별칭: VerifyAccessTokenFunction() - -```ts -type VerifyAccessTokenFunction = (token: string) => MaybePromise; -``` - -액세스 토큰 (Access token) 검증을 위한 함수 타입입니다. - -이 함수는 토큰이 유효하지 않은 경우 [MCPAuthTokenVerificationError](/references/js/classes/MCPAuthTokenVerificationError.md)를 throw 해야 하며, -토큰이 유효한 경우 AuthInfo 객체를 반환해야 합니다. - -예를 들어, JWT 검증 함수가 있다면, 최소한 토큰의 서명, 만료 여부를 확인하고 필요한 클레임 (Claim)을 추출하여 `AuthInfo` -객체를 반환해야 합니다. - -**참고:** 다음 필드는 핸들러에서 확인하므로 토큰에서 별도로 검증할 필요가 없습니다: - -- `iss` (발급자 (Issuer)) -- `aud` (대상 (Audience)) -- `scope` (스코프 (Scopes)) - -## 매개변수 {#parameters} - -### token {#token} - -`string` - -검증할 액세스 토큰 (Access token) 문자열입니다. - -## 반환값 {#returns} - -`MaybePromise`\<`AuthInfo`\> - -토큰이 유효한 경우 AuthInfo 객체 또는 동기 값으로 resolve 되는 promise 입니다. diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenMode.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenMode.md deleted file mode 100644 index 3a63d5d..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenMode.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: VerifyAccessTokenMode ---- - -# 타입 별칭: VerifyAccessTokenMode - -```ts -type VerifyAccessTokenMode = "jwt"; -``` diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authServerErrorDescription.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authServerErrorDescription.md deleted file mode 100644 index a143d01..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authServerErrorDescription.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: authServerErrorDescription ---- - -# 변수: authServerErrorDescription - -```ts -const authServerErrorDescription: Readonly>; -``` diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authorizationServerMetadataSchema.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authorizationServerMetadataSchema.md deleted file mode 100644 index e5b36ab..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authorizationServerMetadataSchema.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: authorizationServerMetadataSchema ---- - -# 변수: authorizationServerMetadataSchema - -```ts -const authorizationServerMetadataSchema: ZodObject; -``` - -RFC 8414에서 정의된 OAuth 2.0 인가 서버 메타데이터 (Authorization Server Metadata)를 위한 Zod 스키마입니다. - -## 참고 {#see} - -https://datatracker.ietf.org/doc/html/rfc8414 \ No newline at end of file diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/bearerAuthErrorDescription.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/bearerAuthErrorDescription.md deleted file mode 100644 index f8cb15e..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/bearerAuthErrorDescription.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: bearerAuthErrorDescription ---- - -# 변수: bearerAuthErrorDescription (bearerAuthErrorDescription) - -```ts -const bearerAuthErrorDescription: Readonly>; -``` diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md deleted file mode 100644 index 948b360..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: camelCaseAuthorizationServerMetadataSchema ---- - -# 변수: camelCaseAuthorizationServerMetadataSchema - -```ts -const camelCaseAuthorizationServerMetadataSchema: ZodObject; -``` - -OAuth 2.0 인가 서버 메타데이터 (Authorization Server Metadata)의 camelCase 버전 Zod 스키마입니다. - -## 참고 {#see} - -원본 스키마 및 필드 정보는 [authorizationServerMetadataSchema](/references/js/variables/authorizationServerMetadataSchema.md)를 참고하세요. diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/serverMetadataPaths.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/serverMetadataPaths.md deleted file mode 100644 index 81b2ee3..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/serverMetadataPaths.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_label: serverMetadataPaths ---- - -# 변수: serverMetadataPaths - -```ts -const serverMetadataPaths: Readonly<{ - oauth: "/.well-known/oauth-authorization-server"; - oidc: "/.well-known/openid-configuration"; -}>; -``` diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/tokenVerificationErrorDescription.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/tokenVerificationErrorDescription.md deleted file mode 100644 index 8442d41..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/tokenVerificationErrorDescription.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: tokenVerificationErrorDescription ---- - -# 변수: tokenVerificationErrorDescription (tokenVerificationErrorDescription) - -```ts -const tokenVerificationErrorDescription: Readonly>; -``` diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/validateServerConfig.md b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/validateServerConfig.md deleted file mode 100644 index b686996..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/validateServerConfig.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: validateServerConfig ---- - -# 변수: validateServerConfig - -```ts -const validateServerConfig: ValidateServerConfig; -``` diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/snippets/_get-started-code.mdx b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/snippets/_get-started-code.mdx deleted file mode 100644 index c7a5319..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/snippets/_get-started-code.mdx +++ /dev/null @@ -1,41 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - - - - - -```python -mcp = FastMCP("MyMCPServer") -mcp_auth = MCPAuth(server=fetch_server_config('', type=AuthServerType.OIDC)) -app = Starlette( - # ... MCP 서버 설정 - middleware=[Middleware( - mcp_auth.bearer_auth_middleware("jwt", required_scopes=["read", "write"]) - )] -) - -# 현재 요청에 대한 인증 (Authentication) 정보를 얻으려면 `mcp_auth.auth_info`를 사용하세요 -@mcp.tool() -def whoami() -> dict[str, Any]: - return mcp_auth.auth_info.claims -``` - - - - -```ts -const server = new McpServer(/* ... */); -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { type: 'oidc' }), -}); -const app = express(); - -app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] })); -server.tool('whoami', ({ authInfo }) => { - // `authInfo`를 사용하여 `req.auth`에서 전달된 인증 (Authentication) 정보를 확인하세요 -}); -``` - - - diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/README.mdx b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/README.mdx deleted file mode 100644 index bc8b779..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/README.mdx +++ /dev/null @@ -1,1143 +0,0 @@ ---- -sidebar_position: 2 -sidebar_label: '튜토리얼: 할 일 관리 앱 만들기' ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import SetupOauthOrOidc from './_setup-oauth-or-oidc.mdx'; -import SetupOidc from './_setup-oidc.mdx'; - -# 튜토리얼: 할 일 관리 앱 만들기 (Tutorial: Build a todo manager) - -이 튜토리얼에서는 사용자 인증 (Authentication) 및 인가 (Authorization)가 적용된 todo manager MCP 서버를 만들어봅니다. - -이 튜토리얼을 완료하면 다음을 얻게 됩니다: - -- ✅ MCP 서버에서 역할 기반 접근 제어 (RBAC)에 대한 기본적인 이해 -- ✅ 개인 할 일 목록을 관리할 수 있는 MCP 서버 - -:::note -시작하기 전에, MCP 서버와 OAuth 2에 익숙하지 않다면 [Who am I 튜토리얼](./whoami)을 먼저 진행하는 것을 강력히 권장합니다. -::: - -## 개요 (Overview) \{#overview} - -이 튜토리얼에는 다음과 같은 구성 요소가 포함됩니다: - -- **MCP 서버**: MCP 공식 SDK를 사용하여 요청을 처리하고, 사용자의 할 일 항목을 관리하는 Todo 서비스를 통합한 간단한 MCP 서버 -- **MCP inspector**: MCP 서버를 시각적으로 테스트할 수 있는 도구. OAuth / OIDC 클라이언트 역할도 하여 인가 플로우를 시작하고 액세스 토큰을 가져옵니다. -- **인가 서버 (Authorization server)**: 사용자 아이덴티티를 관리하고 액세스 토큰을 발급하는 OAuth 2.1 또는 OpenID Connect 제공자 - -아래는 이 구성 요소들 간의 상호작용을 나타낸 고수준 다이어그램입니다: - -```mermaid -sequenceDiagram - participant Client as MCP Inspector - participant Server as MCP Server - participant Auth as 인가 서버 (Authorization Server) - - Client->>Server: 할 일 작업 요청 - Server->>Client: 401 인가되지 않음 반환 - Client->>Auth: 인가 플로우 시작 - Auth->>Auth: 인가 플로우 완료 - Auth->>Client: 인가 코드와 함께 리디렉션 - Client->>Auth: 코드로 액세스 토큰 교환 - Auth->>Client: 액세스 토큰 반환 - Client->>Server: 액세스 토큰과 함께 할 일 작업 요청 - Server->>Server: 액세스 토큰 검증 및 사용자 스코프 추출 - Note over Server: 할 일 작업 실행 - Server->>Client: 할 일 작업 결과 반환 -``` - -## 인가 서버 이해하기 (Understand your authorization server) \{#understand-your-authorization-server} - -### 스코프가 포함된 액세스 토큰 (Access tokens with scopes) \{#access-tokens-with-scopes} - -[MCP 서버에서 역할 기반 접근 제어 (RBAC)](https://auth.wiki/rbac)를 구현하려면, 인가 서버가 스코프가 포함된 액세스 토큰 발급을 지원해야 합니다. 스코프는 사용자가 부여받은 권한을 나타냅니다. - - - - -[Logto](https://logto.io)는 API 리소스([RFC 8707: OAuth 2.0을 위한 리소스 지표](https://datatracker.ietf.org/doc/html/rfc8707)) 및 역할 기능을 통해 RBAC를 지원합니다. 설정 방법은 다음과 같습니다: - -1. [Logto Console](https://cloud.logto.io) (또는 자체 호스팅 Logto Console)에 로그인하세요. - -2. API 리소스 및 스코프 생성: - - - "API Resources"로 이동 - - "Todo Manager"라는 새 API 리소스 생성 - - 다음 스코프 추가: - - `create:todos`: "새 할 일 항목 생성" - - `read:todos`: "모든 할 일 항목 읽기" - - `delete:todos`: "모든 할 일 항목 삭제" - -3. 역할 생성(관리를 쉽게 하기 위해 권장): - - - "Roles"로 이동 - - "Admin" 역할을 생성하고 모든 스코프(`create:todos`, `read:todos`, `delete:todos`) 할당 - - "User" 역할을 생성하고 `create:todos` 스코프만 할당 - -4. 권한 할당: - - "Users"로 이동 - - 사용자를 선택 - - "Roles" 탭에서 역할을 할당(권장) - - 또는 "Permissions" 탭에서 직접 스코프 할당 - -스코프는 JWT 액세스 토큰의 `scope` 클레임에 공백으로 구분된 문자열로 포함됩니다. - - - - -OAuth 2.0 / OIDC 제공자는 일반적으로 스코프 기반 접근 제어를 지원합니다. RBAC를 구현할 때: - -1. 인가 서버에서 필요한 스코프 정의 -2. 클라이언트가 인가 플로우 중에 이 스코프를 요청하도록 구성 -3. 인가 서버가 부여된 스코프를 액세스 토큰에 포함하는지 확인 -4. 스코프는 보통 JWT 액세스 토큰의 `scope` 클레임에 포함됨 - -스코프 정의 및 관리 방법, 액세스 토큰에 스코프가 포함되는 방식, 역할 관리 등 추가 RBAC 기능은 제공자 문서를 참고하세요. - - - - -### 토큰 검증 및 권한 확인 (Validating tokens and checking permissions) \{#validating-tokens-and-checking-permissions} - -MCP 서버가 요청을 받으면 다음을 수행해야 합니다: - -1. 액세스 토큰의 서명 및 만료 검증 -2. 검증된 토큰에서 스코프 추출 -3. 요청된 작업에 필요한 스코프가 토큰에 포함되어 있는지 확인 - -예를 들어, 사용자가 새 할 일 항목을 생성하려면 액세스 토큰에 `create:todos` 스코프가 포함되어 있어야 합니다. 플로우는 다음과 같습니다: - -```mermaid -sequenceDiagram - participant Client - participant MCP Server - participant Auth Server - - Client->>MCP Server: 액세스 토큰과 함께 요청 - - alt JWT 검증 - MCP Server->>Auth Server: JWKS 가져오기 - Auth Server-->>MCP Server: JWKS 반환 - MCP Server->>MCP Server: JWT 로컬 검증 - else 토큰 인트로스펙션 - MCP Server->>Auth Server: POST /introspect
(token=access_token) - Auth Server-->>MCP Server: 토큰 정보 반환
(active, scope 등) - end - - MCP Server->>MCP Server: 스코프 추출 및 확인 - - alt 필요한 스코프 있음 - MCP Server->>Client: 작업 허용 - else 스코프 부족 - MCP Server->>Client: 403 금지 반환 - end -``` - -### 동적 클라이언트 등록 (Dynamic Client Registration) \{#dynamic-client-registration} - -이 튜토리얼에서는 동적 클라이언트 등록이 필수는 아니지만, 인가 서버에 MCP 클라이언트 등록을 자동화하고 싶다면 유용할 수 있습니다. 자세한 내용은 [동적 클라이언트 등록이 필요한가요?](/provider-list#is-dcr-required)를 참고하세요. - -## 할 일 관리 앱에서 RBAC 이해하기 (Understand RBAC in todo manager) \{#understand-rbac-in-todo-manager} - -데모 목적상, todo manager MCP 서버에 간단한 역할 기반 접근 제어 (RBAC) 시스템을 구현합니다. 이를 통해 RBAC의 기본 원리를 쉽게 이해할 수 있습니다. - -:::note -이 튜토리얼은 RBAC 기반 스코프 관리를 시연하지만, 모든 인증 (Authentication) 제공자가 역할을 통한 스코프 관리를 구현하는 것은 아닙니다. 일부 제공자는 자체적인 접근 제어 및 권한 관리 방식을 가질 수 있습니다. -::: - -### 도구와 스코프 (Tools and scopes) \{#tools-and-scopes} - -todo manager MCP 서버는 세 가지 주요 도구를 제공합니다: - -- `create-todo`: 새 할 일 항목 생성 -- `get-todos`: 모든 할 일 목록 조회 -- `delete-todo`: ID로 할 일 삭제 - -이 도구들에 대한 접근을 제어하기 위해 다음과 같은 스코프를 정의합니다: - -- `create:todos`: 새 할 일 항목 생성 허용 -- `delete:todos`: 기존 할 일 항목 삭제 허용 -- `read:todos`: 모든 할 일 목록 조회 및 검색 허용 - -### 역할과 권한 (Roles and permissions) \{#roles-and-permissions} - -접근 수준이 다른 두 가지 역할을 정의합니다: - -| 역할 (Role) | create:todos | read:todos | delete:todos | -| ----------- | ------------ | ---------- | ------------ | -| Admin | ✅ | ✅ | ✅ | -| User | ✅ | | | - -- **User**: 자신의 할 일만 생성, 조회, 삭제할 수 있는 일반 사용자 -- **Admin**: 모든 할 일을 생성, 조회, 삭제할 수 있는 관리자 - -### 리소스 소유권 (Resource ownership) \{#resource-ownership} - -위의 권한 테이블은 각 역할에 명시적으로 할당된 스코프를 보여주지만, 리소스 소유권이라는 중요한 원칙이 있습니다: - -- **User**는 `read:todos` 또는 `delete:todos` 스코프가 없지만, - - 자신의 할 일 항목은 읽을 수 있고 - - 자신의 할 일 항목은 삭제할 수 있습니다. -- **Admin**은 전체 권한(`read:todos`, `delete:todos`)을 가지므로, - - 시스템의 모든 할 일 항목을 볼 수 있고 - - 소유자와 관계없이 모든 할 일 항목을 삭제할 수 있습니다. - -이는 RBAC 시스템에서 리소스 소유권이 사용자의 자신의 리소스에 대한 암묵적 권한을 부여하고, 관리자는 모든 리소스에 대한 명시적 권한을 받는 일반적인 패턴을 보여줍니다. - -:::tip 더 알아보기 -RBAC 개념과 모범 사례를 더 깊이 이해하려면 [Mastering RBAC: A Comprehensive Real-World Example](https://blog.logto.io/mastering-rbac)을 참고하세요. -::: - -## 제공자에서 인가 설정하기 (Configure authorization in your provider) \{#configure-authorization-in-your-provider} - -앞서 설명한 접근 제어 시스템을 구현하려면, 인가 서버에서 필요한 스코프를 지원하도록 설정해야 합니다. 제공자별 설정 방법은 다음과 같습니다: - - - - -[Logto](https://logto.io)는 API 리소스와 역할 기능을 통해 RBAC를 지원합니다. 설정 방법은 다음과 같습니다: - -1. [Logto Console](https://cloud.logto.io) (또는 자체 호스팅 Logto Console)에 로그인하세요. - -2. API 리소스 및 스코프 생성: - - - "API Resources"로 이동 - - "Todo Manager"라는 새 API 리소스를 생성하고, 인디케이터로 `https://todo.mcp-server.app`(데모 목적)를 사용하세요. - - 다음 스코프 생성: - - `create:todos`: "새 할 일 항목 생성" - - `read:todos`: "모든 할 일 항목 읽기" - - `delete:todos`: "모든 할 일 항목 삭제" - -3. 역할 생성(관리를 쉽게 하기 위해 권장): - - - "Roles"로 이동 - - "Admin" 역할을 생성하고 모든 스코프(`create:todos`, `read:todos`, `delete:todos`) 할당 - - "User" 역할을 생성하고 `create:todos` 스코프만 할당 - - "User" 역할 상세 페이지에서 "General" 탭으로 이동하여 "Default role"로 설정 - -4. 사용자 역할 및 권한 관리: - - 신규 사용자: - - "User" 역할이 기본 역할로 자동 할당됨 - - 기존 사용자: - - "User management"로 이동 - - 사용자를 선택 - - "Roles" 탭에서 역할 할당 - -:::tip 프로그래밍 방식의 역할 관리 -Logto의 [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api)를 사용하여 프로그래밍 방식으로 사용자 역할을 관리할 수 있습니다. 자동화된 사용자 관리나 관리자 패널 구축 시 유용합니다. -::: - -액세스 토큰을 요청할 때, Logto는 사용자 역할 권한에 따라 토큰의 `scope` 클레임에 스코프를 포함합니다. - - - - -[Keycloak](https://www.keycloak.org)에서는 클라이언트 스코프를 사용하여 필요한 권한을 설정할 수 있습니다: - -1. 클라이언트 스코프 생성: - - - Realm에서 "Client scopes"로 이동 - - 세 개의 클라이언트 스코프 생성: - - `create:todos` - - `read:todos` - - `delete:todos` - -2. 클라이언트 구성: - - - 클라이언트 설정으로 이동 - - "Client scopes" 탭에서 생성한 모든 스코프 추가 - - 토큰 매퍼가 스코프를 포함하도록 설정 - -3. 선택 사항: 역할을 통한 관리 - - 역할 기반 관리가 필요하다면: - - 접근 수준별로 Realm 역할 생성 - - 스코프를 역할에 매핑 - - 역할을 사용자에게 할당 - - 그렇지 않으면, 스코프를 사용자에게 직접 할당하거나 클라이언트 수준 권한을 통해 할당 - -Keycloak은 부여된 스코프를 액세스 토큰의 `scope` 클레임에 포함합니다. - - - - -OAuth 2.0 또는 OpenID Connect 제공자의 경우, 다양한 권한을 나타내는 스코프를 구성해야 합니다. 구체적인 단계는 제공자마다 다르지만, 일반적으로: - -1. 스코프 정의: - - - 인가 서버에서 다음을 지원하도록 구성: - - `create:todos` - - `read:todos` - - `delete:todos` - -2. 클라이언트 구성: - - - 클라이언트를 등록하거나 업데이트하여 이 스코프를 요청하도록 설정 - - 스코프가 액세스 토큰에 포함되는지 확인 - -3. 권한 할당: - - 제공자 인터페이스를 사용하여 사용자에게 적절한 스코프 부여 - - 일부 제공자는 역할 기반 관리, 일부는 직접 스코프 할당을 지원 - - 권장 접근 방식은 제공자 문서를 참고 - -:::tip -대부분의 제공자는 부여된 스코프를 액세스 토큰의 `scope` 클레임에 포함합니다. 형식은 일반적으로 공백으로 구분된 스코프 값 문자열입니다. -::: - - - - -인가 서버를 설정한 후, 사용자는 부여된 스코프가 포함된 액세스 토큰을 받게 됩니다. MCP 서버는 이 스코프를 사용하여 다음을 판단합니다: - -- 사용자가 새 할 일을 생성할 수 있는지 (`create:todos`) -- 사용자가 모든 할 일을 볼 수 있는지 (`read:todos`) 또는 자신의 할 일만 볼 수 있는지 -- 사용자가 모든 할 일을 삭제할 수 있는지 (`delete:todos`) 또는 자신의 할 일만 삭제할 수 있는지 - -## MCP 서버 설정하기 (Set up the MCP server) \{#set-up-the-mcp-server} - -[MCP 공식 SDK](https://github.com/modelcontextprotocol)를 사용하여 todo manager MCP 서버를 만듭니다. - -### 새 프로젝트 생성 (Create a new project) \{#create-a-new-project} - - - - -```bash -mkdir mcp-server -cd mcp-server -uv init # 또는 `pipenv` 또는 `poetry`로 새 가상환경 생성 -``` - - - - -새 Node.js 프로젝트를 설정하세요: - -```bash -mkdir mcp-server -cd mcp-server -npm init -y # 또는 `pnpm init` -npm pkg set type="module" -npm pkg set main="todo-manager.ts" -npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts" -``` - -:::note -예제에서는 Node.js v22.6.0+에서 `--experimental-strip-types` 플래그로 TypeScript를 네이티브로 실행할 수 있으므로 TypeScript를 사용합니다. JavaScript를 사용할 경우 코드가 유사하며, Node.js v22.6.0 이상을 사용해야 합니다. 자세한 내용은 Node.js 문서를 참고하세요. -::: - - - - -### MCP SDK 및 의존성 설치 (Install the MCP SDK and dependencies) \{#install-the-mcp-sdk-and-dependencies} - - - - -```bash -pip install "mcp[cli]" starlette uvicorn -``` - -또는 `uv`, `poetry` 등 원하는 패키지 매니저를 사용할 수 있습니다. - - - - -```bash -npm install @modelcontextprotocol/sdk express zod -``` - -또는 `pnpm`, `yarn` 등 원하는 패키지 매니저를 사용할 수 있습니다. - - - - -### MCP 서버 만들기 (Create the MCP server) \{#create-the-mcp-server} - -먼저, 도구 정의가 포함된 기본 MCP 서버를 만듭니다: - - - - -`todo-manager.py` 파일을 만들고 다음 코드를 추가하세요: - -```python -from typing import Any -from mcp.server.fastmcp import FastMCP -from starlette.applications import Starlette -from starlette.routing import Mount - -mcp = FastMCP("Todo Manager") - -@mcp.tool() -def create_todo(content: str) -> dict[str, Any]: - """새 할 일 생성.""" - return {"error": "Not implemented"} - -@mcp.tool() -def get_todos() -> dict[str, Any]: - """모든 할 일 목록 조회.""" - return {"error": "Not implemented"} - -@mcp.tool() -def delete_todo(id: str) -> dict[str, Any]: - """ID로 할 일 삭제.""" - return {"error": "Not implemented"} - -app = Starlette( - routes=[Mount('/', app=mcp.sse_app())] -) -``` - -서버 실행: - -```bash -uvicorn todo_manager:app --host 0.0.0.0 --port 3001 -``` - - - - -:::note -현재 MCP inspector 구현은 인가 플로우를 처리하지 않으므로, SSE 방식을 사용하여 MCP 서버를 설정합니다. MCP inspector가 인가 플로우를 지원하면 코드를 업데이트할 예정입니다. -::: - -`pnpm` 또는 `yarn`도 사용할 수 있습니다. - -`todo-manager.ts` 파일을 만들고 다음 코드를 추가하세요: - -```ts -// todo-manager.ts - -import { z } from 'zod'; -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; -import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'; -import express from 'express'; - -// MCP 서버 생성 -const server = new McpServer({ - name: 'Todo Manager', - version: '0.0.0', -}); - -server.tool('create-todo', '새 할 일 생성', { content: z.string() }, async ({ content }) => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }], - }; -}); - -server.tool('get-todos', '모든 할 일 목록 조회', async () => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }], - }; -}); - -server.tool('delete-todo', 'ID로 할 일 삭제', { id: z.string() }, async ({ id }) => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }], - }; -}); - -// 아래는 MCP SDK 문서의 보일러플레이트 코드 -const PORT = 3001; -const app = express(); - -const transports = {}; - -app.get('/sse', async (_req, res) => { - const transport = new SSEServerTransport('/messages', res); - transports[transport.sessionId] = transport; - - res.on('close', () => { - delete transports[transport.sessionId]; - }); - - await server.connect(transport); -}); - -app.post('/messages', async (req, res) => { - const sessionId = String(req.query.sessionId); - const transport = transports[sessionId]; - if (transport) { - await transport.handlePostMessage(req, res, req.body); - } else { - res.status(400).send('No transport found for sessionId'); - } -}); - -app.listen(PORT); -``` - -서버 실행: - -```bash -npm start -``` - - - - -## MCP 서버 검사하기 (Inspect the MCP server) \{#inspect-the-mcp-server} - -### MCP inspector 클론 및 실행 (Clone and run MCP inspector) \{#clone-and-run-mcp-inspector} - -이제 MCP 서버가 실행 중이므로, MCP inspector를 사용하여 `whoami` 도구가 사용 가능한지 확인할 수 있습니다. - -현재 구현의 한계로 인해, [MCP inspector](https://github.com/mcp-auth/inspector)를 포크하여 인증 (Authentication) 및 인가 (Authorization)에 더 유연하고 확장 가능하도록 개선했습니다. 변경 사항을 원본 저장소에 PR로 제출했습니다. - -MCP inspector를 실행하려면 다음 명령어를 사용하세요(Node.js 필요): - -```bash -git clone https://github.com/mcp-auth/inspector.git -cd inspector -npm install -npm run dev -``` - -그런 다음 브라우저에서 `http://localhost:6274/` (또는 터미널에 표시된 URL)로 접속하여 MCP inspector에 접근하세요. - -### MCP inspector를 MCP 서버에 연결 (Connect MCP inspector to the MCP server) \{#connect-mcp-inspector-to-the-mcp-server} - -진행하기 전에 MCP inspector에서 다음 설정을 확인하세요: - -- **Transport Type**: `SSE`로 설정 -- **URL**: MCP 서버의 URL로 설정. 여기서는 `http://localhost:3001/sse`가 됩니다. - -이제 "Connect" 버튼을 클릭하여 MCP inspector가 MCP 서버에 연결되는지 확인하세요. 정상적으로 연결되면 MCP inspector에서 "Connected" 상태를 볼 수 있습니다. - -### 체크포인트: 할 일 관리 도구 실행 (Checkpoint: Run todo manager tools) \{#checkpoint-run-todo-manager-tools} - -1. MCP inspector 상단 메뉴에서 "Tools" 탭 클릭 -2. "List Tools" 버튼 클릭 -3. `create-todo`, `get-todos`, `delete-todo` 도구가 페이지에 표시됩니다. 클릭하여 도구 상세 보기 -4. 우측에 "Run Tool" 버튼이 보입니다. 클릭 후 필요한 파라미터 입력하여 도구 실행 -5. JSON 응답 `{"error": "Not implemented"}`와 함께 도구 결과가 표시됩니다. - -![MCP inspector 첫 실행](/docs-assets/images/tutorials/todo-manager/inspector-first-run.png) - -## 인가 서버와 통합 (Integrate with your authorization server) \{#integrate-with-your-authorization-server} - -이 섹션을 완료하려면 다음 사항을 고려해야 합니다: - -
-**인가 서버의 발급자 URL (issuer URL)** - -일반적으로 인가 서버의 기본 URL입니다. 예: `https://auth.example.com`. 일부 제공자는 `https://example.logto.app/oidc`와 같이 경로가 포함될 수 있으니, 제공자 문서를 꼭 확인하세요. - -
- -
-**인가 서버 메타데이터 가져오기 방법** - -- 인가 서버가 [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) 또는 [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)를 준수한다면, MCP Auth 내장 유틸리티로 자동으로 메타데이터를 가져올 수 있습니다. -- 준수하지 않는 경우, MCP 서버 설정에서 메타데이터 URL 또는 엔드포인트를 수동으로 지정해야 합니다. 제공자 문서에서 엔드포인트를 확인하세요. - -
- -
-**MCP inspector를 인가 서버에 클라이언트로 등록하는 방법** - -- 인가 서버가 [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591)을 지원한다면, MCP inspector가 자동으로 클라이언트로 등록되므로 이 단계를 건너뛸 수 있습니다. -- 지원하지 않는 경우, MCP inspector를 인가 서버에 수동으로 클라이언트로 등록해야 합니다. - -
- -
-**토큰 요청 파라미터 이해하기** - -인가 서버에서 액세스 토큰을 요청할 때, 대상 리소스와 권한을 지정하는 다양한 방식이 있습니다. 주요 패턴은 다음과 같습니다: - -- **리소스 지표 기반**: - - - `resource` 파라미터로 대상 API 지정([RFC 8707: OAuth 2.0을 위한 리소스 지표](https://datatracker.ietf.org/doc/html/rfc8707) 참고) - - 최신 OAuth 2.0 구현에서 일반적 - - 예시 요청: - ```json - { - "resource": "https://todo.mcp-server.app", - "scope": "create:todos read:todos" - } - ``` - - 서버는 요청된 리소스에 바인딩된 토큰을 발급 - -- **Audience 기반**: - - - `audience` 파라미터로 토큰 수신자 지정 - - 리소스 지표와 유사하지만 의미가 다름 - - 예시 요청: - ```json - { - "audience": "todo-api", - "scope": "create:todos read:todos" - } - ``` - -- **순수 스코프 기반**: - - 리소스/audience 파라미터 없이 스코프만 사용 - - 전통적인 OAuth 2.0 방식 - - 예시 요청: - ```json - { - "scope": "todo-api:create todo-api:read openid profile" - } - ``` - - 권한 네임스페이스를 위해 접두어 스코프 사용 - - 간단한 OAuth 2.0 구현에서 일반적 - -:::tip 모범 사례 - -- 제공자 문서에서 지원되는 파라미터 확인 -- 일부 제공자는 여러 방식을 동시에 지원 -- 리소스 지표는 audience 제한을 통해 보안 강화 -- 가능하다면 리소스 지표 사용을 권장 - ::: - -
- -각 제공자마다 세부 요구사항이 다를 수 있지만, 아래 단계는 MCP inspector와 MCP 서버를 제공자별 설정과 통합하는 과정을 안내합니다. - -### MCP inspector를 클라이언트로 등록 (Register MCP inspector as a client) \{#register-mcp-inspector-as-a-client} - - - - -[Logto](https://logto.io)는 OpenID Connect 제공자로, 리소스 지표와 스코프를 지원하므로 `https://todo.mcp-server.app`를 리소스 지표로 사용하여 todo API를 안전하게 보호할 수 있습니다. - -Logto는 아직 동적 클라이언트 등록을 지원하지 않으므로, MCP inspector를 Logto 테넌트에 수동으로 클라이언트로 등록해야 합니다: - -1. MCP inspector를 열고 "OAuth Configuration" 버튼을 클릭하세요. **Redirect URL (auto-populated)** 값을 복사합니다(예: `http://localhost:6274/oauth/callback`). -2. [Logto Console](https://cloud.logto.io) (또는 자체 호스팅 Logto Console)에 로그인하세요. -3. "Applications" 탭으로 이동, "Create application" 클릭. 페이지 하단에서 "Create app without framework" 클릭. -4. 애플리케이션 세부 정보 입력 후 "Create application" 클릭: - - **Select an application type**: "Single-page application" 선택 - - **Application name**: 예: "MCP Inspector" -5. "Settings / Redirect URIs" 섹션에서 복사한 **Redirect URL (auto-populated)** 값을 붙여넣고, 하단 바에서 "Save changes" 클릭 -6. 상단 카드에서 "App ID" 값을 복사 -7. MCP inspector로 돌아가 "OAuth Configuration"의 "Client ID"에 "App ID" 값 붙여넣기 -8. "Auth Params" 필드에 `{"scope": "create:todos read:todos delete:todos", "resource": "https://todo.mcp-server.app"}` 입력. Logto가 todo manager에 필요한 스코프가 포함된 액세스 토큰을 반환하도록 합니다. - - - - -:::note -이 가이드는 일반적인 OAuth 2.0 / OpenID Connect 제공자 통합 가이드입니다. OIDC는 OAuth 2.0 위에 구축되어 있으므로 두 방식 모두 유사한 단계를 따릅니다. 구체적인 내용은 제공자 문서를 참고하세요. -::: - -제공자가 동적 클라이언트 등록을 지원한다면 아래 8번 단계로 바로 이동하여 MCP inspector를 설정하세요. 그렇지 않으면 MCP inspector를 수동으로 클라이언트로 등록해야 합니다: - -1. MCP inspector를 열고 "OAuth Configuration" 버튼을 클릭하세요. **Redirect URL (auto-populated)** 값을 복사합니다(예: `http://localhost:6274/oauth/callback`). - -2. 제공자 콘솔에 로그인하세요. - -3. "Applications" 또는 "Clients" 섹션으로 이동, 새 애플리케이션 또는 클라이언트 생성 - -4. 클라이언트 유형을 요구하는 경우 "Single-page application" 또는 "Public client" 선택 - -5. 애플리케이션 생성 후, 리디렉션 URI를 설정해야 합니다. MCP inspector에서 복사한 **Redirect URL (auto-populated)** 값을 붙여넣으세요. - -6. 새로 생성된 애플리케이션의 "Client ID" 또는 "Application ID"를 찾아 복사 - -7. MCP inspector로 돌아가 "OAuth Configuration"의 "Client ID"에 붙여넣기 - -8. "Auth Params" 필드에 다음 값을 입력하여 todo 작업에 필요한 스코프를 요청하세요: - -```json -{ "scope": "create:todos read:todos delete:todos" } -``` - - - - -### MCP Auth 설정 (Set up MCP auth) \{#set-up-mcp-auth} - -MCP 서버 프로젝트에서 MCP Auth SDK를 설치하고, 인가 서버 메타데이터를 사용하도록 구성해야 합니다. - - - - -먼저 `mcpauth` 패키지를 설치하세요: - -```bash -pip install mcpauth -``` - -또는 `uv`, `poetry` 등 원하는 패키지 매니저를 사용할 수 있습니다. - - - - -먼저 `mcp-auth` 패키지를 설치하세요: - -```bash -npm install mcp-auth -``` - - - - -MCP Auth는 인가 서버 메타데이터가 필요합니다. 제공자에 따라: - - - - - -발급자 URL(issuer URL)은 Logto Console의 애플리케이션 상세 페이지 "Endpoints & Credentials / Issuer endpoint" 섹션에서 확인할 수 있습니다. 예: `https://my-project.logto.app/oidc`. - - - - - - - -OAuth 2.0 제공자의 경우: - -1. 제공자 문서에서 인가 서버 URL(issuer URL 또는 base URL) 확인 -2. 일부 제공자는 `https://{your-domain}/.well-known/oauth-authorization-server`에서 노출 -3. 제공자 관리 콘솔의 OAuth/API 설정에서 확인 - - - - - - - - - - - -`todo-manager.py`를 업데이트하여 MCP Auth 구성을 추가하세요: - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # 발급자 엔드포인트로 교체 -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -`todo-manager.ts`를 업데이트하여 MCP Auth 구성을 추가하세요: - -```ts -// todo-manager.ts - -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // 발급자 엔드포인트로 교체 -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oidc' }), -}); -``` - - - - -### MCP 서버 업데이트 (Update MCP server) \{#update-mcp-server} - -거의 다 왔습니다! 이제 MCP Auth 라우트 및 미들웨어 함수를 적용하고, 사용자의 스코프에 기반한 권한 제어를 할 일 관리 도구에 구현합니다. - - - - -```python -@mcp.tool() -def create_todo(content: str) -> dict[str, Any]: - """새 할 일 생성.""" - return ( - mcp_auth.auth_info.scopes - if mcp_auth.auth_info # Bearer 인증 미들웨어에서 채워짐 - else {"error": "Not authenticated"} - ) - -# ... - -bearer_auth = Middleware(mcp_auth.bearer_auth_middleware("jwt")) -app = Starlette( - routes=[ - # 메타데이터 라우트 추가 (`/.well-known/oauth-authorization-server`) - mcp_auth.metadata_route(), - # Bearer 인증 미들웨어로 MCP 서버 보호 - Mount('/', app=mcp.sse_app(), middleware=[bearer_auth]), - ], -) -``` - - - - -```js -server.tool( - 'create-todo', - '새 할 일 생성', - { content: z.string() }, - async ({ content, authInfo }) => { - return { - content: [ - { type: 'text', text: JSON.stringify(authInfo?.scopes ?? { error: 'Not authenticated' }) }, - ], - }; - } -); - -// ... - -app.use(mcpAuth.delegatedRouter()); -app.use(mcpAuth.bearerAuth('jwt')); -``` - - - - -다음으로, 구체적인 도구를 구현해봅시다. - -먼저, 메모리 내에서 할 일 항목을 관리하는 간단한 todo 서비스를 만듭니다. - - - -```python -# service.py - -""" -데모용 간단한 Todo 서비스. -메모리 내 리스트로 todo를 저장합니다. -""" - -from datetime import datetime -from typing import List, Optional, Dict, Any -import random -import string - -class Todo: -"""할 일 항목을 나타냅니다.""" - - def __init__(self, id: str, content: str, owner_id: str, created_at: str): - self.id = id - self.content = content - self.owner_id = owner_id - self.created_at = created_at - - def to_dict(self) -> Dict[str, Any]: - """todo를 JSON 직렬화를 위한 딕셔너리로 변환.""" - return { - "id": self.id, - "content": self.content, - "ownerId": self.owner_id, - "createdAt": self.created_at - } - -class TodoService: -"""데모용 간단한 Todo 서비스.""" - - def __init__(self): - self._todos: List[Todo] = [] - - def get_all_todos(self, owner_id: Optional[str] = None) -> List[Dict[str, Any]]: - """ - 모든 todo 조회, owner_id로 필터링 가능 - - Args: - owner_id: 제공 시 해당 사용자의 todo만 반환 - - Returns: - todo 딕셔너리 리스트 - """ - if owner_id: - filtered_todos = [todo for todo in self._todos if todo.owner_id == owner_id] - return [todo.to_dict() for todo in filtered_todos] - return [todo.to_dict() for todo in self._todos] - - def get_todo_by_id(self, todo_id: str) -> Optional[Todo]: - """ - ID로 todo 조회 - - Args: - todo_id: 조회할 todo의 ID - - Returns: - 찾으면 Todo 객체, 아니면 None - """ - for todo in self._todos: - if todo.id == todo_id: - return todo - return None - - def create_todo(self, content: str, owner_id: str) -> Dict[str, Any]: - """ - 새 todo 생성 - - Args: - content: todo 내용 - owner_id: todo 소유자 ID - - Returns: - 생성된 todo의 딕셔너리 표현 - """ - todo = Todo( - id=self._generate_id(), - content=content, - owner_id=owner_id, - created_at=datetime.now().isoformat() - ) - self._todos.append(todo) - return todo.to_dict() - - def delete_todo(self, todo_id: str) -> Optional[Dict[str, Any]]: - """ - ID로 todo 삭제 - - Args: - todo_id: 삭제할 todo의 ID - - Returns: - 삭제된 todo의 딕셔너리 표현(찾으면), 아니면 None - """ - for i, todo in enumerate(self._todos): - if todo.id == todo_id: - deleted_todo = self._todos.pop(i) - return deleted_todo.to_dict() - return None - - def _generate_id(self) -> str: - """todo용 랜덤 ID 생성""" - return ''.join(random.choices(string.ascii_lowercase + string.digits, k=8)) - -```` - - - - - -```ts -// todo-service.ts - -type Todo = { - id: string; - content: string; - ownerId: string; - createdAt: string; -}; - -/** - * 데모용 간단한 Todo 서비스. - * 메모리 배열로 todo를 저장합니다. - */ -export class TodoService { - private readonly todos: Todo[] = []; - - getAllTodos(ownerId?: string): Todo[] { - if (ownerId) { - return this.todos.filter((todo) => todo.ownerId === ownerId); - } - return this.todos; - } - - getTodoById(id: string): Todo | undefined { - return this.todos.find((todo) => todo.id === id); - } - - createTodo({ content, ownerId }: { content: string; ownerId: string }): Todo { - const todo: Todo = { - id: this.genId(), - content, - ownerId, - createdAt: new Date().toISOString(), - }; - - // eslint-disable-next-line @silverhand/fp/no-mutating-methods - this.todos.push(todo); - return todo; - } - - deleteTodo(id: string): Todo | undefined { - const index = this.todos.findIndex((todo) => todo.id === id); - - if (index === -1) { - return undefined; - } - - // eslint-disable-next-line @silverhand/fp/no-mutating-methods - const [deleted] = this.todos.splice(index, 1); - return deleted; - } - - private genId(): string { - return Math.random().toString(36).slice(2, 10); - } -} -```` - - - - -이제 도구 계층에서 사용자의 스코프에 따라 작업 허용 여부를 결정합니다: - - - - -```python -# todo-manager.py - -from typing import Any, Optional -from mcpauth.errors import MCPAuthBearerAuthError - -def assert_user_id(auth_info: Optional[dict]) -> str: - """auth info에서 사용자 ID 추출 및 검증""" - subject = auth_info.get('subject') if auth_info else None - if not subject: - raise ValueError('Invalid auth info') - return subject - -def has_required_scopes(user_scopes: list[str], required_scopes: list[str]) -> bool: - """사용자가 모든 필수 스코프를 가지고 있는지 확인""" - return all(scope in user_scopes for scope in required_scopes) - -# TodoService 인스턴스 생성 -todo_service = TodoService() - -@mcp.tool() -def create_todo(content: str) -> dict[str, Any]: - """새 할 일 생성 - - 'create:todos' 스코프가 있는 사용자만 생성 가능 - """ - # 인증 정보 가져오기 - auth_info = mcp_auth.auth_info - - # 사용자 ID 검증 - try: - user_id = assert_user_id(auth_info) - except ValueError as e: - return {"error": str(e)} - - # 권한 확인 - if not has_required_scopes(auth_info.scopes if auth_info else [], ['create:todos']): - raise MCPAuthBearerAuthError('missing_required_scopes') - - # 새 todo 생성 - created_todo = todo_service.create_todo(content=content, owner_id=user_id) - - # 생성된 todo 반환 - return created_todo.__dict__ - -# ... -``` - -전체 구현 예시는 [샘플 코드](https://github.com/mcp-auth/python/tree/master/samples/server)를 참고하세요. - - - - -```ts -// todo-manager.ts - -// ... 기타 import -import assert from 'node:assert'; -import { type AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js'; -import { TodoService } from './todo-service.js'; - -const todoService = new TodoService(); - -const assertUserId = (authInfo?: AuthInfo) => { - const { subject } = authInfo ?? {}; - assert(subject, 'Invalid auth info'); - return subject; -}; - -/** - * 사용자가 작업에 필요한 모든 스코프를 가지고 있는지 확인 - */ -const hasRequiredScopes = (userScopes: string[], requiredScopes: string[]): boolean => { - return requiredScopes.every((scope) => userScopes.includes(scope)); -}; - -server.tool( - 'create-todo', - '새 할 일 생성', - { content: z.string() }, - ({ content }: { content: string }, { authInfo }) => { - const userId = assertUserId(authInfo); - - /** - * 'create:todos' 스코프가 있는 사용자만 생성 가능 - */ - if (!hasRequiredScopes(authInfo?.scopes ?? [], ['create:todos'])) { - throw new MCPAuthBearerAuthError('missing_required_scopes'); - } - - const createdTodo = todoService.createTodo({ content, ownerId: userId }); - - return { - content: [{ type: 'text', text: JSON.stringify(createdTodo) }], - }; - } -); - -// ... -``` - -전체 구현 예시는 [샘플 코드](https://github.com/mcp-auth/js/tree/master/packages/sample-servers/src/todo-manager)를 참고하세요. - - - - -## 체크포인트: `todo-manager` 도구 실행 (Checkpoint: Run the `todo-manager` tools) \{#checkpoint-run-the-todo-manager-tools} - -MCP 서버를 재시작하고 브라우저에서 MCP inspector를 엽니다. "Connect" 버튼을 클릭하면 인가 서버의 로그인 페이지로 리디렉션됩니다. - -로그인 후 MCP inspector로 돌아오면, 이전 체크포인트에서 했던 것처럼 todo manager 도구를 실행해보세요. 이번에는 인증된 사용자 아이덴티티로 도구를 사용할 수 있습니다. 도구의 동작은 사용자에게 할당된 역할과 권한에 따라 달라집니다: - -- **User**(오직 `create:todos` 스코프만 있는 경우)로 로그인했다면: - - `create-todo` 도구로 새 할 일 생성 가능 - - 자신의 할 일만 조회 및 삭제 가능 - - 다른 사용자의 할 일은 볼 수 없고 삭제할 수 없음 - -- **Admin**(모든 스코프: `create:todos`, `read:todos`, `delete:todos`가 있는 경우)로 로그인했다면: - - 새 할 일 생성 가능 - - `get-todos` 도구로 시스템의 모든 할 일 조회 가능 - - `delete-todo` 도구로 소유자와 관계없이 모든 할 일 삭제 가능 - -다른 권한 수준을 테스트하려면: - -1. 현재 세션에서 로그아웃(MCP inspector에서 "Disconnect" 클릭) -2. 다른 역할/권한을 가진 사용자 계정으로 로그인 -3. 동일한 도구를 다시 실행하여 권한에 따라 동작이 어떻게 달라지는지 확인 - -이렇게 하면 역할 기반 접근 제어 (RBAC)가 실제로 어떻게 동작하는지 체험할 수 있습니다. - -![MCP inspector todo manager 도구 결과](/docs-assets/images/tutorials/todo-manager/result.png) - - - - -:::info -MCP 서버( OIDC 버전 )의 전체 코드는 [MCP Auth Python SDK 저장소](https://github.com/mcp-auth/python/blob/master/samples/server/todo-manager/server.py)를 참고하세요. -::: - - - - -:::info -MCP 서버( OIDC 버전 )의 전체 코드는 [MCP Auth Node.js SDK 저장소](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src)를 참고하세요. -::: - - - - -## 마무리 (Closing notes) \{#closing-notes} - -🎊 축하합니다! 튜토리얼을 성공적으로 완료했습니다. 지금까지 한 일을 요약해봅시다: - -- 할 일 관리 도구(`create-todo`, `get-todos`, `delete-todo`)가 포함된 기본 MCP 서버 설정 -- 사용자와 관리자를 위한 다양한 권한 수준의 역할 기반 접근 제어 (RBAC) 구현 -- MCP Auth를 사용하여 MCP 서버를 인가 서버와 통합 -- MCP Inspector를 구성하여 사용자를 인증하고, 스코프가 포함된 액세스 토큰으로 도구 호출 - -MCP Auth를 최대한 활용하려면 다른 튜토리얼과 문서도 꼭 확인해보세요. diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_manual-metadata-fetching.mdx b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_manual-metadata-fetching.mdx deleted file mode 100644 index 07629a1..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_manual-metadata-fetching.mdx +++ /dev/null @@ -1,3 +0,0 @@ -:::note -만약 사용하시는 제공자가 {props.oidc ? 'OpenID Connect Discovery' : 'OAuth 2.0 인가 서버 메타데이터'}를 지원하지 않는 경우, 메타데이터 URL 또는 엔드포인트를 수동으로 지정할 수 있습니다. 자세한 내용은 [MCP Auth를 초기화하는 다른 방법](../../configure-server/mcp-auth.mdx#other-ways)을 확인하세요. -::: \ No newline at end of file diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oauth-or-oidc.mdx b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oauth-or-oidc.mdx deleted file mode 100644 index e7df9cb..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oauth-or-oidc.mdx +++ /dev/null @@ -1,41 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -`todo-manager.py` 파일을 업데이트하여 MCP Auth 구성을 포함하세요: - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # 발급자 엔드포인트로 교체하세요 -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OAUTH) # 또는 AuthServerType.OIDC -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -`todo-manager.ts` 파일을 업데이트하여 MCP Auth 구성을 포함하세요: - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // 발급자 엔드포인트로 교체하세요 -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oauth' }), // 또는 { type: 'oidc' } -}); -``` - - - - - - \ No newline at end of file diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oidc.mdx b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oidc.mdx deleted file mode 100644 index bd8c95a..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oidc.mdx +++ /dev/null @@ -1,41 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -`todo-manager.py` 파일을 업데이트하여 MCP Auth 구성을 포함하세요: - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # 발급자 엔드포인트로 교체하세요 -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -`todo-manager.ts` 파일을 업데이트하여 MCP Auth 구성을 포함하세요: - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // 발급자 엔드포인트로 교체하세요 -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oidc' }), -}); -``` - - - - -{props.showAlternative && } -{props.showAlternative && } \ No newline at end of file diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_transpile-metadata.mdx b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_transpile-metadata.mdx deleted file mode 100644 index 0683cd0..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_transpile-metadata.mdx +++ /dev/null @@ -1,31 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -일부 경우에는 provider의 응답이 잘못되었거나 예상된 메타데이터 형식에 부합하지 않을 수 있습니다. provider가 규격을 준수한다고 확신한다면, config 옵션을 통해 메타데이터를 변환(transpile)할 수 있습니다: - - - - -```python -mcp_auth = MCPAuth( - server=fetch_server_config( - # ...other options - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { - // ...other options - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/README.mdx b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/README.mdx deleted file mode 100644 index e0fb4d8..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/README.mdx +++ /dev/null @@ -1,611 +0,0 @@ ---- -sidebar_position: 1 -sidebar_label: '튜토리얼: 나는 누구인가? (Who am I?)' ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import SetupOauth from './_setup-oauth.mdx'; -import SetupOidc from './_setup-oidc.mdx'; - -# 튜토리얼: 나는 누구인가? (Who am I?) - -이 튜토리얼에서는 MCP Auth를 설정하여 사용자를 인증 (Authentication)하고 인가 (Authorization) 서버에서 아이덴티티 정보를 가져오는 과정을 안내합니다. - -이 튜토리얼을 완료하면 다음을 얻게 됩니다: - -- ✅ MCP Auth를 사용하여 사용자를 인증 (Authentication)하는 방법에 대한 기본적인 이해 -- ✅ 사용자 아이덴티티 정보를 조회할 수 있는 MCP 서버 - -## 개요 (Overview) \{#overview} - -이 튜토리얼에는 다음과 같은 구성 요소가 포함됩니다: - -- **MCP 서버**: MCP 공식 SDK를 사용하여 요청을 처리하는 간단한 MCP 서버 -- **MCP 인스펙터**: MCP 서버를 위한 시각적 테스트 도구. OAuth / OIDC 클라이언트 역할도 하여 인가 (Authorization) 플로우를 시작하고 액세스 토큰 (Access token)을 가져옵니다. -- **인가 (Authorization) 서버**: 사용자 아이덴티티를 관리하고 액세스 토큰 (Access token)을 발급하는 OAuth 2.1 또는 OpenID Connect 제공자 - -아래는 이 구성 요소들 간의 상호작용을 나타낸 고수준 다이어그램입니다: - -```mermaid -sequenceDiagram - participant Client as MCP 인스펙터 - participant Server as MCP 서버 - participant Auth as 인가 (Authorization) 서버 - - Client->>Server: `whoami` 도구 요청 - Server->>Client: 401 인가되지 않음 반환 - Client->>Auth: 인가 (Authorization) 플로우 시작 - Auth->>Auth: 인가 (Authorization) 플로우 완료 - Auth->>Client: 인가 코드와 함께 리디렉션 - Client->>Auth: 코드로 액세스 토큰 (Access token) 교환 - Auth->>Client: 액세스 토큰 (Access token) 반환 - Client->>Server: 액세스 토큰 (Access token)으로 `whoami` 요청 - Server->>Auth: 액세스 토큰 (Access token)으로 사용자 아이덴티티 조회 - Auth->>Server: 사용자 아이덴티티 반환 - Server->>Client: 사용자 아이덴티티 반환 -``` - -## 인가 (Authorization) 서버 이해하기 \{#understand-your-authorization-server} - -### 사용자 아이덴티티 정보 조회하기 \{#retrieving-user-identity-information} - -이 튜토리얼을 완료하려면, 인가 (Authorization) 서버가 사용자 아이덴티티 정보를 조회할 수 있는 API를 제공해야 합니다: - - - - -[Logto](https://logto.io)는 표준 [userinfo 엔드포인트](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)를 지원하는 OpenID Connect 제공자입니다. - -userinfo 엔드포인트에 접근할 수 있는 액세스 토큰 (Access token)을 얻으려면 최소 두 개의 스코프 (Scope), 즉 `openid`와 `profile`이 필요합니다. 스코프 설정은 아래에서 다루니 계속 읽어주세요. - - - - -[Keycloak](https://www.keycloak.org)은 OpenID Connect (OIDC)를 포함한 여러 프로토콜을 지원하는 오픈소스 아이덴티티 및 접근 관리 솔루션입니다. OIDC 제공자로서 표준 [userinfo 엔드포인트](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)를 구현하여 사용자 아이덴티티 정보를 조회할 수 있습니다. - -userinfo 엔드포인트에 접근할 수 있는 액세스 토큰 (Access token)을 얻으려면 최소 두 개의 스코프 (Scope), 즉 `openid`와 `profile`이 필요합니다. 스코프 설정은 아래에서 다루니 계속 읽어주세요. - - - - -대부분의 OpenID Connect 제공자는 [userinfo 엔드포인트](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)를 지원하여 사용자 아이덴티티 정보를 조회할 수 있습니다. - -제공자의 문서를 확인하여 이 엔드포인트를 지원하는지 확인하세요. 제공자가 [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)를 지원한다면, `.well-known/openid-configuration` 엔드포인트의 응답에서 `userinfo_endpoint`가 포함되어 있는지 확인할 수 있습니다. - -userinfo 엔드포인트에 접근할 수 있는 액세스 토큰 (Access token)을 얻으려면 최소 두 개의 스코프 (Scope), 즉 `openid`와 `profile`이 필요합니다. 스코프와 사용자 아이덴티티 클레임 (Claim) 매핑은 제공자 문서를 참고하세요. - - - - -OAuth 2.0은 사용자 아이덴티티 정보를 조회하는 표준 방법을 정의하지 않지만, 많은 제공자가 자체 엔드포인트를 구현합니다. 액세스 토큰 (Access token)으로 사용자 아이덴티티 정보를 어떻게 조회하는지, 인가 (Authorization) 플로우에서 어떤 파라미터가 필요한지 제공자 문서를 확인하세요. - - - - -### 동적 클라이언트 등록 (Dynamic Client Registration) \{#dynamic-client-registration} - -이 튜토리얼에서는 동적 클라이언트 등록이 필수는 아니지만, MCP 클라이언트 등록 과정을 자동화하고 싶다면 유용할 수 있습니다. 자세한 내용은 [동적 클라이언트 등록이 필요한가요?](/provider-list#is-dcr-required) 를 참고하세요. - -## MCP 서버 설정하기 \{#set-up-the-mcp-server} - -[MCP 공식 SDK](https://github.com/modelcontextprotocol)를 사용하여 인가 (Authorization) 서버에서 사용자 아이덴티티 정보를 조회하는 `whoami` 도구가 포함된 MCP 서버를 만듭니다. - -### 새 프로젝트 생성하기 \{#create-a-new-project} - - - - -```bash -mkdir mcp-server -cd mcp-server -uv init # 또는 `pipenv`나 `poetry`로 새 가상환경 생성 -``` - - - - -새 Node.js 프로젝트를 설정하세요: - -```bash -mkdir mcp-server -cd mcp-server -npm init -y # 또는 `pnpm init` -npm pkg set type="module" -npm pkg set main="whoami.js" -npm pkg set scripts.start="node whoami.js" -``` - - - - -### MCP SDK 및 의존성 설치하기 \{#install-the-mcp-sdk-and-dependencies} - - - - -```bash -pip install "mcp[cli]" starlette uvicorn -``` - -또는 `uv`, `poetry` 등 원하는 패키지 매니저를 사용하세요. - - - - -```bash -npm install @modelcontextprotocol/sdk express -``` - -또는 `pnpm`, `yarn` 등 원하는 패키지 매니저를 사용하세요. - - - - -### MCP 서버 만들기 \{#create-the-mcp-server} - -먼저, `whoami` 도구를 구현하는 MCP 서버를 만듭니다. - - - - -`whoami.py`라는 파일을 만들고 다음 코드를 추가하세요: - -```python -from mcp.server.fastmcp import FastMCP -from starlette.applications import Starlette -from starlette.routing import Mount -from typing import Any - -mcp = FastMCP("WhoAmI") - -@mcp.tool() -def whoami() -> dict[str, Any]: - """현재 사용자의 정보를 반환하는 도구입니다.""" - return {"error": "Not authenticated"} - -app = Starlette( - routes=[Mount('/', app=mcp.sse_app())] -) -``` - -서버 실행: - -```bash -uvicorn whoami:app --host 0.0.0.0 --port 3001 -``` - - - - -:::note -현재 MCP 인스펙터 구현은 인가 (Authorization) 플로우를 처리하지 않으므로, SSE 방식을 사용해 MCP 서버를 설정합니다. MCP 인스펙터가 인가 (Authorization) 플로우를 지원하면 코드를 업데이트하겠습니다. -::: - -`pnpm`이나 `yarn`도 사용할 수 있습니다. - -`whoami.js`라는 파일을 만들고 다음 코드를 추가하세요: - -```js -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; -import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'; -import express from 'express'; - -// MCP 서버 생성 -const server = new McpServer({ - name: 'WhoAmI', - version: '0.0.0', -}); - -// 현재 사용자의 정보를 반환하는 도구 추가 -server.tool('whoami', async () => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Not authenticated' }) }], - }; -}); - -// 아래는 MCP SDK 문서의 보일러플레이트 코드입니다 -const PORT = 3001; -const app = express(); - -const transports = {}; - -app.get('/sse', async (_req, res) => { - const transport = new SSEServerTransport('/messages', res); - transports[transport.sessionId] = transport; - - res.on('close', () => { - delete transports[transport.sessionId]; - }); - - await server.connect(transport); -}); - -app.post('/messages', async (req, res) => { - const sessionId = String(req.query.sessionId); - const transport = transports[sessionId]; - if (transport) { - await transport.handlePostMessage(req, res, req.body); - } else { - res.status(400).send('No transport found for sessionId'); - } -}); - -app.listen(PORT); -``` - -서버 실행: - -```bash -npm start -``` - - - - -## MCP 서버 점검하기 \{#inspect-the-mcp-server} - -### MCP 인스펙터 클론 및 실행 \{#clone-and-run-mcp-inspector} - -이제 MCP 서버가 실행 중이므로, MCP 인스펙터를 사용해 `whoami` 도구가 사용 가능한지 확인할 수 있습니다. - -현재 구현의 한계로 인해, [MCP 인스펙터](https://github.com/mcp-auth/inspector)를 포크하여 인증 (Authentication) 및 인가 (Authorization)에 더 유연하고 확장 가능하도록 개선했습니다. 변경 사항을 원본 저장소에 PR로 제출했습니다. - -MCP 인스펙터를 실행하려면 (Node.js 필요): - -```bash -git clone https://github.com/mcp-auth/inspector.git -cd inspector -npm install -npm run dev -``` - -그런 다음 브라우저에서 `http://localhost:6274/` (또는 터미널에 표시된 URL)로 접속하여 MCP 인스펙터에 접근하세요. - -### MCP 인스펙터를 MCP 서버에 연결하기 \{#connect-mcp-inspector-to-the-mcp-server} - -진행하기 전에 MCP 인스펙터에서 다음 설정을 확인하세요: - -- **Transport Type**: `SSE`로 설정 -- **URL**: MCP 서버의 URL로 설정 (예: `http://localhost:3001/sse`) - -이제 "Connect" 버튼을 클릭하여 MCP 인스펙터가 MCP 서버에 연결되는지 확인하세요. 정상적으로 연결되면 MCP 인스펙터에서 "Connected" 상태를 볼 수 있습니다. - -### 체크포인트: `whoami` 도구 실행하기 \{#checkpoint-run-the-whoami-tool} - -1. MCP 인스펙터 상단 메뉴에서 "Tools" 탭 클릭 -2. "List Tools" 버튼 클릭 -3. 페이지에 `whoami` 도구가 표시되어야 합니다. 클릭하여 도구 상세 보기 -4. 우측에 "Run Tool" 버튼이 보입니다. 클릭하여 도구 실행 -5. JSON 응답 `{"error": "Not authenticated"}`가 결과로 표시되어야 합니다. - -![MCP 인스펙터 첫 실행](/docs-assets/images/tutorials/whoami/inspector-first-run.png) - -## 인가 (Authorization) 서버와 통합하기 \{#integrate-with-your-authorization-server} - -이 섹션을 완료하려면 다음 사항들을 고려해야 합니다: - -
-**인가 (Authorization) 서버의 발급자 (Issuer) URL** - -일반적으로 인가 (Authorization) 서버의 기본 URL입니다. 예: `https://auth.example.com`. 일부 제공자는 `https://example.logto.app/oidc`와 같이 경로가 포함될 수 있으니, 제공자 문서를 꼭 확인하세요. - -
- -
-**인가 (Authorization) 서버 메타데이터 조회 방법** - -- 인가 (Authorization) 서버가 [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) 또는 [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)를 준수한다면, MCP Auth 내장 유틸리티로 메타데이터를 자동으로 가져올 수 있습니다. -- 준수하지 않는 경우, MCP 서버 설정에서 메타데이터 URL 또는 엔드포인트를 수동으로 지정해야 합니다. 제공자 문서에서 엔드포인트를 확인하세요. - -
- -
-**MCP 인스펙터를 인가 (Authorization) 서버에 클라이언트로 등록하는 방법** - -- 인가 (Authorization) 서버가 [동적 클라이언트 등록](https://datatracker.ietf.org/doc/html/rfc7591)을 지원한다면, MCP 인스펙터가 자동으로 클라이언트로 등록되므로 이 단계를 건너뛸 수 있습니다. -- 지원하지 않는 경우, MCP 인스펙터를 인가 (Authorization) 서버에 수동으로 클라이언트로 등록해야 합니다. - -
- -
-**사용자 아이덴티티 정보 조회 및 인가 (Authorization) 요청 파라미터 설정 방법** - -- OpenID Connect 제공자의 경우: 인가 (Authorization) 플로우 시작 시 최소 `openid`와 `profile` 스코프 (Scope)를 요청해야 합니다. 이렇게 하면 인가 (Authorization) 서버가 반환하는 액세스 토큰 (Access token)에 [userinfo 엔드포인트](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)에 접근할 수 있는 권한이 포함됩니다. - - 참고: 일부 제공자는 userinfo 엔드포인트를 지원하지 않을 수 있습니다. - -- OAuth 2.0 / OAuth 2.1 제공자의 경우: 액세스 토큰 (Access token)으로 사용자 아이덴티티 정보를 어떻게 조회하는지, 어떤 파라미터가 필요한지 제공자 문서를 확인하세요. - -
- -각 제공자마다 세부 요구사항이 다를 수 있지만, 아래 단계에 따라 MCP 인스펙터와 MCP 서버를 제공자별 설정으로 통합할 수 있습니다. - -### MCP 인스펙터를 클라이언트로 등록하기 \{#register-mcp-inspector-as-a-client} - - - - -[Logto](https://logto.io)는 표준 [userinfo 엔드포인트](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)를 지원하는 OpenID Connect 제공자이므로 통합이 간단합니다. - -Logto는 아직 동적 클라이언트 등록을 지원하지 않으므로, MCP 인스펙터를 Logto 테넌트에 수동으로 클라이언트로 등록해야 합니다: - -1. MCP 인스펙터에서 "OAuth Configuration" 버튼을 클릭하고 **Redirect URL (자동 입력)** 값을 복사하세요. 예: `http://localhost:6274/oauth/callback` -2. [Logto Console](https://cloud.logto.io) (또는 자체 호스팅 Logto Console)에 로그인하세요. -3. "Applications" 탭에서 "Create application" 클릭. 페이지 하단에서 "Create app without framework" 클릭. -4. 애플리케이션 정보를 입력하고 "Create application" 클릭: - - **Select an application type**: "Single-page application" 선택 - - **Application name**: 예: "MCP Inspector" -5. "Settings / Redirect URIs" 섹션에 복사한 **Redirect URL (자동 입력)** 값을 붙여넣고, 하단 바에서 "Save changes" 클릭 -6. 상단 카드에서 "App ID" 값을 복사하세요. -7. MCP 인스펙터로 돌아가 "OAuth Configuration"의 "Client ID"에 "App ID" 값을 붙여넣으세요. -8. "Auth Params" 필드에 `{"scope": "openid profile email"}` 값을 입력하세요. 이렇게 하면 Logto가 반환하는 액세스 토큰 (Access token)에 userinfo 엔드포인트 접근에 필요한 스코프가 포함됩니다. - - - - -[Keycloak](https://www.keycloak.org)은 OpenID Connect 프로토콜을 지원하는 오픈소스 아이덴티티 및 접근 관리 솔루션입니다. - -Keycloak은 동적 클라이언트 등록을 지원하지만, 클라이언트 등록 엔드포인트가 CORS를 지원하지 않아 대부분의 MCP 클라이언트가 직접 등록할 수 없습니다. 따라서 수동으로 클라이언트를 등록해야 합니다. - -:::note -Keycloak은 [여러 방식](https://www.keycloak.org/guides#getting-started) (베어메탈, 쿠버네티스 등)으로 설치할 수 있지만, 이 튜토리얼에서는 Docker로 빠르게 설정합니다. -::: - -Keycloak 인스턴스를 설정하고 구성해봅시다: - -1. [공식 문서](https://www.keycloak.org/getting-started/getting-started-docker)를 참고하여 Docker로 Keycloak 인스턴스 실행: - -```bash -docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.2.4 start-dev -``` - -2. Keycloak Admin Console (http://localhost:8080/admin)에 접속하여 아래 계정으로 로그인: - - - Username: `admin` - - Password: `admin` - -3. 새 Realm 생성: - - - 좌측 상단 "Create Realm" 클릭 - - "Realm name"에 `mcp-realm` 입력 - - "Create" 클릭 - -4. 테스트 사용자 생성: - - - 좌측 메뉴 "Users" 클릭 - - "Create new user" 클릭 - - 사용자 정보 입력: - - Username: `testuser` - - First name, Last name은 임의 값 - - "Create" 클릭 - - "Credentials" 탭에서 비밀번호 설정, "Temporary" 해제 - -5. MCP 인스펙터를 클라이언트로 등록: - - - MCP 인스펙터에서 "OAuth Configuration" 버튼 클릭, **Redirect URL (자동 입력)** 값 복사 (예: `http://localhost:6274/oauth/callback`) - - Keycloak Admin Console에서 좌측 "Clients" 클릭 - - "Create client" 클릭 - - 클라이언트 정보 입력: - - Client type: "OpenID Connect" 선택 - - Client ID: `mcp-inspector` 입력 - - "Next" 클릭 - - "Capability config" 페이지: - - "Standard flow" 활성화 확인 - - "Next" 클릭 - - "Login settings" 페이지: - - "Valid redirect URIs"에 MCP 인스펙터 콜백 URL 붙여넣기 - - "Web origins"에 `http://localhost:6274` 입력 - - "Save" 클릭 - - "Client ID" (`mcp-inspector`) 복사 - -6. MCP 인스펙터로 돌아가서: - - "OAuth Configuration"의 "Client ID" 필드에 복사한 Client ID 붙여넣기 - - "Auth Params" 필드에 아래 값 입력: - -```json -{ "scope": "openid profile email" } -``` - - - - -:::note -이 가이드는 일반적인 OpenID Connect 제공자 통합 안내입니다. 세부 사항은 제공자 문서를 참고하세요. -::: - -OpenID Connect 제공자가 동적 클라이언트 등록을 지원한다면 아래 8번 단계로 바로 이동하여 MCP 인스펙터를 설정하세요. 그렇지 않으면 MCP 인스펙터를 수동으로 클라이언트로 등록해야 합니다: - -1. MCP 인스펙터에서 "OAuth Configuration" 버튼 클릭, **Redirect URL (자동 입력)** 값 복사 (예: `http://localhost:6274/oauth/callback`) -2. OpenID Connect 제공자 콘솔에 로그인 -3. "Applications" 또는 "Clients" 섹션에서 새 애플리케이션/클라이언트 생성 -4. 클라이언트 타입이 필요하다면 "Single-page application" 또는 "Public client" 선택 -5. 애플리케이션 생성 후, 리디렉션 URI에 MCP 인스펙터의 **Redirect URL (자동 입력)** 값 붙여넣기 -6. 새로 생성된 애플리케이션의 "Client ID" 또는 "Application ID" 복사 -7. MCP 인스펙터로 돌아가 "OAuth Configuration"의 "Client ID"에 붙여넣기 -8. 표준 OpenID Connect 제공자의 경우, userinfo 엔드포인트 접근에 필요한 스코프를 요청하려면 "Auth Params" 필드에 아래 값 입력: - -```json -{ "scope": "openid profile email" } -``` - - - - -:::note -이 가이드는 일반적인 OAuth 2.0 / OAuth 2.1 제공자 통합 안내입니다. 세부 사항은 제공자 문서를 참고하세요. -::: - -OAuth 2.0 / OAuth 2.1 제공자가 동적 클라이언트 등록을 지원한다면 아래 8번 단계로 바로 이동하여 MCP 인스펙터를 설정하세요. 그렇지 않으면 MCP 인스펙터를 수동으로 클라이언트로 등록해야 합니다: - -1. MCP 인스펙터에서 "OAuth Configuration" 버튼 클릭, **Redirect URL (자동 입력)** 값 복사 (예: `http://localhost:6274/oauth/callback`) -2. OAuth 2.0 / OAuth 2.1 제공자 콘솔에 로그인 -3. "Applications" 또는 "Clients" 섹션에서 새 애플리케이션/클라이언트 생성 -4. 클라이언트 타입이 필요하다면 "Single-page application" 또는 "Public client" 선택 -5. 애플리케이션 생성 후, 리디렉션 URI에 MCP 인스펙터의 **Redirect URL (자동 입력)** 값 붙여넣기 -6. 새로 생성된 애플리케이션의 "Client ID" 또는 "Application ID" 복사 -7. MCP 인스펙터로 돌아가 "OAuth Configuration"의 "Client ID"에 붙여넣기 -8. 사용자 아이덴티티 정보 조회를 위한 액세스 토큰 (Access token) 발급 방법은 제공자 문서를 참고하세요. 예를 들어, `profile` 스코프가 필요하다면 "Auth Params" 필드에 아래 값 입력: - -```json -{ "scope": "profile" } -``` - - - - -### MCP Auth 설정하기 \{#set-up-mcp-auth} - -MCP 서버 프로젝트에서 MCP Auth SDK를 설치하고 인가 (Authorization) 서버 메타데이터를 사용하도록 설정해야 합니다. - - - - -먼저 `mcpauth` 패키지를 설치하세요: - -```bash -pip install mcpauth -``` - -또는 `uv`, `poetry` 등 원하는 패키지 매니저를 사용하세요. - - - - -먼저 `mcp-auth` 패키지를 설치하세요: - -```bash -npm install mcp-auth -``` - - - - -MCP Auth는 인가 (Authorization) 서버 메타데이터가 필요합니다. 제공자에 따라 아래를 참고하세요: - - - - - -발급자 (Issuer) URL은 Logto Console의 애플리케이션 상세 페이지 "Endpoints & Credentials / Issuer endpoint" 섹션에서 확인할 수 있습니다. 예: `https://my-project.logto.app/oidc` - - - - - - - -발급자 (Issuer) URL은 Keycloak Admin Console에서 'mcp-realm'의 "Realm settings / Endpoints" 섹션에서 "OpenID Endpoint Configuration" 링크를 클릭해 JSON 문서의 `issuer` 필드에서 확인할 수 있습니다. 예: `http://localhost:8080/realms/mcp-realm` - - - - - - - -아래 코드는 인가 (Authorization) 서버가 [userinfo 엔드포인트](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)를 지원한다고 가정합니다. 지원하지 않는 경우, 제공자 문서에서 엔드포인트를 확인하고 userinfo 엔드포인트 변수를 올바른 URL로 교체하세요. - - - - - - -앞서 언급했듯이, OAuth 2.0은 사용자 아이덴티티 정보를 조회하는 표준 방법을 정의하지 않습니다. 아래 코드는 제공자가 액세스 토큰 (Access token)으로 사용자 아이덴티티 정보를 조회할 수 있는 특정 엔드포인트를 제공한다고 가정합니다. 제공자 문서에서 엔드포인트를 확인하고 userinfo 엔드포인트 변수를 올바른 URL로 교체하세요. - - - - - - -### MCP 서버 업데이트하기 \{#update-mcp-server} - -거의 다 왔습니다! 이제 MCP Auth 라우트와 미들웨어를 적용하고, `whoami` 도구가 실제 사용자 아이덴티티 정보를 반환하도록 MCP 서버를 업데이트합니다. - - - - -```python -@mcp.tool() -def whoami() -> dict[str, Any]: - """현재 사용자의 정보를 반환하는 도구입니다.""" - return ( - mcp_auth.auth_info.claims - if mcp_auth.auth_info # Bearer 인증 (Authentication) 미들웨어에서 채워집니다 - else {"error": "Not authenticated"} - ) - -# ... - -bearer_auth = Middleware(mcp_auth.bearer_auth_middleware(verify_access_token)) -app = Starlette( - routes=[ - # 메타데이터 라우트 추가 (`/.well-known/oauth-authorization-server`) - mcp_auth.metadata_route(), - # Bearer 인증 (Authentication) 미들웨어로 MCP 서버 보호 - Mount('/', app=mcp.sse_app(), middleware=[bearer_auth]), - ], -) -``` - - - - -```js -server.tool('whoami', ({ authInfo }) => { - return { - content: [ - { type: 'text', text: JSON.stringify(authInfo?.claims ?? { error: 'Not authenticated' }) }, - ], - }; -}); - -// ... - -app.use(mcpAuth.delegatedRouter()); -app.use(mcpAuth.bearerAuth(verifyToken)); -``` - - - - -## 체크포인트: 인증 (Authentication)과 함께 `whoami` 도구 실행하기 \{#checkpoint-run-the-whoami-tool-with-authentication} - -MCP 서버를 재시작하고 MCP 인스펙터를 브라우저에서 엽니다. "Connect" 버튼을 클릭하면 인가 (Authorization) 서버의 로그인 페이지로 리디렉션됩니다. - -로그인 후 MCP 인스펙터로 돌아오면, 이전 체크포인트에서 했던 것처럼 `whoami` 도구를 실행하세요. 이번에는 인가 (Authorization) 서버가 반환하는 사용자 아이덴티티 정보가 표시됩니다. - -![MCP 인스펙터 whoami 도구 결과](/docs-assets/images/tutorials/whoami/result.png) - - - - -:::info -[MCP Auth Python SDK 저장소](https://github.com/mcp-auth/python/blob/master/samples/server/whoami.py)에서 MCP 서버(OIDC 버전)의 전체 코드를 확인할 수 있습니다. -::: - - - - -:::info -[MCP Auth Node.js SDK 저장소](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src)에서 MCP 서버(OIDC 버전)의 전체 코드를 확인할 수 있습니다. 이 디렉터리에는 TypeScript 및 JavaScript 버전이 모두 포함되어 있습니다. -::: - - - - -## 마무리 (Closing notes) \{#closing-notes} - -🎊 축하합니다! 튜토리얼을 성공적으로 완료하셨습니다. 지금까지 한 내용을 요약하면: - -- `whoami` 도구가 포함된 기본 MCP 서버 설정 -- MCP Auth를 사용하여 MCP 서버를 인가 (Authorization) 서버와 통합 -- MCP 인스펙터를 설정하여 사용자 인증 (Authentication) 및 아이덴티티 정보 조회 - -추가로 다음과 같은 고급 주제도 탐구해보세요: - -- 인증 (Authentication) 및 인가 (Authorization)에 [JWT (JSON Web Token)](https://auth.wiki/jwt) 사용 -- 접근하는 리소스를 지정하기 위한 [리소스 지표 (Resource indicator, RFC 8707)](https://auth-wiki.logto.io/resource-indicator) 활용 -- [역할 기반 접근 제어 (RBAC)](https://auth.wiki/rbac) 또는 [속성 기반 접근 제어 (ABAC)](https://auth.wiki/abac) 등 맞춤형 접근 제어 구현 - -MCP Auth를 최대한 활용하려면 다른 튜토리얼과 문서도 꼭 확인해보세요. diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_manual-metadata-fetching.mdx b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_manual-metadata-fetching.mdx deleted file mode 100644 index 5a7782e..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_manual-metadata-fetching.mdx +++ /dev/null @@ -1,3 +0,0 @@ -:::note -만약 사용 중인 provider가 {props.oidc ? 'OpenID Connect Discovery' : 'OAuth 2.0 Authorization Server Metadata'}를 지원하지 않는 경우, 메타데이터 URL 또는 엔드포인트를 수동으로 지정할 수 있습니다. 자세한 내용은 [MCP Auth를 초기화하는 다른 방법](../../configure-server/mcp-auth.mdx#other-ways)을 확인하세요. -::: \ No newline at end of file diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oauth.mdx b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oauth.mdx deleted file mode 100644 index 0afced7..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oauth.mdx +++ /dev/null @@ -1,138 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -`whoami.py`를 업데이트하여 MCP Auth 구성을 포함하세요: - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # 발급자 엔드포인트로 교체하세요 -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OAUTH) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -`whoami.js`를 업데이트하여 MCP Auth 구성을 포함하세요: - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // 발급자 엔드포인트로 교체하세요 -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oauth' }), -}); -``` - - - - - - - -이제 MCP 인스펙터에서 제공한 액세스 토큰 (Access token)을 사용하여 인가 (Authorization) 서버에서 사용자 아이덴티티 정보를 가져오는 커스텀 액세스 토큰 (Access token) 검증기를 만들어야 합니다. - - - - -```python -import pydantic -import requests -from mcpauth.exceptions import ( - MCPAuthTokenVerificationException, - MCPAuthTokenVerificationExceptionCode, -) -from mcpauth.types import AuthInfo - -def verify_access_token(token: str) -> AuthInfo: - """ - 제공된 Bearer 토큰을 인가 (Authorization) 서버에서 사용자 정보를 가져와 검증합니다. - 토큰이 유효하다면, 사용자의 정보를 담은 `AuthInfo` 객체를 반환합니다. - - :param token: MCP 인스펙터에서 받은 Bearer 토큰. - """ - - try: - # 아래 코드는 인가 (Authorization) 서버가 액세스 토큰 (Access token)으로 사용자 정보를 가져오는 엔드포인트를 - # 제공한다고 가정합니다. 공급자의 API에 따라 URL과 헤더를 조정하세요. - response = requests.get( - "https://your-authorization-server.com/userinfo", - headers={"Authorization": f"Bearer {token}"}, - ) - response.raise_for_status() # HTTP 오류 발생 시 예외 처리 - json = response.json() # JSON 응답 파싱 - - # 아래 코드는 사용자 정보 응답이 사용자를 식별하는 'sub' 필드를 포함한다고 가정합니다. - # 공급자의 API에 따라 조정이 필요할 수 있습니다. - return AuthInfo( - token=token, - subject=json.get("sub"), - issuer=auth_issuer, # 설정된 발급자 사용 - claims=json, # 엔드포인트에서 반환된 모든 클레임 (Claims) (JSON 필드) 포함 - ) - # `AuthInfo`는 Pydantic 모델이므로, 검증 오류는 응답 구조가 예상과 다름을 의미합니다. - except pydantic.ValidationError as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.INVALID_TOKEN, - cause=e, - ) - # 요청 중 발생할 수 있는 기타 예외 처리 - except Exception as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.TOKEN_VERIFICATION_FAILED, - cause=e, - ) -``` - - - - -```js -import { MCPAuthTokenVerificationError } from 'mcp-auth'; - -/** - * 제공된 Bearer 토큰을 인가 (Authorization) 서버에서 사용자 정보를 가져와 검증합니다. - * 토큰이 유효하다면, 사용자의 정보를 담은 `AuthInfo` 객체를 반환합니다. - */ -const verifyToken = async (token) => { - // 아래 코드는 인가 (Authorization) 서버가 액세스 토큰 (Access token)으로 사용자 정보를 가져오는 엔드포인트를 - // 제공한다고 가정합니다. 공급자의 API에 따라 URL과 헤더를 조정하세요. - const response = await fetch('https://your-authorization-server.com/userinfo', { - headers: { Authorization: `Bearer ${token}` }, - }); - - if (!response.ok) { - throw new MCPAuthTokenVerificationError('token_verification_failed', response); - } - - const userInfo = await response.json(); - - // 아래 코드는 사용자 정보 응답이 사용자를 식별하는 'sub' 필드를 포함한다고 가정합니다. - // 공급자의 API에 따라 조정이 필요할 수 있습니다. - if (typeof userInfo !== 'object' || userInfo === null || !('sub' in userInfo)) { - throw new MCPAuthTokenVerificationError('invalid_token', response); - } - - return { - token, - issuer: authIssuer, - subject: String(userInfo.sub), // 공급자의 사용자 ID 필드에 따라 조정 - clientId: '', // 이 예제에서는 Client ID를 사용하지 않지만 필요시 설정 가능 - scopes: [], - claims: userInfo, - }; -}; -``` - - - diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oidc.mdx b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oidc.mdx deleted file mode 100644 index de7ab7c..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oidc.mdx +++ /dev/null @@ -1,142 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -`whoami.py` 파일을 업데이트하여 MCP Auth 구성을 포함하세요: - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # 발급자 엔드포인트로 교체하세요 -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -`whoami.js` 파일을 업데이트하여 MCP Auth 구성을 포함하세요: - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // 발급자 엔드포인트로 교체하세요 -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oidc' }), -}); -``` - - - - -{props.showAlternative && } -{props.showAlternative && } - -이제 MCP 인스펙터에서 제공한 액세스 토큰 (Access token)을 사용하여 인가 서버에서 사용자 아이덴티티 정보를 가져오는 커스텀 액세스 토큰 (Access token) 검증기를 만들어야 합니다. - - - - -```python -import pydantic -import requests -from mcpauth.exceptions import ( - MCPAuthTokenVerificationException, - MCPAuthTokenVerificationExceptionCode, -) -from mcpauth.types import AuthInfo - -def verify_access_token(token: str) -> AuthInfo: - """ - 제공된 Bearer 토큰을 인가 서버에서 사용자 정보를 가져와 검증합니다. - 토큰이 유효하면 사용자의 정보가 담긴 `AuthInfo` 객체를 반환합니다. - - :param token: MCP 인스펙터에서 받은 Bearer 토큰. - """ - - issuer = auth_server_config.metadata.issuer - endpoint = auth_server_config.metadata.userinfo_endpoint # 공급자가 userinfo 엔드포인트를 지원해야 합니다 - if not endpoint: - raise ValueError( - "Userinfo 엔드포인트가 인증 서버 메타데이터에 구성되어 있지 않습니다." - ) - - try: - response = requests.get( - endpoint, - headers={"Authorization": f"Bearer {token}"}, # 표준 Bearer 토큰 헤더 - ) - response.raise_for_status() # HTTP 오류 발생 시 예외 발생 - json = response.json() # JSON 응답 파싱 - return AuthInfo( - token=token, - subject=json.get("sub"), # 'sub'는 주체(사용자 ID)에 대한 표준 클레임 (Claim)입니다 - issuer=issuer, # 메타데이터의 발급자 (Issuer) 사용 - claims=json, # userinfo 엔드포인트에서 반환된 모든 클레임 (Claim) (JSON 필드) 포함 - ) - # `AuthInfo`는 Pydantic 모델이므로, 검증 오류는 보통 응답이 예상 구조와 일치하지 않을 때 발생합니다 - except pydantic.ValidationError as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.INVALID_TOKEN, - cause=e, - ) - # 요청 중 발생할 수 있는 기타 예외 처리 - except Exception as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.TOKEN_VERIFICATION_FAILED, - cause=e, - ) -``` - - - - -```js -import { MCPAuthTokenVerificationError } from 'mcp-auth'; - -/** - * 제공된 Bearer 토큰을 인가 서버에서 사용자 정보를 가져와 검증합니다. - * 토큰이 유효하면 사용자의 정보가 담긴 `AuthInfo` 객체를 반환합니다. - */ -const verifyToken = async (token) => { - const { issuer, userinfoEndpoint } = mcpAuth.config.server.metadata; - - if (!userinfoEndpoint) { - throw new Error('Userinfo 엔드포인트가 서버 메타데이터에 구성되어 있지 않습니다'); - } - - const response = await fetch(userinfoEndpoint, { - headers: { Authorization: `Bearer ${token}` }, - }); - - if (!response.ok) { - throw new MCPAuthTokenVerificationError('token_verification_failed', response); - } - - const userInfo = await response.json(); - - if (typeof userInfo !== 'object' || userInfo === null || !('sub' in userInfo)) { - throw new MCPAuthTokenVerificationError('invalid_token', response); - } - - return { - token, - issuer, - subject: String(userInfo.sub), // 'sub'는 주체(사용자 ID)에 대한 표준 클레임 (Claim)입니다 - clientId: '', // 이 예제에서는 Client ID를 사용하지 않지만 필요하다면 설정할 수 있습니다 - scopes: [], - claims: userInfo, - }; -}; -``` - - - diff --git a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_transpile-metadata.mdx b/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_transpile-metadata.mdx deleted file mode 100644 index 0683cd0..0000000 --- a/i18n/ko/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_transpile-metadata.mdx +++ /dev/null @@ -1,31 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -일부 경우에는 provider의 응답이 잘못되었거나 예상된 메타데이터 형식에 부합하지 않을 수 있습니다. provider가 규격을 준수한다고 확신한다면, config 옵션을 통해 메타데이터를 변환(transpile)할 수 있습니다: - - - - -```python -mcp_auth = MCPAuth( - server=fetch_server_config( - # ...other options - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { - // ...other options - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1.json b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1.json deleted file mode 100644 index 0f1b3eb..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1.json +++ /dev/null @@ -1,50 +0,0 @@ -{ - "sidebar.docsSidebar.category.Tutorials": { - "message": "Tutoriais", - "description": "The label for category Tutorials in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.Tutorials.link.generated-index.title": { - "message": "Tutoriais", - "description": "The generated-index page title for category Tutorials in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.Configure MCP server": { - "message": "Configurar servidor MCP", - "description": "The label for category Configure MCP server in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.Configure MCP server.link.generated-index.title": { - "message": "Configurar servidor MCP", - "description": "The generated-index page title for category Configure MCP server in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.SDK references": { - "message": "Referências do SDK", - "description": "The label for category SDK references in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.SDK references.link.generated-index.title": { - "message": "Referências do SDK MCP Auth", - "description": "The generated-index page title for category SDK references in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.SDK references.link.generated-index.description": { - "message": "Informações sobre classes, métodos e propriedades extraídas do SDK MCP Auth.\n", - "description": "The generated-index page description for category SDK references in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.Node.js SDK": { - "message": "Node.js SDK", - "description": "The label for category Node.js SDK in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.classes": { - "message": "Classes", - "description": "The label for category classes in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.functions": { - "message": "Funções", - "description": "The label for category functions in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.type-aliases": { - "message": "Aliases de Tipo", - "description": "The label for category type-aliases in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.variables": { - "message": "Variáveis", - "description": "The label for category variables in sidebar docsSidebar" - } -} diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/README.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/README.mdx deleted file mode 100644 index 39836ed..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/README.mdx +++ /dev/null @@ -1,242 +0,0 @@ ---- -sidebar_position: 1 -sidebar_label: Primeiros passos ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -# Primeiros passos - -## Escolha um provedor compatível com OAuth 2.1 ou OpenID Connect \{#choose-a-compatible-oauth-2-1-or-openid-connect-provider} - -A especificação MCP possui alguns [requisitos específicos](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization#1-3-standards-compliance) para autorização: - -- [OAuth 2.1 IETF DRAFT](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12) -- OAuth 2.0 Authorization Server Metadata ([RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)) -- OAuth 2.0 Dynamic Client Registration Protocol ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) - -Embora os dois últimos não sejam obrigatórios, o primeiro é necessário para garantir uma implementação segura e compatível. - -:::note -No novo draft do MCP, o RFC 8414 será obrigatório para servidores de autorização (provedores). Atualizaremos a documentação assim que o novo draft for finalizado. -::: - -Você pode conferir a [lista de provedores compatíveis com MCP](/provider-list) para ver se seu provedor é suportado. - -## Instale o MCP Auth SDK \{#install-mcp-auth-sdk} - -O MCP Auth está disponível para Python e TypeScript. Nos avise se precisar de suporte para outra linguagem ou framework! - - - - -```bash -pip install mcpauth -``` - -Ou qualquer outro gerenciador de pacotes de sua preferência, como pipenv ou poetry. - - - - -```bash -npm install mcp-auth -``` - -Ou qualquer outro gerenciador de pacotes de sua preferência, como pnpm ou yarn. - - - - -## Inicialize o MCP Auth \{#init-mcp-auth} - -O primeiro passo é inicializar a instância do MCP Auth com os metadados do servidor de autorização do seu provedor. Se seu provedor estiver em conformidade com um dos seguintes: - -- [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) -- [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) - -Você pode usar a função integrada para buscar os metadados e inicializar a instância do MCP Auth: - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -mcp_auth = MCPAuth( - server=fetch_server_config( - '', - type=AuthServerType.OIDC # ou AuthServerType.OAUTH - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { type: 'oidc' }), // ou 'oauth' -}); -``` - - - - -Se você precisar especificar manualmente a URL dos metadados ou endpoints, confira [Outras formas de inicializar o MCP Auth](./configure-server/mcp-auth.mdx#other-ways). - -## Monte o endpoint de metadados \{#mount-the-metadata-endpoint} - -Para estar em conformidade com a especificação MCP atual, o MCP Auth monta o endpoint OAuth 2.0 Authorization Server Metadata (`/.well-known/oauth-authorization-server`) no seu servidor MCP: - - - - -```python -from starlette.applications import Starlette - -app = Starlette(routes=[ - mcp_auth.metadata_route(), -]) -``` - - - - -```ts -import express from 'express'; - -const app = express(); -app.use(mcpAuth.delegatedRouter()); -``` - - - - -As URLs nos metadados são mantidas como estão, então o papel de servidor de autorização é totalmente delegado ao provedor. Você pode testar o endpoint de metadados acessando `/.well-known/oauth-authorization-server` no seu servidor MCP. - -### Por que apenas o endpoint de metadados? \{#why-only-the-metadata-endpoint} - -Você pode notar que os SDKs oficiais fornecem um roteador de autenticação que monta endpoints de autorização como `/authorize`, `/token`, etc. Veja por que não fazemos isso: - -1. Montar apenas o endpoint de metadados permite que você aproveite todas as capacidades do seu provedor sem "reinventar a roda" e injetar complexidade desnecessária no seu servidor MCP. -2. Também há um esforço em andamento para transferir o [papel do servidor MCP para um resource server](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/205) e exigir OAuth 2.0 Protected Resource Metadata ([RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728)). Isso significa que o servidor MCP **não lidará mais com nenhuma lógica de autorização** (incluindo o endpoint de metadados), servindo apenas como um resource server que depende do provedor para autenticação e autorização. - -:::note -Atualizaremos o MCP Auth para suportar a nova especificação MCP quando ela for finalizada. Enquanto isso, você pode usar a versão atual, que é compatível com a especificação vigente. -::: - -## Use o middleware Bearer auth \{#use-the-bearer-auth-middleware} - -Depois de inicializar a instância do MCP Auth, você pode aplicar o middleware Bearer auth para proteger suas rotas MCP: - - - - -```python -from starlette.applications import Starlette -from starlette.middleware import Middleware -from starlette.routing import Mount -from mcpauth import MCPAuth -from mcp.server.fastmcp import FastMCP - -mcp = FastMCP() -mcp_auth = MCPAuth( - # Inicialize com a configuração do seu servidor de autenticação -) -bearer_auth = mcp_auth.bearer_auth_middleware( - "jwt", required_scopes=["read", "write"] -) - -app = Starlette(routes=[ - mcp_auth.metadata_route(), - Mount( - "/", - app=mcp.sse_app(), - middleware=[Middleware(bearer_auth)], - ), -]) -``` - - - - -```ts -import express from 'express'; -import { MCPAuth } from 'mcp-auth'; - -const app = express(); -const server = new McpServer(/* ... */); -const mcpAuth = new MCPAuth({ - /* ... */ -}); - -app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] })); -``` - - - - -No exemplo acima, especificamos o tipo de token `jwt` e exigimos os escopos `read` e `write`. Ele validará automaticamente o JWT (JSON Web Token) e preencherá um objeto com as informações do usuário autenticado. - -:::info -Nunca ouviu falar de JWT (JSON Web Token)? Não se preocupe, continue lendo a documentação e explicaremos quando necessário. Você também pode conferir o [Auth Wiki](https://auth.wiki/jwt) para uma introdução rápida. -::: - -Para mais informações sobre a configuração do Bearer auth, confira [Configurar Bearer auth](./configure-server/bearer-auth.mdx). - -## Recupere as informações de autenticação na sua implementação MCP \{#retrieve-the-auth-info-in-your-mcp-implementation} - -Depois que o middleware Bearer auth for aplicado, você pode acessar as informações do usuário autenticado (ou identidade) na sua implementação MCP: - - - - -O MCP Auth armazenará as informações do usuário autenticado em uma variável de contexto após a autenticação bem-sucedida, uma vez que o middleware Bearer auth for aplicado. Você pode acessá-la em seus handlers de ferramentas MCP assim: - -```python -from mcp.server.fastmcp import FastMCP - -mcp = FastMCP() -mcp_auth = MCPAuth( - # Inicialize com a configuração do seu servidor de autenticação -) - -@mcp.tool() -def add(a: int, b: int): - """ - Uma ferramenta que soma dois números. - As informações do usuário autenticado estarão disponíveis no contexto. - """ - auth_info = mcp_auth.auth_info # Acesse as informações de autenticação no contexto atual - if auth_info: - print(f"Usuário autenticado: {auth_info.claims}") - return a + b -``` - - - - -O segundo argumento do handler da ferramenta conterá o objeto `authInfo`, que inclui as informações do usuário autenticado: - -```ts -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; -import { z } from 'zod'; - -const server = new McpServer(/* ... */); -server.tool('add', { a: z.number(), b: z.number() }, async ({ a, b }, { authInfo }) => { - // Agora você pode usar o objeto `authInfo` para acessar as informações autenticadas -}); -``` - - - - -## Próximos passos \{#next-steps} - -Continue lendo para aprender um exemplo de ponta a ponta de como integrar o MCP Auth ao seu servidor MCP e como lidar com o fluxo de autenticação em clientes MCP. \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/comparison.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/comparison.mdx deleted file mode 100644 index edd553a..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/comparison.mdx +++ /dev/null @@ -1,80 +0,0 @@ ---- -sidebar_position: 101 -sidebar_label: Comparação ---- - -# Escolhendo entre MCP Auth e outras soluções - -O ecossistema MCP está evoluindo. À medida que a especificação do Model Context Protocol (MCP) avança do modelo de “servidor de autorização” para o novo modelo de “servidor de recursos + IdP de terceiros”, é importante entender como diferentes soluções de integração se encaixam, tanto agora quanto no futuro. - -Esta página destaca as principais diferenças entre o mcp-auth e outras soluções populares, para ajudar você a escolher a melhor abordagem para o seu projeto. - -## Contexto: Abordagem proxy vs. integração com IdP \{#background-proxy-approach-vs-idp-integration} - -A maioria das soluções de autenticação MCP existentes utiliza uma “abordagem proxy”. Nesse modelo, o servidor MCP faz proxy das solicitações de autorização para um Provedor de Identidade (IdP) de terceiros, atuando efetivamente como intermediário entre o cliente e o IdP. - -**Abordagem proxy ([03-26 spec](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization))** - -```mermaid -sequenceDiagram - participant Client as Cliente - participant MCP_Server as Servidor MCP - participant ThirdParty_IdP as IdP de terceiros - - Client->>MCP_Server: Solicitação de autorização - MCP_Server->>ThirdParty_IdP: Faz proxy da solicitação - ThirdParty_IdP->>MCP_Server: Resposta - MCP_Server->>Client: Resposta - Client->>MCP_Server: Acessar recurso - alt Validação remota - MCP_Server->>ThirdParty_IdP: Validar token - ThirdParty_IdP->>MCP_Server: Token válido - else Validação local - MCP_Server->>MCP_Server: Validar token localmente (ex: JWK em cache) - end - MCP_Server->>Client: Dados do recurso -``` - -Embora isso funcione com a especificação MCP atual (2025-03-26), é essencialmente uma solução alternativa. Assume que o servidor MCP também atuará como servidor de autorização, o que não é a direção da última versão da especificação. - -**MCP Auth / futura especificação (servidor de recursos + IdP de terceiros)** - -```mermaid -sequenceDiagram - participant Client as Cliente - participant MCP_Server as Servidor MCP - participant ThirdParty_IdP as IdP de terceiros - - Client->>ThirdParty_IdP: Solicitação de autorização - ThirdParty_IdP->>Client: Token - Client->>MCP_Server: Acessar recurso (com token) - alt Validação remota - MCP_Server->>ThirdParty_IdP: Validar token - ThirdParty_IdP->>MCP_Server: Token válido - else Validação local - MCP_Server->>MCP_Server: Validar token localmente (ex: JWK em cache) - end - MCP_Server->>Client: Dados do recurso -``` - -A próxima especificação MCP [transfere a responsabilidade da autorização para um IdP de terceiros dedicado](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/205). Nesse modelo, o servidor MCP atua apenas como servidor de recursos, e todos os endpoints de autorização vêm diretamente do IdP de terceiros. - -## Por que escolher o MCP Auth? \{#why-choose-mcp-auth} - -- Alinhamento com a especificação: O MCP Auth segue diretamente a direção do último rascunho, tornando-se a única solução compatível tanto com a especificação 03-26 quanto com a futura. -- Chega de soluções alternativas: Em vez de atuar como proxy de servidor de autorização, o MCP Auth permite que o IdP de terceiros gerencie toda a autorização, como previsto na nova especificação. -- Independente de provedor: O MCP Auth funciona com qualquer provedor compatível com OAuth 2.0 / OIDC. -- Transição suave: O MCP Auth retorna todos os endpoints de terceiros como estão via OAuth 2.0 Authorization Server Metadata. Isso mantém a integração simples agora e pronta para mudanças futuras. -- Experiência do desenvolvedor: Oferece tutoriais, utilitários e recursos futuros como [OAuth 2.0 Protected Resource Metadata](https://auth.wiki/protected-resource-metadata) para facilitar a vida dos desenvolvedores de servidores MCP. - -| Recurso | Soluções proxy | MCP Auth | -| ---------------------------------- | -------------------- | -------- | -| Funciona com a especificação 03-26 | ✅ | ✅ | -| Funciona com a futura especificação| ❌ | ✅ | -| Suporta IdPs de terceiros diretamente | ❌ (apenas alternativa) | ✅ | -| Independente de provedor | Limitado[^1] | Sim | -| Pronto para transição | ❌ | ✅ | - -Se você precisa suportar IdPs de terceiros agora e quer estar pronto para a próxima especificação, o MCP Auth é a solução recomendada. Abordagens baseadas em proxy podem em breve ser descontinuadas ou exigir uma reformulação significativa. - -[^1]: Algumas soluções proxy podem codificar parâmetros ou endpoints específicos, limitando a flexibilidade. \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/configure-server/bearer-auth.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/configure-server/bearer-auth.mdx deleted file mode 100644 index e94e0ed..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/configure-server/bearer-auth.mdx +++ /dev/null @@ -1,250 +0,0 @@ ---- -sidebar_position: 2 -sidebar_label: Bearer auth ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -# Configurar autenticação Bearer no servidor MCP - -O MCP Auth oferece várias formas de configurar a autorização Bearer em seu servidor MCP: - -- Modo [JWT (JSON Web Token)](https://auth.wiki/jwt): Um método de autorização integrado que verifica JWTs com afirmações de reivindicações (claims). -- Modo personalizado: Permite implementar sua própria lógica de autorização. - -## Configurar autenticação Bearer com modo JWT \{#configure-bearer-auth-with-jwt-mode} - -Se o seu provedor OAuth / OIDC emitir JWTs para autorização, você pode usar o modo JWT integrado no MCP Auth. Ele verifica a assinatura do JWT, expiração e outras reivindicações que você especificar; em seguida, preenche as informações de autenticação no contexto da requisição para processamento posterior na sua implementação MCP. - -### Validação de escopo (Scope) \{#scope-validation} - -Aqui está um exemplo de validação básica de escopo: - - - - -```python -from mcpauth import MCPAuth -from starlette.applications import Starlette -from starlette.middleware import Middleware -from starlette.routing import Mount -from mcp.server.fastmcp import FastMCP - -mcp = FastMCP("MyMCPServer") -mcp_auth = MCPAuth( - # Inicialize com a configuração do seu servidor de autenticação -) -bearer_auth = mcp_auth.bearer_auth_middleware("jwt", required_scopes=["read", "write"]) # [!code highlight] - -app = Starlette( - routes=[Mount('/', app=mcp.sse_app(), middleware=[Middleware(bearer_auth)])] -) -``` - - - - -```ts -import express from 'express'; -import { MCPAuth } from 'mcp-auth'; - -const app = express(); -const mcpAuth = new MCPAuth({ - /* ... */ -}); -const bearerAuth = mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }); // [!code highlight] - -app.use('/mcp', bearerAuth, (req, res) => { - // Agora `req.auth` contém as informações de autenticação - console.log(req.auth); -}); -``` - - - - -No exemplo acima, especificamos que o JWT requer os escopos `read` e `write`. Se o JWT não contiver **nenhum** desses escopos, a requisição será rejeitada com um erro 403 Forbidden. - -### Validação de indicador de recurso (Resource indicator) (RFC 8707) \{#resource-indicator-validation-rfc-8707} - -Se o seu provedor for baseado em OIDC, ou suportar a extensão [Resource Indicator](https://datatracker.ietf.org/doc/html/rfc8707), você também pode especificar a opção `audience` para validar a reivindicação `aud` (público) no JWT. Isso é útil para garantir que o JWT seja destinado ao seu servidor MCP. - -Verifique a documentação do seu provedor para saber se ele suporta a extensão Resource Indicator e como configurá-la. Alguns provedores podem usar outros termos como "audience", "API resource" ou "API indicator" para se referir ao mesmo conceito. - -Uma vez que o indicador de recurso esteja configurado, você pode especificá-lo no middleware `bearerAuth`: - - - - -```python -bearer_auth = mcp_auth.bearer_auth_middleware( - "jwt", - audience="https://api.example.com/mcp", # O público esperado para o JWT [!code highlight] - required_scopes=["read", "write"] -) -``` - - - - -```ts -const bearerAuth = mcpAuth.bearerAuth('jwt', { - audience: 'https://api.example.com/mcp', // O público esperado para o JWT [!code highlight] - requiredScopes: ['read', 'write'], -}); -``` - - - - -No exemplo acima, o MCP Auth irá validar **tanto** a reivindicação `aud` no JWT quanto os escopos necessários. - -### Fornecer opções personalizadas para a verificação do JWT \{#provide-custom-options-to-the-jwt-verification} - -Você também pode fornecer opções personalizadas para a biblioteca de verificação de JWT subjacente: - - - - -No SDK Python, usamos [PyJWT](https://pyjwt.readthedocs.io/en/stable/) para verificação de JWT. Você pode usar as seguintes opções: - -- `leeway`: Permite uma certa margem ao verificar o tempo de expiração do JWT (em segundos). O padrão é 60 segundos. - -```python -bearer_auth = mcp_auth.bearer_auth_middleware( - "jwt", - audience="https://api.example.com/mcp", - required_scopes=["read", "write"] - leeway=10, # Reduz a diferença de relógio permitindo 10 segundos de margem [!code highlight] -) -``` - - - - -No SDK Node.js, usamos a biblioteca [jose](https://github.com/panva/jose) para verificação de JWT. Você pode fornecer as seguintes opções: - -- `jwtVerify`: Opções para o processo de verificação do JWT (função `jwtVerify` do `jose`). -- `remoteJwtSet`: Opções para buscar o conjunto remoto de JWT (`createRemoteJWKSet` do `jose`). - -```ts {4-9} -const bearerAuth = mcpAuth.bearerAuth('jwt', { - audience: 'https://api.example.com/mcp', - requiredScopes: ['read', 'write'], - jwtVerify: { - clockTolerance: 60, // Permite uma diferença de relógio de 60 segundos - }, - remoteJwtSet: { - timeoutDuration: 10 * 1000, // Timeout de 10 segundos para buscar o conjunto remoto de JWT - }, -}); -``` - - - - -## Configurar autenticação Bearer com verificação personalizada \{#configure-bearer-auth-with-custom-verification} - -Se o seu provedor OAuth / OIDC não emitir JWTs, ou se você quiser implementar sua própria lógica de autorização, o MCP Auth permite criar uma função de verificação personalizada: - -:::info -Como o middleware Bearer auth irá verificar o emissor (`iss`), público (`aud`) e escopos necessários (`scope`) com o resultado da verificação fornecido, não há necessidade de implementar essas verificações em sua função de verificação personalizada. Você pode focar em verificar a validade do token (por exemplo, assinatura, expiração, etc.) e retornar o objeto de informações de autenticação. -::: - - - - -```python -from mcpauth.exceptions import MCPAuthJwtVerificationException, MCPAuthJwtVerificationExceptionCode -from mcpauth.types import AuthInfo - -async def custom_verification(token: str) -> AuthInfo: - # Implemente sua lógica personalizada de verificação aqui - info = await verify_token(token) - if not info: - raise MCPAuthJwtVerificationException( - MCPAuthJwtVerificationExceptionCode.JWT_VERIFICATION_FAILED - ) - return info # Retorne o objeto de informações de autenticação - -bearer_auth = mcp_auth.bearer_auth_middleware( - custom_verification, - required_scopes=["read", "write"] -) -``` - - - - -```ts -const bearerAuth = mcpAuth.bearerAuth( - async (token) => { - // Implemente sua lógica personalizada de verificação aqui - const info = await verifyToken(token); - if (!info) { - throw new MCPAuthJwtVerificationError('jwt_verification_failed'); - } - return info; // Retorne o objeto de informações de autenticação - }, - { requiredScopes: ['read', 'write'] } -); -``` - - - - -## Aplicar autenticação Bearer no seu servidor MCP \{#apply-bearer-auth-in-your-mcp-server} - -Para proteger seu servidor MCP com autenticação Bearer, você precisa aplicar o middleware Bearer auth à instância do seu servidor MCP. - - - - -```python -bearer_auth = mcp_auth.bearer_auth_middleware("jwt", required_scopes=["read", "write"]) -app = Starlette( - routes=[Mount('/', app=mcp.sse_app(), middleware=[Middleware(bearer_auth)])] -) -``` - - - - -```js -const app = express(); -app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] })); -``` - - - - -Isso garantirá que todas as requisições recebidas sejam autenticadas e autorizadas de acordo com as configurações de autenticação Bearer, e as informações de autenticação estarão disponíveis no contexto da requisição. - -Você pode então acessar as informações na implementação do seu servidor MCP: - - - - -```python -@mcp.tool() -async def whoami() -> dict: - # `mcp_auth.auth_info` é o objeto de contexto para a requisição atual - auth_info = mcp_auth.auth_info - print(f"Usuário autenticado: {auth_info.subject}") - return {"subject": auth_info.subject} -``` - - - - -```js -// `authInfo` será carregado a partir do objeto `req.auth` -server.tool('whoami', ({ authInfo }) => { - console.log(`Usuário autenticado: ${authInfo.subject}`); - return { subject: authInfo.subject }; -}); -``` - - - \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/configure-server/mcp-auth.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/configure-server/mcp-auth.mdx deleted file mode 100644 index 17cf96a..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/configure-server/mcp-auth.mdx +++ /dev/null @@ -1,208 +0,0 @@ ---- -sidebar_position: 1 -sidebar_label: MCP Auth ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -# Configurar MCP Auth no servidor MCP - -Para conectar seu servidor MCP a um provedor OAuth 2.1 ou OpenID Connect, você precisa configurar a instância do MCP Auth. Isso envolve inicializar a instância com os metadados do servidor de autorização do seu provedor e configurar os fluxos de autorização necessários. - -## Inicializar MCP Auth \{#init-mcp-auth} - -### Busca automática de metadados \{#automatic-metadata-fetching} - -A maneira mais fácil de inicializar a instância do MCP Auth é usando as funções integradas que buscam os metadados a partir de uma URL well-known. Se o seu provedor estiver em conformidade com um dos seguintes padrões: - -- [Metadados do Servidor de Autorização OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8414) -- [Descoberta OpenID Connect](https://openid.net/specs/openid-connect-discovery-1_0.html) - -Você pode usar o `fetchServerConfig` para recuperar automaticamente os metadados fornecendo a URL do `issuer`: - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType, fetch_server_config - -mcp_auth = MCPAuth( - server=fetch_server_config( - '', - type=AuthServerType.OIDC # ou AuthServerType.OAUTH - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { type: 'oidc' }), // ou 'oauth' -}); -``` - - - - -Se o seu issuer incluir um caminho, o comportamento difere um pouco entre OAuth 2.0 e OpenID Connect: - -- **OAuth 2.0**: A URL well-known é anexada ao **domínio** do issuer. Por exemplo, se seu issuer for `https://my-project.logto.app/oauth`, a URL well-known será `https://auth.logto.io/.well-known/oauth-authorization-server/oauth`. -- **OpenID Connect**: A URL well-known é anexada diretamente ao **issuer**. Por exemplo, se seu issuer for `https://my-project.logto.app/oidc`, a URL well-known será `https://auth.logto.io/oidc/.well-known/openid-configuration`. - -### Outras formas de inicializar o MCP Auth \{#other-ways} - -#### Transpilação personalizada de dados \{#custom-data-transpilation} - -Em alguns casos, os metadados retornados pelo provedor podem não estar no formato esperado. Se você tiver certeza de que o provedor está em conformidade, pode usar a opção `transpile_data` para modificar os metadados antes de serem utilizados: - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -mcp_auth = MCPAuth( - server=fetch_server_config( - '', - type=AuthServerType.OIDC, - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { - type: 'oidc', - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - - -Isso permite que você modifique o objeto de metadados antes que ele seja utilizado pelo MCP Auth. Por exemplo, você pode adicionar ou remover campos, alterar seus valores ou convertê-los para um formato diferente. - -#### Buscar metadados de uma URL específica \{#fetch-metadata-from-a-specific-url} - -Se o seu provedor possui uma URL de metadados específica em vez das padrões, você pode usá-la de forma semelhante: - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config_by_well_known_url - -mcp_auth = MCPAuth( - server=fetch_server_config_by_well_known_url( - '', - type=AuthServerType.OIDC # ou AuthServerType.OAUTH - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfigByWellKnownUrl } from 'mcp-auth'; - -const mcpAuth = new MCPAuth({ - server: await fetchServerConfigByWellKnownUrl('', { type: 'oidc' }), // ou 'oauth' -}); -``` - - - - -#### Buscar metadados de uma URL específica com transpilação personalizada de dados \{#fetch-metadata-from-a-specific-url-with-custom-data-transpilation} - -Em alguns casos, a resposta do provedor pode estar malformada ou não estar em conformidade com o formato de metadados esperado. Se você tiver certeza de que o provedor está em conformidade, pode transpilar os metadados via opção de configuração: - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType, fetch_server_config_by_well_known_url - -mcp_auth = MCPAuth( - server=fetch_server_config_by_well_known_url( - '', - type=AuthServerType.OIDC, - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: await fetchServerConfigByWellKnownUrl('', { - type: 'oidc', - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - - -#### Fornecer metadados manualmente \{#manually-provide-metadata} - -Se o seu provedor não suporta busca de metadados, você pode fornecer manualmente o objeto de metadados: - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerConfig, AuthServerType, AuthorizationServerMetadata - -mcp_auth = MCPAuth( - server=AuthServerConfig( - type=AuthServerType.OIDC, # ou AuthServerType.OAUTH - metadata=AuthorizationServerMetadata( - issuer='', - authorization_endpoint='', - # ... outros campos de metadados - ), - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: { - metadata: { - issuer: '', - // Os campos de metadados devem estar em camelCase - authorizationEndpoint: '', - // ... outros campos de metadados - }, - type: 'oidc', // ou 'oauth' - }, -}); -``` - - - \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/README.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/README.md deleted file mode 100644 index 8797c4a..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/README.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -sidebar_label: Node.js SDK ---- - -# Referência do MCP Auth Node.js SDK - -## Classes \{#classes} - -- [MCPAuth](/references/js/classes/MCPAuth.md) -- [MCPAuthAuthServerError](/references/js/classes/MCPAuthAuthServerError.md) -- [MCPAuthBearerAuthError](/references/js/classes/MCPAuthBearerAuthError.md) -- [MCPAuthConfigError](/references/js/classes/MCPAuthConfigError.md) -- [MCPAuthError](/references/js/classes/MCPAuthError.md) -- [MCPAuthTokenVerificationError](/references/js/classes/MCPAuthTokenVerificationError.md) - -## Alias de Tipos \{#type-aliases} - -- [AuthorizationServerMetadata](/references/js/type-aliases/AuthorizationServerMetadata.md) -- [AuthServerConfig](/references/js/type-aliases/AuthServerConfig.md) -- [AuthServerConfigError](/references/js/type-aliases/AuthServerConfigError.md) -- [AuthServerConfigErrorCode](/references/js/type-aliases/AuthServerConfigErrorCode.md) -- [AuthServerConfigWarning](/references/js/type-aliases/AuthServerConfigWarning.md) -- [AuthServerConfigWarningCode](/references/js/type-aliases/AuthServerConfigWarningCode.md) -- [AuthServerErrorCode](/references/js/type-aliases/AuthServerErrorCode.md) -- [AuthServerSuccessCode](/references/js/type-aliases/AuthServerSuccessCode.md) -- [AuthServerType](/references/js/type-aliases/AuthServerType.md) -- [BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) -- [BearerAuthErrorCode](/references/js/type-aliases/BearerAuthErrorCode.md) -- [BearerAuthJwtConfig](/references/js/type-aliases/BearerAuthJwtConfig.md) -- [CamelCaseAuthorizationServerMetadata](/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md) -- [MCPAuthBearerAuthErrorDetails](/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md) -- [MCPAuthConfig](/references/js/type-aliases/MCPAuthConfig.md) -- [MCPAuthTokenVerificationErrorCode](/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md) -- [VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) -- [VerifyAccessTokenMode](/references/js/type-aliases/VerifyAccessTokenMode.md) - -## Variáveis \{#variables} - -- [authorizationServerMetadataSchema](/references/js/variables/authorizationServerMetadataSchema.md) -- [authServerErrorDescription](/references/js/variables/authServerErrorDescription.md) -- [bearerAuthErrorDescription](/references/js/variables/bearerAuthErrorDescription.md) -- [camelCaseAuthorizationServerMetadataSchema](/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md) -- [serverMetadataPaths](/references/js/variables/serverMetadataPaths.md) -- [tokenVerificationErrorDescription](/references/js/variables/tokenVerificationErrorDescription.md) -- [validateServerConfig](/references/js/variables/validateServerConfig.md) - -## Funções \{#functions} - -- [createVerifyJwt](/references/js/functions/createVerifyJwt.md) -- [fetchServerConfig](/references/js/functions/fetchServerConfig.md) -- [fetchServerConfigByWellKnownUrl](/references/js/functions/fetchServerConfigByWellKnownUrl.md) -- [handleBearerAuth](/references/js/functions/handleBearerAuth.md) diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuth.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuth.md deleted file mode 100644 index db5172b..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuth.md +++ /dev/null @@ -1,195 +0,0 @@ ---- -sidebar_label: MCPAuth ---- - -# Classe: MCPAuth - -A classe principal da biblioteca mcp-auth, que fornece métodos para criar roteadores e manipuladores úteis para autenticação (Autenticação) e autorização (Autorização) em servidores MCP. - -## Veja também {#see} - -[MCP Auth](https://mcp-auth.dev) para mais informações sobre a biblioteca e seu uso. - -## Exemplo {#example} - -Um exemplo integrando com um provedor OIDC remoto: - -```ts -import express from 'express'; -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const app = express(); -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig( - 'https://auth.logto.io/oidc', - { type: 'oidc' } - ), -}); - -// Monta o roteador para lidar com o Metadata do Servidor de Autorização OAuth 2.0 -app.use(mcpAuth.delegatedRouter()); - -// Usa o manipulador Bearer auth na rota MCP -app.get( - '/mcp', - mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }), - (req, res) => { - console.log('Auth info:', req.auth); - // Lide com a requisição MCP aqui - }, -); - -// Usa as informações de autenticação no callback MCP -server.tool( - 'add', - { a: z.number(), b: z.number() }, - async ({ a, b }, { authInfo }) => { - console.log('Auth Info:', authInfo); - // ... - }, -); -``` - -## Construtores {#constructors} - -### Construtor {#constructor} - -```ts -new MCPAuth(config: MCPAuthConfig): MCPAuth; -``` - -#### Parâmetros {#parameters} - -##### config {#config} - -[`MCPAuthConfig`](/references/js/type-aliases/MCPAuthConfig.md) - -#### Retorna {#returns} - -`MCPAuth` - -## Propriedades {#properties} - -### config {#config} - -```ts -readonly config: MCPAuthConfig; -``` - -## Métodos {#methods} - -### bearerAuth() {#bearerauth} - -#### Assinatura de chamada {#call-signature} - -```ts -bearerAuth(verifyAccessToken: VerifyAccessTokenFunction, config?: Omit): RequestHandler; -``` - -Cria um manipulador Bearer auth (middleware Express) que verifica o token de acesso (Access token) no cabeçalho `Authorization` da requisição. - -##### Parâmetros {#parameters} - -###### verifyAccessToken {#verifyaccesstoken} - -[`VerifyAccessTokenFunction`](/references/js/type-aliases/VerifyAccessTokenFunction.md) - -Uma função que verifica o token de acesso (Access token). Deve aceitar o token de acesso como uma string e retornar uma promise (ou um valor) que resolve para o resultado da verificação. - -**Veja também** - -[VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) para a definição do tipo da função `verifyAccessToken`. - -###### config? {#config} - -`Omit`\<[`BearerAuthConfig`](/references/js/type-aliases/BearerAuthConfig.md), `"verifyAccessToken"` \| `"issuer"`\> - -Configuração opcional para o manipulador Bearer auth. - -**Veja também** - -[BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) para as opções de configuração disponíveis (excluindo `verifyAccessToken` e `issuer`). - -##### Retorna {#returns} - -`RequestHandler` - -Uma função middleware Express que verifica o token de acesso (Access token) e adiciona o resultado da verificação ao objeto da requisição (`req.auth`). - -##### Veja também {#see} - -[handleBearerAuth](/references/js/functions/handleBearerAuth.md) para detalhes da implementação e os tipos estendidos do objeto `req.auth` (`AuthInfo`). - -#### Assinatura de chamada {#call-signature} - -```ts -bearerAuth(mode: "jwt", config?: Omit & BearerAuthJwtConfig): RequestHandler; -``` - -Cria um manipulador Bearer auth (middleware Express) que verifica o token de acesso (Access token) no cabeçalho `Authorization` da requisição usando um modo de verificação predefinido. - -No modo `'jwt'`, o manipulador criará uma função de verificação de JWT usando o JWK Set do URI JWKS do servidor de autorização (Authorization). - -##### Parâmetros {#parameters} - -###### mode {#mode} - -`"jwt"` - -O modo de verificação para o token de acesso (Access token). Atualmente, apenas 'jwt' é suportado. - -**Veja também** - -[VerifyAccessTokenMode](/references/js/type-aliases/VerifyAccessTokenMode.md) para os modos disponíveis. - -###### config? {#config} - -`Omit`\<[`BearerAuthConfig`](/references/js/type-aliases/BearerAuthConfig.md), `"verifyAccessToken"` \| `"issuer"`\> & [`BearerAuthJwtConfig`](/references/js/type-aliases/BearerAuthJwtConfig.md) - -Configuração opcional para o manipulador Bearer auth, incluindo opções de verificação JWT e opções remotas de JWK set. - -**Veja também** - - - [BearerAuthJwtConfig](/references/js/type-aliases/BearerAuthJwtConfig.md) para as opções de configuração disponíveis para verificação JWT. - - [BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) para as opções de configuração disponíveis (excluindo `verifyAccessToken` e `issuer`). - -##### Retorna {#returns} - -`RequestHandler` - -Uma função middleware Express que verifica o token de acesso (Access token) e adiciona o resultado da verificação ao objeto da requisição (`req.auth`). - -##### Veja também {#see} - -[handleBearerAuth](/references/js/functions/handleBearerAuth.md) para detalhes da implementação e os tipos estendidos do objeto `req.auth` (`AuthInfo`). - -##### Lança {#throws} - -se o URI JWKS não for fornecido nos metadados do servidor ao usar o modo `'jwt'`. - -*** - -### delegatedRouter() {#delegatedrouter} - -```ts -delegatedRouter(): Router; -``` - -Cria um roteador delegado que serve o endpoint Metadata do Servidor de Autorização OAuth 2.0 (`/.well-known/oauth-authorization-server`) com os metadados fornecidos para a instância. - -#### Retorna {#returns} - -`Router` - -Um roteador que serve o endpoint Metadata do Servidor de Autorização OAuth 2.0 com os metadados fornecidos para a instância. - -#### Exemplo {#example} - -```ts -import express from 'express'; -import { MCPAuth } from 'mcp-auth'; - -const app = express(); -const mcpAuth: MCPAuth; // Suponha que já esteja inicializado -app.use(mcpAuth.delegatedRouter()); -``` \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthAuthServerError.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthAuthServerError.md deleted file mode 100644 index e80f115..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthAuthServerError.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -sidebar_label: MCPAuthAuthServerError ---- - -# Classe: MCPAuthAuthServerError - -Erro lançado quando há um problema com o servidor de autorização remoto. - -## Estende {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## Construtores {#constructors} - -### Construtor {#constructor} - -```ts -new MCPAuthAuthServerError(code: AuthServerErrorCode, cause?: unknown): MCPAuthAuthServerError; -``` - -#### Parâmetros {#parameters} - -##### code {#code} - -[`AuthServerErrorCode`](/references/js/type-aliases/AuthServerErrorCode.md) - -##### cause? {#cause} - -`unknown` - -#### Retorna {#returns} - -`MCPAuthAuthServerError` - -#### Sobrescreve {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## Propriedades {#properties} - -### cause? {#cause} - -```ts -readonly optional cause: unknown; -``` - -#### Herdado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: AuthServerErrorCode; -``` - -O código de erro no formato snake_case. - -#### Herdado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### Herdado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthAuthServerError'; -``` - -#### Sobrescreve {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### Herdado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -Sobrescrita opcional para formatação de rastreamentos de pilha - -#### Parâmetros {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### Retorna {#returns} - -`any` - -#### Veja também {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### Herdado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### Herdado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## Métodos {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -Converte o erro para um formato JSON amigável para resposta HTTP. - -#### Parâmetros {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -Se deve incluir a causa do erro na resposta JSON. -O padrão é `false`. - -#### Retorna {#returns} - -`Record`\<`string`, `unknown`\> - -#### Herdado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -Cria a propriedade .stack em um objeto de destino - -#### Parâmetros {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### Retorna {#returns} - -`void` - -#### Herdado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthBearerAuthError.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthBearerAuthError.md deleted file mode 100644 index faa9d73..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthBearerAuthError.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -sidebar_label: MCPAuthBearerAuthError ---- - -# Classe: MCPAuthBearerAuthError - -Erro lançado quando há um problema ao autenticar com tokens Bearer. - -## Estende {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## Construtores {#constructors} - -### Construtor {#constructor} - -```ts -new MCPAuthBearerAuthError(code: BearerAuthErrorCode, cause?: MCPAuthBearerAuthErrorDetails): MCPAuthBearerAuthError; -``` - -#### Parâmetros {#parameters} - -##### code {#code} - -[`BearerAuthErrorCode`](/references/js/type-aliases/BearerAuthErrorCode.md) - -##### cause? {#cause} - -[`MCPAuthBearerAuthErrorDetails`](/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md) - -#### Retorna {#returns} - -`MCPAuthBearerAuthError` - -#### Sobrescreve {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## Propriedades {#properties} - -### cause? {#cause} - -```ts -readonly optional cause: MCPAuthBearerAuthErrorDetails; -``` - -#### Herdado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: BearerAuthErrorCode; -``` - -O código de erro no formato snake_case. - -#### Herdado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### Herdado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthBearerAuthError'; -``` - -#### Sobrescreve {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### Herdado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -Sobrescrita opcional para formatação de rastreamentos de pilha - -#### Parâmetros {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### Retorna {#returns} - -`any` - -#### Veja também {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### Herdado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### Herdado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## Métodos {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -Converte o erro para um formato JSON amigável para resposta HTTP. - -#### Parâmetros {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -Se deve incluir a causa do erro na resposta JSON. -O padrão é `false`. - -#### Retorna {#returns} - -`Record`\<`string`, `unknown`\> - -#### Sobrescreve {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -Cria a propriedade .stack em um objeto alvo - -#### Parâmetros {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### Retorna {#returns} - -`void` - -#### Herdado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthConfigError.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthConfigError.md deleted file mode 100644 index 4f76114..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthConfigError.md +++ /dev/null @@ -1,202 +0,0 @@ ---- -sidebar_label: MCPAuthConfigError ---- - -# Classe: MCPAuthConfigError - -Erro lançado quando há um problema de configuração com o mcp-auth. - -## Estende {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## Construtores {#constructors} - -### Construtor {#constructor} - -```ts -new MCPAuthConfigError(code: string, message: string): MCPAuthConfigError; -``` - -#### Parâmetros {#parameters} - -##### code {#code} - -`string` - -O código do erro no formato snake_case. - -##### message {#message} - -`string` - -Uma descrição legível do erro. - -#### Retorna {#returns} - -`MCPAuthConfigError` - -#### Herdado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## Propriedades {#properties} - -### cause? {#cause} - -```ts -optional cause: unknown; -``` - -#### Herdado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: string; -``` - -O código do erro no formato snake_case. - -#### Herdado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### Herdado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthConfigError'; -``` - -#### Sobrescreve {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### Herdado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -Sobrescrita opcional para formatação de rastreamentos de pilha - -#### Parâmetros {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### Retorna {#returns} - -`any` - -#### Veja também {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### Herdado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### Herdado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## Métodos {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -Converte o erro para um formato JSON amigável para resposta HTTP. - -#### Parâmetros {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -Se deve incluir a causa do erro na resposta JSON. -O padrão é `false`. - -#### Retorna {#returns} - -`Record`\<`string`, `unknown`\> - -#### Herdado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -Cria a propriedade .stack em um objeto alvo - -#### Parâmetros {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### Retorna {#returns} - -`void` - -#### Herdado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthError.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthError.md deleted file mode 100644 index 32fa6f2..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthError.md +++ /dev/null @@ -1,219 +0,0 @@ ---- -sidebar_label: MCPAuthError ---- - -# Classe: MCPAuthError - -Classe base para todos os erros do mcp-auth. - -Ela fornece uma maneira padronizada de lidar com erros relacionados à autenticação (Authentication) e autorização (Authorization) MCP. - -## Estende {#extends} - -- `Error` - -## Estendida por {#extended-by} - -- [`MCPAuthConfigError`](/references/js/classes/MCPAuthConfigError.md) -- [`MCPAuthAuthServerError`](/references/js/classes/MCPAuthAuthServerError.md) -- [`MCPAuthBearerAuthError`](/references/js/classes/MCPAuthBearerAuthError.md) -- [`MCPAuthTokenVerificationError`](/references/js/classes/MCPAuthTokenVerificationError.md) - -## Construtores {#constructors} - -### Construtor {#constructor} - -```ts -new MCPAuthError(code: string, message: string): MCPAuthError; -``` - -#### Parâmetros {#parameters} - -##### code {#code} - -`string` - -O código do erro no formato snake_case. - -##### message {#message} - -`string` - -Uma descrição legível do erro. - -#### Retorna {#returns} - -`MCPAuthError` - -#### Sobrescreve {#overrides} - -```ts -Error.constructor -``` - -## Propriedades {#properties} - -### cause? {#cause} - -```ts -optional cause: unknown; -``` - -#### Herdado de {#inherited-from} - -```ts -Error.cause -``` - -*** - -### code {#code} - -```ts -readonly code: string; -``` - -O código do erro no formato snake_case. - -*** - -### message {#message} - -```ts -message: string; -``` - -#### Herdado de {#inherited-from} - -```ts -Error.message -``` - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthError'; -``` - -#### Sobrescreve {#overrides} - -```ts -Error.name -``` - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### Herdado de {#inherited-from} - -```ts -Error.stack -``` - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -Sobrescrita opcional para formatação de rastreamentos de pilha - -#### Parâmetros {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### Retorna {#returns} - -`any` - -#### Veja também {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### Herdado de {#inherited-from} - -```ts -Error.prepareStackTrace -``` - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### Herdado de {#inherited-from} - -```ts -Error.stackTraceLimit -``` - -## Métodos {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -Converte o erro para um formato JSON amigável para resposta HTTP. - -#### Parâmetros {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -Se deve incluir a causa do erro na resposta JSON. -O padrão é `false`. - -#### Retorna {#returns} - -`Record`\<`string`, `unknown`\> - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -Cria a propriedade .stack em um objeto alvo - -#### Parâmetros {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### Retorna {#returns} - -`void` - -#### Herdado de {#inherited-from} - -```ts -Error.captureStackTrace -``` diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthTokenVerificationError.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthTokenVerificationError.md deleted file mode 100644 index 98d6e58..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthTokenVerificationError.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -sidebar_label: MCPAuthTokenVerificationError ---- - -# Classe: MCPAuthTokenVerificationError - -Erro lançado quando há um problema ao verificar tokens. - -## Estende {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## Construtores {#constructors} - -### Construtor {#constructor} - -```ts -new MCPAuthTokenVerificationError(code: MCPAuthTokenVerificationErrorCode, cause?: unknown): MCPAuthTokenVerificationError; -``` - -#### Parâmetros {#parameters} - -##### code {#code} - -[`MCPAuthTokenVerificationErrorCode`](/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md) - -##### cause? {#cause} - -`unknown` - -#### Retorna {#returns} - -`MCPAuthTokenVerificationError` - -#### Sobrescreve {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## Propriedades {#properties} - -### cause? {#cause} - -```ts -readonly optional cause: unknown; -``` - -#### Herdado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: MCPAuthTokenVerificationErrorCode; -``` - -O código de erro no formato snake_case. - -#### Herdado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### Herdado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthTokenVerificationError'; -``` - -#### Sobrescreve {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### Herdado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -Sobrescrita opcional para formatação de rastreamentos de pilha - -#### Parâmetros {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### Retorna {#returns} - -`any` - -#### Veja também {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### Herdado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### Herdado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## Métodos {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -Converte o erro para um formato JSON amigável para resposta HTTP. - -#### Parâmetros {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -Se deve incluir a causa do erro na resposta JSON. -O padrão é `false`. - -#### Retorna {#returns} - -`Record`\<`string`, `unknown`\> - -#### Herdado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -Cria a propriedade .stack em um objeto alvo - -#### Parâmetros {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### Retorna {#returns} - -`void` - -#### Herdado de {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/createVerifyJwt.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/createVerifyJwt.md deleted file mode 100644 index 083b554..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/createVerifyJwt.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -sidebar_label: createVerifyJwt ---- - -# Função: createVerifyJwt() - -```ts -function createVerifyJwt(getKey: JWTVerifyGetKey, options?: JWTVerifyOptions): VerifyAccessTokenFunction; -``` - -Cria uma função para verificar tokens de acesso JWT usando a função de recuperação de chave fornecida -e opções. - -## Parâmetros {#parameters} - -### getKey {#getkey} - -`JWTVerifyGetKey` - -A função para recuperar a chave usada para verificar o JWT. - -**Veja também** - -JWTVerifyGetKey para a definição de tipo da função de recuperação de chave. - -### options? {#options} - -`JWTVerifyOptions` - -Opções opcionais de verificação de JWT. - -**Veja também** - -JWTVerifyOptions para a definição de tipo das opções. - -## Retorno {#returns} - -[`VerifyAccessTokenFunction`](/references/js/type-aliases/VerifyAccessTokenFunction.md) - -Uma função que verifica tokens de acesso JWT (Access tokens) e retorna um objeto AuthInfo se -o token for válido. Ela exige que o JWT contenha os campos `iss`, `client_id` e `sub` em -seu payload, e pode opcionalmente conter os campos `scope` ou `scopes`. A função utiliza a -biblioteca `jose` internamente para realizar a verificação do JWT. - -## Veja também {#see} - -[VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) para a definição de tipo da função retornada. \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfig.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfig.md deleted file mode 100644 index a845427..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfig.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -sidebar_label: fetchServerConfig ---- - -# Função: fetchServerConfig() - -```ts -function fetchServerConfig(issuer: string, config: ServerMetadataConfig): Promise; -``` - -Busca a configuração do servidor de acordo com o emissor (Issuer) e o tipo de servidor de autorização (Authorization). - -Esta função determina automaticamente a URL well-known com base no tipo de servidor, já que servidores OAuth e -OpenID Connect possuem convenções diferentes para seus endpoints de metadados. - -## Parâmetros {#parameters} - -### issuer {#issuer} - -`string` - -A URL do emissor (Issuer) do servidor de autorização (Authorization). - -### config {#config} - -`ServerMetadataConfig` - -O objeto de configuração contendo o tipo de servidor e a função de transpile opcional. - -## Retorno {#returns} - -`Promise`\<[`AuthServerConfig`](/references/js/type-aliases/AuthServerConfig.md)\> - -Uma promise que resolve para a configuração do servidor. - -## Veja também {#see} - - - [fetchServerConfigByWellKnownUrl](/references/js/functions/fetchServerConfigByWellKnownUrl.md) para a implementação subjacente. - - [https://www.rfc-editor.org/rfc/rfc8414](https://www.rfc-editor.org/rfc/rfc8414) para a especificação de Metadados do Servidor de Autorização OAuth 2.0. - - [https://openid.net/specs/openid-connect-discovery-1\_0.html](https://openid.net/specs/openid-connect-discovery-1_0.html) para a especificação de Descoberta do OpenID Connect. - -## Exemplo {#example} - -```ts -import { fetchServerConfig } from 'mcp-auth'; -// Buscando configuração do servidor OAuth -// Isso buscará os metadados de `https://auth.logto.io/.well-known/oauth-authorization-server/oauth` -const oauthConfig = await fetchServerConfig('https://auth.logto.io/oauth', { type: 'oauth' }); - -// Buscando configuração do servidor OpenID Connect -// Isso buscará os metadados de `https://auth.logto.io/oidc/.well-known/openid-configuration` -const oidcConfig = await fetchServerConfig('https://auth.logto.io/oidc', { type: 'oidc' }); -``` - -## Lança exceção {#throws} - -se a operação de busca falhar. - -## Lança exceção {#throws} - -se os metadados do servidor forem inválidos ou não corresponderem à -especificação MCP. \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfigByWellKnownUrl.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfigByWellKnownUrl.md deleted file mode 100644 index 85ae065..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfigByWellKnownUrl.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -sidebar_label: fetchServerConfigByWellKnownUrl ---- - -# Função: fetchServerConfigByWellKnownUrl() - -```ts -function fetchServerConfigByWellKnownUrl(wellKnownUrl: string | URL, config: ServerMetadataConfig): Promise; -``` - -Busca a configuração do servidor a partir da well-known URL fornecida e a valida conforme a especificação MCP. - -Se os metadados do servidor não estiverem em conformidade com o esquema esperado, mas você tiver certeza de que são compatíveis, é possível definir uma função `transpileData` para transformar os metadados no formato esperado. - -## Parâmetros {#parameters} - -### wellKnownUrl {#wellknownurl} - -A well-known URL de onde buscar a configuração do servidor. Pode ser uma string ou um objeto URL. - -`string` | `URL` - -### config {#config} - -`ServerMetadataConfig` - -O objeto de configuração contendo o tipo do servidor e, opcionalmente, a função de transpile. - -## Retorno {#returns} - -`Promise`\<[`AuthServerConfig`](/references/js/type-aliases/AuthServerConfig.md)\> - -Uma promise que resolve para a configuração do servidor. - -## Lança exceção {#throws} - -se a operação de busca falhar. - -## Lança exceção {#throws} - -se os metadados do servidor forem inválidos ou não corresponderem à especificação MCP. \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/handleBearerAuth.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/handleBearerAuth.md deleted file mode 100644 index 3c9d1fa..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/handleBearerAuth.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -sidebar_label: handleBearerAuth ---- - -# Função: handleBearerAuth() - -```ts -function handleBearerAuth(param0: BearerAuthConfig): RequestHandler; -``` - -Cria uma função middleware para lidar com autenticação Bearer em uma aplicação Express. - -Este middleware extrai o token Bearer do cabeçalho `Authorization`, verifica-o usando a função -`verifyAccessToken` fornecida e checa o emissor (Issuer), público (Audience) e escopos (Scopes) necessários. - -- Se o token for válido, adiciona as informações de autenticação à propriedade `request.auth`; -caso contrário, responde com uma mensagem de erro apropriada. -- Se a verificação do token de acesso (Access token) falhar, responde com um erro 401 Não autorizado. -- Se o token não possuir os escopos (Scopes) necessários, responde com um erro 403 Proibido. -- Se ocorrerem erros inesperados durante o processo de autenticação (Authentication), o middleware irá relançá-los. - -**Nota:** O objeto `request.auth` conterá campos estendidos em comparação com a interface padrão -AuthInfo definida no módulo `@modelcontextprotocol/sdk`. Veja a interface estendida neste arquivo para mais detalhes. - -## Parâmetros {#parameters} - -### param0 {#param0} - -[`BearerAuthConfig`](/references/js/type-aliases/BearerAuthConfig.md) - -Configuração para o manipulador de autenticação Bearer. - -## Retorno {#returns} - -`RequestHandler` - -Uma função middleware para Express que lida com autenticação Bearer. - -## Veja também {#see} - -[BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) para as opções de configuração. \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfig.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfig.md deleted file mode 100644 index 76476e0..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfig.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -sidebar_label: AuthServerConfig ---- - -# Alias de Tipo: AuthServerConfig - -```ts -type AuthServerConfig = { - metadata: CamelCaseAuthorizationServerMetadata; - type: AuthServerType; -}; -``` - -Configuração para o servidor de autorização remoto integrado com o servidor MCP. - -## Propriedades {#properties} - -### metadata {#metadata} - -```ts -metadata: CamelCaseAuthorizationServerMetadata; -``` - -Os metadados do servidor de autorização, que devem estar em conformidade com a especificação MCP -(baseada nos Metadados do Servidor de Autorização OAuth 2.0). - -Esses metadados são normalmente obtidos a partir do endpoint well-known do servidor (Metadados do Servidor de Autorização OAuth 2.0 -ou OpenID Connect Discovery); eles também podem ser fornecidos -diretamente na configuração caso o servidor não suporte tais endpoints. - -**Nota:** Os metadados devem estar no formato camelCase conforme preferido pela biblioteca mcp-auth. - -#### Veja também {#see} - - - [Metadados do Servidor de Autorização OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8414) - - [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) - -*** - -### type {#type} - -```ts -type: AuthServerType; -``` - -O tipo do servidor de autorização. - -#### Veja também {#see} - -[AuthServerType](/references/js/type-aliases/AuthServerType.md) para os valores possíveis. \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigError.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigError.md deleted file mode 100644 index bce4d15..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigError.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -sidebar_label: AuthServerConfigError ---- - -# Alias de Tipo: AuthServerConfigError - -```ts -type AuthServerConfigError = { - cause?: Error; - code: AuthServerConfigErrorCode; - description: string; -}; -``` - -Representa um erro que ocorre durante a validação dos metadados do servidor de autorização (authorization server). - -## Propriedades {#properties} - -### cause? {#cause} - -```ts -optional cause: Error; -``` - -Uma causa opcional do erro, normalmente uma instância de `Error` que fornece mais contexto. - -*** - -### code {#code} - -```ts -code: AuthServerConfigErrorCode; -``` - -O código que representa o erro de validação específico. - -*** - -### description {#description} - -```ts -description: string; -``` - -Uma descrição legível do erro. \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigErrorCode.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigErrorCode.md deleted file mode 100644 index d6e374d..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigErrorCode.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_label: AuthServerConfigErrorCode ---- - -# Alias de Tipo: AuthServerConfigErrorCode - -```ts -type AuthServerConfigErrorCode = - | "invalid_server_metadata" - | "code_response_type_not_supported" - | "authorization_code_grant_not_supported" - | "pkce_not_supported" - | "s256_code_challenge_method_not_supported"; -``` - -Os códigos para erros que podem ocorrer ao validar os metadados do servidor de autorização. \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarning.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarning.md deleted file mode 100644 index dc4b057..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarning.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -sidebar_label: AuthServerConfigWarning ---- - -# Alias de Tipo: AuthServerConfigWarning - -```ts -type AuthServerConfigWarning = { - code: AuthServerConfigWarningCode; - description: string; -}; -``` - -Representa um aviso que ocorre durante a validação dos metadados do servidor de autorização (authorization server). - -## Propriedades {#properties} - -### code {#code} - -```ts -code: AuthServerConfigWarningCode; -``` - -O código que representa o aviso de validação específico. - -*** - -### description {#description} - -```ts -description: string; -``` - -Uma descrição legível por humanos do aviso. \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarningCode.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarningCode.md deleted file mode 100644 index 3e2035f..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarningCode.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -sidebar_label: AuthServerConfigWarningCode ---- - -# Alias de Tipo: AuthServerConfigWarningCode - -```ts -type AuthServerConfigWarningCode = "dynamic_registration_not_supported"; -``` - -Os códigos para avisos que podem ocorrer ao validar os metadados do servidor de autorização. \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerErrorCode.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerErrorCode.md deleted file mode 100644 index 5c2a3fd..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerErrorCode.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_label: AuthServerErrorCode ---- - -# Alias de Tipo: AuthServerErrorCode - -```ts -type AuthServerErrorCode = - | "invalid_server_metadata" - | "invalid_server_config" - | "missing_jwks_uri"; -``` diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerSuccessCode.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerSuccessCode.md deleted file mode 100644 index a5cb4c5..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerSuccessCode.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -sidebar_label: AuthServerSuccessCode ---- - -# Alias de Tipo: AuthServerSuccessCode - -```ts -type AuthServerSuccessCode = - | "server_metadata_valid" - | "dynamic_registration_supported" - | "pkce_supported" - | "s256_code_challenge_method_supported" - | "authorization_code_grant_supported" - | "code_response_type_supported"; -``` - -Os códigos para validação bem-sucedida dos metadados do servidor de autorização. \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerType.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerType.md deleted file mode 100644 index 1252cf4..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerType.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -sidebar_label: AuthServerType ---- - -# Alias de Tipo: AuthServerType - -```ts -type AuthServerType = "oauth" | "oidc"; -``` - -O tipo do servidor de autorização (authorization server). Esta informação deve ser fornecida pela configuração do servidor e indica se o servidor é um servidor de autorização OAuth 2.0 ou OpenID Connect (OIDC). \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthorizationServerMetadata.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthorizationServerMetadata.md deleted file mode 100644 index 714d536..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthorizationServerMetadata.md +++ /dev/null @@ -1,234 +0,0 @@ ---- -sidebar_label: AuthorizationServerMetadata ---- - -# Alias de Tipo: AuthorizationServerMetadata - -```ts -type AuthorizationServerMetadata = { - authorization_endpoint: string; - code_challenge_methods_supported?: string[]; - grant_types_supported?: string[]; - introspection_endpoint?: string; - introspection_endpoint_auth_methods_supported?: string[]; - introspection_endpoint_auth_signing_alg_values_supported?: string[]; - issuer: string; - jwks_uri?: string; - op_policy_uri?: string; - op_tos_uri?: string; - registration_endpoint?: string; - response_modes_supported?: string[]; - response_types_supported: string[]; - revocation_endpoint?: string; - revocation_endpoint_auth_methods_supported?: string[]; - revocation_endpoint_auth_signing_alg_values_supported?: string[]; - scope_supported?: string[]; - service_documentation?: string; - token_endpoint: string; - token_endpoint_auth_methods_supported?: string[]; - token_endpoint_auth_signing_alg_values_supported?: string[]; - ui_locales_supported?: string[]; - userinfo_endpoint?: string; -}; -``` - -Esquema para os metadados do Servidor de Autorização OAuth 2.0 conforme definido na RFC 8414. - -## Declaração do tipo {#type-declaration} - -### authorization\_endpoint {#authorization-endpoint} - -```ts -authorization_endpoint: string; -``` - -URL do endpoint de autorização do servidor de autorização [[RFC6749](https://rfc-editor.org/rfc/rfc6749)]. -Isto é OBRIGATÓRIO, a menos que nenhum tipo de concessão seja suportado que utilize o endpoint de autorização. - -#### Veja {#see} - -https://rfc-editor.org/rfc/rfc6749#section-3.1 - -### code\_challenge\_methods\_supported? {#code-challenge-methods-supported} - -```ts -optional code_challenge_methods_supported: string[]; -``` - -Array JSON contendo uma lista de métodos de desafio de código Proof Key for Code Exchange (PKCE) -[[RFC7636](https://www.rfc-editor.org/rfc/rfc7636)] suportados por este servidor de autorização. - -### grant\_types\_supported? {#grant-types-supported} - -```ts -optional grant_types_supported: string[]; -``` - -Array JSON contendo uma lista dos valores de tipo de concessão OAuth 2.0 que este servidor de autorização -suporta. Os valores do array usados são os mesmos usados com o parâmetro `grant_types` -definido pelo "OAuth 2.0 Dynamic Client Registration Protocol" [[RFC7591](https://www.rfc-editor.org/rfc/rfc7591)]. -Se omitido, o valor padrão é `["authorization_code", "implicit"]`. - -### introspection\_endpoint? {#introspection-endpoint} - -```ts -optional introspection_endpoint: string; -``` - -URL do endpoint de introspecção OAuth 2.0 do servidor de autorização -[[RFC7662](https://www.rfc-editor.org/rfc/rfc7662)]. - -### introspection\_endpoint\_auth\_methods\_supported? {#introspection-endpoint-auth-methods-supported} - -```ts -optional introspection_endpoint_auth_methods_supported: string[]; -``` - -### introspection\_endpoint\_auth\_signing\_alg\_values\_supported? {#introspection-endpoint-auth-signing-alg-values-supported} - -```ts -optional introspection_endpoint_auth_signing_alg_values_supported: string[]; -``` - -### issuer {#issuer} - -```ts -issuer: string; -``` - -O identificador do emissor (Issuer) do servidor de autorização, que é uma URL que utiliza o esquema `https` e -não possui componentes de consulta ou fragmento. - -### jwks\_uri? {#jwks-uri} - -```ts -optional jwks_uri: string; -``` - -URL do documento JWK Set [[JWK](https://www.rfc-editor.org/rfc/rfc8414.html#ref-JWK)] -do servidor de autorização. O documento referenciado contém a(s) chave(s) de assinatura que o cliente usa para validar -assinaturas do servidor de autorização. Esta URL DEVE usar o esquema `https`. - -### op\_policy\_uri? {#op-policy-uri} - -```ts -optional op_policy_uri: string; -``` - -### op\_tos\_uri? {#op-tos-uri} - -```ts -optional op_tos_uri: string; -``` - -### registration\_endpoint? {#registration-endpoint} - -```ts -optional registration_endpoint: string; -``` - -URL do endpoint de Registro Dinâmico de Cliente OAuth 2.0 do servidor de autorização -[[RFC7591](https://www.rfc-editor.org/rfc/rfc7591)]. - -### response\_modes\_supported? {#response-modes-supported} - -```ts -optional response_modes_supported: string[]; -``` - -Array JSON contendo uma lista dos valores de `response_mode` do OAuth 2.0 que este -servidor de autorização suporta, conforme especificado em "OAuth 2.0 Multiple Response -Type Encoding Practices" -[[OAuth.Responses](https://datatracker.ietf.org/doc/html/rfc8414#ref-OAuth.Responses)]. - -Se omitido, o padrão é `["query", "fragment"]`. O valor de response mode `"form_post"` também é -definido em "OAuth 2.0 Form Post Response Mode" -[[OAuth.FormPost](https://datatracker.ietf.org/doc/html/rfc8414#ref-OAuth.Post)]. - -### response\_types\_supported {#response-types-supported} - -```ts -response_types_supported: string[]; -``` - -Array JSON contendo uma lista dos valores de `response_type` do OAuth 2.0 que este servidor de autorização -suporta. Os valores do array usados são os mesmos usados com o parâmetro `response_types` -definido pelo "OAuth 2.0 Dynamic Client Registration Protocol" -[[RFC7591](https://www.rfc-editor.org/rfc/rfc7591)]. - -### revocation\_endpoint? {#revocation-endpoint} - -```ts -optional revocation_endpoint: string; -``` - -URL do endpoint de revogação OAuth 2.0 do servidor de autorização -[[RFC7009](https://www.rfc-editor.org/rfc/rfc7009)]. - -### revocation\_endpoint\_auth\_methods\_supported? {#revocation-endpoint-auth-methods-supported} - -```ts -optional revocation_endpoint_auth_methods_supported: string[]; -``` - -### revocation\_endpoint\_auth\_signing\_alg\_values\_supported? {#revocation-endpoint-auth-signing-alg-values-supported} - -```ts -optional revocation_endpoint_auth_signing_alg_values_supported: string[]; -``` - -### scope\_supported? {#scope-supported} - -```ts -optional scope_supported: string[]; -``` - -### service\_documentation? {#service-documentation} - -```ts -optional service_documentation: string; -``` - -### token\_endpoint {#token-endpoint} - -```ts -token_endpoint: string; -``` - -URL do endpoint de token do servidor de autorização [[RFC6749](https://rfc-editor.org/rfc/rfc6749)]. -Isto é OBRIGATÓRIO, a menos que apenas o tipo de concessão implícita seja suportado. - -#### Veja {#see} - -https://rfc-editor.org/rfc/rfc6749#section-3.2 - -### token\_endpoint\_auth\_methods\_supported? {#token-endpoint-auth-methods-supported} - -```ts -optional token_endpoint_auth_methods_supported: string[]; -``` - -### token\_endpoint\_auth\_signing\_alg\_values\_supported? {#token-endpoint-auth-signing-alg-values-supported} - -```ts -optional token_endpoint_auth_signing_alg_values_supported: string[]; -``` - -### ui\_locales\_supported? {#ui-locales-supported} - -```ts -optional ui_locales_supported: string[]; -``` - -### userinfo\_endpoint? {#userinfo-endpoint} - -```ts -optional userinfo_endpoint: string; -``` - -URL do [endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) do OpenID Connect. -Este endpoint é usado para recuperar informações sobre o usuário autenticado. - -## Veja {#see} - -https://datatracker.ietf.org/doc/html/rfc8414 \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthConfig.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthConfig.md deleted file mode 100644 index e6ad246..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthConfig.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -sidebar_label: BearerAuthConfig ---- - -# Alias de Tipo: BearerAuthConfig - -```ts -type BearerAuthConfig = { - audience?: string; - issuer: string; - requiredScopes?: string[]; - showErrorDetails?: boolean; - verifyAccessToken: VerifyAccessTokenFunction; -}; -``` - -## Propriedades {#properties} - -### audience? {#audience} - -```ts -optional audience: string; -``` - -O público (Audience) esperado do token de acesso (`aud` claim). Normalmente, este é o servidor de recursos -(API) para o qual o token se destina. Se não for fornecido, a verificação do público será ignorada. - -**Nota:** Se seu servidor de autorização não suporta Indicadores de Recurso (Resource Indicators) (RFC 8707), -você pode omitir este campo, pois o público pode não ser relevante. - -#### Veja também {#see} - -https://datatracker.ietf.org/doc/html/rfc8707 - -*** - -### issuer {#issuer} - -```ts -issuer: string; -``` - -O emissor (Issuer) esperado do token de acesso (`iss` claim). Deve ser a URL do -servidor de autorização que emitiu o token. - -*** - -### requiredScopes? {#requiredscopes} - -```ts -optional requiredScopes: string[]; -``` - -Um array de escopos (Scopes) obrigatórios que o token de acesso deve possuir. Se o token não contiver -todos esses escopos, um erro será lançado. - -**Nota:** O handler verificará a reivindicação `scope` no token, que pode ser uma string separada por espaços -ou um array de strings, dependendo da implementação do servidor de autorização. Se a reivindicação `scope` não estiver presente, o handler verificará a reivindicação `scopes` -se disponível. - -*** - -### showErrorDetails? {#showerrordetails} - -```ts -optional showErrorDetails: boolean; -``` - -Indica se deve mostrar informações detalhadas de erro na resposta. Isso é útil para depuração -durante o desenvolvimento, mas deve ser desativado em produção para evitar vazamento de informações sensíveis. - -#### Padrão {#default} - -```ts -false -``` - -*** - -### verifyAccessToken {#verifyaccesstoken} - -```ts -verifyAccessToken: VerifyAccessTokenFunction; -``` - -Tipo de função para verificar um token de acesso (Access token). - -Esta função deve lançar um [MCPAuthTokenVerificationError](/references/js/classes/MCPAuthTokenVerificationError.md) se o token for inválido, -ou retornar um objeto AuthInfo se o token for válido. - -#### Veja também {#see} - -[VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) para mais detalhes. \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthErrorCode.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthErrorCode.md deleted file mode 100644 index 45363f7..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthErrorCode.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_label: BearerAuthErrorCode ---- - -# Alias de Tipo: BearerAuthErrorCode - -```ts -type BearerAuthErrorCode = - | "missing_auth_header" - | "invalid_auth_header_format" - | "missing_bearer_token" - | "invalid_issuer" - | "invalid_audience" - | "missing_required_scopes" - | "invalid_token"; -``` diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthJwtConfig.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthJwtConfig.md deleted file mode 100644 index e2bf15b..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthJwtConfig.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -sidebar_label: BearerAuthJwtConfig ---- - -# Alias de Tipo: BearerAuthJwtConfig - -```ts -type BearerAuthJwtConfig = { - jwtVerify?: JWTVerifyOptions; - remoteJwkSet?: RemoteJWKSetOptions; -}; -``` - -Configuração para o manipulador de autenticação Bearer ao usar verificação JWT. - -## Propriedades {#properties} - -### jwtVerify? {#jwtverify} - -```ts -optional jwtVerify: JWTVerifyOptions; -``` - -Opções para passar para a função `jwtVerify` da biblioteca `jose`. - -#### Veja também {#see} - -JWTVerifyOptions para a definição do tipo das opções. - -*** - -### remoteJwkSet? {#remotejwkset} - -```ts -optional remoteJwkSet: RemoteJWKSetOptions; -``` - -Opções para passar para a função `createRemoteJWKSet` da biblioteca `jose`. - -#### Veja também {#see} - -RemoteJWKSetOptions para a definição do tipo das opções. \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md deleted file mode 100644 index c0c70b4..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -sidebar_label: CamelCaseAuthorizationServerMetadata ---- - -# Alias de Tipo: CamelCaseAuthorizationServerMetadata - -```ts -type CamelCaseAuthorizationServerMetadata = { - authorizationEndpoint: string; - codeChallengeMethodsSupported?: string[]; - grantTypesSupported?: string[]; - introspectionEndpoint?: string; - introspectionEndpointAuthMethodsSupported?: string[]; - introspectionEndpointAuthSigningAlgValuesSupported?: string[]; - issuer: string; - jwksUri?: string; - opPolicyUri?: string; - opTosUri?: string; - registrationEndpoint?: string; - responseModesSupported?: string[]; - responseTypesSupported: string[]; - revocationEndpoint?: string; - revocationEndpointAuthMethodsSupported?: string[]; - revocationEndpointAuthSigningAlgValuesSupported?: string[]; - scopeSupported?: string[]; - serviceDocumentation?: string; - tokenEndpoint: string; - tokenEndpointAuthMethodsSupported?: string[]; - tokenEndpointAuthSigningAlgValuesSupported?: string[]; - uiLocalesSupported?: string[]; - userinfoEndpoint?: string; -}; -``` - -A versão em camelCase do tipo Metadata do Servidor de Autorização OAuth 2.0. - -## Declaração do tipo {#type-declaration} - -### authorizationEndpoint {#authorizationendpoint} - -```ts -authorizationEndpoint: string; -``` - -### codeChallengeMethodsSupported? {#codechallengemethodssupported} - -```ts -optional codeChallengeMethodsSupported: string[]; -``` - -### grantTypesSupported? {#granttypessupported} - -```ts -optional grantTypesSupported: string[]; -``` - -### introspectionEndpoint? {#introspectionendpoint} - -```ts -optional introspectionEndpoint: string; -``` - -### introspectionEndpointAuthMethodsSupported? {#introspectionendpointauthmethodssupported} - -```ts -optional introspectionEndpointAuthMethodsSupported: string[]; -``` - -### introspectionEndpointAuthSigningAlgValuesSupported? {#introspectionendpointauthsigningalgvaluessupported} - -```ts -optional introspectionEndpointAuthSigningAlgValuesSupported: string[]; -``` - -### issuer {#issuer} - -```ts -issuer: string; -``` - -### jwksUri? {#jwksuri} - -```ts -optional jwksUri: string; -``` - -### opPolicyUri? {#oppolicyuri} - -```ts -optional opPolicyUri: string; -``` - -### opTosUri? {#optosuri} - -```ts -optional opTosUri: string; -``` - -### registrationEndpoint? {#registrationendpoint} - -```ts -optional registrationEndpoint: string; -``` - -### responseModesSupported? {#responsemodessupported} - -```ts -optional responseModesSupported: string[]; -``` - -### responseTypesSupported {#responsetypessupported} - -```ts -responseTypesSupported: string[]; -``` - -### revocationEndpoint? {#revocationendpoint} - -```ts -optional revocationEndpoint: string; -``` - -### revocationEndpointAuthMethodsSupported? {#revocationendpointauthmethodssupported} - -```ts -optional revocationEndpointAuthMethodsSupported: string[]; -``` - -### revocationEndpointAuthSigningAlgValuesSupported? {#revocationendpointauthsigningalgvaluessupported} - -```ts -optional revocationEndpointAuthSigningAlgValuesSupported: string[]; -``` - -### scopeSupported? {#scopesupported} - -```ts -optional scopeSupported: string[]; -``` - -### serviceDocumentation? {#servicedocumentation} - -```ts -optional serviceDocumentation: string; -``` - -### tokenEndpoint {#tokenendpoint} - -```ts -tokenEndpoint: string; -``` - -### tokenEndpointAuthMethodsSupported? {#tokenendpointauthmethodssupported} - -```ts -optional tokenEndpointAuthMethodsSupported: string[]; -``` - -### tokenEndpointAuthSigningAlgValuesSupported? {#tokenendpointauthsigningalgvaluessupported} - -```ts -optional tokenEndpointAuthSigningAlgValuesSupported: string[]; -``` - -### uiLocalesSupported? {#uilocalessupported} - -```ts -optional uiLocalesSupported: string[]; -``` - -### userinfoEndpoint? {#userinfoendpoint} - -```ts -optional userinfoEndpoint: string; -``` - -## Veja também {#see} - -[AuthorizationServerMetadata](/references/js/type-aliases/AuthorizationServerMetadata.md) para o tipo original e informações dos campos. \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md deleted file mode 100644 index b2ebc3e..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -sidebar_label: MCPAuthBearerAuthErrorDetails ---- - -# Alias de Tipo: MCPAuthBearerAuthErrorDetails - -```ts -type MCPAuthBearerAuthErrorDetails = { - actual?: unknown; - cause?: unknown; - expected?: unknown; - missingScopes?: string[]; - uri?: URL; -}; -``` - -## Propriedades {#properties} - -### actual? {#actual} - -```ts -optional actual: unknown; -``` - -*** - -### cause? {#cause} - -```ts -optional cause: unknown; -``` - -*** - -### expected? {#expected} - -```ts -optional expected: unknown; -``` - -*** - -### missingScopes? {#missingscopes} - -```ts -optional missingScopes: string[]; -``` - -*** - -### uri? {#uri} - -```ts -optional uri: URL; -``` diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthConfig.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthConfig.md deleted file mode 100644 index 6152dd7..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthConfig.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -sidebar_label: MCPAuthConfig ---- - -# Alias de Tipo: MCPAuthConfig - -```ts -type MCPAuthConfig = { - server: AuthServerConfig; -}; -``` - -Configuração para a classe [MCPAuth](/references/js/classes/MCPAuth.md). - -## Propriedades {#properties} - -### server {#server} - -```ts -server: AuthServerConfig; -``` - -Configuração para o servidor remoto de autorização. \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md deleted file mode 100644 index b9cc556..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: MCPAuthTokenVerificationErrorCode ---- - -# Alias de Tipo: MCPAuthTokenVerificationErrorCode - -```ts -type MCPAuthTokenVerificationErrorCode = "invalid_token" | "token_verification_failed"; -``` diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenFunction.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenFunction.md deleted file mode 100644 index a16a14c..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenFunction.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -sidebar_label: VerifyAccessTokenFunction ---- - -# Alias de Tipo: VerifyAccessTokenFunction() - -```ts -type VerifyAccessTokenFunction = (token: string) => MaybePromise; -``` - -Tipo de função para verificar um token de acesso (Access token). - -Esta função deve lançar um [MCPAuthTokenVerificationError](/references/js/classes/MCPAuthTokenVerificationError.md) se o token for inválido, -ou retornar um objeto AuthInfo se o token for válido. - -Por exemplo, se você tiver uma função de verificação de JWT, ela deve pelo menos verificar a -assinatura do token, validar sua expiração e extrair as reivindicações (Claims) necessárias para retornar um objeto `AuthInfo`. - -**Nota:** Não há necessidade de verificar os seguintes campos no token, pois eles serão verificados -pelo handler: - -- `iss` (emissor / issuer) -- `aud` (público / audience) -- `scope` (escopos / scopes) - -## Parâmetros {#parameters} - -### token {#token} - -`string` - -A string do token de acesso (Access token) a ser verificada. - -## Retorno {#returns} - -`MaybePromise`\<`AuthInfo`\> - -Uma promise que resolve para um objeto AuthInfo ou um valor síncrono se o -token for válido. \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenMode.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenMode.md deleted file mode 100644 index 2003170..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenMode.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: VerifyAccessTokenMode ---- - -# Alias de Tipo: VerifyAccessTokenMode - -```ts -type VerifyAccessTokenMode = "jwt"; -``` diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authServerErrorDescription.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authServerErrorDescription.md deleted file mode 100644 index 940ff45..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authServerErrorDescription.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: authServerErrorDescription ---- - -# Variável: authServerErrorDescription - -```ts -const authServerErrorDescription: Readonly>; -``` diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authorizationServerMetadataSchema.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authorizationServerMetadataSchema.md deleted file mode 100644 index 6f1c6c7..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authorizationServerMetadataSchema.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: authorizationServerMetadataSchema ---- - -# Variável: authorizationServerMetadataSchema - -```ts -const authorizationServerMetadataSchema: ZodObject; -``` - -Schema Zod para Metadados do Servidor de Autorização OAuth 2.0 conforme definido na RFC 8414. - -## Veja também {#see} - -https://datatracker.ietf.org/doc/html/rfc8414 \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/bearerAuthErrorDescription.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/bearerAuthErrorDescription.md deleted file mode 100644 index 0f6a202..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/bearerAuthErrorDescription.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: bearerAuthErrorDescription ---- - -# Variável: bearerAuthErrorDescription - -```ts -const bearerAuthErrorDescription: Readonly>; -``` diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md deleted file mode 100644 index f998119..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: camelCaseAuthorizationServerMetadataSchema ---- - -# Variável: camelCaseAuthorizationServerMetadataSchema - -```ts -const camelCaseAuthorizationServerMetadataSchema: ZodObject; -``` - -A versão em camelCase do esquema Zod de Metadados do Servidor de Autorização (Authorization Server Metadata) do OAuth 2.0. - -## Veja também {#see} - -[authorizationServerMetadataSchema](/references/js/variables/authorizationServerMetadataSchema.md) para o esquema original e informações dos campos. \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/serverMetadataPaths.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/serverMetadataPaths.md deleted file mode 100644 index ea1e9cf..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/serverMetadataPaths.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_label: serverMetadataPaths ---- - -# Variável: serverMetadataPaths - -```ts -const serverMetadataPaths: Readonly<{ - oauth: "/.well-known/oauth-authorization-server"; - oidc: "/.well-known/openid-configuration"; -}>; -``` diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/tokenVerificationErrorDescription.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/tokenVerificationErrorDescription.md deleted file mode 100644 index 4458928..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/tokenVerificationErrorDescription.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: tokenVerificationErrorDescription ---- - -# Variável: tokenVerificationErrorDescription - -```ts -const tokenVerificationErrorDescription: Readonly>; -``` diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/validateServerConfig.md b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/validateServerConfig.md deleted file mode 100644 index 2f08822..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/validateServerConfig.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: validateServerConfig ---- - -# Variável: validateServerConfig - -```ts -const validateServerConfig: ValidateServerConfig; -``` diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/snippets/_get-started-code.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/snippets/_get-started-code.mdx deleted file mode 100644 index 1d8da9c..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/snippets/_get-started-code.mdx +++ /dev/null @@ -1,41 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - - - - - -```python -mcp = FastMCP("MyMCPServer") -mcp_auth = MCPAuth(server=fetch_server_config('', type=AuthServerType.OIDC)) -app = Starlette( - # ... sua configuração do servidor MCP - middleware=[Middleware( - mcp_auth.bearer_auth_middleware("jwt", required_scopes=["read", "write"]) - )] -) - -# Use `mcp_auth.auth_info` para acessar as informações de autenticação da requisição atual -@mcp.tool() -def whoami() -> dict[str, Any]: - return mcp_auth.auth_info.claims -``` - - - - -```ts -const server = new McpServer(/* ... */); -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { type: 'oidc' }), -}); -const app = express(); - -app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] })); -server.tool('whoami', ({ authInfo }) => { - // Use `authInfo` para acessar as informações de autenticação carregadas de `req.auth` -}); -``` - - - diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/README.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/README.mdx deleted file mode 100644 index e307cf5..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/README.mdx +++ /dev/null @@ -1,1149 +0,0 @@ ---- -sidebar_position: 2 -sidebar_label: 'Tutorial: Construa um gerenciador de tarefas' ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import SetupOauthOrOidc from './_setup-oauth-or-oidc.mdx'; -import SetupOidc from './_setup-oidc.mdx'; - -# Tutorial: Construa um gerenciador de tarefas - -Neste tutorial, vamos construir um servidor MCP de gerenciador de tarefas com autenticação e autorização de usuário. - -Após concluir este tutorial, você terá: - -- ✅ Uma compreensão básica de como configurar controle de acesso baseado em papel (RBAC) em seu servidor MCP. -- ✅ Um servidor MCP que pode gerenciar listas de tarefas pessoais. - -:::note -Antes de começar, recomendamos fortemente que você faça primeiro o [tutorial Quem sou eu](./whoami) caso não esteja familiarizado com o servidor MCP e OAuth 2. -::: - -## Visão geral \{#overview} - -O tutorial envolverá os seguintes componentes: - -- **Servidor MCP**: Um servidor MCP simples que usa os SDKs oficiais do MCP para lidar com requisições, com um serviço integrado de Tarefas para gerenciar os itens de tarefas do usuário. -- **MCP inspector**: Uma ferramenta visual de testes para servidores MCP. Também atua como um cliente OAuth / OIDC para iniciar o fluxo de autorização e recuperar tokens de acesso. -- **Servidor de autorização**: Um provedor OAuth 2.1 ou OpenID Connect que gerencia identidades de usuários e emite tokens de acesso. - -Aqui está um diagrama de alto nível da interação entre esses componentes: - -```mermaid -sequenceDiagram - participant Client as MCP Inspector - participant Server as MCP Server - participant Auth as Servidor de Autorização - - Client->>Server: Solicitar operação de tarefa - Server->>Client: Retornar 401 Não autorizado - Client->>Auth: Iniciar fluxo de autorização - Auth->>Auth: Completar fluxo de autorização - Auth->>Client: Redirecionar de volta com código de autorização - Client->>Auth: Trocar código por token de acesso - Auth->>Client: Retornar token de acesso - Client->>Server: Solicitar operação de tarefa com token de acesso - Server->>Server: Validar token de acesso e obter escopos do usuário do token de acesso - Note over Server: Executar operação de tarefa - Server->>Client: Retornar resultado da operação de tarefa -``` - -## Entenda seu servidor de autorização \{#understand-your-authorization-server} - -### Tokens de acesso com escopos \{#access-tokens-with-scopes} - -Para implementar [controle de acesso baseado em papel (RBAC)](https://auth.wiki/rbac) em seu servidor MCP, seu servidor de autorização precisa suportar a emissão de tokens de acesso com escopos. Escopos representam as permissões que um usuário recebeu. - - - - -[Logto](https://logto.io) oferece suporte a RBAC por meio de seus recursos de API (conforme [RFC 8707: Indicadores de Recurso para OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)) e funcionalidades de papéis. Veja como configurar: - -1. Faça login no [Logto Console](https://cloud.logto.io) (ou em seu Logto Console auto-hospedado) - -2. Crie recurso de API e escopos: - - - Vá para "Recursos de API" - - Crie um novo recurso de API chamado "Gerenciador de Tarefas" - - Adicione os seguintes escopos: - - `create:todos`: "Criar novos itens de tarefa" - - `read:todos`: "Ler todos os itens de tarefa" - - `delete:todos`: "Excluir qualquer item de tarefa" - -3. Crie papéis (recomendado para facilitar o gerenciamento): - - - Vá para "Papéis" - - Crie um papel "Admin" e atribua todos os escopos (`create:todos`, `read:todos`, `delete:todos`) - - Crie um papel "User" e atribua apenas o escopo `create:todos` - -4. Atribua permissões: - - Vá para "Usuários" - - Selecione um usuário - - Você pode: - - Atribuir papéis na aba "Papéis" (recomendado) - - Ou atribuir escopos diretamente na aba "Permissões" - -Os escopos serão incluídos na reivindicação `scope` do token de acesso JWT como uma string separada por espaços. - - - - -Provedores OAuth 2.0 / OIDC normalmente suportam controle de acesso baseado em escopo. Ao implementar RBAC: - -1. Defina os escopos necessários em seu servidor de autorização -2. Configure seu cliente para solicitar esses escopos durante o fluxo de autorização -3. Certifique-se de que seu servidor de autorização inclua os escopos concedidos no token de acesso -4. Os escopos geralmente são incluídos na reivindicação `scope` do token de acesso JWT - -Consulte a documentação do seu provedor para detalhes específicos sobre: - -- Como definir e gerenciar escopos -- Como os escopos são incluídos no token de acesso -- Quaisquer recursos adicionais de RBAC, como gerenciamento de papéis - - - - -### Validando tokens e verificando permissões \{#validating-tokens-and-checking-permissions} - -Quando seu servidor MCP recebe uma requisição, ele precisa: - -1. Validar a assinatura e expiração do token de acesso -2. Extrair os escopos do token validado -3. Verificar se o token possui os escopos necessários para a operação solicitada - -Por exemplo, se um usuário deseja criar um novo item de tarefa, seu token de acesso deve incluir o escopo `create:todos`. Veja como funciona o fluxo: - -```mermaid -sequenceDiagram - participant Client - participant MCP Server - participant Auth Server - - Client->>MCP Server: Solicitação com token de acesso - - alt Validação JWT - MCP Server->>Auth Server: Buscar JWKS - Auth Server-->>MCP Server: Retornar JWKS - MCP Server->>MCP Server: Validar JWT localmente - else Introspecção de Token - MCP Server->>Auth Server: POST /introspect
(token=access_token) - Auth Server-->>MCP Server: Retornar informações do token
(ativo, escopo, etc.) - end - - MCP Server->>MCP Server: Extrair & verificar escopos - - alt Possui escopos necessários - MCP Server->>Client: Permitir operação - else Escopos ausentes - MCP Server->>Client: Retornar 403 Proibido - end -``` - -### Registro Dinâmico de Cliente \{#dynamic-client-registration} - -O Registro Dinâmico de Cliente não é necessário para este tutorial, mas pode ser útil se você quiser automatizar o processo de registro do cliente MCP com seu servidor de autorização. Veja [Registro Dinâmico de Cliente é necessário?](/provider-list#is-dcr-required) para mais detalhes. - -## Entenda RBAC no gerenciador de tarefas \{#understand-rbac-in-todo-manager} - -Para fins de demonstração, implementaremos um sistema simples de controle de acesso baseado em papel (RBAC) em nosso servidor MCP de gerenciador de tarefas. Isso mostrará os princípios básicos do RBAC mantendo a implementação direta. - -:::note -Embora este tutorial demonstre o gerenciamento de escopos baseado em RBAC, é importante observar que nem todos os provedores de autenticação implementam o gerenciamento de escopos por meio de papéis. Alguns provedores podem ter suas próprias implementações e mecanismos únicos para gerenciar controle de acesso e permissões. -::: - -### Ferramentas e escopos \{#tools-and-scopes} - -Nosso servidor MCP de gerenciador de tarefas fornece três ferramentas principais: - -- `create-todo`: Criar um novo item de tarefa -- `get-todos`: Listar todas as tarefas -- `delete-todo`: Excluir uma tarefa pelo ID - -Para controlar o acesso a essas ferramentas, definimos os seguintes escopos: - -- `create:todos`: Permite criar novos itens de tarefa -- `delete:todos`: Permite excluir itens de tarefa existentes -- `read:todos`: Permite consultar e recuperar a lista de todas as tarefas - -### Papéis e permissões \{#roles-and-permissions} - -Definiremos dois papéis com diferentes níveis de acesso: - -| Papel | create:todos | read:todos | delete:todos | -| ------ | ------------ | ---------- | ------------ | -| Admin | ✅ | ✅ | ✅ | -| User | ✅ | | | - -- **User**: Um usuário comum que pode criar itens de tarefa e visualizar ou excluir apenas suas próprias tarefas -- **Admin**: Um administrador que pode criar, visualizar e excluir todos os itens de tarefa, independentemente da propriedade - -### Propriedade do recurso \{#resource-ownership} - -Embora a tabela de permissões acima mostre os escopos explícitos atribuídos a cada papel, há um princípio importante de propriedade de recurso a considerar: - -- **Usuários** não possuem os escopos `read:todos` ou `delete:todos`, mas ainda podem: - - Ler seus próprios itens de tarefa - - Excluir seus próprios itens de tarefa -- **Admins** possuem permissões totais (`read:todos` e `delete:todos`), permitindo que: - - Visualizem todos os itens de tarefa no sistema - - Excluam qualquer item de tarefa, independentemente da propriedade - -Isso demonstra um padrão comum em sistemas RBAC onde a propriedade do recurso concede permissões implícitas aos usuários para seus próprios recursos, enquanto papéis administrativos recebem permissões explícitas para todos os recursos. - -:::tip Saiba mais -Para se aprofundar nos conceitos e melhores práticas de RBAC, confira [Dominando RBAC: Um Exemplo Abrangente do Mundo Real](https://blog.logto.io/mastering-rbac). -::: - -## Configure a autorização em seu provedor \{#configure-authorization-in-your-provider} - -Para implementar o sistema de controle de acesso que descrevemos anteriormente, você precisará configurar seu servidor de autorização para suportar os escopos necessários. Veja como fazer isso com diferentes provedores: - - - - -[Logto](https://logto.io) oferece suporte a RBAC por meio de recursos de API e funcionalidades de papéis. Veja como configurar: - -1. Faça login no [Logto Console](https://cloud.logto.io) (ou em seu Logto Console auto-hospedado) - -2. Crie recurso de API e escopos: - - - Vá para "Recursos de API" - - Crie um novo recurso de API chamado "Gerenciador de Tarefas" e use `https://todo.mcp-server.app` (para demonstração) como indicador. - - Crie os seguintes escopos: - - `create:todos`: "Criar novos itens de tarefa" - - `read:todos`: "Ler todos os itens de tarefa" - - `delete:todos`: "Excluir qualquer item de tarefa" - -3. Crie papéis (recomendado para facilitar o gerenciamento): - - - Vá para "Papéis" - - Crie um papel "Admin" e atribua todos os escopos (`create:todos`, `read:todos`, `delete:todos`) - - Crie um papel "User" e atribua apenas o escopo `create:todos` - - Na página de detalhes do papel "User", vá para a aba "Geral" e defina o papel "User" como o "Papel padrão". - -4. Gerencie papéis e permissões dos usuários: - - Para novos usuários: - - Eles receberão automaticamente o papel "User" já que o definimos como padrão - - Para usuários existentes: - - Vá para "Gerenciamento de usuários" - - Selecione um usuário - - Atribua papéis ao usuário na aba "Papéis" - -:::tip Gerenciamento de Papéis Programático -Você também pode usar a [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api) do Logto para gerenciar papéis de usuários programaticamente. Isso é especialmente útil para automação de gerenciamento de usuários ou ao construir painéis administrativos. -::: - -Ao solicitar um token de acesso, o Logto incluirá os escopos na reivindicação `scope` do token com base nas permissões do papel do usuário. - - - - -No [Keycloak](https://www.keycloak.org), você pode configurar as permissões necessárias usando escopos de cliente: - -1. Crie escopos de cliente: - - - No seu realm, vá para "Client scopes" - - Crie três novos escopos de cliente: - - `create:todos` - - `read:todos` - - `delete:todos` - -2. Configure o cliente: - - - Vá para as configurações do seu cliente - - Na aba "Client scopes", adicione todos os escopos que você criou - - Certifique-se de que o token mapper está configurado para incluir escopos - -3. Opcional: Use papéis para facilitar o gerenciamento - - Se preferir gerenciamento baseado em papel: - - Crie papéis de realm para diferentes níveis de acesso - - Mapeie escopos para papéis - - Atribua papéis aos usuários - - Caso contrário, você pode atribuir escopos diretamente aos usuários ou por permissões no nível do cliente - -O Keycloak incluirá os escopos concedidos na reivindicação `scope` do token de acesso. - - - - -Para provedores OAuth 2.0 ou OpenID Connect, você precisará configurar os escopos que representam diferentes permissões. Os passos exatos dependerão do seu provedor, mas geralmente: - -1. Defina escopos: - - - Configure seu servidor de autorização para suportar: - - `create:todos` - - `read:todos` - - `delete:todos` - -2. Configure o cliente: - - - Registre ou atualize seu cliente para solicitar esses escopos - - Certifique-se de que os escopos estão incluídos no token de acesso - -3. Atribua permissões: - - Use a interface do seu provedor para conceder os escopos apropriados aos usuários - - Alguns provedores podem suportar gerenciamento baseado em papel, enquanto outros podem usar atribuições diretas de escopos - - Consulte a documentação do seu provedor para a abordagem recomendada - -:::tip -A maioria dos provedores incluirá os escopos concedidos na reivindicação `scope` do token de acesso. O formato normalmente é uma string de escopos separados por espaço. -::: - - - - -Após configurar seu servidor de autorização, os usuários receberão tokens de acesso contendo seus escopos concedidos. O servidor MCP usará esses escopos para determinar: - -- Se um usuário pode criar novas tarefas (`create:todos`) -- Se um usuário pode visualizar todas as tarefas (`read:todos`) ou apenas as suas próprias -- Se um usuário pode excluir qualquer tarefa (`delete:todos`) ou apenas as suas próprias - -## Configure o servidor MCP \{#set-up-the-mcp-server} - -Usaremos os [SDKs oficiais do MCP](https://github.com/modelcontextprotocol) para criar nosso servidor MCP de gerenciador de tarefas. - -### Crie um novo projeto \{#create-a-new-project} - - - - -```bash -mkdir mcp-server -cd mcp-server -uv init # Ou use `pipenv` ou `poetry` para criar um novo ambiente virtual -``` - - - - -Configure um novo projeto Node.js: - -```bash -mkdir mcp-server -cd mcp-server -npm init -y # Ou use `pnpm init` -npm pkg set type="module" -npm pkg set main="todo-manager.ts" -npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts" -``` - -:::note -Estamos usando TypeScript em nossos exemplos, pois o Node.js v22.6.0+ suporta execução nativa de TypeScript usando a flag `--experimental-strip-types`. Se estiver usando JavaScript, o código será semelhante - apenas certifique-se de estar usando Node.js v22.6.0 ou superior. Veja a documentação do Node.js para detalhes. -::: - - - - -### Instale o SDK MCP e dependências \{#install-the-mcp-sdk-and-dependencies} - - - - -```bash -pip install "mcp[cli]" starlette uvicorn -``` - -Ou qualquer outro gerenciador de pacotes de sua preferência, como `uv` ou `poetry`. - - - - -```bash -npm install @modelcontextprotocol/sdk express zod -``` - -Ou qualquer outro gerenciador de pacotes de sua preferência, como `pnpm` ou `yarn`. - - - - -### Crie o servidor MCP \{#create-the-mcp-server} - -Primeiro, vamos criar um servidor MCP básico com as definições das ferramentas: - - - - -Crie um arquivo chamado `todo-manager.py` e adicione o seguinte código: - -```python -from typing import Any -from mcp.server.fastmcp import FastMCP -from starlette.applications import Starlette -from starlette.routing import Mount - -mcp = FastMCP("Gerenciador de Tarefas") - -@mcp.tool() -def create_todo(content: str) -> dict[str, Any]: - """Criar uma nova tarefa.""" - return {"error": "Não implementado"} - -@mcp.tool() -def get_todos() -> dict[str, Any]: - """Listar todas as tarefas.""" - return {"error": "Não implementado"} - -@mcp.tool() -def delete_todo(id: str) -> dict[str, Any]: - """Excluir uma tarefa pelo id.""" - return {"error": "Não implementado"} - -app = Starlette( - routes=[Mount('/', app=mcp.sse_app())] -) -``` - -Execute o servidor com: - -```bash -uvicorn todo_manager:app --host 0.0.0.0 --port 3001 -``` - - - - -:::note -Como a implementação atual do MCP inspector não lida com fluxos de autorização, usaremos a abordagem SSE para configurar o servidor MCP. Atualizaremos o código aqui assim que o MCP inspector suportar fluxos de autorização. -::: - -Você também pode usar `pnpm` ou `yarn` se preferir. - -Crie um arquivo chamado `todo-manager.ts` e adicione o seguinte código: - -```ts -// todo-manager.ts - -import { z } from 'zod'; -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; -import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'; -import express from 'express'; - -// Crie um servidor MCP -const server = new McpServer({ - name: 'Gerenciador de Tarefas', - version: '0.0.0', -}); - -server.tool('create-todo', 'Criar uma nova tarefa', { content: z.string() }, async ({ content }) => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Não implementado' }) }], - }; -}); - -server.tool('get-todos', 'Listar todas as tarefas', async () => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Não implementado' }) }], - }; -}); - -server.tool('delete-todo', 'Excluir uma tarefa pelo id', { id: z.string() }, async ({ id }) => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Não implementado' }) }], - }; -}); - -// Abaixo está o código boilerplate da documentação do MCP SDK -const PORT = 3001; -const app = express(); - -const transports = {}; - -app.get('/sse', async (_req, res) => { - const transport = new SSEServerTransport('/messages', res); - transports[transport.sessionId] = transport; - - res.on('close', () => { - delete transports[transport.sessionId]; - }); - - await server.connect(transport); -}); - -app.post('/messages', async (req, res) => { - const sessionId = String(req.query.sessionId); - const transport = transports[sessionId]; - if (transport) { - await transport.handlePostMessage(req, res, req.body); - } else { - res.status(400).send('Nenhum transporte encontrado para sessionId'); - } -}); - -app.listen(PORT); -``` - -Execute o servidor com: - -```bash -npm start -``` - - - - -## Inspecione o servidor MCP \{#inspect-the-mcp-server} - -### Clone e execute o MCP inspector \{#clone-and-run-mcp-inspector} - -Agora que temos o servidor MCP rodando, podemos usar o MCP inspector para ver se a ferramenta `whoami` está disponível. - -Devido à limitação da implementação atual, fizemos um fork do [MCP inspector](https://github.com/mcp-auth/inspector) para torná-lo mais flexível e escalável para autenticação e autorização. Também enviamos um pull request para o repositório original para incluir nossas alterações. - -Para rodar o MCP inspector, você pode usar o seguinte comando (Node.js é necessário): - -```bash -git clone https://github.com/mcp-auth/inspector.git -cd inspector -npm install -npm run dev -``` - -Depois, abra seu navegador e acesse `http://localhost:6274/` (ou outro URL exibido no terminal) para acessar o MCP inspector. - -### Conecte o MCP inspector ao servidor MCP \{#connect-mcp-inspector-to-the-mcp-server} - -Antes de prosseguir, verifique a seguinte configuração no MCP inspector: - -- **Tipo de Transporte**: Defina como `SSE`. -- **URL**: Defina para a URL do seu servidor MCP. No nosso caso, deve ser `http://localhost:3001/sse`. - -Agora você pode clicar no botão "Connect" para ver se o MCP inspector consegue se conectar ao servidor MCP. Se tudo estiver certo, você verá o status "Connected" no MCP inspector. - -### Checkpoint: Execute as ferramentas do gerenciador de tarefas \{#checkpoint-run-todo-manager-tools} - -1. No menu superior do MCP inspector, clique na aba "Tools". -2. Clique no botão "List Tools". -3. Você deve ver as ferramentas `create-todo`, `get-todos` e `delete-todo` listadas na página. Clique para abrir os detalhes da ferramenta. -4. Você deve ver o botão "Run Tool" no lado direito. Clique nele e insira os parâmetros necessários para executar a ferramenta. -5. Você verá o resultado da ferramenta com a resposta JSON `{"error": "Não implementado"}`. - -![Primeira execução do MCP inspector](/docs-assets/images/tutorials/todo-manager/inspector-first-run.png) - -## Integre com seu servidor de autorização \{#integrate-with-your-authorization-server} - -Para concluir esta seção, há várias considerações a serem feitas: - -
-**A URL do emissor do seu servidor de autorização** - -Geralmente é a URL base do seu servidor de autorização, como `https://auth.example.com`. Alguns provedores podem ter um caminho como `https://example.logto.app/oidc`, então verifique a documentação do seu provedor. - -
- -
-**Como recuperar os metadados do servidor de autorização** - -- Se seu servidor de autorização estiver em conformidade com o [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) ou [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html), você pode usar as utilidades integradas do MCP Auth para buscar os metadados automaticamente. -- Se seu servidor de autorização não estiver em conformidade com esses padrões, você precisará especificar manualmente a URL dos metadados ou endpoints na configuração do servidor MCP. Consulte a documentação do seu provedor para os endpoints específicos. - -
- -
-**Como registrar o MCP inspector como cliente em seu servidor de autorização** - -- Se seu servidor de autorização suporta [Registro Dinâmico de Cliente](https://datatracker.ietf.org/doc/html/rfc7591), você pode pular esta etapa, pois o MCP inspector se registrará automaticamente como cliente. -- Se seu servidor de autorização não suporta Registro Dinâmico de Cliente, você precisará registrar manualmente o MCP inspector como cliente em seu servidor de autorização. - -
- -
-**Entenda os parâmetros de solicitação de token** - -Ao solicitar tokens de acesso de diferentes servidores de autorização, você encontrará várias abordagens para especificar o recurso alvo e as permissões. Aqui estão os principais padrões: - -- **Baseado em indicador de recurso**: - - - Usa o parâmetro `resource` para especificar a API alvo (veja [RFC 8707: Indicadores de Recurso para OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)) - - Comum em implementações modernas de OAuth 2.0 - - Exemplo de requisição: - ```json - { - "resource": "https://todo.mcp-server.app", - "scope": "create:todos read:todos" - } - ``` - - O servidor emite tokens vinculados especificamente ao recurso solicitado - -- **Baseado em audiência**: - - - Usa o parâmetro `audience` para especificar o destinatário pretendido do token - - Semelhante aos indicadores de recurso, mas com semânticas diferentes - - Exemplo de requisição: - ```json - { - "audience": "todo-api", - "scope": "create:todos read:todos" - } - ``` - -- **Baseado apenas em escopo**: - - Depende apenas de escopos sem parâmetros de recurso/audiência - - Abordagem tradicional do OAuth 2.0 - - Exemplo de requisição: - ```json - { - "scope": "todo-api:create todo-api:read openid profile" - } - ``` - - Frequentemente usa escopos prefixados para namespacing de permissões - - Comum em implementações mais simples de OAuth 2.0 - -:::tip Melhores Práticas - -- Verifique a documentação do seu provedor para os parâmetros suportados -- Alguns provedores suportam múltiplas abordagens simultaneamente -- Indicadores de recurso fornecem melhor segurança por restrição de audiência -- Considere usar indicadores de recurso quando disponíveis para melhor controle de acesso - ::: - -
- -Embora cada provedor possa ter requisitos específicos, os passos a seguir irão guiá-lo no processo de integração do MCP inspector e do servidor MCP com configurações específicas do provedor. - -### Registre o MCP inspector como cliente \{#register-mcp-inspector-as-a-client} - - - - -Integrar o gerenciador de tarefas com o [Logto](https://logto.io) é simples, pois é um provedor OpenID Connect que suporta indicadores de recurso e escopos, permitindo proteger sua API de tarefas com `https://todo.mcp-server.app` como indicador de recurso. - -Como o Logto ainda não suporta Registro Dinâmico de Cliente, você precisará registrar manualmente o MCP inspector como cliente em seu tenant Logto: - -1. Abra seu MCP inspector, clique no botão "OAuth Configuration". Copie o valor **Redirect URL (auto-populated)**, que deve ser algo como `http://localhost:6274/oauth/callback`. -2. Faça login no [Logto Console](https://cloud.logto.io) (ou em seu Logto Console auto-hospedado). -3. Navegue até a aba "Applications", clique em "Create application". No final da página, clique em "Create app without framework". -4. Preencha os detalhes do aplicativo e clique em "Create application": - - **Selecione um tipo de aplicativo**: Escolha "Single-page application". - - **Nome do aplicativo**: Insira um nome para seu aplicativo, por exemplo, "MCP Inspector". -5. Na seção "Settings / Redirect URIs", cole o valor **Redirect URL (auto-populated)** copiado do MCP inspector. Depois clique em "Save changes" na barra inferior. -6. No card superior, você verá o valor "App ID". Copie-o. -7. Volte ao MCP inspector e cole o valor "App ID" na seção "OAuth Configuration" em "Client ID". -8. Insira o valor `{"scope": "create:todos read:todos delete:todos", "resource": "https://todo.mcp-server.app"}` no campo "Auth Params". Isso garantirá que o token de acesso retornado pelo Logto contenha os escopos necessários para acessar o gerenciador de tarefas. - - - - -:::note -Este é um guia genérico de integração com provedores OAuth 2.0 / OpenID Connect. Ambos seguem passos semelhantes, pois OIDC é construído sobre OAuth 2.0. Consulte a documentação do seu provedor para detalhes específicos. -::: - -Se seu provedor suporta Registro Dinâmico de Cliente, você pode ir direto ao passo 8 abaixo para configurar o MCP inspector; caso contrário, será necessário registrar manualmente o MCP inspector como cliente: - -1. Abra seu MCP inspector, clique no botão "OAuth Configuration". Copie o valor **Redirect URL (auto-populated)**, que deve ser algo como `http://localhost:6274/oauth/callback`. - -2. Faça login no console do seu provedor. - -3. Navegue até a seção "Applications" ou "Clients" e crie um novo aplicativo ou cliente. - -4. Se seu provedor exigir um tipo de cliente, selecione "Single-page application" ou "Public client". - -5. Após criar o aplicativo, será necessário configurar o redirect URI. Cole o valor **Redirect URL (auto-populated)** copiado do MCP inspector. - -6. Encontre o "Client ID" ou "Application ID" do novo aplicativo e copie-o. - -7. Volte ao MCP inspector e cole o valor "Client ID" na seção "OAuth Configuration" em "Client ID". - -8. Insira o seguinte valor no campo "Auth Params" para solicitar os escopos necessários para operações de tarefas: - -```json -{ "scope": "create:todos read:todos delete:todos" } -``` - - - - -### Configure o MCP auth \{#set-up-mcp-auth} - -No seu projeto do servidor MCP, você precisa instalar o SDK MCP Auth e configurá-lo para usar os metadados do seu servidor de autorização. - - - - -Primeiro, instale o pacote `mcpauth`: - -```bash -pip install mcpauth -``` - -Ou qualquer outro gerenciador de pacotes de sua preferência, como `uv` ou `poetry`. - - - - -Primeiro, instale o pacote `mcp-auth`: - -```bash -npm install mcp-auth -``` - - - - -O MCP Auth requer os metadados do servidor de autorização para poder inicializar. Dependendo do seu provedor: - - - - - -A URL do emissor pode ser encontrada na página de detalhes do seu aplicativo no Logto Console, na seção "Endpoints & Credentials / Issuer endpoint". Deve ser algo como `https://meu-projeto.logto.app/oidc`. - - - - - - - -Para provedores OAuth 2.0, você precisará: - -1. Verificar a documentação do seu provedor para a URL do servidor de autorização (geralmente chamada de issuer URL ou base URL) -2. Alguns provedores podem expor isso em `https://{seu-dominio}/.well-known/oauth-authorization-server` -3. Procurar no console administrativo do seu provedor em configurações OAuth/API - - - - - - - - - - - -Atualize o `todo-manager.py` para incluir a configuração do MCP Auth: - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # Substitua pelo endpoint do seu emissor -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -Atualize o `todo-manager.ts` para incluir a configuração do MCP Auth: - -```ts -// todo-manager.ts - -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // Substitua pelo endpoint do seu emissor -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oidc' }), -}); -``` - - - - -### Atualize o servidor MCP \{#update-mcp-server} - -Estamos quase lá! É hora de atualizar o servidor MCP para aplicar a rota e middleware do MCP Auth, depois implementar o controle de acesso baseado em permissões para as ferramentas do gerenciador de tarefas com base nos escopos do usuário. - - - - -```python -@mcp.tool() -def create_todo(content: str) -> dict[str, Any]: - """Criar uma nova tarefa.""" - return ( - mcp_auth.auth_info.scopes - if mcp_auth.auth_info # Isso será preenchido pelo middleware Bearer auth - else {"error": "Não autenticado"} - ) - -# ... - -bearer_auth = Middleware(mcp_auth.bearer_auth_middleware("jwt")) -app = Starlette( - routes=[ - # Adicione a rota de metadados (`/.well-known/oauth-authorization-server`) - mcp_auth.metadata_route(), - # Proteja o servidor MCP com o middleware Bearer auth - Mount('/', app=mcp.sse_app(), middleware=[bearer_auth]), - ], -) -``` - - - - -```js -server.tool( - 'create-todo', - 'Criar uma nova tarefa', - { content: z.string() }, - async ({ content, authInfo }) => { - return { - content: [ - { type: 'text', text: JSON.stringify(authInfo?.scopes ?? { error: 'Não autenticado' }) }, - ], - }; - } -); - -// ... - -app.use(mcpAuth.delegatedRouter()); -app.use(mcpAuth.bearerAuth('jwt')); -``` - - - - -Em seguida, vamos implementar as ferramentas específicas. - -Primeiro, vamos criar um serviço simples de tarefas para fornecer operações básicas de CRUD para gerenciar itens de tarefas em memória. - - - -```python -# service.py - -""" -Um serviço simples de Tarefas para fins de demonstração. -Usa uma lista em memória para armazenar tarefas. -""" - -from datetime import datetime -from typing import List, Optional, Dict, Any -import random -import string - -class Todo: -"""Representa um item de tarefa.""" - - def __init__(self, id: str, content: str, owner_id: str, created_at: str): - self.id = id - self.content = content - self.owner_id = owner_id - self.created_at = created_at - - def to_dict(self) -> Dict[str, Any]: - """Converte a tarefa para dicionário para serialização JSON.""" - return { - "id": self.id, - "content": self.content, - "ownerId": self.owner_id, - "createdAt": self.created_at - } - -class TodoService: -"""Um serviço simples de Tarefas para fins de demonstração.""" - - def __init__(self): - self._todos: List[Todo] = [] - - def get_all_todos(self, owner_id: Optional[str] = None) -> List[Dict[str, Any]]: - """ - Obtém todas as tarefas, opcionalmente filtradas por owner_id. - - Args: - owner_id: Se fornecido, retorna apenas tarefas deste usuário - - Returns: - Lista de dicionários de tarefas - """ - if owner_id: - filtered_todos = [todo for todo in self._todos if todo.owner_id == owner_id] - return [todo.to_dict() for todo in filtered_todos] - return [todo.to_dict() for todo in self._todos] - - def get_todo_by_id(self, todo_id: str) -> Optional[Todo]: - """ - Obtém uma tarefa pelo ID. - - Args: - todo_id: O ID da tarefa a ser recuperada - - Returns: - Objeto Todo se encontrado, None caso contrário - """ - for todo in self._todos: - if todo.id == todo_id: - return todo - return None - - def create_todo(self, content: str, owner_id: str) -> Dict[str, Any]: - """ - Cria uma nova tarefa. - - Args: - content: O conteúdo da tarefa - owner_id: O ID do usuário dono da tarefa - - Returns: - Dicionário da tarefa criada - """ - todo = Todo( - id=self._generate_id(), - content=content, - owner_id=owner_id, - created_at=datetime.now().isoformat() - ) - self._todos.append(todo) - return todo.to_dict() - - def delete_todo(self, todo_id: str) -> Optional[Dict[str, Any]]: - """ - Exclui uma tarefa pelo ID. - - Args: - todo_id: O ID da tarefa a ser excluída - - Returns: - Dicionário da tarefa excluída se encontrada, None caso contrário - """ - for i, todo in enumerate(self._todos): - if todo.id == todo_id: - deleted_todo = self._todos.pop(i) - return deleted_todo.to_dict() - return None - - def _generate_id(self) -> str: - """Gera um ID aleatório para uma tarefa.""" - return ''.join(random.choices(string.ascii_lowercase + string.digits, k=8)) - -```` - - - - - -```ts -// todo-service.ts - -type Todo = { - id: string; - content: string; - ownerId: string; - createdAt: string; -}; - -/** - * Um serviço simples de Tarefas para fins de demonstração. - * Usa um array em memória para armazenar tarefas - */ -export class TodoService { - private readonly todos: Todo[] = []; - - getAllTodos(ownerId?: string): Todo[] { - if (ownerId) { - return this.todos.filter((todo) => todo.ownerId === ownerId); - } - return this.todos; - } - - getTodoById(id: string): Todo | undefined { - return this.todos.find((todo) => todo.id === id); - } - - createTodo({ content, ownerId }: { content: string; ownerId: string }): Todo { - const todo: Todo = { - id: this.genId(), - content, - ownerId, - createdAt: new Date().toISOString(), - }; - - // eslint-disable-next-line @silverhand/fp/no-mutating-methods - this.todos.push(todo); - return todo; - } - - deleteTodo(id: string): Todo | undefined { - const index = this.todos.findIndex((todo) => todo.id === id); - - if (index === -1) { - return undefined; - } - - // eslint-disable-next-line @silverhand/fp/no-mutating-methods - const [deleted] = this.todos.splice(index, 1); - return deleted; - } - - private genId(): string { - return Math.random().toString(36).slice(2, 10); - } -} -```` - - - - -então na camada de ferramentas, vamos determinar se as operações são permitidas com base nos escopos do usuário: - - - - -```python -# todo-manager.py - -from typing import Any, Optional -from mcpauth.errors import MCPAuthBearerAuthError - -def assert_user_id(auth_info: Optional[dict]) -> str: - """Extrai e valida o ID do usuário do auth info.""" - subject = auth_info.get('subject') if auth_info else None - if not subject: - raise ValueError('Informação de autenticação inválida') - return subject - -def has_required_scopes(user_scopes: list[str], required_scopes: list[str]) -> bool: - """Verifica se o usuário possui todos os escopos necessários.""" - return all(scope in user_scopes for scope in required_scopes) - -# Crie uma instância do TodoService -todo_service = TodoService() - -@mcp.tool() -def create_todo(content: str) -> dict[str, Any]: - """Criar uma nova tarefa. - - Apenas usuários com o escopo 'create:todos' podem criar tarefas. - """ - # Obter informações de autenticação - auth_info = mcp_auth.auth_info - - # Validar ID do usuário - try: - user_id = assert_user_id(auth_info) - except ValueError as e: - return {"error": str(e)} - - # Verificar se o usuário possui as permissões necessárias - if not has_required_scopes(auth_info.scopes if auth_info else [], ['create:todos']): - raise MCPAuthBearerAuthError('missing_required_scopes') - - # Criar nova tarefa - created_todo = todo_service.create_todo(content=content, owner_id=user_id) - - # Retornar a tarefa criada - return created_todo.__dict__ - -# ... -``` - -Você pode conferir nosso [código de exemplo](https://github.com/mcp-auth/python/tree/master/samples/server) para todas as outras implementações detalhadas. - - - - -```ts -// todo-manager.ts - -// ... outros imports -import assert from 'node:assert'; -import { type AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js'; -import { TodoService } from './todo-service.js'; - -const todoService = new TodoService(); - -const assertUserId = (authInfo?: AuthInfo) => { - const { subject } = authInfo ?? {}; - assert(subject, 'Informação de autenticação inválida'); - return subject; -}; - -/** - * Verifica se o usuário possui todos os escopos necessários para uma operação - */ -const hasRequiredScopes = (userScopes: string[], requiredScopes: string[]): boolean => { - return requiredScopes.every((scope) => userScopes.includes(scope)); -}; - -server.tool( - 'create-todo', - 'Criar uma nova tarefa', - { content: z.string() }, - ({ content }: { content: string }, { authInfo }) => { - const userId = assertUserId(authInfo); - - /** - * Apenas usuários com o escopo 'create:todos' podem criar tarefas - */ - if (!hasRequiredScopes(authInfo?.scopes ?? [], ['create:todos'])) { - throw new MCPAuthBearerAuthError('missing_required_scopes'); - } - - const createdTodo = todoService.createTodo({ content, ownerId: userId }); - - return { - content: [{ type: 'text', text: JSON.stringify(createdTodo) }], - }; - } -); - -// ... -``` - -Você pode conferir nosso [código de exemplo](https://github.com/mcp-auth/js/tree/master/packages/sample-servers/src/todo-manager) para todas as outras implementações detalhadas. - - - - -## Checkpoint: Execute as ferramentas `todo-manager` \{#checkpoint-run-the-todo-manager-tools} - -Reinicie seu servidor MCP e abra o MCP inspector no navegador. Ao clicar no botão "Connect", você será redirecionado para a página de login do seu servidor de autorização. - -Depois de fazer login e retornar ao MCP inspector, repita as ações do checkpoint anterior para executar as ferramentas do gerenciador de tarefas. Desta vez, você poderá usar essas ferramentas com sua identidade de usuário autenticada. O comportamento das ferramentas dependerá dos papéis e permissões atribuídos ao seu usuário: - -- Se você estiver logado como **User** (com apenas o escopo `create:todos`): - - - Você pode criar novas tarefas usando a ferramenta `create-todo` - - Você só poderá visualizar e excluir suas próprias tarefas - - Não poderá ver ou excluir tarefas de outros usuários - -- Se estiver logado como **Admin** (com todos os escopos: `create:todos`, `read:todos`, `delete:todos`): - - Você pode criar novas tarefas - - Pode visualizar todas as tarefas do sistema usando a ferramenta `get-todos` - - Pode excluir qualquer tarefa usando a ferramenta `delete-todo`, independentemente de quem a criou - -Você pode testar esses diferentes níveis de permissão: - -1. Saindo da sessão atual (clique no botão "Disconnect" no MCP inspector) -2. Fazendo login com outra conta de usuário que tenha papéis/permissões diferentes -3. Tentando as mesmas ferramentas novamente para observar como o comportamento muda de acordo com as permissões do usuário - -Isso demonstra como o controle de acesso baseado em papel (RBAC) funciona na prática, onde diferentes usuários têm diferentes níveis de acesso à funcionalidade do sistema. - -![Resultado da ferramenta do gerenciador de tarefas no MCP inspector](/docs-assets/images/tutorials/todo-manager/result.png) - - - - -:::info -Confira o [repositório do MCP Auth Python SDK](https://github.com/mcp-auth/python/blob/master/samples/server/todo-manager/server.py) para o código completo do servidor MCP (versão OIDC). -::: - - - - -:::info -Confira o [repositório do MCP Auth Node.js SDK](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) para o código completo do servidor MCP (versão OIDC). -::: - - - - -## Notas finais \{#closing-notes} - -🎊 Parabéns! Você concluiu com sucesso o tutorial. Vamos recapitular o que fizemos: - -- Configuração de um servidor MCP básico com ferramentas de gerenciamento de tarefas (`create-todo`, `get-todos`, `delete-todo`) -- Implementação de controle de acesso baseado em papel (RBAC) com diferentes níveis de permissão para usuários e administradores -- Integração do servidor MCP com um servidor de autorização usando MCP Auth -- Configuração do MCP Inspector para autenticar usuários e usar tokens de acesso com escopos para chamar ferramentas - -Não deixe de conferir outros tutoriais e a documentação para aproveitar ao máximo o MCP Auth. \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_manual-metadata-fetching.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_manual-metadata-fetching.mdx deleted file mode 100644 index 97bd107..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_manual-metadata-fetching.mdx +++ /dev/null @@ -1,3 +0,0 @@ -:::note -Se o seu provedor não suportar {props.oidc ? 'OpenID Connect Discovery' : 'Metadados do servidor de autorização OAuth 2.0'}, você pode especificar manualmente a URL de metadados ou os endpoints. Confira [Outras formas de inicializar o MCP Auth](../../configure-server/mcp-auth.mdx#other-ways) para mais detalhes. -::: \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oauth-or-oidc.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oauth-or-oidc.mdx deleted file mode 100644 index fc2f426..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oauth-or-oidc.mdx +++ /dev/null @@ -1,41 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -Atualize o `todo-manager.py` para incluir a configuração do MCP Auth: - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # Substitua pelo seu endpoint do emissor -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OAUTH) # ou AuthServerType.OIDC -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -Atualize o `todo-manager.ts` para incluir a configuração do MCP Auth: - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // Substitua pelo seu endpoint do emissor -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oauth' }), // ou { type: 'oidc' } -}); -``` - - - - - - \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oidc.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oidc.mdx deleted file mode 100644 index 1ea1719..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oidc.mdx +++ /dev/null @@ -1,41 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -Atualize o `todo-manager.py` para incluir a configuração do MCP Auth: - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # Substitua pelo seu endpoint do emissor -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -Atualize o `todo-manager.ts` para incluir a configuração do MCP Auth: - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // Substitua pelo seu endpoint do emissor -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oidc' }), -}); -``` - - - - -{props.showAlternative && } -{props.showAlternative && } \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_transpile-metadata.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_transpile-metadata.mdx deleted file mode 100644 index 71b23e8..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_transpile-metadata.mdx +++ /dev/null @@ -1,31 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -Em alguns casos, a resposta do provedor pode estar malformada ou não estar em conformidade com o formato de metadados esperado. Se você tem certeza de que o provedor está em conformidade, é possível transpilar os metadados através da opção de configuração: - - - - -```python -mcp_auth = MCPAuth( - server=fetch_server_config( - # ...outras opções - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { - // ...outras opções - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/README.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/README.mdx deleted file mode 100644 index 988ee4d..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/README.mdx +++ /dev/null @@ -1,611 +0,0 @@ ---- -sidebar_position: 1 -sidebar_label: 'Tutorial: Quem sou eu?' ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import SetupOauth from './_setup-oauth.mdx'; -import SetupOidc from './_setup-oidc.mdx'; - -# Tutorial: Quem sou eu? (Who am I?) - -Este tutorial irá guiá-lo pelo processo de configuração do MCP Auth para autenticar usuários e recuperar suas informações de identidade do servidor de autorização. - -Após concluir este tutorial, você terá: - -- ✅ Uma compreensão básica de como usar o MCP Auth para autenticar usuários. -- ✅ Um servidor MCP que oferece uma ferramenta para recuperar informações de identidade do usuário. - -## Visão geral (Overview) \{#overview} - -O tutorial envolverá os seguintes componentes: - -- **Servidor MCP (MCP server)**: Um servidor MCP simples que utiliza os SDKs oficiais do MCP para lidar com requisições. -- **MCP inspector**: Uma ferramenta visual de testes para servidores MCP. Também atua como um cliente OAuth / OIDC para iniciar o fluxo de autorização e recuperar tokens de acesso. -- **Servidor de autorização (Authorization server)**: Um provedor OAuth 2.1 ou OpenID Connect que gerencia identidades de usuários e emite tokens de acesso. - -Aqui está um diagrama de alto nível da interação entre esses componentes: - -```mermaid -sequenceDiagram - participant Client as MCP Inspector - participant Server as Servidor MCP - participant Auth as Servidor de Autorização - - Client->>Server: Solicitar ferramenta `whoami` - Server->>Client: Retornar 401 Não autorizado - Client->>Auth: Iniciar fluxo de autorização - Auth->>Auth: Completar fluxo de autorização - Auth->>Client: Redirecionar de volta com código de autorização - Client->>Auth: Trocar código por token de acesso - Auth->>Client: Retornar token de acesso - Client->>Server: Solicitar `whoami` com token de acesso - Server->>Auth: Buscar identidade do usuário com token de acesso - Auth->>Server: Retornar identidade do usuário - Server->>Client: Retornar identidade do usuário -``` - -## Entenda seu servidor de autorização (Understand your authorization server) \{#understand-your-authorization-server} - -### Recuperando informações de identidade do usuário (Retrieving user identity information) \{#retrieving-user-identity-information} - -Para concluir este tutorial, seu servidor de autorização deve oferecer uma API para recuperar informações de identidade do usuário: - - - - -[Logto](https://logto.io) é um provedor OpenID Connect que suporta o endpoint padrão [userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) para recuperar informações de identidade do usuário. - -Para buscar um token de acesso que possa ser usado para acessar o endpoint userinfo, pelo menos dois escopos são necessários: `openid` e `profile`. Você pode continuar lendo, pois abordaremos a configuração de escopos mais adiante. - - - - -[Keycloak](https://www.keycloak.org) é uma solução open-source de gerenciamento de identidade e acesso que suporta múltiplos protocolos, incluindo OpenID Connect (OIDC). Como um provedor OIDC, ele implementa o endpoint padrão [userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) para recuperar informações de identidade do usuário. - -Para buscar um token de acesso que possa ser usado para acessar o endpoint userinfo, pelo menos dois escopos são necessários: `openid` e `profile`. Você pode continuar lendo, pois abordaremos a configuração de escopos mais adiante. - - - - -A maioria dos provedores OpenID Connect suporta o [endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) para recuperar informações de identidade do usuário. - -Verifique a documentação do seu provedor para saber se ele suporta esse endpoint. Se seu provedor suporta [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html), você também pode verificar se o `userinfo_endpoint` está incluído no documento de descoberta (resposta do endpoint `.well-known/openid-configuration`). - -Para buscar um token de acesso que possa ser usado para acessar o endpoint userinfo, pelo menos dois escopos são necessários: `openid` e `profile`. Verifique a documentação do seu provedor para ver o mapeamento de escopos para reivindicações de identidade do usuário. - - - - -Embora o OAuth 2.0 não defina uma maneira padrão de recuperar informações de identidade do usuário, muitos provedores implementam seus próprios endpoints para isso. Verifique a documentação do seu provedor para saber como recuperar informações de identidade do usuário usando um token de acesso e quais parâmetros são necessários para obter esse token ao invocar o fluxo de autorização. - - - - -### Registro dinâmico de cliente (Dynamic Client Registration) \{#dynamic-client-registration} - -O registro dinâmico de cliente não é necessário para este tutorial, mas pode ser útil se você quiser automatizar o processo de registro do cliente MCP com seu servidor de autorização. Consulte [O registro dinâmico de cliente é necessário?](/provider-list#is-dcr-required) para mais detalhes. - -## Configure o servidor MCP (Set up the MCP server) \{#set-up-the-mcp-server} - -Usaremos os [SDKs oficiais do MCP](https://github.com/modelcontextprotocol) para criar um servidor MCP com uma ferramenta `whoami` que recupera informações de identidade do usuário do servidor de autorização. - -### Crie um novo projeto (Create a new project) \{#create-a-new-project} - - - - -```bash -mkdir mcp-server -cd mcp-server -uv init # Ou use `pipenv` ou `poetry` para criar um novo ambiente virtual -``` - - - - -Configure um novo projeto Node.js: - -```bash -mkdir mcp-server -cd mcp-server -npm init -y # Ou use `pnpm init` -npm pkg set type="module" -npm pkg set main="whoami.js" -npm pkg set scripts.start="node whoami.js" -``` - - - - -### Instale o MCP SDK e dependências (Install the MCP SDK and dependencies) \{#install-the-mcp-sdk-and-dependencies} - - - - -```bash -pip install "mcp[cli]" starlette uvicorn -``` - -Ou qualquer outro gerenciador de pacotes de sua preferência, como `uv` ou `poetry`. - - - - -```bash -npm install @modelcontextprotocol/sdk express -``` - -Ou qualquer outro gerenciador de pacotes de sua preferência, como `pnpm` ou `yarn`. - - - - -### Crie o servidor MCP (Create the MCP server) \{#create-the-mcp-server} - -Primeiro, vamos criar um servidor MCP que implementa uma ferramenta `whoami`. - - - - -Crie um arquivo chamado `whoami.py` e adicione o seguinte código: - -```python -from mcp.server.fastmcp import FastMCP -from starlette.applications import Starlette -from starlette.routing import Mount -from typing import Any - -mcp = FastMCP("WhoAmI") - -@mcp.tool() -def whoami() -> dict[str, Any]: - """Uma ferramenta que retorna as informações do usuário atual.""" - return {"error": "Not authenticated"} - -app = Starlette( - routes=[Mount('/', app=mcp.sse_app())] -) -``` - -Execute o servidor com: - -```bash -uvicorn whoami:app --host 0.0.0.0 --port 3001 -``` - - - - -:::note -Como a implementação atual do MCP inspector não lida com fluxos de autorização, usaremos a abordagem SSE para configurar o servidor MCP. Atualizaremos o código aqui assim que o MCP inspector suportar fluxos de autorização. -::: - -Você também pode usar `pnpm` ou `yarn` se preferir. - -Crie um arquivo chamado `whoami.js` e adicione o seguinte código: - -```js -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; -import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'; -import express from 'express'; - -// Crie um servidor MCP -const server = new McpServer({ - name: 'WhoAmI', - version: '0.0.0', -}); - -// Adicione uma ferramenta ao servidor que retorna as informações do usuário atual -server.tool('whoami', async () => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Not authenticated' }) }], - }; -}); - -// Abaixo está o código boilerplate da documentação do MCP SDK -const PORT = 3001; -const app = express(); - -const transports = {}; - -app.get('/sse', async (_req, res) => { - const transport = new SSEServerTransport('/messages', res); - transports[transport.sessionId] = transport; - - res.on('close', () => { - delete transports[transport.sessionId]; - }); - - await server.connect(transport); -}); - -app.post('/messages', async (req, res) => { - const sessionId = String(req.query.sessionId); - const transport = transports[sessionId]; - if (transport) { - await transport.handlePostMessage(req, res, req.body); - } else { - res.status(400).send('No transport found for sessionId'); - } -}); - -app.listen(PORT); -``` - -Execute o servidor com: - -```bash -npm start -``` - - - - -## Inspecione o servidor MCP (Inspect the MCP server) \{#inspect-the-mcp-server} - -### Clone e execute o MCP inspector (Clone and run MCP inspector) \{#clone-and-run-mcp-inspector} - -Agora que temos o servidor MCP em execução, podemos usar o MCP inspector para ver se a ferramenta `whoami` está disponível. - -Devido à limitação da implementação atual, fizemos um fork do [MCP inspector](https://github.com/mcp-auth/inspector) para torná-lo mais flexível e escalável para autenticação e autorização. Também enviamos um pull request para o repositório original para incluir nossas alterações. - -Para executar o MCP inspector, você pode usar o seguinte comando (Node.js é necessário): - -```bash -git clone https://github.com/mcp-auth/inspector.git -cd inspector -npm install -npm run dev -``` - -Em seguida, abra seu navegador e acesse `http://localhost:6274/` (ou outro URL exibido no terminal) para acessar o MCP inspector. - -### Conecte o MCP inspector ao servidor MCP (Connect MCP inspector to the MCP server) \{#connect-mcp-inspector-to-the-mcp-server} - -Antes de prosseguir, verifique a seguinte configuração no MCP inspector: - -- **Tipo de transporte (Transport Type)**: Defina como `SSE`. -- **URL**: Defina como a URL do seu servidor MCP. No nosso caso, deve ser `http://localhost:3001/sse`. - -Agora você pode clicar no botão "Connect" para ver se o MCP inspector consegue se conectar ao servidor MCP. Se tudo estiver correto, você verá o status "Connected" no MCP inspector. - -### Ponto de verificação: Execute a ferramenta `whoami` (Checkpoint: Run the `whoami` tool) \{#checkpoint-run-the-whoami-tool} - -1. No menu superior do MCP inspector, clique na guia "Tools". -2. Clique no botão "List Tools". -3. Você deve ver a ferramenta `whoami` listada na página. Clique nela para abrir os detalhes da ferramenta. -4. Você deve ver o botão "Run Tool" no lado direito. Clique nele para executar a ferramenta. -5. Você deve ver o resultado da ferramenta com a resposta JSON `{"error": "Not authenticated"}`. - -![Primeira execução do MCP inspector](/docs-assets/images/tutorials/whoami/inspector-first-run.png) - -## Integre com seu servidor de autorização (Integrate with your authorization server) \{#integrate-with-your-authorization-server} - -Para concluir esta seção, há várias considerações a serem levadas em conta: - -
-**A URL do emissor do seu servidor de autorização (The issuer URL of your authorization server)** - -Normalmente, é a URL base do seu servidor de autorização, como `https://auth.example.com`. Alguns provedores podem ter um caminho como `https://example.logto.app/oidc`, então certifique-se de verificar a documentação do seu provedor. - -
- -
-**Como recuperar os metadados do servidor de autorização (How to retrieve the authorization server metadata)** - -- Se seu servidor de autorização estiver em conformidade com o [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) ou [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html), você pode usar as utilidades integradas do MCP Auth para buscar os metadados automaticamente. -- Se seu servidor de autorização não estiver em conformidade com esses padrões, você precisará especificar manualmente a URL dos metadados ou endpoints na configuração do servidor MCP. Verifique a documentação do seu provedor para os endpoints específicos. - -
- -
-**Como registrar o MCP inspector como cliente em seu servidor de autorização (How to register the MCP inspector as a client in your authorization server)** - -- Se seu servidor de autorização suporta [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591), você pode pular esta etapa, pois o MCP inspector se registrará automaticamente como cliente. -- Se seu servidor de autorização não suporta Dynamic Client Registration, você precisará registrar manualmente o MCP inspector como cliente em seu servidor de autorização. - -
- -
-**Como recuperar informações de identidade do usuário e como configurar os parâmetros da solicitação de autorização (How to retrieve user identity information and how to configure the authorization request parameters)** - -- Para provedores OpenID Connect: normalmente você precisa solicitar pelo menos os escopos `openid` e `profile` ao iniciar o fluxo de autorização. Isso garantirá que o token de acesso retornado pelo servidor de autorização contenha os escopos necessários para acessar o [endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) para recuperar informações de identidade do usuário. - - Nota: Alguns provedores podem não suportar o endpoint userinfo. - -- Para provedores OAuth 2.0 / OAuth 2.1: verifique a documentação do seu provedor para saber como recuperar informações de identidade do usuário usando um token de acesso e quais parâmetros são necessários para obter esse token ao invocar o fluxo de autorização. - -
- -Embora cada provedor possa ter seus próprios requisitos específicos, as etapas a seguir irão guiá-lo pelo processo de integração do MCP inspector e do servidor MCP com configurações específicas do provedor. - -### Registre o MCP inspector como cliente (Register MCP inspector as a client) \{#register-mcp-inspector-as-a-client} - - - - -Integrar com o [Logto](https://logto.io) é simples, pois é um provedor OpenID Connect que suporta o endpoint padrão [userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) para recuperar informações de identidade do usuário. - -Como o Logto ainda não suporta Dynamic Client Registration, você precisará registrar manualmente o MCP inspector como cliente em seu tenant Logto: - -1. Abra seu MCP inspector, clique no botão "OAuth Configuration". Copie o valor **Redirect URL (auto-populated)**, que deve ser algo como `http://localhost:6274/oauth/callback`. -2. Faça login no [Logto Console](https://cloud.logto.io) (ou seu Logto Console auto-hospedado). -3. Navegue até a aba "Applications", clique em "Create application". No final da página, clique em "Create app without framework". -4. Preencha os detalhes do aplicativo e clique em "Create application": - - **Selecione um tipo de aplicativo**: Escolha "Single-page application". - - **Nome do aplicativo**: Insira um nome para seu aplicativo, por exemplo, "MCP Inspector". -5. Na seção "Settings / Redirect URIs", cole o valor **Redirect URL (auto-populated)** que você copiou do MCP inspector. Em seguida, clique em "Save changes" na barra inferior. -6. No cartão superior, você verá o valor "App ID". Copie-o. -7. Volte ao MCP inspector e cole o valor "App ID" na seção "OAuth Configuration" em "Client ID". -8. Insira o valor `{"scope": "openid profile email"}` no campo "Auth Params". Isso garantirá que o token de acesso retornado pelo Logto contenha os escopos necessários para acessar o endpoint userinfo. - - - - -[Keycloak](https://www.keycloak.org) é uma solução open-source de gerenciamento de identidade e acesso que suporta o protocolo OpenID Connect. - -Embora o Keycloak suporte registro dinâmico de cliente, seu endpoint de registro de cliente não suporta CORS, impedindo que a maioria dos clientes MCP se registrem diretamente. Portanto, precisaremos registrar nosso cliente manualmente. - -:::note -Embora o Keycloak possa ser instalado de [várias formas](https://www.keycloak.org/guides#getting-started) (bare metal, kubernetes, etc.), para este tutorial, usaremos Docker para uma configuração rápida e simples. -::: - -Vamos configurar uma instância Keycloak e ajustá-la para nossas necessidades: - -1. Primeiro, execute uma instância Keycloak usando Docker conforme a [documentação oficial](https://www.keycloak.org/getting-started/getting-started-docker): - -```bash -docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.2.4 start-dev -``` - -2. Acesse o Keycloak Admin Console (http://localhost:8080/admin) e faça login com estas credenciais: - - - Usuário: `admin` - - Senha: `admin` - -3. Crie um novo Realm: - - - Clique em "Create Realm" no canto superior esquerdo - - Digite `mcp-realm` no campo "Realm name" - - Clique em "Create" - -4. Crie um usuário de teste: - - - Clique em "Users" no menu à esquerda - - Clique em "Create new user" - - Preencha os detalhes do usuário: - - Username: `testuser` - - Nome e sobrenome podem ser quaisquer valores - - Clique em "Create" - - Na aba "Credentials", defina uma senha e desmarque "Temporary" - -5. Registre o MCP Inspector como cliente: - - - Abra seu MCP inspector, clique no botão "OAuth Configuration". Copie o valor **Redirect URL (auto-populated)**, que deve ser algo como `http://localhost:6274/oauth/callback`. - - No Keycloak Admin Console, clique em "Clients" no menu à esquerda - - Clique em "Create client" - - Preencha os detalhes do cliente: - - Tipo de cliente: Selecione "OpenID Connect" - - Client ID: Digite `mcp-inspector` - - Clique em "Next" - - Na página "Capability config": - - Certifique-se de que "Standard flow" está habilitado - - Clique em "Next" - - Na página "Login settings": - - Cole a URL de callback do MCP Inspector em "Valid redirect URIs" - - Digite `http://localhost:6274` em "Web origins" - - Clique em "Save" - - Copie o "Client ID" (que é `mcp-inspector`) - -6. De volta ao MCP Inspector: - - Cole o Client ID copiado no campo "Client ID" na seção "OAuth Configuration" - - Insira o seguinte valor no campo "Auth Params" para solicitar os escopos necessários: - -```json -{ "scope": "openid profile email" } -``` - - - - -:::note -Este é um guia genérico de integração com provedores OpenID Connect. Verifique a documentação do seu provedor para detalhes específicos. -::: - -Se seu provedor OpenID Connect suporta Dynamic Client Registration, você pode ir diretamente para o passo 8 abaixo para configurar o MCP inspector; caso contrário, será necessário registrar manualmente o MCP inspector como cliente em seu provedor OpenID Connect: - -1. Abra seu MCP inspector, clique no botão "OAuth Configuration". Copie o valor **Redirect URL (auto-populated)**, que deve ser algo como `http://localhost:6274/oauth/callback`. -2. Faça login no console do seu provedor OpenID Connect. -3. Navegue até a seção "Applications" ou "Clients" e crie um novo aplicativo ou cliente. -4. Se seu provedor exigir um tipo de cliente, selecione "Single-page application" ou "Public client". -5. Após criar o aplicativo, será necessário configurar a URI de redirecionamento. Cole o valor **Redirect URL (auto-populated)** que você copiou do MCP inspector. -6. Encontre o "Client ID" ou "Application ID" do aplicativo recém-criado e copie-o. -7. Volte ao MCP inspector e cole o valor "Client ID" na seção "OAuth Configuration" em "Client ID". -8. Para provedores OpenID Connect padrão, você pode inserir o seguinte valor no campo "Auth Params" para solicitar os escopos necessários para acessar o endpoint userinfo: - -```json -{ "scope": "openid profile email" } -``` - - - - -:::note -Este é um guia genérico de integração com provedores OAuth 2.0 / OAuth 2.1. Verifique a documentação do seu provedor para detalhes específicos. -::: - -Se seu provedor OAuth 2.0 / OAuth 2.1 suporta Dynamic Client Registration, você pode ir diretamente para o passo 8 abaixo para configurar o MCP inspector; caso contrário, será necessário registrar manualmente o MCP inspector como cliente em seu provedor OAuth 2.0 / OAuth 2.1: - -1. Abra seu MCP inspector, clique no botão "OAuth Configuration". Copie o valor **Redirect URL (auto-populated)**, que deve ser algo como `http://localhost:6274/oauth/callback`. -2. Faça login no console do seu provedor OAuth 2.0 / OAuth 2.1. -3. Navegue até a seção "Applications" ou "Clients" e crie um novo aplicativo ou cliente. -4. Se seu provedor exigir um tipo de cliente, selecione "Single-page application" ou "Public client". -5. Após criar o aplicativo, será necessário configurar a URI de redirecionamento. Cole o valor **Redirect URL (auto-populated)** que você copiou do MCP inspector. -6. Encontre o "Client ID" ou "Application ID" do aplicativo recém-criado e copie-o. -7. Volte ao MCP inspector e cole o valor "Client ID" na seção "OAuth Configuration" em "Client ID". -8. Leia a documentação do seu provedor para saber como recuperar tokens de acesso para informações de identidade do usuário. Pode ser necessário especificar os escopos ou parâmetros necessários para obter o token de acesso. Por exemplo, se seu provedor exigir o escopo `profile` para acessar informações de identidade do usuário, você pode inserir o seguinte valor no campo "Auth Params": - -```json -{ "scope": "profile" } -``` - - - - -### Configure o MCP auth (Set up MCP auth) \{#set-up-mcp-auth} - -No seu projeto do servidor MCP, você precisa instalar o SDK MCP Auth e configurá-lo para usar os metadados do seu servidor de autorização. - - - - -Primeiro, instale o pacote `mcpauth`: - -```bash -pip install mcpauth -``` - -Ou qualquer outro gerenciador de pacotes de sua preferência, como `uv` ou `poetry`. - - - - -Primeiro, instale o pacote `mcp-auth`: - -```bash -npm install mcp-auth -``` - - - - -O MCP Auth requer os metadados do servidor de autorização para poder inicializar. Dependendo do seu provedor: - - - - - -A URL do emissor pode ser encontrada na página de detalhes do seu aplicativo no Logto Console, na seção "Endpoints & Credentials / Issuer endpoint". Deve ser algo como `https://my-project.logto.app/oidc`. - - - - - - - -A URL do emissor pode ser encontrada no Keycloak Admin Console. Em seu 'mcp-realm', navegue até a seção "Realm settings / Endpoints" e clique no link "OpenID Endpoint Configuration". O campo `issuer` no documento JSON conterá sua URL de emissor, que deve ser algo como `http://localhost:8080/realms/mcp-realm`. - - - - - - - -O código a seguir também assume que o servidor de autorização suporta o [endpoint userinfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) para recuperar informações de identidade do usuário. Se seu provedor não suportar esse endpoint, será necessário verificar a documentação do seu provedor para o endpoint específico e substituir a variável do endpoint userinfo pela URL correta. - - - - - - -Como mencionamos anteriormente, o OAuth 2.0 não define uma maneira padrão de recuperar informações de identidade do usuário. O código a seguir assume que seu provedor possui um endpoint específico para recuperar informações de identidade do usuário usando um token de acesso. Você precisará verificar a documentação do seu provedor para o endpoint específico e substituir a variável do endpoint userinfo pela URL correta. - - - - - - -### Atualize o servidor MCP (Update MCP server) \{#update-mcp-server} - -Estamos quase lá! É hora de atualizar o servidor MCP para aplicar a rota e o middleware do MCP Auth, e então fazer a ferramenta `whoami` retornar as informações reais de identidade do usuário. - - - - -```python -@mcp.tool() -def whoami() -> dict[str, Any]: - """Uma ferramenta que retorna as informações do usuário atual.""" - return ( - mcp_auth.auth_info.claims - if mcp_auth.auth_info # Isso será preenchido pelo middleware Bearer auth - else {"error": "Not authenticated"} - ) - -# ... - -bearer_auth = Middleware(mcp_auth.bearer_auth_middleware(verify_access_token)) -app = Starlette( - routes=[ - # Adicione a rota de metadados (`/.well-known/oauth-authorization-server`) - mcp_auth.metadata_route(), - # Proteja o servidor MCP com o middleware Bearer auth - Mount('/', app=mcp.sse_app(), middleware=[bearer_auth]), - ], -) -``` - - - - -```js -server.tool('whoami', ({ authInfo }) => { - return { - content: [ - { type: 'text', text: JSON.stringify(authInfo?.claims ?? { error: 'Not authenticated' }) }, - ], - }; -}); - -// ... - -app.use(mcpAuth.delegatedRouter()); -app.use(mcpAuth.bearerAuth(verifyToken)); -``` - - - - -## Ponto de verificação: Execute a ferramenta `whoami` com autenticação (Checkpoint: Run the `whoami` tool with authentication) \{#checkpoint-run-the-whoami-tool-with-authentication} - -Reinicie seu servidor MCP e abra o MCP inspector no navegador. Ao clicar no botão "Connect", você deve ser redirecionado para a página de login do seu servidor de autorização. - -Depois de fazer login e retornar ao MCP inspector, repita as ações que fizemos no ponto de verificação anterior para executar a ferramenta `whoami`. Desta vez, você deve ver as informações de identidade do usuário retornadas pelo servidor de autorização. - -![Resultado da ferramenta whoami no MCP inspector](/docs-assets/images/tutorials/whoami/result.png) - - - - -:::info -Confira o [repositório do MCP Auth Python SDK](https://github.com/mcp-auth/python/blob/master/samples/server/whoami.py) para o código completo do servidor MCP (versão OIDC). -::: - - - - -:::info -Confira o [repositório do MCP Auth Node.js SDK](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) para o código completo do servidor MCP (versão OIDC). Este diretório contém versões em TypeScript e JavaScript do código. -::: - - - - -## Notas finais (Closing notes) \{#closing-notes} - -🎊 Parabéns! Você concluiu com sucesso o tutorial. Vamos recapitular o que fizemos: - -- Configuração de um servidor MCP básico com a ferramenta `whoami` -- Integração do servidor MCP com um servidor de autorização usando MCP Auth -- Configuração do MCP Inspector para autenticar usuários e recuperar suas informações de identidade - -Você também pode explorar alguns tópicos avançados, incluindo: - -- Uso de [JWT (JSON Web Token)](https://auth.wiki/jwt) para autenticação e autorização -- Aproveitamento de [indicadores de recurso (RFC 8707)](https://auth-wiki.logto.io/resource-indicator) para especificar os recursos acessados -- Implementação de mecanismos personalizados de controle de acesso, como [controle de acesso baseado em papel (RBAC)](https://auth.wiki/rbac) ou [controle de acesso baseado em atributos (ABAC)](https://auth.wiki/abac) - -Não deixe de conferir outros tutoriais e a documentação para aproveitar ao máximo o MCP Auth. \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_manual-metadata-fetching.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_manual-metadata-fetching.mdx deleted file mode 100644 index 97bd107..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_manual-metadata-fetching.mdx +++ /dev/null @@ -1,3 +0,0 @@ -:::note -Se o seu provedor não suportar {props.oidc ? 'OpenID Connect Discovery' : 'Metadados do servidor de autorização OAuth 2.0'}, você pode especificar manualmente a URL de metadados ou os endpoints. Confira [Outras formas de inicializar o MCP Auth](../../configure-server/mcp-auth.mdx#other-ways) para mais detalhes. -::: \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oauth.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oauth.mdx deleted file mode 100644 index dac7727..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oauth.mdx +++ /dev/null @@ -1,141 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -Atualize o `whoami.py` para incluir a configuração do MCP Auth: - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # Substitua pelo endpoint do seu emissor -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OAUTH) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -Atualize o `whoami.js` para incluir a configuração do MCP Auth: - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // Substitua pelo endpoint do seu emissor -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oauth' }), -}); -``` - - - - - - - -Agora, precisamos criar um verificador personalizado de token de acesso (Access token) que buscará as informações de identidade do usuário no servidor de autorização usando o token de acesso fornecido pelo inspetor MCP. - - - - -```python -import pydantic -import requests -from mcpauth.exceptions import ( - MCPAuthTokenVerificationException, - MCPAuthTokenVerificationExceptionCode, -) -from mcpauth.types import AuthInfo - -def verify_access_token(token: str) -> AuthInfo: - """ - Verifica o Bearer token fornecido buscando informações do usuário no servidor de autorização. - Se o token for válido, retorna um objeto `AuthInfo` contendo as informações do usuário. - - :param token: O Bearer token recebido do inspetor MCP. - """ - - try: - # O código a seguir assume que seu servidor de autorização possui um endpoint para buscar informações do usuário - # usando o token de acesso emitido pelo fluxo de autorização. - # Ajuste a URL e os headers conforme necessário com base na API do seu provedor. - response = requests.get( - "https://your-authorization-server.com/userinfo", - headers={"Authorization": f"Bearer {token}"}, - ) - response.raise_for_status() # Garante que um erro será lançado para erros HTTP - json = response.json() # Analisa a resposta JSON - - # O código a seguir assume que a resposta de informações do usuário é um objeto com um campo 'sub' que - # identifica o usuário. Você pode precisar ajustar isso conforme a API do seu provedor. - return AuthInfo( - token=token, - subject=json.get("sub"), - issuer=auth_issuer, # Use o emissor configurado - claims=json, # Inclui todas as reivindicações (claims) retornadas pelo endpoint - ) - # `AuthInfo` é um modelo Pydantic, então erros de validação geralmente significam que a resposta não correspondeu - # à estrutura esperada - except pydantic.ValidationError as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.INVALID_TOKEN, - cause=e, - ) - # Lida com outras exceções que podem ocorrer durante a requisição - except Exception as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.TOKEN_VERIFICATION_FAILED, - cause=e, - ) -``` - - - - -```js -import { MCPAuthTokenVerificationError } from 'mcp-auth'; - -/** - * Verifica o Bearer token fornecido buscando informações do usuário no servidor de autorização. - * Se o token for válido, retorna um objeto `AuthInfo` contendo as informações do usuário. - */ -const verifyToken = async (token) => { - // O código a seguir assume que seu servidor de autorização possui um endpoint para buscar informações do usuário - // usando o token de acesso emitido pelo fluxo de autorização. - // Ajuste a URL e os headers conforme necessário com base na API do seu provedor. - const response = await fetch('https://your-authorization-server.com/userinfo', { - headers: { Authorization: `Bearer ${token}` }, - }); - - if (!response.ok) { - throw new MCPAuthTokenVerificationError('token_verification_failed', response); - } - - const userInfo = await response.json(); - - // O código a seguir assume que a resposta de informações do usuário é um objeto com um campo 'sub' que - // identifica o usuário. Você pode precisar ajustar isso conforme a API do seu provedor. - if (typeof userInfo !== 'object' || userInfo === null || !('sub' in userInfo)) { - throw new MCPAuthTokenVerificationError('invalid_token', response); - } - - return { - token, - issuer: authIssuer, - subject: String(userInfo.sub), // Ajuste conforme o campo de ID do usuário do seu provedor - clientId: '', // O Client ID não é usado neste exemplo, mas pode ser definido se necessário - scopes: [], - claims: userInfo, - }; -}; -``` - - - \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oidc.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oidc.mdx deleted file mode 100644 index b9c5689..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oidc.mdx +++ /dev/null @@ -1,143 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -Atualize o `whoami.py` para incluir a configuração do MCP Auth: - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # Substitua pelo endpoint do seu emissor -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -Atualize o `whoami.js` para incluir a configuração do MCP Auth: - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // Substitua pelo endpoint do seu emissor -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oidc' }), -}); -``` - - - - -{props.showAlternative && } -{props.showAlternative && } - -Agora, precisamos criar um verificador personalizado de token de acesso (Access token) que buscará as informações de identidade do usuário no servidor de autorização usando o token de acesso fornecido pelo inspetor MCP. - - - - -```python -import pydantic -import requests -from mcpauth.exceptions import ( - MCPAuthTokenVerificationException, - MCPAuthTokenVerificationExceptionCode, -) -from mcpauth.types import AuthInfo - -def verify_access_token(token: str) -> AuthInfo: - """ - Verifica o Bearer token fornecido buscando informações do usuário no servidor de autorização. - Se o token for válido, retorna um objeto `AuthInfo` contendo as informações do usuário. - - :param token: O Bearer token recebido do inspetor MCP. - """ - - issuer = auth_server_config.metadata.issuer - endpoint = auth_server_config.metadata.userinfo_endpoint # O provedor deve suportar o endpoint userinfo - if not endpoint: - raise ValueError( - "O endpoint userinfo não está configurado nos metadados do servidor de autenticação." - ) - - try: - response = requests.get( - endpoint, - headers={"Authorization": f"Bearer {token}"}, # Cabeçalho padrão Bearer token - ) - response.raise_for_status() # Garante que um erro seja lançado para erros HTTP - json = response.json() # Analisa a resposta JSON - return AuthInfo( - token=token, - subject=json.get("sub"), # 'sub' é uma reivindicação padrão para o sujeito (ID do usuário) - issuer=issuer, # Usa o emissor dos metadados - claims=json, # Inclui todas as reivindicações (campos JSON) retornadas pelo endpoint userinfo - ) - # `AuthInfo` é um modelo Pydantic, então erros de validação geralmente significam que a resposta não correspondeu - # à estrutura esperada - except pydantic.ValidationError as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.INVALID_TOKEN, - cause=e, - ) - # Lida com outras exceções que podem ocorrer durante a requisição - except Exception as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.TOKEN_VERIFICATION_FAILED, - cause=e, - ) -``` - - - - -```js -import { MCPAuthTokenVerificationError } from 'mcp-auth'; - -/** - * Verifica o Bearer token fornecido buscando informações do usuário no servidor de autorização. - * Se o token for válido, retorna um objeto `AuthInfo` contendo as informações do usuário. - */ -const verifyToken = async (token) => { - const { issuer, userinfoEndpoint } = mcpAuth.config.server.metadata; - - if (!userinfoEndpoint) { - throw new Error('O endpoint userinfo não está configurado nos metadados do servidor'); - } - - const response = await fetch(userinfoEndpoint, { - headers: { Authorization: `Bearer ${token}` }, - }); - - if (!response.ok) { - throw new MCPAuthTokenVerificationError('token_verification_failed', response); - } - - const userInfo = await response.json(); - - if (typeof userInfo !== 'object' || userInfo === null || !('sub' in userInfo)) { - throw new MCPAuthTokenVerificationError('invalid_token', response); - } - - return { - token, - issuer, - subject: String(userInfo.sub), // 'sub' é uma reivindicação padrão para o sujeito (ID do usuário) - clientId: '', // O Client ID não é usado neste exemplo, mas pode ser definido se necessário - scopes: [], - claims: userInfo, - }; -}; -``` - - - \ No newline at end of file diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_transpile-metadata.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_transpile-metadata.mdx deleted file mode 100644 index 71b23e8..0000000 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_transpile-metadata.mdx +++ /dev/null @@ -1,31 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -Em alguns casos, a resposta do provedor pode estar malformada ou não estar em conformidade com o formato de metadados esperado. Se você tem certeza de que o provedor está em conformidade, é possível transpilar os metadados através da opção de configuração: - - - - -```python -mcp_auth = MCPAuth( - server=fetch_server_config( - # ...outras opções - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { - // ...outras opções - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - \ No newline at end of file diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1.json b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1.json deleted file mode 100644 index f4b7bf1..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1.json +++ /dev/null @@ -1,50 +0,0 @@ -{ - "sidebar.docsSidebar.category.Tutorials": { - "message": "教程", - "description": "The label for category Tutorials in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.Tutorials.link.generated-index.title": { - "message": "教程", - "description": "The generated-index page title for category Tutorials in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.Configure MCP server": { - "message": "配置 MCP 服务器", - "description": "The label for category Configure MCP server in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.Configure MCP server.link.generated-index.title": { - "message": "配置 MCP 服务器", - "description": "The generated-index page title for category Configure MCP server in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.SDK references": { - "message": "SDK 参考", - "description": "The label for category SDK references in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.SDK references.link.generated-index.title": { - "message": "MCP Auth SDK 参考", - "description": "The generated-index page title for category SDK references in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.SDK references.link.generated-index.description": { - "message": "从 MCP Auth SDK 中提取的类、方法和属性信息。\n", - "description": "The generated-index page description for category SDK references in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.Node.js SDK": { - "message": "Node.js SDK", - "description": "The label for category Node.js SDK in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.classes": { - "message": "类", - "description": "The label for category classes in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.functions": { - "message": "函数", - "description": "The label for category functions in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.type-aliases": { - "message": "类型别名", - "description": "The label for category type-aliases in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.variables": { - "message": "变量", - "description": "The label for category variables in sidebar docsSidebar" - } -} diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/README.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/README.mdx deleted file mode 100644 index eb8ca61..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/README.mdx +++ /dev/null @@ -1,242 +0,0 @@ ---- -sidebar_position: 1 -sidebar_label: 入门 ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -# 入门 - -## 选择兼容的 OAuth 2.1 或 OpenID Connect 提供商 \{#choose-a-compatible-oauth-2-1-or-openid-connect-provider} - -MCP 规范对授权 (Authorization) 有一些[特定要求](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization#1-3-standards-compliance)： - -- [OAuth 2.1 IETF DRAFT](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12) -- OAuth 2.0 授权服务器元数据 ([RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)) -- OAuth 2.0 动态客户端注册协议 ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) - -虽然后两者不是强制性的，但第一个是确保安全和合规实现所必需的。 - -:::note -在新的 MCP 草案中，RFC 8414 将对授权服务器（提供商）强制要求。我们会在新草案最终确定后更新文档。 -::: - -你可以查看 [MCP 兼容提供商列表](/provider-list) 来确认你的提供商是否受支持。 - -## 安装 MCP Auth SDK \{#install-mcp-auth-sdk} - -MCP Auth 同时支持 Python 和 TypeScript。如果你需要其他语言或框架的支持，请告诉我们！ - - - - -```bash -pip install mcpauth -``` - -或者你喜欢的其他包管理器，如 pipenv 或 poetry。 - - - - -```bash -npm install mcp-auth -``` - -或者你喜欢的其他包管理器，如 pnpm 或 yarn。 - - - - -## 初始化 MCP Auth \{#init-mcp-auth} - -第一步是使用你的提供商的授权服务器元数据初始化 MCP Auth 实例。如果你的提供商符合以下之一： - -- [OAuth 2.0 授权服务器元数据](https://datatracker.ietf.org/doc/html/rfc8414) -- [OpenID Connect 发现](https://openid.net/specs/openid-connect-discovery-1_0.html) - -你可以使用内置函数获取元数据并初始化 MCP Auth 实例： - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -mcp_auth = MCPAuth( - server=fetch_server_config( - '', - type=AuthServerType.OIDC # 或 AuthServerType.OAUTH - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { type: 'oidc' }), // 或 'oauth' -}); -``` - - - - -如果你需要手动指定元数据 URL 或端点，请查看 [其他初始化 MCP Auth 的方式](./configure-server/mcp-auth.mdx#other-ways)。 - -## 挂载元数据端点 \{#mount-the-metadata-endpoint} - -为了符合当前 MCP 规范，MCP Auth 会将 OAuth 2.0 授权服务器元数据端点 (`/.well-known/oauth-authorization-server`) 挂载到你的 MCP 服务器： - - - - -```python -from starlette.applications import Starlette - -app = Starlette(routes=[ - mcp_auth.metadata_route(), -]) -``` - - - - -```ts -import express from 'express'; - -const app = express(); -app.use(mcpAuth.delegatedRouter()); -``` - - - - -元数据中的 URL 会保持不变，因此授权服务器的角色完全委托给提供商。你可以通过访问 MCP 服务器的 `/.well-known/oauth-authorization-server` 来测试元数据端点。 - -### 为什么只挂载元数据端点？ \{#why-only-the-metadata-endpoint} - -你可能会看到官方 SDK 提供了一个 auth 路由器，挂载了 `/authorize`、`/token` 等授权端点。我们不这样做的原因如下： - -1. 只挂载元数据端点可以让你充分利用提供商的全部能力，而无需“重复造轮子”并给 MCP 服务器引入不必要的复杂性。 -2. 目前也在推动[将 MCP 服务器角色转变为资源服务器](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/205)，并要求 OAuth 2.0 受保护资源元数据 ([RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728))。这意味着 MCP 服务器将**不再处理任何授权 (Authorization) 逻辑**（包括元数据端点），而只作为依赖提供商进行认证 (Authentication) 和授权 (Authorization) 的资源服务器。 - -:::note -我们会在新 MCP 规范最终确定后，更新 MCP Auth 以支持新规范。在此期间，你可以使用当前版本，它与现有规范兼容。 -::: - -## 使用 Bearer 认证 (Authentication) 中间件 \{#use-the-bearer-auth-middleware} - -一旦初始化 MCP Auth 实例，你就可以应用 Bearer 认证 (Authentication) 中间件来保护你的 MCP 路由： - - - - -```python -from starlette.applications import Starlette -from starlette.middleware import Middleware -from starlette.routing import Mount -from mcpauth import MCPAuth -from mcp.server.fastmcp import FastMCP - -mcp = FastMCP() -mcp_auth = MCPAuth( - # 用你的授权服务器配置初始化 -) -bearer_auth = mcp_auth.bearer_auth_middleware( - "jwt", required_scopes=["read", "write"] -) - -app = Starlette(routes=[ - mcp_auth.metadata_route(), - Mount( - "/", - app=mcp.sse_app(), - middleware=[Middleware(bearer_auth)], - ), -]) -``` - - - - -```ts -import express from 'express'; -import { MCPAuth } from 'mcp-auth'; - -const app = express(); -const server = new McpServer(/* ... */); -const mcpAuth = new MCPAuth({ - /* ... */ -}); - -app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] })); -``` - - - - -在上面的例子中，我们指定了 `jwt` 令牌类型，并要求 `read` 和 `write` 权限 (Scopes)。它会自动校验 JWT (JSON Web Token)，并填充一个包含已认证 (Authentication) 用户信息的对象。 - -:::info -之前没听说过 JWT (JSON Web Token)？别担心，你可以继续阅读文档，我们会在需要时进行解释。你也可以查看 [Auth Wiki](https://auth.wiki/jwt) 进行快速了解。 -::: - -关于 Bearer 认证 (Authentication) 配置的更多信息，请查看 [配置 Bearer 认证 (Authentication)](./configure-server/bearer-auth.mdx)。 - -## 在 MCP 实现中获取认证 (Authentication) 信息 \{#retrieve-the-auth-info-in-your-mcp-implementation} - -应用 Bearer 认证 (Authentication) 中间件后，你可以在 MCP 实现中访问已认证 (Authentication) 用户（或身份）的信息： - - - - -MCP Auth 会在 Bearer 认证 (Authentication) 中间件成功认证 (Authentication) 后，将已认证 (Authentication) 用户信息存储在上下文变量中。你可以在 MCP 工具处理器中这样访问： - -```python -from mcp.server.fastmcp import FastMCP - -mcp = FastMCP() -mcp_auth = MCPAuth( - # 用你的授权服务器配置初始化 -) - -@mcp.tool() -def add(a: int, b: int): - """ - 一个将两个数字相加的工具。 - 已认证 (Authentication) 用户的信息会在上下文中可用。 - """ - auth_info = mcp_auth.auth_info # 在当前上下文中访问认证 (Authentication) 信息 - if auth_info: - print(f"Authenticated user: {auth_info.claims}") - return a + b -``` - - - - -工具处理器的第二个参数会包含 `authInfo` 对象，其中包括已认证 (Authentication) 用户的信息： - -```ts -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; -import { z } from 'zod'; - -const server = new McpServer(/* ... */); -server.tool('add', { a: z.number(), b: z.number() }, async ({ a, b }, { authInfo }) => { - // 现在你可以使用 `authInfo` 对象访问认证 (Authentication) 信息 -}); -``` - - - - -## 下一步 \{#next-steps} - -继续阅读，了解如何将 MCP Auth 与 MCP 服务器集成的端到端示例，以及如何在 MCP 客户端中处理认证 (Authentication) 流程。 \ No newline at end of file diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/comparison.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/comparison.mdx deleted file mode 100644 index ba68302..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/comparison.mdx +++ /dev/null @@ -1,80 +0,0 @@ ---- -sidebar_position: 101 -sidebar_label: 对比 ---- - -# 在 MCP Auth 与其他方案之间的选择 - -MCP 生态正在不断发展。随着 Model Context Protocol (MCP) 规范从“授权 (Authorization) 服务器”模式转向全新的“资源服务器 + 第三方身份提供商 (IdP)”模型，了解不同集成方案在现在和未来的适用性变得尤为重要。 - -本页将概述 mcp-auth 与其他主流方案的主要区别，帮助你为项目选择最佳方案。 - -## 背景：代理模式 vs. IdP 集成 \{#background-proxy-approach-vs-idp-integration} - -大多数现有的 MCP 认证 (Authentication) 方案采用“代理模式”。在这种模式下，MCP 服务器将授权 (Authorization) 请求代理到第三方身份提供商 (IdP)，实际上充当了客户端与 IdP 之间的中间人。 - -**代理模式（[03-26 规范](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization)）** - -```mermaid -sequenceDiagram - participant Client as 客户端 - participant MCP_Server as MCP 服务器 - participant ThirdParty_IdP as 第三方 IdP - - Client->>MCP_Server: 授权 (Authorization) 请求 - MCP_Server->>ThirdParty_IdP: 代理请求 - ThirdParty_IdP->>MCP_Server: 响应 - MCP_Server->>Client: 响应 - Client->>MCP_Server: 访问资源 - alt 远程验证 - MCP_Server->>ThirdParty_IdP: 验证令牌 - ThirdParty_IdP->>MCP_Server: 令牌有效 - else 本地验证 - MCP_Server->>MCP_Server: 本地验证令牌（如缓存的 JWK） - end - MCP_Server->>Client: 资源数据 -``` - -虽然这种方式兼容当前（2025-03-26）MCP 规范，但本质上是一种变通方案。它假设 MCP 服务器也充当授权 (Authorization) 服务器，而这并不是最新规范草案的发展方向。 - -**MCP Auth / 未来规范（资源服务器 + 第三方 IdP）** - -```mermaid -sequenceDiagram - participant Client as 客户端 - participant MCP_Server as MCP 服务器 - participant ThirdParty_IdP as 第三方 IdP - - Client->>ThirdParty_IdP: 授权 (Authorization) 请求 - ThirdParty_IdP->>Client: 令牌 - Client->>MCP_Server: 访问资源（携带令牌） - alt 远程验证 - MCP_Server->>ThirdParty_IdP: 验证令牌 - ThirdParty_IdP->>MCP_Server: 令牌有效 - else 本地验证 - MCP_Server->>MCP_Server: 本地验证令牌（如缓存的 JWK） - end - MCP_Server->>Client: 资源数据 -``` - -即将发布的 MCP 规范[将授权 (Authorization) 的责任转移给专用的第三方 IdP](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/205)。在这种模式下，MCP 服务器仅作为资源服务器，所有授权 (Authorization) 端点都直接来自第三方 IdP。 - -## 为什么选择 MCP Auth？\{#why-choose-mcp-auth} - -- 规范对齐：MCP Auth 直接遵循最新草案方向，是唯一同时兼容 03-26 规范和即将发布规范的方案。 -- 不再需要变通：MCP Auth 不再让 MCP 服务器充当授权 (Authorization) 服务器代理，而是让第三方 IdP 负责所有授权 (Authorization)，这正是新规范的设计初衷。 -- 不依赖特定厂商：MCP Auth 可与任何符合标准的 OAuth 2.0 / OIDC 提供商配合使用。 -- 平滑过渡：MCP Auth 通过 OAuth 2.0 授权 (Authorization) 服务器元数据原样返回所有第三方端点，使集成现在简单，未来也能无缝适配变更。 -- 开发者体验：提供教程、工具，以及即将上线的 [OAuth 2.0 受保护资源元数据](https://auth.wiki/protected-resource-metadata) 等功能，让 MCP 服务器开发者更轻松。 - -| 功能 | 代理方案 | MCP Auth | -| ------------------------------------ | --------------------- | -------- | -| 兼容 03-26 规范 | ✅ | ✅ | -| 兼容未来规范 | ❌ | ✅ | -| 直接支持第三方 IdP | ❌（仅变通支持） | ✅ | -| 不依赖特定厂商 | 有限[^1] | 是 | -| 支持平滑过渡 | ❌ | ✅ | - -如果你现在就需要支持第三方 IdP，并希望为即将到来的新规范做好准备，MCP Auth 是推荐方案。基于代理的方式可能很快会被弃用或需要大量重构。 - -[^1]: 某些代理方案可能会硬编码特定参数或端点，限制了灵活性。 \ No newline at end of file diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/configure-server/bearer-auth.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/configure-server/bearer-auth.mdx deleted file mode 100644 index ac83fad..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/configure-server/bearer-auth.mdx +++ /dev/null @@ -1,250 +0,0 @@ ---- -sidebar_position: 2 -sidebar_label: Bearer 认证 (Authentication) ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -# 在 MCP 服务器中配置 Bearer 认证 (Authentication) - -MCP Auth 提供多种方式在你的 MCP 服务器中配置 Bearer 授权 (Authorization)： - -- [JWT (JSON Web Token)](https://auth.wiki/jwt) 模式：内置的授权 (Authorization) 方法，通过声明 (Claims) 断言验证 JWT。 -- 自定义模式：允许你实现自己的授权 (Authorization) 逻辑。 - -## 使用 JWT 模式配置 Bearer 认证 (Authentication) \{#configure-bearer-auth-with-jwt-mode} - -如果你的 OAuth / OIDC 提供商为授权 (Authorization) 签发 JWT，你可以在 MCP Auth 中使用内置的 JWT 模式。它会验证 JWT 的签名、过期时间以及你指定的其他声明 (Claims)；然后会在请求上下文中填充认证 (Authentication) 信息，供你的 MCP 实现进一步处理。 - -### 权限 (Scope) 校验 \{#scope-validation} - -以下是基本权限 (Scope) 校验的示例： - - - - -```python -from mcpauth import MCPAuth -from starlette.applications import Starlette -from starlette.middleware import Middleware -from starlette.routing import Mount -from mcp.server.fastmcp import FastMCP - -mcp = FastMCP("MyMCPServer") -mcp_auth = MCPAuth( - # Initialize with your auth server config -) -bearer_auth = mcp_auth.bearer_auth_middleware("jwt", required_scopes=["read", "write"]) # [!code highlight] - -app = Starlette( - routes=[Mount('/', app=mcp.sse_app(), middleware=[Middleware(bearer_auth)])] -) -``` - - - - -```ts -import express from 'express'; -import { MCPAuth } from 'mcp-auth'; - -const app = express(); -const mcpAuth = new MCPAuth({ - /* ... */ -}); -const bearerAuth = mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }); // [!code highlight] - -app.use('/mcp', bearerAuth, (req, res) => { - // Now `req.auth` contains the auth info - console.log(req.auth); -}); -``` - - - - -在上面的示例中，我们指定 JWT 需要包含 `read` 和 `write` 权限 (Scopes)。如果 JWT 没有包含**任意一个**这些权限 (Scopes)，请求将被拒绝并返回 403 Forbidden 错误。 - -### 资源指示器 (Resource indicator) 校验（RFC 8707）\{#resource-indicator-validation-rfc-8707} - -如果你的提供商基于 OIDC，或支持 [资源指示器 (Resource Indicator)](https://datatracker.ietf.org/doc/html/rfc8707) 扩展，你还可以指定 `audience` 选项来校验 JWT 中的 `aud`（受众 (Audience)）声明 (Claim)。这有助于确保 JWT 是专门为你的 MCP 服务器签发的。 - -请查阅你的提供商文档，了解是否支持资源指示器 (Resource Indicator) 扩展以及如何配置。有些提供商可能会用“audience”、“API 资源 (API resource)”或“API indicator”等术语来指代同一概念。 - -配置好资源指示器 (Resource indicator) 后，你可以在 `bearerAuth` 中间件中指定它： - - - - -```python -bearer_auth = mcp_auth.bearer_auth_middleware( - "jwt", - audience="https://api.example.com/mcp", # JWT 期望的受众 (Audience) [!code highlight] - required_scopes=["read", "write"] -) -``` - - - - -```ts -const bearerAuth = mcpAuth.bearerAuth('jwt', { - audience: 'https://api.example.com/mcp', // JWT 期望的受众 (Audience) [!code highlight] - requiredScopes: ['read', 'write'], -}); -``` - - - - -在上面的示例中，MCP Auth 会同时校验 JWT 的 `aud` 声明 (Claim) 和所需的权限 (Scopes)。 - -### 为 JWT 校验提供自定义选项 \{#provide-custom-options-to-the-jwt-verification} - -你还可以为底层的 JWT 校验库提供自定义选项： - - - - -在 Python SDK 中，我们使用 [PyJWT](https://pyjwt.readthedocs.io/en/stable/) 进行 JWT 校验。你可以使用以下选项： - -- `leeway`：在校验 JWT 过期时间时允许一定的宽限时间（秒）。默认是 60 秒。 - -```python -bearer_auth = mcp_auth.bearer_auth_middleware( - "jwt", - audience="https://api.example.com/mcp", - required_scopes=["read", "write"] - leeway=10, # 允许 10 秒的宽限时间以减少时钟偏差 [!code highlight] -) -``` - - - - -在 Node.js SDK 中，我们使用 [jose](https://github.com/panva/jose) 库进行 JWT 校验。你可以提供以下选项： - -- `jwtVerify`：JWT 校验过程的选项（`jose` 的 `jwtVerify` 函数）。 -- `remoteJwtSet`：获取远程 JWT 集合的选项（`jose` 的 `createRemoteJWKSet` 函数）。 - -```ts {4-9} -const bearerAuth = mcpAuth.bearerAuth('jwt', { - audience: 'https://api.example.com/mcp', - requiredScopes: ['read', 'write'], - jwtVerify: { - clockTolerance: 60, // 允许 60 秒的时钟偏差 - }, - remoteJwtSet: { - timeoutDuration: 10 * 1000, // 远程 JWT 集合获取超时时间为 10 秒 - }, -}); -``` - - - - -## 使用自定义校验配置 Bearer 认证 (Authentication) \{#configure-bearer-auth-with-custom-verification} - -如果你的 OAuth / OIDC 提供商不签发 JWT，或者你想实现自己的授权 (Authorization) 逻辑，MCP Auth 允许你创建自定义校验函数： - -:::info -由于 Bearer 认证 (Authentication) 中间件会根据发行者 (Issuer)（`iss`）、受众 (Audience)（`aud`）和所需权限 (Scopes)（`scope`）与给定的校验结果进行检查，因此你无需在自定义校验函数中实现这些检查。你只需专注于校验令牌的有效性（如签名、过期等）并返回认证 (Authentication) 信息对象即可。 -::: - - - - -```python -from mcpauth.exceptions import MCPAuthJwtVerificationException, MCPAuthJwtVerificationExceptionCode -from mcpauth.types import AuthInfo - -async def custom_verification(token: str) -> AuthInfo: - # 在这里实现你的自定义校验逻辑 - info = await verify_token(token) - if not info: - raise MCPAuthJwtVerificationException( - MCPAuthJwtVerificationExceptionCode.JWT_VERIFICATION_FAILED - ) - return info # 返回认证 (Authentication) 信息对象 - -bearer_auth = mcp_auth.bearer_auth_middleware( - custom_verification, - required_scopes=["read", "write"] -) -``` - - - - -```ts -const bearerAuth = mcpAuth.bearerAuth( - async (token) => { - // 在这里实现你的自定义校验逻辑 - const info = await verifyToken(token); - if (!info) { - throw new MCPAuthJwtVerificationError('jwt_verification_failed'); - } - return info; // 返回认证 (Authentication) 信息对象 - }, - { requiredScopes: ['read', 'write'] } -); -``` - - - - -## 在 MCP 服务器中应用 Bearer 认证 (Authentication) \{#apply-bearer-auth-in-your-mcp-server} - -要用 Bearer 认证 (Authentication) 保护你的 MCP 服务器，你需要将 Bearer 认证 (Authentication) 中间件应用到 MCP 服务器实例上。 - - - - -```python -bearer_auth = mcp_auth.bearer_auth_middleware("jwt", required_scopes=["read", "write"]) -app = Starlette( - routes=[Mount('/', app=mcp.sse_app(), middleware=[Middleware(bearer_auth)])] -) -``` - - - - -```js -const app = express(); -app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] })); -``` - - - - -这样可以确保所有传入请求都根据配置的 Bearer 认证 (Authentication) 设置进行认证 (Authentication) 和授权 (Authorization)，并且认证 (Authentication) 信息会在请求上下文中可用。 - -你可以在 MCP 服务器实现中访问这些信息： - - - - -```python -@mcp.tool() -async def whoami() -> dict: - # `mcp_auth.auth_info` 是当前请求的上下文对象 - auth_info = mcp_auth.auth_info - print(f"Authenticated user: {auth_info.subject}") - return {"subject": auth_info.subject} -``` - - - - -```js -// `authInfo` 会从 `req.auth` 对象中传递过来 -server.tool('whoami', ({ authInfo }) => { - console.log(`Authenticated user: ${authInfo.subject}`); - return { subject: authInfo.subject }; -}); -``` - - - diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/configure-server/mcp-auth.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/configure-server/mcp-auth.mdx deleted file mode 100644 index abeb395..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/configure-server/mcp-auth.mdx +++ /dev/null @@ -1,208 +0,0 @@ ---- -sidebar_position: 1 -sidebar_label: MCP Auth ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -# 在 MCP 服务器中配置 MCP Auth - -要将你的 MCP 服务器连接到 OAuth 2.1 或 OpenID Connect 提供商，你需要配置 MCP Auth 实例。这包括使用你的提供商授权服务器元数据初始化实例，并设置必要的授权 (Authorization) 流程。 - -## 初始化 MCP Auth \{#init-mcp-auth} - -### 自动获取元数据 \{#automatic-metadata-fetching} - -初始化 MCP Auth 实例最简单的方法是使用内置函数，从 well-known URL 获取元数据。如果你的提供商符合以下标准之一： - -- [OAuth 2.0 授权服务器元数据](https://datatracker.ietf.org/doc/html/rfc8414) -- [OpenID Connect 发现](https://openid.net/specs/openid-connect-discovery-1_0.html) - -你可以使用 `fetchServerConfig`，通过提供 `issuer` URL 自动获取元数据： - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType, fetch_server_config - -mcp_auth = MCPAuth( - server=fetch_server_config( - '', - type=AuthServerType.OIDC # 或 AuthServerType.OAUTH - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { type: 'oidc' }), // 或 'oauth' -}); -``` - - - - -如果你的 issuer 包含路径，OAuth 2.0 和 OpenID Connect 的行为略有不同： - -- **OAuth 2.0**：well-known URL 会追加到 issuer 的**域名**后。例如，如果你的 issuer 是 `https://my-project.logto.app/oauth`，well-known URL 会是 `https://auth.logto.io/.well-known/oauth-authorization-server/oauth`。 -- **OpenID Connect**：well-known URL 会直接追加到**issuer**后。例如，如果你的 issuer 是 `https://my-project.logto.app/oidc`，well-known URL 会是 `https://auth.logto.io/oidc/.well-known/openid-configuration`。 - -### 其他初始化 MCP Auth 的方式 \{#other-ways} - -#### 自定义数据转换 \{#custom-data-transpilation} - -在某些情况下，提供商返回的元数据可能不符合预期格式。如果你确定提供商是兼容的，可以使用 `transpile_data` 选项，在使用前修改元数据： - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -mcp_auth = MCPAuth( - server=fetch_server_config( - '', - type=AuthServerType.OIDC, - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { - type: 'oidc', - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - - -这样你可以在 MCP Auth 使用元数据对象之前进行修改。例如，你可以添加或移除字段、修改字段值，或转换为不同格式。 - -#### 从指定 URL 获取元数据 \{#fetch-metadata-from-a-specific-url} - -如果你的提供商有特定的元数据 URL，而不是标准的 URL，也可以类似使用： - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config_by_well_known_url - -mcp_auth = MCPAuth( - server=fetch_server_config_by_well_known_url( - '', - type=AuthServerType.OIDC # 或 AuthServerType.OAUTH - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfigByWellKnownUrl } from 'mcp-auth'; - -const mcpAuth = new MCPAuth({ - server: await fetchServerConfigByWellKnownUrl('', { type: 'oidc' }), // 或 'oauth' -}); -``` - - - - -#### 从指定 URL 获取元数据并自定义数据转换 \{#fetch-metadata-from-a-specific-url-with-custom-data-transpilation} - -在某些情况下，提供商响应可能格式不正确或不符合预期元数据格式。如果你确定提供商是兼容的，可以通过配置项转换元数据： - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType, fetch_server_config_by_well_known_url - -mcp_auth = MCPAuth( - server=fetch_server_config_by_well_known_url( - '', - type=AuthServerType.OIDC, - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: await fetchServerConfigByWellKnownUrl('', { - type: 'oidc', - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - - -#### 手动提供元数据 \{#manually-provide-metadata} - -如果你的提供商不支持元数据获取，你可以手动提供元数据对象： - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerConfig, AuthServerType, AuthorizationServerMetadata - -mcp_auth = MCPAuth( - server=AuthServerConfig( - type=AuthServerType.OIDC, # 或 AuthServerType.OAUTH - metadata=AuthorizationServerMetadata( - issuer='', - authorization_endpoint='', - # ... 其他元数据字段 - ), - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: { - metadata: { - issuer: '', - // 元数据字段应为 camelCase - authorizationEndpoint: '', - // ... 其他元数据字段 - }, - type: 'oidc', // 或 'oauth' - }, -}); -``` - - - diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/README.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/README.md deleted file mode 100644 index 2b61a4f..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/README.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -sidebar_label: Node.js SDK ---- - -# MCP Auth Node.js SDK 参考 - -## 类 {#classes} - -- [MCPAuth](/references/js/classes/MCPAuth.md) -- [MCPAuthAuthServerError](/references/js/classes/MCPAuthAuthServerError.md) -- [MCPAuthBearerAuthError](/references/js/classes/MCPAuthBearerAuthError.md) -- [MCPAuthConfigError](/references/js/classes/MCPAuthConfigError.md) -- [MCPAuthError](/references/js/classes/MCPAuthError.md) -- [MCPAuthTokenVerificationError](/references/js/classes/MCPAuthTokenVerificationError.md) - -## 类型别名 {#type-aliases} - -- [AuthorizationServerMetadata](/references/js/type-aliases/AuthorizationServerMetadata.md) -- [AuthServerConfig](/references/js/type-aliases/AuthServerConfig.md) -- [AuthServerConfigError](/references/js/type-aliases/AuthServerConfigError.md) -- [AuthServerConfigErrorCode](/references/js/type-aliases/AuthServerConfigErrorCode.md) -- [AuthServerConfigWarning](/references/js/type-aliases/AuthServerConfigWarning.md) -- [AuthServerConfigWarningCode](/references/js/type-aliases/AuthServerConfigWarningCode.md) -- [AuthServerErrorCode](/references/js/type-aliases/AuthServerErrorCode.md) -- [AuthServerSuccessCode](/references/js/type-aliases/AuthServerSuccessCode.md) -- [AuthServerType](/references/js/type-aliases/AuthServerType.md) -- [BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) -- [BearerAuthErrorCode](/references/js/type-aliases/BearerAuthErrorCode.md) -- [BearerAuthJwtConfig](/references/js/type-aliases/BearerAuthJwtConfig.md) -- [CamelCaseAuthorizationServerMetadata](/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md) -- [MCPAuthBearerAuthErrorDetails](/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md) -- [MCPAuthConfig](/references/js/type-aliases/MCPAuthConfig.md) -- [MCPAuthTokenVerificationErrorCode](/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md) -- [VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) -- [VerifyAccessTokenMode](/references/js/type-aliases/VerifyAccessTokenMode.md) - -## 变量 {#variables} - -- [authorizationServerMetadataSchema](/references/js/variables/authorizationServerMetadataSchema.md) -- [authServerErrorDescription](/references/js/variables/authServerErrorDescription.md) -- [bearerAuthErrorDescription](/references/js/variables/bearerAuthErrorDescription.md) -- [camelCaseAuthorizationServerMetadataSchema](/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md) -- [serverMetadataPaths](/references/js/variables/serverMetadataPaths.md) -- [tokenVerificationErrorDescription](/references/js/variables/tokenVerificationErrorDescription.md) -- [validateServerConfig](/references/js/variables/validateServerConfig.md) - -## 函数 {#functions} - -- [createVerifyJwt](/references/js/functions/createVerifyJwt.md) -- [fetchServerConfig](/references/js/functions/fetchServerConfig.md) -- [fetchServerConfigByWellKnownUrl](/references/js/functions/fetchServerConfigByWellKnownUrl.md) -- [handleBearerAuth](/references/js/functions/handleBearerAuth.md) diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuth.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuth.md deleted file mode 100644 index 718599d..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuth.md +++ /dev/null @@ -1,196 +0,0 @@ ---- -sidebar_label: MCPAuth ---- - -# 类：MCPAuth - -mcp-auth 库的主类，提供在 MCP 服务器中创建路由器以及用于认证 (Authentication) 和授权 (Authorization) 的实用处理器的方法。 - -## 参见 {#see} - -更多关于该库及其用法的信息，请参见 [MCP Auth](https://mcp-auth.dev)。 - -## 示例 {#example} - -与远程 OIDC 提供方集成的示例： - -```ts -import express from 'express'; -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const app = express(); -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig( - 'https://auth.logto.io/oidc', - { type: 'oidc' } - ), -}); - -// 挂载路由以处理 OAuth 2.0 授权 (Authorization) 服务器元数据 -app.use(mcpAuth.delegatedRouter()); - -// 在 MCP 路由中使用 Bearer 认证 (Authentication) 处理器 -app.get( - '/mcp', - mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }), - (req, res) => { - console.log('Auth info:', req.auth); - // 在这里处理 MCP 请求 - }, -); - -// 在 MCP 回调中使用认证 (Authentication) 信息 -server.tool( - 'add', - { a: z.number(), b: z.number() }, - async ({ a, b }, { authInfo }) => { - console.log('Auth Info:', authInfo); - // ... - }, -); -``` - -## 构造函数 {#constructors} - -### 构造函数 {#constructor} - -```ts -new MCPAuth(config: MCPAuthConfig): MCPAuth; -``` - -#### 参数 {#parameters} - -##### config {#config} - -[`MCPAuthConfig`](/references/js/type-aliases/MCPAuthConfig.md) - -#### 返回值 {#returns} - -`MCPAuth` - -## 属性 {#properties} - -### config {#config} - -```ts -readonly config: MCPAuthConfig; -``` - -## 方法 {#methods} - -### bearerAuth() {#bearerauth} - -#### 调用签名 {#call-signature} - -```ts -bearerAuth(verifyAccessToken: VerifyAccessTokenFunction, config?: Omit): RequestHandler; -``` - -创建一个 Bearer 认证 (Authentication) 处理器（Express 中间件），用于验证请求的 `Authorization` 头中的访问令牌 (Access token)。 - -##### 参数 {#parameters} - -###### verifyAccessToken {#verifyaccesstoken} - -[`VerifyAccessTokenFunction`](/references/js/type-aliases/VerifyAccessTokenFunction.md) - -一个用于验证访问令牌 (Access token) 的函数。它应接受访问令牌 (Access token) 字符串，并返回一个 promise（或值），解析为验证结果。 - -**参见** - -[VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) 以获取 `verifyAccessToken` 函数的类型定义。 - -###### config? {#config} - -`Omit`\<[`BearerAuthConfig`](/references/js/type-aliases/BearerAuthConfig.md), `"verifyAccessToken"` \| `"issuer"`\> - -Bearer 认证 (Authentication) 处理器的可选配置。 - -**参见** - -[BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) 以获取可用的配置选项（不包括 `verifyAccessToken` 和 `issuer`）。 - -##### 返回值 {#returns} - -`RequestHandler` - -一个 Express 中间件函数，用于验证访问令牌 (Access token) 并将验证结果添加到请求对象（`req.auth`）。 - -##### 参见 {#see} - -[handleBearerAuth](/references/js/functions/handleBearerAuth.md) 以了解实现细节以及 `req.auth`（`AuthInfo`）对象的扩展类型。 - -#### 调用签名 {#call-signature} - -```ts -bearerAuth(mode: "jwt", config?: Omit & BearerAuthJwtConfig): RequestHandler; -``` - -创建一个 Bearer 认证 (Authentication) 处理器（Express 中间件），使用预定义的验证模式，验证请求的 `Authorization` 头中的访问令牌 (Access token)。 - -在 `'jwt'` 模式下，处理器将使用授权 (Authorization) 服务器的 JWKS URI 创建 JWT 验证函数。 - -##### 参数 {#parameters} - -###### mode {#mode} - -`"jwt"` - -访问令牌 (Access token) 的验证模式。目前仅支持 'jwt'。 - -**参见** - -[VerifyAccessTokenMode](/references/js/type-aliases/VerifyAccessTokenMode.md) 以获取可用模式。 - -###### config? {#config} - -`Omit`\<[`BearerAuthConfig`](/references/js/type-aliases/BearerAuthConfig.md), `"verifyAccessToken"` \| `"issuer"`\> & [`BearerAuthJwtConfig`](/references/js/type-aliases/BearerAuthJwtConfig.md) - -Bearer 认证 (Authentication) 处理器的可选配置，包括 JWT 验证选项和远程 JWK 集选项。 - -**参见** - - - [BearerAuthJwtConfig](/references/js/type-aliases/BearerAuthJwtConfig.md) 以获取 JWT 验证的可用配置选项。 - - [BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) 以获取可用的配置选项（不包括 `verifyAccessToken` 和 `issuer`）。 - -##### 返回值 {#returns} - -`RequestHandler` - -一个 Express 中间件函数，用于验证访问令牌 (Access token) 并将验证结果添加到请求对象（`req.auth`）。 - -##### 参见 {#see} - -[handleBearerAuth](/references/js/functions/handleBearerAuth.md) 以了解实现细节以及 `req.auth`（`AuthInfo`）对象的扩展类型。 - -##### 抛出异常 {#throws} - -当在 `'jwt'` 模式下，服务器元数据中未提供 JWKS URI 时会抛出异常。 - -*** - -### delegatedRouter() {#delegatedrouter} - -```ts -delegatedRouter(): Router; -``` - -创建一个委托路由器，服务于 OAuth 2.0 授权 (Authorization) 服务器元数据端点 -(`/.well-known/oauth-authorization-server`)，并使用实例提供的元数据。 - -#### 返回值 {#returns} - -`Router` - -一个路由器，服务于 OAuth 2.0 授权 (Authorization) 服务器元数据端点，并使用实例提供的元数据。 - -#### 示例 {#example} - -```ts -import express from 'express'; -import { MCPAuth } from 'mcp-auth'; - -const app = express(); -const mcpAuth: MCPAuth; // 假设已初始化 -app.use(mcpAuth.delegatedRouter()); -``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthAuthServerError.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthAuthServerError.md deleted file mode 100644 index 27b1c90..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthAuthServerError.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -sidebar_label: MCPAuthAuthServerError ---- - -# 类：MCPAuthAuthServerError - -当远程授权 (Authorization) 服务器出现问题时抛出的错误。 - -## 继承自 {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## 构造函数 {#constructors} - -### 构造函数 {#constructor} - -```ts -new MCPAuthAuthServerError(code: AuthServerErrorCode, cause?: unknown): MCPAuthAuthServerError; -``` - -#### 参数 {#parameters} - -##### code {#code} - -[`AuthServerErrorCode`](/references/js/type-aliases/AuthServerErrorCode.md) - -##### cause? {#cause} - -`unknown` - -#### 返回值 {#returns} - -`MCPAuthAuthServerError` - -#### 重写自 {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## 属性 {#properties} - -### cause? {#cause} - -```ts -readonly optional cause: unknown; -``` - -#### 继承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: AuthServerErrorCode; -``` - -错误代码，采用 snake_case 格式。 - -#### 继承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### 继承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthAuthServerError'; -``` - -#### 重写自 {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### 继承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -可选的堆栈跟踪格式化重写 - -#### 参数 {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### 返回值 {#returns} - -`any` - -#### 参见 {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### 继承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### 继承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## 方法 {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -将错误转换为适合 HTTP 响应的 JSON 格式。 - -#### 参数 {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -是否在 JSON 响应中包含错误原因。 -默认为 `false`。 - -#### 返回值 {#returns} - -`Record`\<`string`, `unknown`\> - -#### 继承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -在目标对象上创建 .stack 属性 - -#### 参数 {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### 返回值 {#returns} - -`void` - -#### 继承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthBearerAuthError.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthBearerAuthError.md deleted file mode 100644 index 8b3507c..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthBearerAuthError.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -sidebar_label: MCPAuthBearerAuthError ---- - -# 类：MCPAuthBearerAuthError - -当使用 Bearer 令牌进行认证 (Authentication) 时出现问题时抛出的错误。 - -## 继承关系 {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## 构造函数 {#constructors} - -### 构造函数 {#constructor} - -```ts -new MCPAuthBearerAuthError(code: BearerAuthErrorCode, cause?: MCPAuthBearerAuthErrorDetails): MCPAuthBearerAuthError; -``` - -#### 参数 {#parameters} - -##### code {#code} - -[`BearerAuthErrorCode`](/references/js/type-aliases/BearerAuthErrorCode.md) - -##### cause? {#cause} - -[`MCPAuthBearerAuthErrorDetails`](/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md) - -#### 返回值 {#returns} - -`MCPAuthBearerAuthError` - -#### 重写自 {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## 属性 {#properties} - -### cause? {#cause} - -```ts -readonly optional cause: MCPAuthBearerAuthErrorDetails; -``` - -#### 继承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: BearerAuthErrorCode; -``` - -错误码，采用 snake_case 格式。 - -#### 继承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### 继承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthBearerAuthError'; -``` - -#### 重写自 {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### 继承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -可选的堆栈跟踪格式化重写方法 - -#### 参数 {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### 返回值 {#returns} - -`any` - -#### 参见 {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### 继承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### 继承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## 方法 {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -将错误转换为适合 HTTP 响应的 JSON 格式。 - -#### 参数 {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -是否在 JSON 响应中包含错误原因。 -默认为 `false`。 - -#### 返回值 {#returns} - -`Record`\<`string`, `unknown`\> - -#### 重写自 {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -在目标对象上创建 .stack 属性 - -#### 参数 {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### 返回值 {#returns} - -`void` - -#### 继承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthConfigError.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthConfigError.md deleted file mode 100644 index 6e6170a..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthConfigError.md +++ /dev/null @@ -1,202 +0,0 @@ ---- -sidebar_label: MCPAuthConfigError ---- - -# 类：MCPAuthConfigError - -当 mcp-auth 配置出现问题时抛出的错误。 - -## 继承关系 {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## 构造函数 {#constructors} - -### 构造函数 {#constructor} - -```ts -new MCPAuthConfigError(code: string, message: string): MCPAuthConfigError; -``` - -#### 参数 {#parameters} - -##### code {#code} - -`string` - -以 snake_case 格式表示的错误代码。 - -##### message {#message} - -`string` - -对错误的人类可读描述。 - -#### 返回值 {#returns} - -`MCPAuthConfigError` - -#### 继承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## 属性 {#properties} - -### cause? {#cause} - -```ts -optional cause: unknown; -``` - -#### 继承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: string; -``` - -以 snake_case 格式表示的错误代码。 - -#### 继承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### 继承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthConfigError'; -``` - -#### 重写自 {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### 继承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -可选的堆栈跟踪格式化重写 - -#### 参数 {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### 返回值 {#returns} - -`any` - -#### 参见 {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### 继承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### 继承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## 方法 {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -将错误转换为适合 HTTP 响应的 JSON 格式。 - -#### 参数 {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -是否在 JSON 响应中包含错误原因。 -默认为 `false`。 - -#### 返回值 {#returns} - -`Record`\<`string`, `unknown`\> - -#### 继承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -在目标对象上创建 .stack 属性 - -#### 参数 {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### 返回值 {#returns} - -`void` - -#### 继承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthError.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthError.md deleted file mode 100644 index 7e6746c..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthError.md +++ /dev/null @@ -1,219 +0,0 @@ ---- -sidebar_label: MCPAuthError ---- - -# 类：MCPAuthError - -所有 mcp-auth 错误的基类。 - -它为处理与 MCP 认证 (Authentication) 和授权 (Authorization) 相关的错误提供了标准化方式。 - -## 继承自 {#extends} - -- `Error` - -## 被继承 {#extended-by} - -- [`MCPAuthConfigError`](/references/js/classes/MCPAuthConfigError.md) -- [`MCPAuthAuthServerError`](/references/js/classes/MCPAuthAuthServerError.md) -- [`MCPAuthBearerAuthError`](/references/js/classes/MCPAuthBearerAuthError.md) -- [`MCPAuthTokenVerificationError`](/references/js/classes/MCPAuthTokenVerificationError.md) - -## 构造函数 {#constructors} - -### 构造函数 {#constructor} - -```ts -new MCPAuthError(code: string, message: string): MCPAuthError; -``` - -#### 参数 {#parameters} - -##### code {#code} - -`string` - -错误代码，使用 snake_case 格式。 - -##### message {#message} - -`string` - -对错误的人类可读描述。 - -#### 返回值 {#returns} - -`MCPAuthError` - -#### 重写自 {#overrides} - -```ts -Error.constructor -``` - -## 属性 {#properties} - -### cause? {#cause} - -```ts -optional cause: unknown; -``` - -#### 继承自 {#inherited-from} - -```ts -Error.cause -``` - -*** - -### code {#code} - -```ts -readonly code: string; -``` - -错误代码，使用 snake_case 格式。 - -*** - -### message {#message} - -```ts -message: string; -``` - -#### 继承自 {#inherited-from} - -```ts -Error.message -``` - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthError'; -``` - -#### 重写自 {#overrides} - -```ts -Error.name -``` - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### 继承自 {#inherited-from} - -```ts -Error.stack -``` - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -可选的堆栈跟踪格式化重写 - -#### 参数 {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### 返回值 {#returns} - -`any` - -#### 参见 {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### 继承自 {#inherited-from} - -```ts -Error.prepareStackTrace -``` - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### 继承自 {#inherited-from} - -```ts -Error.stackTraceLimit -``` - -## 方法 {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -将错误转换为适合 HTTP 响应的 JSON 格式。 - -#### 参数 {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -是否在 JSON 响应中包含错误原因。 -默认为 `false`。 - -#### 返回值 {#returns} - -`Record`\<`string`, `unknown`\> - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -在目标对象上创建 .stack 属性 - -#### 参数 {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### 返回值 {#returns} - -`void` - -#### 继承自 {#inherited-from} - -```ts -Error.captureStackTrace -``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthTokenVerificationError.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthTokenVerificationError.md deleted file mode 100644 index f1be2f7..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthTokenVerificationError.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -sidebar_label: MCPAuthTokenVerificationError ---- - -# 类：MCPAuthTokenVerificationError - -在验证令牌时出现问题时抛出的错误。 - -## 继承自 {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## 构造函数 {#constructors} - -### 构造函数 {#constructor} - -```ts -new MCPAuthTokenVerificationError(code: MCPAuthTokenVerificationErrorCode, cause?: unknown): MCPAuthTokenVerificationError; -``` - -#### 参数 {#parameters} - -##### code {#code} - -[`MCPAuthTokenVerificationErrorCode`](/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md) - -##### cause? {#cause} - -`unknown` - -#### 返回值 {#returns} - -`MCPAuthTokenVerificationError` - -#### 重写自 {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## 属性 {#properties} - -### cause? {#cause} - -```ts -readonly optional cause: unknown; -``` - -#### 继承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: MCPAuthTokenVerificationErrorCode; -``` - -以 snake_case 格式表示的错误代码。 - -#### 继承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### 继承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthTokenVerificationError'; -``` - -#### 重写自 {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### 继承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -可选的堆栈跟踪格式化重写 - -#### 参数 {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### 返回值 {#returns} - -`any` - -#### 参考 {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### 继承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### 继承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## 方法 {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -将错误转换为适合 HTTP 响应的 JSON 格式。 - -#### 参数 {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -是否在 JSON 响应中包含错误原因。 -默认为 `false`。 - -#### 返回值 {#returns} - -`Record`\<`string`, `unknown`\> - -#### 继承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -在目标对象上创建 .stack 属性 - -#### 参数 {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### 返回值 {#returns} - -`void` - -#### 继承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/createVerifyJwt.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/createVerifyJwt.md deleted file mode 100644 index b3c3169..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/createVerifyJwt.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -sidebar_label: createVerifyJwt ---- - -# 函数：createVerifyJwt() - -```ts -function createVerifyJwt(getKey: JWTVerifyGetKey, options?: JWTVerifyOptions): VerifyAccessTokenFunction; -``` - -使用提供的密钥检索函数和选项，创建一个用于验证 JWT 访问令牌 (Access token) 的函数。 - -## 参数 {#parameters} - -### getKey {#getkey} - -`JWTVerifyGetKey` - -用于检索验证 JWT 所需密钥的函数。 - -**参见** - -JWTVerifyGetKey 以获取密钥检索函数的类型定义。 - -### options? {#options} - -`JWTVerifyOptions` - -可选的 JWT 验证选项。 - -**参见** - -JWTVerifyOptions 以获取选项的类型定义。 - -## 返回值 {#returns} - -[`VerifyAccessTokenFunction`](/references/js/type-aliases/VerifyAccessTokenFunction.md) - -一个用于验证 JWT 访问令牌 (Access token) 的函数，如果令牌有效，则返回一个 AuthInfo 对象。该函数要求 JWT 的 payload 中包含 `iss`、`client_id` 和 `sub` 字段，并且可以选择性地包含 `scope` 或 `scopes` 字段。该函数底层使用 `jose` 库来执行 JWT 验证。 - -## 参见 {#see} - -[VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) 以获取返回函数的类型定义。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfig.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfig.md deleted file mode 100644 index 5cf1460..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfig.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -sidebar_label: fetchServerConfig ---- - -# 函数：fetchServerConfig() - -```ts -function fetchServerConfig(issuer: string, config: ServerMetadataConfig): Promise; -``` - -根据发行者 (Issuer) 和授权 (Authorization) 服务器类型获取服务器配置。 - -此函数会根据服务器类型自动确定 well-known URL，因为 OAuth 和 OpenID Connect 服务器在其元数据端点上有不同的约定。 - -## 参数 {#parameters} - -### issuer {#issuer} - -`string` - -授权 (Authorization) 服务器的发行者 (Issuer) URL。 - -### config {#config} - -`ServerMetadataConfig` - -包含服务器类型和可选转译函数的配置对象。 - -## 返回值 {#returns} - -`Promise`\<[`AuthServerConfig`](/references/js/type-aliases/AuthServerConfig.md)\> - -一个解析为服务器配置的 Promise。 - -## 参见 {#see} - - - [fetchServerConfigByWellKnownUrl](/references/js/functions/fetchServerConfigByWellKnownUrl.md) 了解底层实现。 - - [https://www.rfc-editor.org/rfc/rfc8414](https://www.rfc-editor.org/rfc/rfc8414) 查看 OAuth 2.0 授权 (Authorization) 服务器元数据规范。 - - [https://openid.net/specs/openid-connect-discovery-1\_0.html](https://openid.net/specs/openid-connect-discovery-1_0.html) 查看 OpenID Connect 发现规范。 - -## 示例 {#example} - -```ts -import { fetchServerConfig } from 'mcp-auth'; -// 获取 OAuth 服务器配置 -// 这将从 `https://auth.logto.io/.well-known/oauth-authorization-server/oauth` 获取元数据 -const oauthConfig = await fetchServerConfig('https://auth.logto.io/oauth', { type: 'oauth' }); - -// 获取 OpenID Connect 服务器配置 -// 这将从 `https://auth.logto.io/oidc/.well-known/openid-configuration` 获取元数据 -const oidcConfig = await fetchServerConfig('https://auth.logto.io/oidc', { type: 'oidc' }); -``` - -## 抛出异常 {#throws} - -如果获取操作失败。 - -## 抛出异常 {#throws} - -如果服务器元数据无效或不符合 MCP 规范。 \ No newline at end of file diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfigByWellKnownUrl.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfigByWellKnownUrl.md deleted file mode 100644 index df22954..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfigByWellKnownUrl.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -sidebar_label: fetchServerConfigByWellKnownUrl ---- - -# 函数：fetchServerConfigByWellKnownUrl() - -```ts -function fetchServerConfigByWellKnownUrl(wellKnownUrl: string | URL, config: ServerMetadataConfig): Promise; -``` - -从提供的 well-known URL 获取服务器配置，并根据 MCP 规范进行校验。 - -如果服务器元数据不符合预期的 schema，但你确定它是兼容的，你可以定义一个 `transpileData` 函数，将元数据转换为预期格式。 - -## 参数 {#parameters} - -### wellKnownUrl {#wellknownurl} - -用于获取服务器配置的 well-known URL。可以是字符串或 URL 对象。 - -`string` | `URL` - -### config {#config} - -`ServerMetadataConfig` - -包含服务器类型和可选转换函数的配置对象。 - -## 返回值 {#returns} - -`Promise`\<[`AuthServerConfig`](/references/js/type-aliases/AuthServerConfig.md)\> - -一个解析为服务器配置的 promise。 - -## 抛出异常 {#throws} - -如果获取操作失败。 - -## 抛出异常 {#throws} - -如果服务器元数据无效或不符合 MCP 规范。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/handleBearerAuth.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/handleBearerAuth.md deleted file mode 100644 index 332833b..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/handleBearerAuth.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -sidebar_label: handleBearerAuth ---- - -# 函数：handleBearerAuth() - -```ts -function handleBearerAuth(param0: BearerAuthConfig): RequestHandler; -``` - -在 Express 应用中创建用于处理 Bearer 认证 (Authentication) 的中间件函数。 - -该中间件会从 `Authorization` 头中提取 Bearer 访问令牌 (Access token)，使用提供的 `verifyAccessToken` 函数进行验证，并检查发行者 (Issuer)、受众 (Audience) 和所需权限 (Scopes)。 - -- 如果令牌有效，会将认证 (Authentication) 信息添加到 `request.auth` 属性中； - 如果无效，则返回相应的错误信息。 -- 如果访问令牌 (Access token) 验证失败，则返回 401 未授权错误。 -- 如果令牌不包含所需的权限 (Scopes)，则返回 403 禁止访问错误。 -- 如果在认证 (Authentication) 过程中发生意外错误，中间件会重新抛出这些错误。 - -**注意：** `request.auth` 对象会包含比 `@modelcontextprotocol/sdk` 模块中定义的标准 AuthInfo 接口更多的扩展字段。详情请参见本文件中的扩展接口。 - -## 参数 {#parameters} - -### param0 {#param0} - -[`BearerAuthConfig`](/references/js/type-aliases/BearerAuthConfig.md) - -Bearer 认证 (Authentication) 处理器的配置。 - -## 返回值 {#returns} - -`RequestHandler` - -用于 Express 的 Bearer 认证 (Authentication) 中间件函数。 - -## 参见 {#see} - -[BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) 以了解配置选项。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfig.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfig.md deleted file mode 100644 index 3388fba..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfig.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -sidebar_label: AuthServerConfig ---- - -# 类型别名：AuthServerConfig - -```ts -type AuthServerConfig = { - metadata: CamelCaseAuthorizationServerMetadata; - type: AuthServerType; -}; -``` - -与 MCP 服务器集成的远程授权服务器 (Authorization Server) 配置。 - -## 属性 {#properties} - -### metadata {#metadata} - -```ts -metadata: CamelCaseAuthorizationServerMetadata; -``` - -授权服务器 (Authorization Server) 的元数据，需符合 MCP 规范 -（基于 OAuth 2.0 授权服务器元数据）。 - -此元数据通常从服务器的 well-known 端点（OAuth 2.0 授权服务器元数据或 OpenID Connect 发现）获取；如果服务器不支持这些端点，也可以直接在配置中提供。 - -**注意：** 元数据应为 camelCase 格式，这是 mcp-auth 库所推荐的。 - -#### 参见 {#see} - - - [OAuth 2.0 授权服务器元数据](https://datatracker.ietf.org/doc/html/rfc8414) - - [OpenID Connect 发现](https://openid.net/specs/openid-connect-discovery-1_0.html) - -*** - -### type {#type} - -```ts -type: AuthServerType; -``` - -授权服务器 (Authorization Server) 的类型。 - -#### 参见 {#see} - -[AuthServerType](/references/js/type-aliases/AuthServerType.md) 以获取可能的取值。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigError.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigError.md deleted file mode 100644 index f442d8f..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigError.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -sidebar_label: AuthServerConfigError ---- - -# 类型别名：AuthServerConfigError - -```ts -type AuthServerConfigError = { - cause?: Error; - code: AuthServerConfigErrorCode; - description: string; -}; -``` - -表示在验证授权服务器元数据时发生的错误。 - -## 属性 {#properties} - -### cause? {#cause} - -```ts -optional cause: Error; -``` - -错误的可选原因，通常是一个 `Error` 实例，用于提供更多上下文信息。 - -*** - -### code {#code} - -```ts -code: AuthServerConfigErrorCode; -``` - -表示具体验证错误的代码。 - -*** - -### description {#description} - -```ts -description: string; -``` - -对错误的人类可读描述。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigErrorCode.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigErrorCode.md deleted file mode 100644 index a5b9d02..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigErrorCode.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_label: AuthServerConfigErrorCode ---- - -# 类型别名：AuthServerConfigErrorCode - -```ts -type AuthServerConfigErrorCode = - | "invalid_server_metadata" - | "code_response_type_not_supported" - | "authorization_code_grant_not_supported" - | "pkce_not_supported" - | "s256_code_challenge_method_not_supported"; -``` - -在验证授权服务器元数据时可能出现的错误代码。 \ No newline at end of file diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarning.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarning.md deleted file mode 100644 index 656f510..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarning.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -sidebar_label: AuthServerConfigWarning ---- - -# 类型别名：AuthServerConfigWarning - -```ts -type AuthServerConfigWarning = { - code: AuthServerConfigWarningCode; - description: string; -}; -``` - -表示在验证授权服务器元数据时发生的警告。 - -## 属性 {#properties} - -### code {#code} - -```ts -code: AuthServerConfigWarningCode; -``` - -表示特定验证警告的代码。 - -*** - -### description {#description} - -```ts -description: string; -``` - -对警告的人类可读描述。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarningCode.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarningCode.md deleted file mode 100644 index 2f51a52..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarningCode.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -sidebar_label: AuthServerConfigWarningCode ---- - -# 类型别名：AuthServerConfigWarningCode - -```ts -type AuthServerConfigWarningCode = "dynamic_registration_not_supported"; -``` - -在验证授权服务器元数据时可能出现的警告代码。 \ No newline at end of file diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerErrorCode.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerErrorCode.md deleted file mode 100644 index f285c5a..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerErrorCode.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_label: AuthServerErrorCode ---- - -# 类型别名：AuthServerErrorCode - -```ts -type AuthServerErrorCode = - | "invalid_server_metadata" - | "invalid_server_config" - | "missing_jwks_uri"; -``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerSuccessCode.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerSuccessCode.md deleted file mode 100644 index 28f9ba1..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerSuccessCode.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -sidebar_label: AuthServerSuccessCode ---- - -# 类型别名：AuthServerSuccessCode - -```ts -type AuthServerSuccessCode = - | "server_metadata_valid" - | "dynamic_registration_supported" - | "pkce_supported" - | "s256_code_challenge_method_supported" - | "authorization_code_grant_supported" - | "code_response_type_supported"; -``` - -授权服务器元数据验证成功的代码。 \ No newline at end of file diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerType.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerType.md deleted file mode 100644 index 0e4748a..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerType.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -sidebar_label: AuthServerType ---- - -# 类型别名：AuthServerType - -```ts -type AuthServerType = "oauth" | "oidc"; -``` - -授权 (Authorization) 服务器的类型。此信息应由服务器配置提供，并指示该服务器是 OAuth 2.0 还是 OpenID Connect (OIDC) 授权 (Authorization) 服务器。 \ No newline at end of file diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthorizationServerMetadata.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthorizationServerMetadata.md deleted file mode 100644 index f2cae09..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthorizationServerMetadata.md +++ /dev/null @@ -1,220 +0,0 @@ ---- -sidebar_label: AuthorizationServerMetadata ---- - -# 类型别名：AuthorizationServerMetadata - -```ts -type AuthorizationServerMetadata = { - authorization_endpoint: string; - code_challenge_methods_supported?: string[]; - grant_types_supported?: string[]; - introspection_endpoint?: string; - introspection_endpoint_auth_methods_supported?: string[]; - introspection_endpoint_auth_signing_alg_values_supported?: string[]; - issuer: string; - jwks_uri?: string; - op_policy_uri?: string; - op_tos_uri?: string; - registration_endpoint?: string; - response_modes_supported?: string[]; - response_types_supported: string[]; - revocation_endpoint?: string; - revocation_endpoint_auth_methods_supported?: string[]; - revocation_endpoint_auth_signing_alg_values_supported?: string[]; - scope_supported?: string[]; - service_documentation?: string; - token_endpoint: string; - token_endpoint_auth_methods_supported?: string[]; - token_endpoint_auth_signing_alg_values_supported?: string[]; - ui_locales_supported?: string[]; - userinfo_endpoint?: string; -}; -``` - -OAuth 2.0 授权服务器元数据（Authorization Server Metadata）的模式，定义见 RFC 8414。 - -## 类型声明 {#type-declaration} - -### authorization\_endpoint {#authorization-endpoint} - -```ts -authorization_endpoint: string; -``` - -授权服务器的授权端点（authorization endpoint）的 URL [[RFC6749](https://rfc-editor.org/rfc/rfc6749)]。 -除非不支持任何使用授权端点的授权类型，否则这是必需的。 - -#### 参见 {#see} - -https://rfc-editor.org/rfc/rfc6749#section-3.1 - -### code\_challenge\_methods\_supported? {#code-challenge-methods-supported} - -```ts -optional code_challenge_methods_supported: string[]; -``` - -包含此授权服务器支持的 Proof Key for Code Exchange (PKCE) [[RFC7636](https://www.rfc-editor.org/rfc/rfc7636)] code challenge 方法列表的 JSON 数组。 - -### grant\_types\_supported? {#grant-types-supported} - -```ts -optional grant_types_supported: string[]; -``` - -包含此授权服务器支持的 OAuth 2.0 授权类型（grant type）值列表的 JSON 数组。数组中的值与 “OAuth 2.0 动态客户端注册协议” [[RFC7591](https://www.rfc-editor.org/rfc/rfc7591)] 中 `grant_types` 参数所用的值相同。 -如果省略，默认值为 `["authorization_code", "implicit"]`。 - -### introspection\_endpoint? {#introspection-endpoint} - -```ts -optional introspection_endpoint: string; -``` - -授权服务器的 OAuth 2.0 introspection 端点的 URL [[RFC7662](https://www.rfc-editor.org/rfc/rfc7662)]。 - -### introspection\_endpoint\_auth\_methods\_supported? {#introspection-endpoint-auth-methods-supported} - -```ts -optional introspection_endpoint_auth_methods_supported: string[]; -``` - -### introspection\_endpoint\_auth\_signing\_alg\_values\_supported? {#introspection-endpoint-auth-signing-alg-values-supported} - -```ts -optional introspection_endpoint_auth_signing_alg_values_supported: string[]; -``` - -### issuer {#issuer} - -```ts -issuer: string; -``` - -授权服务器的发行者（Issuer）标识符，是一个使用 `https` 协议且没有查询或片段部分的 URL。 - -### jwks\_uri? {#jwks-uri} - -```ts -optional jwks_uri: string; -``` - -授权服务器的 JWK Set [[JWK](https://www.rfc-editor.org/rfc/rfc8414.html#ref-JWK)] 文档的 URL。被引用的文档包含客户端用于验证授权服务器签名的密钥。此 URL 必须使用 `https` 协议。 - -### op\_policy\_uri? {#op-policy-uri} - -```ts -optional op_policy_uri: string; -``` - -### op\_tos\_uri? {#op-tos-uri} - -```ts -optional op_tos_uri: string; -``` - -### registration\_endpoint? {#registration-endpoint} - -```ts -optional registration_endpoint: string; -``` - -授权服务器的 OAuth 2.0 动态客户端注册端点的 URL [[RFC7591](https://www.rfc-editor.org/rfc/rfc7591)]。 - -### response\_modes\_supported? {#response-modes-supported} - -```ts -optional response_modes_supported: string[]; -``` - -包含此授权服务器支持的 OAuth 2.0 `response_mode` 值列表的 JSON 数组，详见 “OAuth 2.0 多响应类型编码实践” -[[OAuth.Responses](https://datatracker.ietf.org/doc/html/rfc8414#ref-OAuth.Responses)]。 - -如果省略，默认值为 `["query", "fragment"]`。响应模式值 `"form_post"` 也在 “OAuth 2.0 表单提交响应模式” -[[OAuth.FormPost](https://datatracker.ietf.org/doc/html/rfc8414#ref-OAuth.Post)] 中定义。 - -### response\_types\_supported {#response-types-supported} - -```ts -response_types_supported: string[]; -``` - -包含此授权服务器支持的 OAuth 2.0 `response_type` 值列表的 JSON 数组。数组中的值与 “OAuth 2.0 动态客户端注册协议” -[[RFC7591](https://www.rfc-editor.org/rfc/rfc7591)] 中 `response_types` 参数所用的值相同。 - -### revocation\_endpoint? {#revocation-endpoint} - -```ts -optional revocation_endpoint: string; -``` - -授权服务器的 OAuth 2.0 撤销端点（revocation endpoint）的 URL [[RFC7009](https://www.rfc-editor.org/rfc/rfc7009)]。 - -### revocation\_endpoint\_auth\_methods\_supported? {#revocation-endpoint-auth-methods-supported} - -```ts -optional revocation_endpoint_auth_methods_supported: string[]; -``` - -### revocation\_endpoint\_auth\_signing\_alg\_values\_supported? {#revocation-endpoint-auth-signing-alg-values-supported} - -```ts -optional revocation_endpoint_auth_signing_alg_values_supported: string[]; -``` - -### scope\_supported? {#scope-supported} - -```ts -optional scope_supported: string[]; -``` - -### service\_documentation? {#service-documentation} - -```ts -optional service_documentation: string; -``` - -### token\_endpoint {#token-endpoint} - -```ts -token_endpoint: string; -``` - -授权服务器的令牌端点（token endpoint）的 URL [[RFC6749](https://rfc-editor.org/rfc/rfc6749)]。 -除非只支持 implicit 授权类型，否则这是必需的。 - -#### 参见 {#see} - -https://rfc-editor.org/rfc/rfc6749#section-3.2 - -### token\_endpoint\_auth\_methods\_supported? {#token-endpoint-auth-methods-supported} - -```ts -optional token_endpoint_auth_methods_supported: string[]; -``` - -### token\_endpoint\_auth\_signing\_alg\_values\_supported? {#token-endpoint-auth-signing-alg-values-supported} - -```ts -optional token_endpoint_auth_signing_alg_values_supported: string[]; -``` - -### ui\_locales\_supported? {#ui-locales-supported} - -```ts -optional ui_locales_supported: string[]; -``` - -### userinfo\_endpoint? {#userinfo-endpoint} - -```ts -optional userinfo_endpoint: string; -``` - -OpenID Connect [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 的 URL。 -此端点用于获取已认证用户的信息。 - -## 参见 {#see} - -https://datatracker.ietf.org/doc/html/rfc8414 \ No newline at end of file diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthConfig.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthConfig.md deleted file mode 100644 index 45c5e1f..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthConfig.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -sidebar_label: BearerAuthConfig ---- - -# 类型别名：BearerAuthConfig - -```ts -type BearerAuthConfig = { - audience?: string; - issuer: string; - requiredScopes?: string[]; - showErrorDetails?: boolean; - verifyAccessToken: VerifyAccessTokenFunction; -}; -``` - -## 属性 {#properties} - -### audience? {#audience} - -```ts -optional audience: string; -``` - -访问令牌 (Access token)（`aud` 声明）的预期受众 (Audience)。这通常是该令牌所针对的资源服务器（API）。如果未提供，将跳过受众 (Audience) 检查。 - -**注意：** 如果你的授权 (Authorization) 服务器不支持资源指示器 (Resource Indicators)（RFC 8707），你可以省略此字段，因为受众 (Audience) 可能不相关。 - -#### 参见 {#see} - -https://datatracker.ietf.org/doc/html/rfc8707 - -*** - -### issuer {#issuer} - -```ts -issuer: string; -``` - -访问令牌 (Access token)（`iss` 声明）的预期发行者 (Issuer)。这应为颁发该令牌的授权 (Authorization) 服务器的 URL。 - -*** - -### requiredScopes? {#requiredscopes} - -```ts -optional requiredScopes: string[]; -``` - -访问令牌 (Access token) 必须包含的权限 (Scopes) 数组。如果令牌未包含所有这些权限 (Scopes)，将抛出错误。 - -**注意：** 处理器将检查令牌中的 `scope` 声明，该声明可能是以空格分隔的字符串，也可能是字符串数组，具体取决于授权 (Authorization) 服务器的实现。如果 `scope` 声明不存在，处理器将检查 `scopes` 声明（如果可用）。 - -*** - -### showErrorDetails? {#showerrordetails} - -```ts -optional showErrorDetails: boolean; -``` - -是否在响应中显示详细的错误信息。这对于开发期间调试很有用，但在生产环境中应禁用，以避免泄露敏感信息。 - -#### 默认值 {#default} - -```ts -false -``` - -*** - -### verifyAccessToken {#verifyaccesstoken} - -```ts -verifyAccessToken: VerifyAccessTokenFunction; -``` - -用于验证访问令牌 (Access token) 的函数类型。 - -如果令牌无效，此函数应抛出 [MCPAuthTokenVerificationError](/references/js/classes/MCPAuthTokenVerificationError.md)；如果令牌有效，则返回 AuthInfo 对象。 - -#### 参见 {#see} - -[VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) 获取更多详情。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthErrorCode.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthErrorCode.md deleted file mode 100644 index becf5bb..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthErrorCode.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_label: BearerAuthErrorCode ---- - -# 类型别名：BearerAuthErrorCode - -```ts -type BearerAuthErrorCode = - | "missing_auth_header" - | "invalid_auth_header_format" - | "missing_bearer_token" - | "invalid_issuer" - | "invalid_audience" - | "missing_required_scopes" - | "invalid_token"; -``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthJwtConfig.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthJwtConfig.md deleted file mode 100644 index 8e1f350..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthJwtConfig.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -sidebar_label: BearerAuthJwtConfig ---- - -# 类型别名：BearerAuthJwtConfig - -```ts -type BearerAuthJwtConfig = { - jwtVerify?: JWTVerifyOptions; - remoteJwkSet?: RemoteJWKSetOptions; -}; -``` - -用于 JWT 验证时 Bearer 认证 (Authentication) 处理器的配置。 - -## 属性 {#properties} - -### jwtVerify? {#jwtverify} - -```ts -optional jwtVerify: JWTVerifyOptions; -``` - -传递给 `jose` 库的 `jwtVerify` 函数的选项。 - -#### 参见 {#see} - -JWTVerifyOptions，用于选项的类型定义。 - -*** - -### remoteJwkSet? {#remotejwkset} - -```ts -optional remoteJwkSet: RemoteJWKSetOptions; -``` - -传递给 `jose` 库的 `createRemoteJWKSet` 函数的选项。 - -#### 参见 {#see} - -RemoteJWKSetOptions，用于选项的类型定义。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md deleted file mode 100644 index 20be0be..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -sidebar_label: CamelCaseAuthorizationServerMetadata ---- - -# 类型别名：CamelCaseAuthorizationServerMetadata - -```ts -type CamelCaseAuthorizationServerMetadata = { - authorizationEndpoint: string; - codeChallengeMethodsSupported?: string[]; - grantTypesSupported?: string[]; - introspectionEndpoint?: string; - introspectionEndpointAuthMethodsSupported?: string[]; - introspectionEndpointAuthSigningAlgValuesSupported?: string[]; - issuer: string; - jwksUri?: string; - opPolicyUri?: string; - opTosUri?: string; - registrationEndpoint?: string; - responseModesSupported?: string[]; - responseTypesSupported: string[]; - revocationEndpoint?: string; - revocationEndpointAuthMethodsSupported?: string[]; - revocationEndpointAuthSigningAlgValuesSupported?: string[]; - scopeSupported?: string[]; - serviceDocumentation?: string; - tokenEndpoint: string; - tokenEndpointAuthMethodsSupported?: string[]; - tokenEndpointAuthSigningAlgValuesSupported?: string[]; - uiLocalesSupported?: string[]; - userinfoEndpoint?: string; -}; -``` - -OAuth 2.0 Authorization Server Metadata 类型的驼峰命名版本。 - -## 类型声明 {#type-declaration} - -### authorizationEndpoint {#authorizationendpoint} - -```ts -authorizationEndpoint: string; -``` - -### codeChallengeMethodsSupported? {#codechallengemethodssupported} - -```ts -optional codeChallengeMethodsSupported: string[]; -``` - -### grantTypesSupported? {#granttypessupported} - -```ts -optional grantTypesSupported: string[]; -``` - -### introspectionEndpoint? {#introspectionendpoint} - -```ts -optional introspectionEndpoint: string; -``` - -### introspectionEndpointAuthMethodsSupported? {#introspectionendpointauthmethodssupported} - -```ts -optional introspectionEndpointAuthMethodsSupported: string[]; -``` - -### introspectionEndpointAuthSigningAlgValuesSupported? {#introspectionendpointauthsigningalgvaluessupported} - -```ts -optional introspectionEndpointAuthSigningAlgValuesSupported: string[]; -``` - -### issuer {#issuer} - -```ts -issuer: string; -``` - -### jwksUri? {#jwksuri} - -```ts -optional jwksUri: string; -``` - -### opPolicyUri? {#oppolicyuri} - -```ts -optional opPolicyUri: string; -``` - -### opTosUri? {#optosuri} - -```ts -optional opTosUri: string; -``` - -### registrationEndpoint? {#registrationendpoint} - -```ts -optional registrationEndpoint: string; -``` - -### responseModesSupported? {#responsemodessupported} - -```ts -optional responseModesSupported: string[]; -``` - -### responseTypesSupported {#responsetypessupported} - -```ts -responseTypesSupported: string[]; -``` - -### revocationEndpoint? {#revocationendpoint} - -```ts -optional revocationEndpoint: string; -``` - -### revocationEndpointAuthMethodsSupported? {#revocationendpointauthmethodssupported} - -```ts -optional revocationEndpointAuthMethodsSupported: string[]; -``` - -### revocationEndpointAuthSigningAlgValuesSupported? {#revocationendpointauthsigningalgvaluessupported} - -```ts -optional revocationEndpointAuthSigningAlgValuesSupported: string[]; -``` - -### scopeSupported? {#scopesupported} - -```ts -optional scopeSupported: string[]; -``` - -### serviceDocumentation? {#servicedocumentation} - -```ts -optional serviceDocumentation: string; -``` - -### tokenEndpoint {#tokenendpoint} - -```ts -tokenEndpoint: string; -``` - -### tokenEndpointAuthMethodsSupported? {#tokenendpointauthmethodssupported} - -```ts -optional tokenEndpointAuthMethodsSupported: string[]; -``` - -### tokenEndpointAuthSigningAlgValuesSupported? {#tokenendpointauthsigningalgvaluessupported} - -```ts -optional tokenEndpointAuthSigningAlgValuesSupported: string[]; -``` - -### uiLocalesSupported? {#uilocalessupported} - -```ts -optional uiLocalesSupported: string[]; -``` - -### userinfoEndpoint? {#userinfoendpoint} - -```ts -optional userinfoEndpoint: string; -``` - -## 参见 {#see} - -[AuthorizationServerMetadata](/references/js/type-aliases/AuthorizationServerMetadata.md) 以获取原始类型和字段信息。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md deleted file mode 100644 index c29c7f4..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -sidebar_label: MCPAuthBearerAuthErrorDetails ---- - -# 类型别名：MCPAuthBearerAuthErrorDetails - -```ts -type MCPAuthBearerAuthErrorDetails = { - actual?: unknown; - cause?: unknown; - expected?: unknown; - missingScopes?: string[]; - uri?: URL; -}; -``` - -## 属性 {#properties} - -### actual? {#actual} - -```ts -optional actual: unknown; -``` - -*** - -### cause? {#cause} - -```ts -optional cause: unknown; -``` - -*** - -### expected? {#expected} - -```ts -optional expected: unknown; -``` - -*** - -### missingScopes? {#missingscopes} - -```ts -optional missingScopes: string[]; -``` - -*** - -### uri? {#uri} - -```ts -optional uri: URL; -``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthConfig.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthConfig.md deleted file mode 100644 index bbcd200..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthConfig.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -sidebar_label: MCPAuthConfig ---- - -# 类型别名：MCPAuthConfig - -```ts -type MCPAuthConfig = { - server: AuthServerConfig; -}; -``` - -[MCPAuth](/references/js/classes/MCPAuth.md) 类的配置。 - -## 属性 {#properties} - -### server {#server} - -```ts -server: AuthServerConfig; -``` - -远程授权 (Authorization) 服务器的配置。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md deleted file mode 100644 index 6daa15a..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: MCPAuthTokenVerificationErrorCode ---- - -# 类型别名：MCPAuthTokenVerificationErrorCode - -```ts -type MCPAuthTokenVerificationErrorCode = "invalid_token" | "token_verification_failed"; -``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenFunction.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenFunction.md deleted file mode 100644 index 3b1b43e..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenFunction.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -sidebar_label: VerifyAccessTokenFunction ---- - -# 类型别名：VerifyAccessTokenFunction() - -```ts -type VerifyAccessTokenFunction = (token: string) => MaybePromise; -``` - -用于验证访问令牌 (Access token) 的函数类型。 - -如果令牌无效，此函数应抛出 [MCPAuthTokenVerificationError](/references/js/classes/MCPAuthTokenVerificationError.md)； -如果令牌有效，则返回一个 AuthInfo 对象。 - -例如，如果你有一个 JWT 验证函数，它至少应检查令牌的签名、验证其过期时间，并提取必要的声明 (Claims) 以返回一个 `AuthInfo` 对象。 - -**注意：** 无需验证令牌中的以下字段，因为它们会由处理程序进行检查： - -- `iss`（发行者 (Issuer)） -- `aud`（受众 (Audience)） -- `scope`（权限 (Scopes)） - -## 参数 {#parameters} - -### token {#token} - -`string` - -要验证的访问令牌 (Access token) 字符串。 - -## 返回值 {#returns} - -`MaybePromise`\<`AuthInfo`\> - -一个 Promise，当令牌有效时解析为 AuthInfo 对象，或同步返回该对象。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenMode.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenMode.md deleted file mode 100644 index acfae6d..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenMode.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: VerifyAccessTokenMode ---- - -# 类型别名：VerifyAccessTokenMode - -```ts -type VerifyAccessTokenMode = "jwt"; -``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authServerErrorDescription.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authServerErrorDescription.md deleted file mode 100644 index ebd2c2d..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authServerErrorDescription.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: authServerErrorDescription ---- - -# 变量：authServerErrorDescription - -```ts -const authServerErrorDescription: Readonly>; -``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authorizationServerMetadataSchema.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authorizationServerMetadataSchema.md deleted file mode 100644 index 1840b81..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authorizationServerMetadataSchema.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: authorizationServerMetadataSchema ---- - -# 变量：authorizationServerMetadataSchema - -```ts -const authorizationServerMetadataSchema: ZodObject; -``` - -用于 OAuth 2.0 授权服务器元数据 (Authorization Server Metadata) 的 Zod schema，定义见 RFC 8414。 - -## 参考 {#see} - -https://datatracker.ietf.org/doc/html/rfc8414 \ No newline at end of file diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/bearerAuthErrorDescription.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/bearerAuthErrorDescription.md deleted file mode 100644 index 17d19d6..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/bearerAuthErrorDescription.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: bearerAuthErrorDescription ---- - -# 变量：bearerAuthErrorDescription - -```ts -const bearerAuthErrorDescription: Readonly>; -``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md deleted file mode 100644 index d42244a..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: camelCaseAuthorizationServerMetadataSchema ---- - -# 变量：camelCaseAuthorizationServerMetadataSchema - -```ts -const camelCaseAuthorizationServerMetadataSchema: ZodObject; -``` - -OAuth 2.0 授权服务器元数据 (Authorization Server Metadata) Zod schema 的 camelCase 版本。 - -## 参见 {#see} - -[authorizationServerMetadataSchema](/references/js/variables/authorizationServerMetadataSchema.md) 以获取原始 schema 和字段信息。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/serverMetadataPaths.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/serverMetadataPaths.md deleted file mode 100644 index 1c3c1a6..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/serverMetadataPaths.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_label: serverMetadataPaths ---- - -# 变量：serverMetadataPaths - -```ts -const serverMetadataPaths: Readonly<{ - oauth: "/.well-known/oauth-authorization-server"; - oidc: "/.well-known/openid-configuration"; -}>; -``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/tokenVerificationErrorDescription.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/tokenVerificationErrorDescription.md deleted file mode 100644 index 06504fa..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/tokenVerificationErrorDescription.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: tokenVerificationErrorDescription ---- - -# 变量：tokenVerificationErrorDescription - -```ts -const tokenVerificationErrorDescription: Readonly>; -``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/validateServerConfig.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/validateServerConfig.md deleted file mode 100644 index 5428676..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/validateServerConfig.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: validateServerConfig ---- - -# 变量：validateServerConfig - -```ts -const validateServerConfig: ValidateServerConfig; -``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/snippets/_get-started-code.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/snippets/_get-started-code.mdx deleted file mode 100644 index 202edd7..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/snippets/_get-started-code.mdx +++ /dev/null @@ -1,41 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - - - - - -```python -mcp = FastMCP("MyMCPServer") -mcp_auth = MCPAuth(server=fetch_server_config('', type=AuthServerType.OIDC)) -app = Starlette( - # ... 你的 MCP 服务器设置 - middleware=[Middleware( - mcp_auth.bearer_auth_middleware("jwt", required_scopes=["read", "write"]) - )] -) - -# 使用 `mcp_auth.auth_info` 获取当前请求的认证 (Authentication) 信息 -@mcp.tool() -def whoami() -> dict[str, Any]: - return mcp_auth.auth_info.claims -``` - - - - -```ts -const server = new McpServer(/* ... */); -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { type: 'oidc' }), -}); -const app = express(); - -app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] })); -server.tool('whoami', ({ authInfo }) => { - // 使用 `authInfo` 获取从 `req.auth` 携带的认证 (Authentication) 信息 -}); -``` - - - diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/README.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/README.mdx deleted file mode 100644 index 16097e7..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/README.mdx +++ /dev/null @@ -1,1149 +0,0 @@ ---- -sidebar_position: 2 -sidebar_label: '教程：构建一个待办事项管理器' ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import SetupOauthOrOidc from './_setup-oauth-or-oidc.mdx'; -import SetupOidc from './_setup-oidc.mdx'; - -# 教程：构建一个待办事项管理器 - -在本教程中，我们将构建一个带有用户认证 (Authentication) 和授权 (Authorization) 的待办事项管理器 MCP 服务器。 - -完成本教程后，你将获得： - -- ✅ 对如何在 MCP 服务器中设置基于角色的访问控制 (RBAC) 有基本了解。 -- ✅ 一个可以管理个人待办事项列表的 MCP 服务器。 - -:::note -在开始之前，如果你对 MCP 服务器和 OAuth 2 不熟悉，强烈建议你先阅读 [Who am I 教程](./whoami)。 -::: - -## 概览 \{#overview} - -本教程将涉及以下组件： - -- **MCP 服务器**：一个使用 MCP 官方 SDK 处理请求的简单 MCP 服务器，集成了用于管理用户待办事项的 Todo 服务。 -- **MCP inspector**：一个用于 MCP 服务器的可视化测试工具。它还充当 OAuth / OIDC 客户端，用于发起授权流程并获取访问令牌 (Access token)。 -- **授权 (Authorization) 服务器**：一个 OAuth 2.1 或 OpenID Connect 提供商，负责管理用户身份并签发访问令牌 (Access token)。 - -以下是这些组件之间交互的高级流程图： - -```mermaid -sequenceDiagram - participant Client as MCP Inspector - participant Server as MCP Server - participant Auth as 授权 (Authorization) 服务器 - - Client->>Server: 请求待办事项操作 - Server->>Client: 返回 401 未授权 - Client->>Auth: 发起授权 (Authorization) 流程 - Auth->>Auth: 完成授权 (Authorization) 流程 - Auth->>Client: 带授权码重定向回客户端 - Client->>Auth: 用授权码换取访问令牌 (Access token) - Auth->>Client: 返回访问令牌 (Access token) - Client->>Server: 携带访问令牌 (Access token) 请求待办事项操作 - Server->>Server: 验证访问令牌 (Access token) 并从中获取用户权限 (Scopes) - Note over Server: 执行待办事项操作 - Server->>Client: 返回待办事项操作结果 -``` - -## 了解你的授权 (Authorization) 服务器 \{#understand-your-authorization-server} - -### 带权限 (Scopes) 的访问令牌 (Access tokens) \{#access-tokens-with-scopes} - -要在 MCP 服务器中实现[基于角色的访问控制 (RBAC)](https://auth.wiki/rbac)，你的授权 (Authorization) 服务器需要支持签发带有权限 (Scopes) 的访问令牌 (Access token)。权限 (Scopes) 代表用户被授予的权限 (Permissions)。 - - - - -[Logto](https://logto.io) 通过其 API 资源和角色功能（符合 [RFC 8707: OAuth 2.0 的资源指示器](https://datatracker.ietf.org/doc/html/rfc8707)）提供 RBAC 支持。设置方法如下： - -1. 登录 [Logto Console](https://cloud.logto.io)（或你的自托管 Logto Console） - -2. 创建 API 资源和权限 (Scopes)： - - - 进入“API 资源” - - 创建一个名为“Todo Manager”的新 API 资源 - - 添加以下权限 (Scopes)： - - `create:todos`：“创建新的待办事项” - - `read:todos`：“读取所有待办事项” - - `delete:todos`：“删除任意待办事项” - -3. 创建角色（推荐，便于管理）： - - - 进入“角色” - - 创建一个“Admin”角色并分配所有权限 (Scopes)（`create:todos`、`read:todos`、`delete:todos`） - - 创建一个“User”角色，仅分配 `create:todos` 权限 (Scope) - -4. 分配权限 (Permissions)： - - 进入“用户” - - 选择一个用户 - - 你可以： - - 在“角色”标签页分配角色（推荐） - - 或在“权限”标签页直接分配权限 (Scopes) - -这些权限 (Scopes) 会作为空格分隔的字符串包含在 JWT 访问令牌 (Access token) 的 `scope` 声明 (Claim) 中。 - - - - -OAuth 2.0 / OIDC 提供商通常支持基于权限 (Scope) 的访问控制。在实现 RBAC 时： - -1. 在授权 (Authorization) 服务器中定义所需的权限 (Scopes) -2. 配置客户端在授权 (Authorization) 流程中请求这些权限 (Scopes) -3. 确保授权 (Authorization) 服务器在访问令牌 (Access token) 中包含已授予的权限 (Scopes) -4. 权限 (Scopes) 通常包含在 JWT 访问令牌 (Access token) 的 `scope` 声明 (Claim) 中 - -请查阅你的提供商文档，了解以下内容： - -- 如何定义和管理权限 (Scopes) -- 权限 (Scopes) 如何包含在访问令牌 (Access token) 中 -- 是否有额外的 RBAC 功能，如角色管理 - - - - -### 验证令牌并检查权限 (Permissions) \{#validating-tokens-and-checking-permissions} - -当你的 MCP 服务器收到请求时，需要： - -1. 验证访问令牌 (Access token) 的签名和过期时间 -2. 从已验证的令牌中提取权限 (Scopes) -3. 检查令牌是否包含所请求操作所需的权限 (Scopes) - -例如，如果用户想创建新的待办事项，他们的访问令牌 (Access token) 必须包含 `create:todos` 权限 (Scope)。流程如下： - -```mermaid -sequenceDiagram - participant Client - participant MCP Server - participant Auth Server - - Client->>MCP Server: 携带访问令牌 (Access token) 的请求 - - alt JWT 验证 - MCP Server->>Auth Server: 获取 JWKS - Auth Server-->>MCP Server: 返回 JWKS - MCP Server->>MCP Server: 本地验证 JWT - else 令牌自省 - MCP Server->>Auth Server: POST /introspect
(token=access_token) - Auth Server-->>MCP Server: 返回令牌信息
(active, scope, 等) - end - - MCP Server->>MCP Server: 提取并检查权限 (Scopes) - - alt 拥有所需权限 (Scopes) - MCP Server->>Client: 允许操作 - else 缺少权限 (Scopes) - MCP Server->>Client: 返回 403 禁止访问 - end -``` - -### 动态客户端注册 (Dynamic Client Registration) \{#dynamic-client-registration} - -本教程不要求动态客户端注册 (Dynamic Client Registration)，但如果你想自动化 MCP 客户端在授权 (Authorization) 服务器的注册流程，可以参考 [是否需要动态客户端注册？](/provider-list#is-dcr-required)。 - -## 了解待办事项管理器中的 RBAC \{#understand-rbac-in-todo-manager} - -为了演示，我们将在待办事项管理器 MCP 服务器中实现一个简单的基于角色的访问控制 (RBAC) 系统。这将向你展示 RBAC 的基本原理，同时保持实现简洁。 - -:::note -虽然本教程演示了基于 RBAC 的权限 (Scope) 管理，但需要注意，并非所有认证 (Authentication) 提供商都通过角色实现权限 (Scope) 管理。有些提供商可能有自己独特的访问控制和权限 (Permission) 管理机制。 -::: - -### 工具与权限 (Scopes) \{#tools-and-scopes} - -我们的待办事项管理器 MCP 服务器提供三个主要工具： - -- `create-todo`：创建新的待办事项 -- `get-todos`：列出所有待办事项 -- `delete-todo`：按 ID 删除待办事项 - -为了控制对这些工具的访问，我们定义以下权限 (Scopes)： - -- `create:todos`：允许创建新的待办事项 -- `delete:todos`：允许删除现有待办事项 -- `read:todos`：允许查询和获取所有待办事项列表 - -### 角色与权限 (Roles and permissions) \{#roles-and-permissions} - -我们将定义两个具有不同访问级别的角色： - -| 角色 (Role) | create:todos | read:todos | delete:todos | -| ----- | ------------ | ---------- | ------------ | -| Admin | ✅ | ✅ | ✅ | -| User | ✅ | | | - -- **User**：普通用户，可以创建待办事项，并且只能查看或删除自己的待办事项 -- **Admin**：管理员，可以创建、查看和删除所有待办事项，无论归属谁 - -### 资源归属 (Resource ownership) \{#resource-ownership} - -虽然上表显示了每个角色明确分配的权限 (Scopes)，但还有一个重要的资源归属原则： - -- **User** 没有 `read:todos` 或 `delete:todos` 权限 (Scopes)，但他们仍然可以： - - 查看自己的待办事项 - - 删除自己的待办事项 -- **Admin** 拥有全部权限 (`read:todos` 和 `delete:todos`)，可以： - - 查看系统中所有待办事项 - - 删除任意待办事项，无论归属谁 - -这展示了 RBAC 系统中的常见模式：资源归属为用户自己的资源隐式授予权限 (Permission)，而管理员角色则获得所有资源的显式权限 (Permission)。 - -:::tip 了解更多 -想深入了解 RBAC 概念和最佳实践，请查阅 [精通 RBAC：一个全面的真实案例](https://blog.logto.io/mastering-rbac)。 -::: - -## 在你的提供商中配置授权 (Authorization) \{#configure-authorization-in-your-provider} - -要实现我们前面描述的访问控制系统，你需要在授权 (Authorization) 服务器中配置所需的权限 (Scopes)。不同提供商的配置方法如下： - - - - -[Logto](https://logto.io) 通过其 API 资源和角色功能提供 RBAC 支持。设置方法如下： - -1. 登录 [Logto Console](https://cloud.logto.io)（或你的自托管 Logto Console） - -2. 创建 API 资源和权限 (Scopes)： - - - 进入“API 资源” - - 创建一个名为“Todo Manager”的新 API 资源，并使用 `https://todo.mcp-server.app`（仅作演示）作为指示器。 - - 创建以下权限 (Scopes)： - - `create:todos`：“创建新的待办事项” - - `read:todos`：“读取所有待办事项” - - `delete:todos`：“删除任意待办事项” - -3. 创建角色（推荐，便于管理）： - - - 进入“角色” - - 创建一个“Admin”角色并分配所有权限 (Scopes)（`create:todos`、`read:todos`、`delete:todos`） - - 创建一个“User”角色，仅分配 `create:todos` 权限 (Scope) - - 在“User”角色详情页，切换到“常规”标签，并将“User”角色设置为“默认角色”。 - -4. 管理用户角色和权限 (Permissions)： - - 新用户： - - 由于我们设置了默认角色，他们会自动获得“User”角色 - - 已有用户： - - 进入“用户管理” - - 选择一个用户 - - 在“角色”标签页为用户分配角色 - -:::tip 编程方式管理角色 -你也可以使用 Logto 的 [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api) 以编程方式管理用户角色。这对于自动化用户管理或构建管理面板特别有用。 -::: - -请求访问令牌 (Access token) 时，Logto 会根据用户角色权限 (Permissions) 在令牌的 `scope` 声明 (Claim) 中包含相应权限 (Scopes)。 - - - - -在 [Keycloak](https://www.keycloak.org) 中，你可以通过客户端权限 (Client scopes) 设置所需的权限 (Permissions)： - -1. 创建客户端权限 (Client scopes)： - - - 在你的 realm 中，进入“客户端权限 (Client scopes)” - - 创建三个新的客户端权限 (Client scopes)： - - `create:todos` - - `read:todos` - - `delete:todos` - -2. 配置客户端： - - - 进入你的客户端设置 - - 在“客户端权限 (Client scopes)”标签页添加你创建的所有权限 (Scopes) - - 确保令牌映射器已配置为包含权限 (Scopes) - -3. 可选：使用角色便于管理 - - 如果你更喜欢基于角色的管理： - - 为不同访问级别创建 realm 角色 - - 将权限 (Scopes) 映射到角色 - - 为用户分配角色 - - 否则，你可以直接为用户分配权限 (Scopes) 或通过客户端级权限 (Client-level permissions) - -Keycloak 会在访问令牌 (Access token) 的 `scope` 声明 (Claim) 中包含已授予的权限 (Scopes)。 - - - - -对于 OAuth 2.0 或 OpenID Connect 提供商，你需要配置代表不同权限 (Permissions) 的权限 (Scopes)。具体步骤取决于你的提供商，但一般流程如下： - -1. 定义权限 (Scopes)： - - - 配置你的授权 (Authorization) 服务器支持： - - `create:todos` - - `read:todos` - - `delete:todos` - -2. 配置客户端： - - - 注册或更新你的客户端以请求这些权限 (Scopes) - - 确保权限 (Scopes) 被包含在访问令牌 (Access token) 中 - -3. 分配权限 (Permissions)： - - 使用你的提供商界面为用户授予相应权限 (Scopes) - - 有些提供商支持基于角色的管理，其他则使用直接分配权限 (Scopes) - - 查阅你的提供商文档，了解推荐做法 - -:::tip -大多数提供商会在访问令牌 (Access token) 的 `scope` 声明 (Claim) 中包含已授予的权限 (Scopes)。格式通常是空格分隔的权限 (Scope) 字符串。 -::: - - - - -配置好授权 (Authorization) 服务器后，用户将获得包含其已授予权限 (Scopes) 的访问令牌 (Access token)。MCP 服务器将使用这些权限 (Scopes) 来判断： - -- 用户是否可以创建新的待办事项（`create:todos`） -- 用户是否可以查看所有待办事项（`read:todos`）或仅查看自己的 -- 用户是否可以删除任意待办事项（`delete:todos`）或仅删除自己的 - -## 搭建 MCP 服务器 \{#set-up-the-mcp-server} - -我们将使用 [MCP 官方 SDK](https://github.com/modelcontextprotocol) 创建我们的待办事项管理器 MCP 服务器。 - -### 创建新项目 \{#create-a-new-project} - - - - -```bash -mkdir mcp-server -cd mcp-server -uv init # 或使用 `pipenv` 或 `poetry` 创建新的虚拟环境 -``` - - - - -创建一个新的 Node.js 项目： - -```bash -mkdir mcp-server -cd mcp-server -npm init -y # 或使用 `pnpm init` -npm pkg set type="module" -npm pkg set main="todo-manager.ts" -npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts" -``` - -:::note -我们的示例使用 TypeScript，因为 Node.js v22.6.0+ 原生支持 `--experimental-strip-types` 运行 TypeScript。如果你使用 JavaScript，代码类似——只需确保 Node.js 版本为 v22.6.0 或更高。详情见 Node.js 官方文档。 -::: - - - - -### 安装 MCP SDK 及依赖 \{#install-the-mcp-sdk-and-dependencies} - - - - -```bash -pip install "mcp[cli]" starlette uvicorn -``` - -或使用你喜欢的包管理器，如 `uv` 或 `poetry`。 - - - - -```bash -npm install @modelcontextprotocol/sdk express zod -``` - -或使用你喜欢的包管理器，如 `pnpm` 或 `yarn`。 - - - - -### 创建 MCP 服务器 \{#create-the-mcp-server} - -首先，让我们创建一个带有工具定义的基础 MCP 服务器： - - - - -创建名为 `todo-manager.py` 的文件，并添加如下代码： - -```python -from typing import Any -from mcp.server.fastmcp import FastMCP -from starlette.applications import Starlette -from starlette.routing import Mount - -mcp = FastMCP("Todo Manager") - -@mcp.tool() -def create_todo(content: str) -> dict[str, Any]: - """Create a new todo.""" - return {"error": "Not implemented"} - -@mcp.tool() -def get_todos() -> dict[str, Any]: - """List all todos.""" - return {"error": "Not implemented"} - -@mcp.tool() -def delete_todo(id: str) -> dict[str, Any]: - """Delete a todo by id.""" - return {"error": "Not implemented"} - -app = Starlette( - routes=[Mount('/', app=mcp.sse_app())] -) -``` - -运行服务器： - -```bash -uvicorn todo_manager:app --host 0.0.0.0 --port 3001 -``` - - - - -:::note -由于当前 MCP inspector 实现尚未处理授权 (Authorization) 流程，我们将采用 SSE 方式搭建 MCP 服务器。待 MCP inspector 支持授权 (Authorization) 流程后，我们会更新此处代码。 -::: - -你也可以使用 `pnpm` 或 `yarn`。 - -创建名为 `todo-manager.ts` 的文件，并添加如下代码： - -```ts -// todo-manager.ts - -import { z } from 'zod'; -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; -import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'; -import express from 'express'; - -// 创建 MCP 服务器 -const server = new McpServer({ - name: 'Todo Manager', - version: '0.0.0', -}); - -server.tool('create-todo', 'Create a new todo', { content: z.string() }, async ({ content }) => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }], - }; -}); - -server.tool('get-todos', 'List all todos', async () => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }], - }; -}); - -server.tool('delete-todo', 'Delete a todo by id', { id: z.string() }, async ({ id }) => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }], - }; -}); - -// 以下为 MCP SDK 文档中的样板代码 -const PORT = 3001; -const app = express(); - -const transports = {}; - -app.get('/sse', async (_req, res) => { - const transport = new SSEServerTransport('/messages', res); - transports[transport.sessionId] = transport; - - res.on('close', () => { - delete transports[transport.sessionId]; - }); - - await server.connect(transport); -}); - -app.post('/messages', async (req, res) => { - const sessionId = String(req.query.sessionId); - const transport = transports[sessionId]; - if (transport) { - await transport.handlePostMessage(req, res, req.body); - } else { - res.status(400).send('No transport found for sessionId'); - } -}); - -app.listen(PORT); -``` - -运行服务器： - -```bash -npm start -``` - - - - -## 检查 MCP 服务器 \{#inspect-the-mcp-server} - -### 克隆并运行 MCP inspector \{#clone-and-run-mcp-inspector} - -现在 MCP 服务器已运行，我们可以使用 MCP inspector 检查 `whoami` 工具是否可用。 - -由于当前实现的限制，我们 fork 了 [MCP inspector](https://github.com/mcp-auth/inspector)，使其在认证 (Authentication) 和授权 (Authorization) 方面更灵活、更易扩展。我们也已向原仓库提交了 pull request。 - -运行 MCP inspector： - -```bash -git clone https://github.com/mcp-auth/inspector.git -cd inspector -npm install -npm run dev -``` - -然后在浏览器中打开 `http://localhost:6274/`（或终端显示的其他 URL）访问 MCP inspector。 - -### 连接 MCP inspector 到 MCP 服务器 \{#connect-mcp-inspector-to-the-mcp-server} - -在继续之前，请检查 MCP inspector 的以下配置： - -- **Transport Type**：设置为 `SSE`。 -- **URL**：设置为你的 MCP 服务器地址，本例为 `http://localhost:3001/sse`。 - -现在你可以点击“Connect”按钮，查看 MCP inspector 是否能连接 MCP 服务器。如果一切正常，你将在 MCP inspector 中看到“Connected”状态。 - -### 检查点：运行待办事项管理工具 \{#checkpoint-run-todo-manager-tools} - -1. 在 MCP inspector 顶部菜单点击“Tools”标签。 -2. 点击“List Tools”按钮。 -3. 你应该能在页面上看到 `create-todo`、`get-todos` 和 `delete-todo` 工具。点击可查看工具详情。 -4. 你将在右侧看到“Run Tool”按钮。点击并输入所需参数运行工具。 -5. 你将看到工具返回的 JSON 响应 `{"error": "Not implemented"}`。 - -![MCP inspector 首次运行](/docs-assets/images/tutorials/todo-manager/inspector-first-run.png) - -## 集成你的授权 (Authorization) 服务器 \{#integrate-with-your-authorization-server} - -完成本节需要考虑以下事项： - -
-**你的授权 (Authorization) 服务器的发行者 (Issuer) URL** - -通常是你的授权 (Authorization) 服务器的基础 URL，如 `https://auth.example.com`。有些提供商可能是 `https://example.logto.app/oidc`，请查阅你的提供商文档。 - -
- -
-**如何获取授权 (Authorization) 服务器元数据** - -- 如果你的授权 (Authorization) 服务器符合 [OAuth 2.0 授权服务器元数据](https://datatracker.ietf.org/doc/html/rfc8414) 或 [OpenID Connect 发现](https://openid.net/specs/openid-connect-discovery-1_0.html)，你可以使用 MCP Auth 内置工具自动获取元数据。 -- 如果不符合这些标准，你需要在 MCP 服务器配置中手动指定元数据 URL 或端点。请查阅你的提供商文档。 - -
- -
-**如何将 MCP inspector 注册为授权 (Authorization) 服务器的客户端** - -- 如果你的授权 (Authorization) 服务器支持 [动态客户端注册 (Dynamic Client Registration)](https://datatracker.ietf.org/doc/html/rfc7591)，可以跳过此步骤，MCP inspector 会自动注册为客户端。 -- 如果不支持动态客户端注册 (Dynamic Client Registration)，你需要手动将 MCP inspector 注册为客户端。 - -
- -
-**了解令牌请求参数** - -向不同授权 (Authorization) 服务器请求访问令牌 (Access token) 时，指定目标资源和权限 (Permissions) 的方式各异。主要模式如下： - -- **基于资源指示器 (Resource indicator)**： - - - 使用 `resource` 参数指定目标 API（见 [RFC 8707: OAuth 2.0 的资源指示器](https://datatracker.ietf.org/doc/html/rfc8707)） - - 现代 OAuth 2.0 实现常用 - - 示例请求： - ```json - { - "resource": "https://todo.mcp-server.app", - "scope": "create:todos read:todos" - } - ``` - - 服务器签发专门绑定到请求资源的令牌 - -- **基于受众 (Audience)**： - - - 使用 `audience` 参数指定令牌的目标接收方 - - 与资源指示器类似，但语义不同 - - 示例请求： - ```json - { - "audience": "todo-api", - "scope": "create:todos read:todos" - } - ``` - -- **纯权限 (Scope) 模式**： - - 仅依赖权限 (Scopes)，无资源/受众参数 - - 传统 OAuth 2.0 方式 - - 示例请求： - ```json - { - "scope": "todo-api:create todo-api:read openid profile" - } - ``` - - 通常使用前缀权限 (Scopes) 进行命名空间隔离 - - 适用于简单的 OAuth 2.0 实现 - -:::tip 最佳实践 - -- 查阅你的提供商文档，了解支持哪些参数 -- 有些提供商同时支持多种方式 -- 资源指示器 (Resource indicator) 通过受众限制提升安全性 -- 如有条件，优先使用资源指示器 (Resource indicator) 以获得更好的访问控制 - ::: - -
- -虽然每个提供商可能有自己的具体要求，以下步骤将指导你如何结合 MCP inspector 和 MCP 服务器进行针对不同提供商的配置。 - -### 注册 MCP inspector 为客户端 \{#register-mcp-inspector-as-a-client} - - - - -将待办事项管理器集成到 [Logto](https://logto.io) 非常简单，因为它是支持资源指示器 (Resource indicator) 和权限 (Scopes) 的 OpenID Connect 提供商，可以用 `https://todo.mcp-server.app` 作为资源指示器保护你的 todo API。 - -由于 Logto 目前不支持动态客户端注册 (Dynamic Client Registration)，你需要手动在 Logto 租户中注册 MCP inspector 为客户端： - -1. 打开 MCP inspector，点击 “OAuth Configuration” 按钮。复制 **Redirect URL (auto-populated)**，如 `http://localhost:6274/oauth/callback`。 -2. 登录 [Logto Console](https://cloud.logto.io)（或你的自托管 Logto Console）。 -3. 进入“应用程序”标签，点击“创建应用程序”。在页面底部点击“Create app without framework”。 -4. 填写应用详情，然后点击“创建应用程序”： - - **选择应用类型**：选择“单页应用程序” - - **应用名称**：如 “MCP Inspector” -5. 在“设置 / Redirect URIs”部分，粘贴你从 MCP inspector 复制的 **Redirect URL (auto-populated)**，然后点击底部栏的“保存更改”。 -6. 在顶部卡片中，你会看到 “App ID” 值。复制它。 -7. 回到 MCP inspector，在 “OAuth Configuration” 的 “Client ID” 字段粘贴 “App ID”。 -8. 在 “Auth Params” 字段输入 `{"scope": "create:todos read:todos delete:todos", "resource": "https://todo.mcp-server.app"}`。这样 Logto 返回的访问令牌 (Access token) 就包含访问待办事项管理器所需的权限 (Scopes)。 - - - - -:::note -这是通用的 OAuth 2.0 / OpenID Connect 提供商集成指南。OAuth 2.0 和 OIDC 步骤类似，因为 OIDC 基于 OAuth 2.0。具体细节请查阅你的提供商文档。 -::: - -如果你的提供商支持动态客户端注册 (Dynamic Client Registration)，可以直接跳到第 8 步配置 MCP inspector；否则需要手动注册 MCP inspector 为客户端： - -1. 打开 MCP inspector，点击 “OAuth Configuration” 按钮。复制 **Redirect URL (auto-populated)**，如 `http://localhost:6274/oauth/callback`。 - -2. 登录你的提供商控制台。 - -3. 进入“应用程序”或“客户端”部分，创建新应用或客户端。 - -4. 如果需要选择客户端类型，选择“单页应用程序”或“公共客户端”。 - -5. 创建应用后，需要配置重定向 URI。粘贴你从 MCP inspector 复制的 **Redirect URL (auto-populated)**。 - -6. 找到新建应用的 “Client ID” 或 “Application ID”，复制它。 - -7. 回到 MCP inspector，在 “OAuth Configuration” 的 “Client ID” 字段粘贴 “Client ID”。 - -8. 在 “Auth Params” 字段输入以下内容，请求待办事项操作所需权限 (Scopes)： - -```json -{ "scope": "create:todos read:todos delete:todos" } -``` - - - - -### 配置 MCP Auth \{#set-up-mcp-auth} - -在你的 MCP 服务器项目中，需要安装 MCP Auth SDK 并配置其使用你的授权 (Authorization) 服务器元数据。 - - - - -首先安装 `mcpauth` 包： - -```bash -pip install mcpauth -``` - -或使用你喜欢的包管理器，如 `uv` 或 `poetry`。 - - - - -首先安装 `mcp-auth` 包： - -```bash -npm install mcp-auth -``` - - - - -MCP Auth 需要授权 (Authorization) 服务器元数据才能初始化。根据你的提供商： - - - - - -发行者 (Issuer) URL 可在 Logto Console 的应用详情页 “Endpoints & Credentials / Issuer endpoint” 部分找到，格式如 `https://my-project.logto.app/oidc`。 - - - - - - - -对于 OAuth 2.0 提供商，你需要： - -1. 查阅你的提供商文档，获取授权 (Authorization) 服务器 URL（通常称为发行者 (Issuer) URL 或基础 URL） -2. 有些提供商会在 `https://{your-domain}/.well-known/oauth-authorization-server` 暴露此信息 -3. 在提供商管理后台的 OAuth/API 设置中查找 - - - - - - - - - - - -更新 `todo-manager.py`，加入 MCP Auth 配置： - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # 替换为你的发行者 (Issuer) 端点 -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -更新 `todo-manager.ts`，加入 MCP Auth 配置： - -```ts -// todo-manager.ts - -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // 替换为你的发行者 (Issuer) 端点 -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oidc' }), -}); -``` - - - - -### 更新 MCP 服务器 \{#update-mcp-server} - -我们快完成了！现在需要更新 MCP 服务器，应用 MCP Auth 路由和中间件，并基于用户权限 (Scopes) 实现待办事项工具的权限 (Permission) 控制。 - - - - -```python -@mcp.tool() -def create_todo(content: str) -> dict[str, Any]: - """Create a new todo.""" - return ( - mcp_auth.auth_info.scopes - if mcp_auth.auth_info # 由 Bearer auth 中间件填充 - else {"error": "Not authenticated"} - ) - -# ... - -bearer_auth = Middleware(mcp_auth.bearer_auth_middleware("jwt")) -app = Starlette( - routes=[ - # 添加元数据路由 (`/.well-known/oauth-authorization-server`) - mcp_auth.metadata_route(), - # 用 Bearer auth 中间件保护 MCP 服务器 - Mount('/', app=mcp.sse_app(), middleware=[bearer_auth]), - ], -) -``` - - - - -```js -server.tool( - 'create-todo', - 'Create a new todo', - { content: z.string() }, - async ({ content, authInfo }) => { - return { - content: [ - { type: 'text', text: JSON.stringify(authInfo?.scopes ?? { error: 'Not authenticated' }) }, - ], - }; - } -); - -// ... - -app.use(mcpAuth.delegatedRouter()); -app.use(mcpAuth.bearerAuth('jwt')); -``` - - - - -接下来，让我们实现具体的工具。 - -首先，创建一个简单的 todo 服务，在内存中提供基本的 CRUD 操作。 - - - -```python -# service.py - -""" -一个简单的 Todo 服务，仅用于演示。 -使用内存列表存储 todos。 -""" - -from datetime import datetime -from typing import List, Optional, Dict, Any -import random -import string - -class Todo: -"""表示一个待办事项。""" - - def __init__(self, id: str, content: str, owner_id: str, created_at: str): - self.id = id - self.content = content - self.owner_id = owner_id - self.created_at = created_at - - def to_dict(self) -> Dict[str, Any]: - """将 todo 转为字典以便 JSON 序列化。""" - return { - "id": self.id, - "content": self.content, - "ownerId": self.owner_id, - "createdAt": self.created_at - } - -class TodoService: -"""一个简单的 Todo 服务，仅用于演示。""" - - def __init__(self): - self._todos: List[Todo] = [] - - def get_all_todos(self, owner_id: Optional[str] = None) -> List[Dict[str, Any]]: - """ - 获取所有 todos，可选按 owner_id 过滤。 - - Args: - owner_id: 如提供，仅返回该用户拥有的 todos - - Returns: - todo 字典列表 - """ - if owner_id: - filtered_todos = [todo for todo in self._todos if todo.owner_id == owner_id] - return [todo.to_dict() for todo in filtered_todos] - return [todo.to_dict() for todo in self._todos] - - def get_todo_by_id(self, todo_id: str) -> Optional[Todo]: - """ - 按 ID 获取 todo。 - - Args: - todo_id: 要获取的 todo ID - - Returns: - 找到则返回 Todo 对象，否则为 None - """ - for todo in self._todos: - if todo.id == todo_id: - return todo - return None - - def create_todo(self, content: str, owner_id: str) -> Dict[str, Any]: - """ - 创建新 todo。 - - Args: - content: todo 内容 - owner_id: 拥有该 todo 的用户 ID - - Returns: - 创建的 todo 字典 - """ - todo = Todo( - id=self._generate_id(), - content=content, - owner_id=owner_id, - created_at=datetime.now().isoformat() - ) - self._todos.append(todo) - return todo.to_dict() - - def delete_todo(self, todo_id: str) -> Optional[Dict[str, Any]]: - """ - 按 ID 删除 todo。 - - Args: - todo_id: 要删除的 todo ID - - Returns: - 删除的 todo 字典，如未找到则为 None - """ - for i, todo in enumerate(self._todos): - if todo.id == todo_id: - deleted_todo = self._todos.pop(i) - return deleted_todo.to_dict() - return None - - def _generate_id(self) -> str: - """生成随机 todo ID。""" - return ''.join(random.choices(string.ascii_lowercase + string.digits, k=8)) - -```` - - - - - -```ts -// todo-service.ts - -type Todo = { - id: string; - content: string; - ownerId: string; - createdAt: string; -}; - -/** - * 一个简单的 Todo 服务，仅用于演示。 - * 使用内存数组存储 todos - */ -export class TodoService { - private readonly todos: Todo[] = []; - - getAllTodos(ownerId?: string): Todo[] { - if (ownerId) { - return this.todos.filter((todo) => todo.ownerId === ownerId); - } - return this.todos; - } - - getTodoById(id: string): Todo | undefined { - return this.todos.find((todo) => todo.id === id); - } - - createTodo({ content, ownerId }: { content: string; ownerId: string }): Todo { - const todo: Todo = { - id: this.genId(), - content, - ownerId, - createdAt: new Date().toISOString(), - }; - - // eslint-disable-next-line @silverhand/fp/no-mutating-methods - this.todos.push(todo); - return todo; - } - - deleteTodo(id: string): Todo | undefined { - const index = this.todos.findIndex((todo) => todo.id === id); - - if (index === -1) { - return undefined; - } - - // eslint-disable-next-line @silverhand/fp/no-mutating-methods - const [deleted] = this.todos.splice(index, 1); - return deleted; - } - - private genId(): string { - return Math.random().toString(36).slice(2, 10); - } -} -```` - - - - -然后在工具层，根据用户权限 (Scopes) 判断操作是否允许： - - - - -```python -# todo-manager.py - -from typing import Any, Optional -from mcpauth.errors import MCPAuthBearerAuthError - -def assert_user_id(auth_info: Optional[dict]) -> str: - """从 auth info 提取并校验用户 ID。""" - subject = auth_info.get('subject') if auth_info else None - if not subject: - raise ValueError('Invalid auth info') - return subject - -def has_required_scopes(user_scopes: list[str], required_scopes: list[str]) -> bool: - """检查用户是否拥有所有所需权限 (Scopes)。""" - return all(scope in user_scopes for scope in required_scopes) - -# 创建 TodoService 实例 -todo_service = TodoService() - -@mcp.tool() -def create_todo(content: str) -> dict[str, Any]: - """创建新 todo。 - - 只有拥有 'create:todos' 权限 (Scope) 的用户才能创建 todo。 - """ - # 获取认证 (Authentication) 信息 - auth_info = mcp_auth.auth_info - - # 校验用户 ID - try: - user_id = assert_user_id(auth_info) - except ValueError as e: - return {"error": str(e)} - - # 检查用户是否有所需权限 (Permissions) - if not has_required_scopes(auth_info.scopes if auth_info else [], ['create:todos']): - raise MCPAuthBearerAuthError('missing_required_scopes') - - # 创建新 todo - created_todo = todo_service.create_todo(content=content, owner_id=user_id) - - # 返回创建的 todo - return created_todo.__dict__ - -# ... -``` - -你可以查看我们的 [示例代码](https://github.com/mcp-auth/python/tree/master/samples/server) 获取其他详细实现。 - - - - -```ts -// todo-manager.ts - -// ... 其他导入 -import assert from 'node:assert'; -import { type AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js'; -import { TodoService } from './todo-service.js'; - -const todoService = new TodoService(); - -const assertUserId = (authInfo?: AuthInfo) => { - const { subject } = authInfo ?? {}; - assert(subject, 'Invalid auth info'); - return subject; -}; - -/** - * 检查用户是否拥有操作所需的所有权限 (Scopes) - */ -const hasRequiredScopes = (userScopes: string[], requiredScopes: string[]): boolean => { - return requiredScopes.every((scope) => userScopes.includes(scope)); -}; - -server.tool( - 'create-todo', - 'Create a new todo', - { content: z.string() }, - ({ content }: { content: string }, { authInfo }) => { - const userId = assertUserId(authInfo); - - /** - * 只有拥有 'create:todos' 权限 (Scope) 的用户才能创建 todo - */ - if (!hasRequiredScopes(authInfo?.scopes ?? [], ['create:todos'])) { - throw new MCPAuthBearerAuthError('missing_required_scopes'); - } - - const createdTodo = todoService.createTodo({ content, ownerId: userId }); - - return { - content: [{ type: 'text', text: JSON.stringify(createdTodo) }], - }; - } -); - -// ... -``` - -你可以查看我们的 [示例代码](https://github.com/mcp-auth/js/tree/master/packages/sample-servers/src/todo-manager) 获取其他详细实现。 - - - - -## 检查点：运行 `todo-manager` 工具 \{#checkpoint-run-the-todo-manager-tools} - -重启你的 MCP 服务器，并在浏览器中打开 MCP inspector。点击“Connect”按钮后，你会被重定向到授权 (Authorization) 服务器的登录页面。 - -登录后回到 MCP inspector，重复上一个检查点的操作运行待办事项管理工具。此时，你可以用已认证 (Authentication) 的用户身份使用这些工具。工具的行为将根据分配给你的角色和权限 (Permissions) 而变化： - -- 如果你以 **User**（仅有 `create:todos` 权限 (Scope)）身份登录： - - - 可以用 `create-todo` 工具创建新待办事项 - - 只能查看和删除自己的待办事项 - - 无法查看或删除其他用户的待办事项 - -- 如果你以 **Admin**（拥有全部权限：`create:todos`、`read:todos`、`delete:todos`）身份登录： - - 可以创建新待办事项 - - 可以用 `get-todos` 工具查看系统中所有待办事项 - - 可以用 `delete-todo` 工具删除任意待办事项，无论归属谁 - -你可以通过以下方式测试不同权限级别： - -1. 退出当前会话（点击 MCP inspector 的“Disconnect”按钮） -2. 用拥有不同角色/权限的其他用户账号登录 -3. 再次尝试相同工具，观察用户权限变化带来的行为差异 - -这展示了基于角色的访问控制 (RBAC) 在实际中的工作方式，不同用户对系统功能有不同访问级别。 - -![MCP inspector 待办事项管理工具结果](/docs-assets/images/tutorials/todo-manager/result.png) - - - - -:::info -完整 MCP 服务器（OIDC 版本）代码请参考 [MCP Auth Python SDK 仓库](https://github.com/mcp-auth/python/blob/master/samples/server/todo-manager/server.py)。 -::: - - - - -:::info -完整 MCP 服务器（OIDC 版本）代码请参考 [MCP Auth Node.js SDK 仓库](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src)。 -::: - - - - -## 结语 \{#closing-notes} - -🎊 恭喜你！你已成功完成本教程。让我们回顾一下所做的内容： - -- 搭建了一个带有待办事项管理工具（`create-todo`、`get-todos`、`delete-todo`）的基础 MCP 服务器 -- 实现了基于角色的访问控制 (RBAC)，为用户和管理员设置了不同权限级别 -- 使用 MCP Auth 将 MCP 服务器集成到授权 (Authorization) 服务器 -- 配置 MCP Inspector 认证 (Authentication) 用户，并用带权限 (Scopes) 的访问令牌 (Access token) 调用工具 - -欢迎查阅其他教程和文档，充分利用 MCP Auth 的强大功能。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_manual-metadata-fetching.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_manual-metadata-fetching.mdx deleted file mode 100644 index bbf7174..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_manual-metadata-fetching.mdx +++ /dev/null @@ -1,3 +0,0 @@ -:::note -如果你的提供商不支持 {props.oidc ? 'OpenID Connect Discovery' : 'OAuth 2.0 授权服务器元数据'}，你可以手动指定元数据 URL 或端点。详见 [其他初始化 MCP Auth 的方式](../../configure-server/mcp-auth.mdx#other-ways)。 -::: \ No newline at end of file diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oauth-or-oidc.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oauth-or-oidc.mdx deleted file mode 100644 index 197e443..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oauth-or-oidc.mdx +++ /dev/null @@ -1,41 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -更新 `todo-manager.py`，加入 MCP Auth 配置： - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # 替换为你的发行者 (Issuer) 端点 -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OAUTH) # 或 AuthServerType.OIDC -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -更新 `todo-manager.ts`，加入 MCP Auth 配置： - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // 替换为你的发行者 (Issuer) 端点 -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oauth' }), // 或 { type: 'oidc' } -}); -``` - - - - - - \ No newline at end of file diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oidc.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oidc.mdx deleted file mode 100644 index b74c764..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oidc.mdx +++ /dev/null @@ -1,41 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -更新 `todo-manager.py`，加入 MCP Auth 配置： - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # 替换为你的发行者 (Issuer) 端点 -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -更新 `todo-manager.ts`，加入 MCP Auth 配置： - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // 替换为你的发行者 (Issuer) 端点 -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oidc' }), -}); -``` - - - - -{props.showAlternative && } -{props.showAlternative && } \ No newline at end of file diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_transpile-metadata.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_transpile-metadata.mdx deleted file mode 100644 index 396455a..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_transpile-metadata.mdx +++ /dev/null @@ -1,31 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -在某些情况下，提供方的响应可能格式错误或不符合预期的元数据格式。如果你确信该提供方是合规的，你可以通过配置选项对元数据进行转译： - - - - -```python -mcp_auth = MCPAuth( - server=fetch_server_config( - # ...other options - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { - // ...other options - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/README.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/README.mdx deleted file mode 100644 index b46cb90..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/README.mdx +++ /dev/null @@ -1,611 +0,0 @@ ---- -sidebar_position: 1 -sidebar_label: '教程：我是谁？' ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import SetupOauth from './_setup-oauth.mdx'; -import SetupOidc from './_setup-oidc.mdx'; - -# 教程：我是谁？ (Tutorial: Who am I?) - -本教程将引导你完成设置 MCP Auth 以认证 (Authentication) 用户并从授权 (Authorization) 服务器获取其身份信息的过程。 - -完成本教程后，你将获得： - -- ✅ 对如何使用 MCP Auth 进行用户认证 (Authentication) 的基本理解。 -- ✅ 一个 MCP 服务器，提供用于获取用户身份信息的工具。 - -## 概览 (Overview) \{#overview} - -本教程将涉及以下组件： - -- **MCP 服务器**：一个简单的 MCP 服务器，使用 MCP 官方 SDK 处理请求。 -- **MCP inspector**：MCP 服务器的可视化测试工具。它还充当 OAuth / OIDC 客户端，发起授权 (Authorization) 流程并获取访问令牌 (Access token)。 -- **授权 (Authorization) 服务器**：一个 OAuth 2.1 或 OpenID Connect 提供商，管理用户身份并颁发访问令牌 (Access token)。 - -以下是这些组件之间交互的高级流程图： - -```mermaid -sequenceDiagram - participant Client as MCP Inspector - participant Server as MCP Server - participant Auth as 授权 (Authorization) 服务器 - - Client->>Server: 请求工具 `whoami` - Server->>Client: 返回 401 未授权 (Unauthorized) - Client->>Auth: 发起授权 (Authorization) 流程 - Auth->>Auth: 完成授权 (Authorization) 流程 - Auth->>Client: 带授权码重定向回客户端 - Client->>Auth: 用授权码换取访问令牌 (Access token) - Auth->>Client: 返回访问令牌 (Access token) - Client->>Server: 携带访问令牌 (Access token) 请求 `whoami` - Server->>Auth: 用访问令牌 (Access token) 获取用户身份 - Auth->>Server: 返回用户身份 - Server->>Client: 返回用户身份 -``` - -## 了解你的授权 (Authorization) 服务器 \{#understand-your-authorization-server} - -### 获取用户身份信息 (Retrieving user identity information) \{#retrieving-user-identity-information} - -要完成本教程，你的授权 (Authorization) 服务器应提供用于获取用户身份信息的 API： - - - - -[Logto](https://logto.io) 是一个 OpenID Connect 提供商，支持标准的 [userinfo 端点](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 用于获取用户身份信息。 - -要获取可用于访问 userinfo 端点的访问令牌 (Access token)，至少需要两个权限 (Scopes)：`openid` 和 `profile`。你可以继续阅读，后续会介绍权限 (Scope) 配置。 - - - - -[Keycloak](https://www.keycloak.org) 是一个开源身份和访问管理解决方案，支持多种协议，包括 OpenID Connect (OIDC)。作为 OIDC 提供商，它实现了标准的 [userinfo 端点](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 用于获取用户身份信息。 - -要获取可用于访问 userinfo 端点的访问令牌 (Access token)，至少需要两个权限 (Scopes)：`openid` 和 `profile`。你可以继续阅读，后续会介绍权限 (Scope) 配置。 - - - - -大多数 OpenID Connect 提供商都支持 [userinfo 端点](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 用于获取用户身份信息。 - -请查阅你的提供商文档，确认是否支持该端点。如果你的提供商支持 [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)，你也可以检查 discovery 文档（`.well-known/openid-configuration` 端点的响应）中是否包含 `userinfo_endpoint`。 - -要获取可用于访问 userinfo 端点的访问令牌 (Access token)，至少需要两个权限 (Scopes)：`openid` 和 `profile`。请查阅你的提供商文档，了解权限 (Scopes) 与用户身份声明 (Claims) 的映射关系。 - - - - -虽然 OAuth 2.0 没有定义获取用户身份信息的标准方式，但许多提供商实现了自己的端点。请查阅你的提供商文档，了解如何使用访问令牌 (Access token) 获取用户身份信息，以及在发起授权 (Authorization) 流程时获取该访问令牌 (Access token) 所需的参数。 - - - - -### 动态客户端注册 (Dynamic Client Registration) \{#dynamic-client-registration} - -本教程不要求动态客户端注册，但如果你希望自动化 MCP 客户端在授权 (Authorization) 服务器的注册流程，它会很有用。详见 [是否需要动态客户端注册？](/provider-list#is-dcr-required)。 - -## 搭建 MCP 服务器 \{#set-up-the-mcp-server} - -我们将使用 [MCP 官方 SDK](https://github.com/modelcontextprotocol) 创建一个带有 `whoami` 工具的 MCP 服务器，用于从授权 (Authorization) 服务器获取用户身份信息。 - -### 创建新项目 (Create a new project) \{#create-a-new-project} - - - - -```bash -mkdir mcp-server -cd mcp-server -uv init # 或使用 `pipenv` 或 `poetry` 创建新虚拟环境 -``` - - - - -创建一个新的 Node.js 项目： - -```bash -mkdir mcp-server -cd mcp-server -npm init -y # 或使用 `pnpm init` -npm pkg set type="module" -npm pkg set main="whoami.js" -npm pkg set scripts.start="node whoami.js" -``` - - - - -### 安装 MCP SDK 及依赖 (Install the MCP SDK and dependencies) \{#install-the-mcp-sdk-and-dependencies} - - - - -```bash -pip install "mcp[cli]" starlette uvicorn -``` - -或使用你喜欢的其他包管理器，如 `uv` 或 `poetry`。 - - - - -```bash -npm install @modelcontextprotocol/sdk express -``` - -或使用你喜欢的其他包管理器，如 `pnpm` 或 `yarn`。 - - - - -### 创建 MCP 服务器 (Create the MCP server) \{#create-the-mcp-server} - -首先，让我们创建一个实现 `whoami` 工具的 MCP 服务器。 - - - - -创建名为 `whoami.py` 的文件，并添加如下代码： - -```python -from mcp.server.fastmcp import FastMCP -from starlette.applications import Starlette -from starlette.routing import Mount -from typing import Any - -mcp = FastMCP("WhoAmI") - -@mcp.tool() -def whoami() -> dict[str, Any]: - """返回当前用户信息的工具。""" - return {"error": "Not authenticated"} - -app = Starlette( - routes=[Mount('/', app=mcp.sse_app())] -) -``` - -使用以下命令运行服务器： - -```bash -uvicorn whoami:app --host 0.0.0.0 --port 3001 -``` - - - - -:::note -由于当前 MCP inspector 实现尚未处理授权 (Authorization) 流程，我们将使用 SSE 方式搭建 MCP 服务器。待 MCP inspector 支持授权 (Authorization) 流程后，我们会更新此处代码。 -::: - -你也可以使用 `pnpm` 或 `yarn`。 - -创建名为 `whoami.js` 的文件，并添加如下代码： - -```js -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; -import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'; -import express from 'express'; - -// 创建 MCP 服务器 -const server = new McpServer({ - name: 'WhoAmI', - version: '0.0.0', -}); - -// 添加一个返回当前用户信息的工具 -server.tool('whoami', async () => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Not authenticated' }) }], - }; -}); - -// 以下为 MCP SDK 文档中的样板代码 -const PORT = 3001; -const app = express(); - -const transports = {}; - -app.get('/sse', async (_req, res) => { - const transport = new SSEServerTransport('/messages', res); - transports[transport.sessionId] = transport; - - res.on('close', () => { - delete transports[transport.sessionId]; - }); - - await server.connect(transport); -}); - -app.post('/messages', async (req, res) => { - const sessionId = String(req.query.sessionId); - const transport = transports[sessionId]; - if (transport) { - await transport.handlePostMessage(req, res, req.body); - } else { - res.status(400).send('No transport found for sessionId'); - } -}); - -app.listen(PORT); -``` - -使用以下命令运行服务器： - -```bash -npm start -``` - - - - -## 检查 MCP 服务器 (Inspect the MCP server) \{#inspect-the-mcp-server} - -### 克隆并运行 MCP inspector (Clone and run MCP inspector) \{#clone-and-run-mcp-inspector} - -现在 MCP 服务器已运行，我们可以使用 MCP inspector 检查 `whoami` 工具是否可用。 - -由于当前实现的限制，我们 fork 了 [MCP inspector](https://github.com/mcp-auth/inspector)，使其在认证 (Authentication) 和授权 (Authorization) 方面更灵活和可扩展。我们也已向原仓库提交了 pull request。 - -运行 MCP inspector，可使用以下命令（需要 Node.js）： - -```bash -git clone https://github.com/mcp-auth/inspector.git -cd inspector -npm install -npm run dev -``` - -然后，在浏览器中打开 `http://localhost:6274/`（或终端显示的其他 URL）访问 MCP inspector。 - -### 连接 MCP inspector 到 MCP 服务器 (Connect MCP inspector to the MCP server) \{#connect-mcp-inspector-to-the-mcp-server} - -在继续之前，请检查 MCP inspector 中的以下配置： - -- **Transport Type**：设置为 `SSE`。 -- **URL**：设置为你的 MCP 服务器的 URL。此处应为 `http://localhost:3001/sse`。 - -现在你可以点击“Connect”按钮，查看 MCP inspector 是否能连接到 MCP 服务器。如果一切正常，你将在 MCP inspector 中看到“Connected”状态。 - -### 检查点：运行 `whoami` 工具 (Checkpoint: Run the `whoami` tool) \{#checkpoint-run-the-whoami-tool} - -1. 在 MCP inspector 顶部菜单点击 "Tools" 标签页。 -2. 点击 "List Tools" 按钮。 -3. 你应该能在页面上看到 `whoami` 工具，点击它查看工具详情。 -4. 在右侧你会看到 "Run Tool" 按钮，点击运行该工具。 -5. 你将看到工具返回的 JSON 响应 `{"error": "Not authenticated"}`。 - -![MCP inspector 首次运行](/docs-assets/images/tutorials/whoami/inspector-first-run.png) - -## 集成你的授权 (Authorization) 服务器 (Integrate with your authorization server) \{#integrate-with-your-authorization-server} - -完成本节内容时，你需要考虑以下事项： - -
-**你的授权 (Authorization) 服务器的发行者 (Issuer) URL** - -通常是你的授权 (Authorization) 服务器的基础 URL，如 `https://auth.example.com`。有些提供商可能是类似 `https://example.logto.app/oidc` 的路径，请查阅你的提供商文档。 - -
- -
-**如何获取授权 (Authorization) 服务器元数据** - -- 如果你的授权 (Authorization) 服务器符合 [OAuth 2.0 授权服务器元数据](https://datatracker.ietf.org/doc/html/rfc8414) 或 [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)，你可以使用 MCP Auth 内置工具自动获取元数据。 -- 如果不符合这些标准，你需要在 MCP 服务器配置中手动指定元数据 URL 或端点。请查阅你的提供商文档获取具体端点。 - -
- -
-**如何将 MCP inspector 注册为授权 (Authorization) 服务器的客户端** - -- 如果你的授权 (Authorization) 服务器支持 [动态客户端注册 (Dynamic Client Registration)](https://datatracker.ietf.org/doc/html/rfc7591)，可以跳过此步骤，MCP inspector 会自动注册为客户端。 -- 如果不支持动态客户端注册，你需要手动在授权 (Authorization) 服务器中注册 MCP inspector 为客户端。 - -
- -
-**如何获取用户身份信息以及如何配置授权 (Authorization) 请求参数** - -- 对于 OpenID Connect 提供商：通常在发起授权 (Authorization) 流程时需要请求至少 `openid` 和 `profile` 权限 (Scopes)。这样授权 (Authorization) 服务器返回的访问令牌 (Access token) 就包含访问 [userinfo 端点](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 所需的权限 (Scopes)。 - - 注意：部分提供商可能不支持 userinfo 端点。 - -- 对于 OAuth 2.0 / OAuth 2.1 提供商：请查阅你的提供商文档，了解如何使用访问令牌 (Access token) 获取用户身份信息，以及发起授权 (Authorization) 流程时获取该访问令牌 (Access token) 所需的参数。 - -
- -虽然每个提供商可能有自己的具体要求，以下步骤将指导你如何结合 MCP inspector 和 MCP 服务器进行针对不同提供商的配置集成。 - -### 注册 MCP inspector 为客户端 (Register MCP inspector as a client) \{#register-mcp-inspector-as-a-client} - - - - -与 [Logto](https://logto.io) 集成非常简单，因为它是一个支持标准 [userinfo 端点](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 的 OpenID Connect 提供商。 - -由于 Logto 目前尚不支持动态客户端注册 (Dynamic Client Registration)，你需要手动在 Logto 租户中注册 MCP inspector 为客户端： - -1. 打开 MCP inspector，点击 "OAuth Configuration" 按钮。复制 **Redirect URL (auto-populated)**，如 `http://localhost:6274/oauth/callback`。 -2. 登录 [Logto Console](https://cloud.logto.io)（或你的自托管 Logto Console）。 -3. 进入 "Applications" 标签页，点击 "Create application"。在页面底部点击 "Create app without framework"。 -4. 填写应用详情，然后点击 "Create application"： - - **选择应用类型**：选择 "Single-page application"。 - - **应用名称**：如 "MCP Inspector"。 -5. 在 "Settings / Redirect URIs" 区域，粘贴刚才复制的 **Redirect URL (auto-populated)**，然后点击底部栏的 "Save changes"。 -6. 在顶部卡片中，你会看到 "App ID"。复制它。 -7. 回到 MCP inspector，在 "OAuth Configuration" 区域的 "Client ID" 字段粘贴 "App ID"。 -8. 在 "Auth Params" 字段输入 `{"scope": "openid profile email"}`，确保 Logto 返回的访问令牌 (Access token) 包含访问 userinfo 端点所需的权限 (Scopes)。 - - - - -[Keycloak](https://www.keycloak.org) 是一个开源身份和访问管理解决方案，支持 OpenID Connect 协议。 - -虽然 Keycloak 支持动态客户端注册 (Dynamic Client Registration)，但其客户端注册端点不支持 CORS，导致大多数 MCP 客户端无法直接注册。因此，我们需要手动注册客户端。 - -:::note -Keycloak 可通过 [多种方式](https://www.keycloak.org/guides#getting-started) 安装（裸机、kubernetes 等），本教程采用 Docker 快速搭建。 -::: - -让我们搭建 Keycloak 实例并进行配置： - -1. 按 [官方文档](https://www.keycloak.org/getting-started/getting-started-docker) 使用 Docker 运行 Keycloak： - -```bash -docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.2.4 start-dev -``` - -2. 访问 Keycloak 管理控制台 (http://localhost:8080/admin)，使用以下凭据登录： - - - 用户名：`admin` - - 密码：`admin` - -3. 创建新 Realm： - - - 左上角点击 "Create Realm" - - "Realm name" 填写 `mcp-realm` - - 点击 "Create" - -4. 创建测试用户： - - - 左侧菜单点击 "Users" - - 点击 "Create new user" - - 填写用户信息： - - 用户名：`testuser` - - 名字和姓氏可任意填写 - - 点击 "Create" - - 在 "Credentials" 标签页设置密码，并取消勾选 "Temporary" - -5. 注册 MCP Inspector 为客户端： - - - 打开 MCP inspector，点击 "OAuth Configuration" 按钮。复制 **Redirect URL (auto-populated)**，如 `http://localhost:6274/oauth/callback`。 - - 在 Keycloak 管理控制台左侧点击 "Clients" - - 点击 "Create client" - - 填写客户端信息： - - Client type: 选择 "OpenID Connect" - - Client ID: 输入 `mcp-inspector` - - 点击 "Next" - - "Capability config" 页面： - - 确保 "Standard flow" 已启用 - - 点击 "Next" - - "Login settings" 页面： - - 在 "Valid redirect URIs" 粘贴 MCP Inspector 回调 URL - - "Web origins" 填写 `http://localhost:6274` - - 点击 "Save" - - 复制 "Client ID"（即 `mcp-inspector`） - -6. 回到 MCP Inspector： - - 在 "OAuth Configuration" 区域的 "Client ID" 字段粘贴复制的 Client ID - - 在 "Auth Params" 字段输入以下内容以请求所需权限 (Scopes)： - -```json -{ "scope": "openid profile email" } -``` - - - - -:::note -这是通用 OpenID Connect 提供商集成指南。具体细节请查阅你的提供商文档。 -::: - -如果你的 OpenID Connect 提供商支持动态客户端注册 (Dynamic Client Registration)，可直接跳到第 8 步配置 MCP inspector；否则需手动注册 MCP inspector 为客户端： - -1. 打开 MCP inspector，点击 "OAuth Configuration" 按钮。复制 **Redirect URL (auto-populated)**，如 `http://localhost:6274/oauth/callback`。 -2. 登录你的 OpenID Connect 提供商控制台。 -3. 进入 "Applications" 或 "Clients" 区域，创建新应用或客户端。 -4. 如需选择客户端类型，选择 "Single-page application" 或 "Public client"。 -5. 创建应用后，需配置重定向 URI。粘贴刚才复制的 **Redirect URL (auto-populated)**。 -6. 找到新建应用的 "Client ID" 或 "Application ID"，复制它。 -7. 回到 MCP inspector，在 "OAuth Configuration" 区域的 "Client ID" 字段粘贴该值。 -8. 对于标准 OpenID Connect 提供商，可在 "Auth Params" 字段输入以下内容以请求访问 userinfo 端点所需权限 (Scopes)： - -```json -{ "scope": "openid profile email" } -``` - - - - -:::note -这是通用 OAuth 2.0 / OAuth 2.1 提供商集成指南。具体细节请查阅你的提供商文档。 -::: - -如果你的 OAuth 2.0 / OAuth 2.1 提供商支持动态客户端注册 (Dynamic Client Registration)，可直接跳到第 8 步配置 MCP inspector；否则需手动注册 MCP inspector 为客户端： - -1. 打开 MCP inspector，点击 "OAuth Configuration" 按钮。复制 **Redirect URL (auto-populated)**，如 `http://localhost:6274/oauth/callback`。 -2. 登录你的 OAuth 2.0 / OAuth 2.1 提供商控制台。 -3. 进入 "Applications" 或 "Clients" 区域，创建新应用或客户端。 -4. 如需选择客户端类型，选择 "Single-page application" 或 "Public client"。 -5. 创建应用后，需配置重定向 URI。粘贴刚才复制的 **Redirect URL (auto-populated)**。 -6. 找到新建应用的 "Client ID" 或 "Application ID"，复制它。 -7. 回到 MCP inspector，在 "OAuth Configuration" 区域的 "Client ID" 字段粘贴该值。 -8. 查阅你的提供商文档，了解如何获取用于用户身份信息的访问令牌 (Access token)。你可能需要指定获取访问令牌 (Access token) 所需的权限 (Scopes) 或参数。例如，如果你的提供商要求 `profile` 权限 (Scope) 才能访问用户身份信息，可在 "Auth Params" 字段输入： - -```json -{ "scope": "profile" } -``` - - - - -### 配置 MCP Auth (Set up MCP auth) \{#set-up-mcp-auth} - -在你的 MCP 服务器项目中，需要安装 MCP Auth SDK 并配置其使用你的授权 (Authorization) 服务器元数据。 - - - - -首先，安装 `mcpauth` 包： - -```bash -pip install mcpauth -``` - -或使用你喜欢的其他包管理器，如 `uv` 或 `poetry`。 - - - - -首先，安装 `mcp-auth` 包： - -```bash -npm install mcp-auth -``` - - - - -MCP Auth 需要授权 (Authorization) 服务器元数据以完成初始化。根据你的提供商： - - - - - -发行者 (Issuer) URL 可在 Logto Console 的应用详情页 "Endpoints & Credentials / Issuer endpoint" 区域找到，类似 `https://my-project.logto.app/oidc`。 - - - - - - - -发行者 (Issuer) URL 可在 Keycloak 管理控制台找到。在你的 'mcp-realm' 下，进入 "Realm settings / Endpoints" 区域，点击 "OpenID Endpoint Configuration" 链接。JSON 文档中的 `issuer` 字段即为你的发行者 (Issuer) URL，类似 `http://localhost:8080/realms/mcp-realm`。 - - - - - - - -以下代码同样假设授权 (Authorization) 服务器支持 [userinfo 端点](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 用于获取用户身份信息。如果你的提供商不支持该端点，请查阅文档获取具体端点，并将 userinfo 端点变量替换为正确的 URL。 - - - - - - -如前所述，OAuth 2.0 没有定义获取用户身份信息的标准方式。以下代码假设你的提供商有专门的端点用于通过访问令牌 (Access token) 获取用户身份信息。请查阅你的提供商文档获取具体端点，并将 userinfo 端点变量替换为正确的 URL。 - - - - - - -### 更新 MCP 服务器 (Update MCP server) \{#update-mcp-server} - -我们快完成了！现在需要更新 MCP 服务器，应用 MCP Auth 路由和中间件函数，并让 `whoami` 工具返回实际的用户身份信息。 - - - - -```python -@mcp.tool() -def whoami() -> dict[str, Any]: - """返回当前用户信息的工具。""" - return ( - mcp_auth.auth_info.claims - if mcp_auth.auth_info # 由 Bearer auth 中间件填充 - else {"error": "Not authenticated"} - ) - -# ... - -bearer_auth = Middleware(mcp_auth.bearer_auth_middleware(verify_access_token)) -app = Starlette( - routes=[ - # 添加元数据路由 (`/.well-known/oauth-authorization-server`) - mcp_auth.metadata_route(), - # 用 Bearer auth 中间件保护 MCP 服务器 - Mount('/', app=mcp.sse_app(), middleware=[bearer_auth]), - ], -) -``` - - - - -```js -server.tool('whoami', ({ authInfo }) => { - return { - content: [ - { type: 'text', text: JSON.stringify(authInfo?.claims ?? { error: 'Not authenticated' }) }, - ], - }; -}); - -// ... - -app.use(mcpAuth.delegatedRouter()); -app.use(mcpAuth.bearerAuth(verifyToken)); -``` - - - - -## 检查点：带认证 (Authentication) 运行 `whoami` 工具 (Checkpoint: Run the `whoami` tool with authentication) \{#checkpoint-run-the-whoami-tool-with-authentication} - -重启你的 MCP 服务器，并在浏览器中打开 MCP inspector。当你点击 "Connect" 按钮时，应会被重定向到授权 (Authorization) 服务器的登录页面。 - -登录后返回 MCP inspector，重复上一个检查点的操作运行 `whoami` 工具。这一次，你应该能看到授权 (Authorization) 服务器返回的用户身份信息。 - -![MCP inspector whoami 工具结果](/docs-assets/images/tutorials/whoami/result.png) - - - - -:::info -完整 MCP 服务器（OIDC 版本）代码请参考 [MCP Auth Python SDK 仓库](https://github.com/mcp-auth/python/blob/master/samples/server/whoami.py)。 -::: - - - - -:::info -完整 MCP 服务器（OIDC 版本）代码请参考 [MCP Auth Node.js SDK 仓库](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src)。该目录包含 TypeScript 和 JavaScript 版本。 -::: - - - - -## 结语 (Closing notes) \{#closing-notes} - -🎊 恭喜你！你已成功完成本教程。让我们回顾一下所做的内容： - -- 搭建了带有 `whoami` 工具的基础 MCP 服务器 -- 使用 MCP Auth 将 MCP 服务器与授权 (Authorization) 服务器集成 -- 配置 MCP Inspector 以认证 (Authentication) 用户并获取其身份信息 - -你还可以探索一些进阶主题，包括： - -- 使用 [JWT (JSON Web Token)](https://auth.wiki/jwt) 进行认证 (Authentication) 和授权 (Authorization) -- 利用 [资源指示器 (resource indicators, RFC 8707)](https://auth-wiki.logto.io/resource-indicator) 指定被访问的资源 -- 实现自定义访问控制机制，如 [基于角色的访问控制 (RBAC)](https://auth.wiki/rbac) 或 [基于属性的访问控制 (ABAC)](https://auth.wiki/abac) - -欢迎查阅更多教程和文档，充分发挥 MCP Auth 的能力。 \ No newline at end of file diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_manual-metadata-fetching.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_manual-metadata-fetching.mdx deleted file mode 100644 index e7d6c24..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_manual-metadata-fetching.mdx +++ /dev/null @@ -1,3 +0,0 @@ -:::note -如果你的提供商不支持 {props.oidc ? 'OpenID Connect Discovery' : 'OAuth 2.0 授权服务器元数据 (Authorization Server Metadata)' }，你可以手动指定元数据 URL 或端点。详见 [其他初始化 MCP Auth 的方式](../../configure-server/mcp-auth.mdx#other-ways)。 -::: \ No newline at end of file diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oauth.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oauth.mdx deleted file mode 100644 index 0e305b0..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oauth.mdx +++ /dev/null @@ -1,138 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -更新 `whoami.py`，加入 MCP Auth 配置： - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # 替换为你的发行者 (Issuer) 端点 -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OAUTH) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -更新 `whoami.js`，加入 MCP Auth 配置： - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // 替换为你的发行者 (Issuer) 端点 -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oauth' }), -}); -``` - - - - - - - -现在，我们需要创建一个自定义访问令牌 (Access token) 验证器，用于通过 MCP inspector 提供的访问令牌 (Access token) 从授权 (Authorization) 服务器获取用户身份信息。 - - - - -```python -import pydantic -import requests -from mcpauth.exceptions import ( - MCPAuthTokenVerificationException, - MCPAuthTokenVerificationExceptionCode, -) -from mcpauth.types import AuthInfo - -def verify_access_token(token: str) -> AuthInfo: - """ - 通过从授权 (Authorization) 服务器获取用户信息来验证提供的 Bearer 令牌 (Token)。 - 如果令牌 (Token) 有效，则返回包含用户信息的 `AuthInfo` 对象。 - - :param token: 从 MCP inspector 接收到的 Bearer 令牌 (Token)。 - """ - - try: - # 以下代码假设你的授权 (Authorization) 服务器有一个用于通过授权 (Authorization) 流程颁发的访问令牌 (Access token) - # 获取用户信息的端点。请根据你的提供商 API 调整 URL 和 headers。 - response = requests.get( - "https://your-authorization-server.com/userinfo", - headers={"Authorization": f"Bearer {token}"}, - ) - response.raise_for_status() # 确保 HTTP 错误时抛出异常 - json = response.json() # 解析 JSON 响应 - - # 以下代码假设用户信息响应对象中有一个 'sub' 字段用于标识用户。 - # 你可能需要根据你的提供商 API 进行调整。 - return AuthInfo( - token=token, - subject=json.get("sub"), - issuer=auth_issuer, # 使用配置的发行者 (Issuer) - claims=json, # 包含端点返回的所有声明 (Claims)（JSON 字段） - ) - # `AuthInfo` 是一个 Pydantic 模型，因此验证错误通常意味着响应结构与预期不符 - except pydantic.ValidationError as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.INVALID_TOKEN, - cause=e, - ) - # 处理请求过程中可能发生的其他异常 - except Exception as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.TOKEN_VERIFICATION_FAILED, - cause=e, - ) -``` - - - - -```js -import { MCPAuthTokenVerificationError } from 'mcp-auth'; - -/** - * 通过从授权 (Authorization) 服务器获取用户信息来验证提供的 Bearer 令牌 (Token)。 - * 如果令牌 (Token) 有效，则返回包含用户信息的 `AuthInfo` 对象。 - */ -const verifyToken = async (token) => { - // 以下代码假设你的授权 (Authorization) 服务器有一个用于通过授权 (Authorization) 流程颁发的访问令牌 (Access token) - // 获取用户信息的端点。请根据你的提供商 API 调整 URL 和 headers。 - const response = await fetch('https://your-authorization-server.com/userinfo', { - headers: { Authorization: `Bearer ${token}` }, - }); - - if (!response.ok) { - throw new MCPAuthTokenVerificationError('token_verification_failed', response); - } - - const userInfo = await response.json(); - - // 以下代码假设用户信息响应对象中有一个 'sub' 字段用于标识用户。 - // 你可能需要根据你的提供商 API 进行调整。 - if (typeof userInfo !== 'object' || userInfo === null || !('sub' in userInfo)) { - throw new MCPAuthTokenVerificationError('invalid_token', response); - } - - return { - token, - issuer: authIssuer, - subject: String(userInfo.sub), // 根据你的提供商用户 ID 字段进行调整 - clientId: '', // 本示例未使用 Client ID，如有需要可设置 - scopes: [], - claims: userInfo, - }; -}; -``` - - - diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oidc.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oidc.mdx deleted file mode 100644 index a9c5db8..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oidc.mdx +++ /dev/null @@ -1,142 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -更新 `whoami.py`，加入 MCP Auth 配置： - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # 替换为你的发行者 (Issuer) 端点 -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -更新 `whoami.js`，加入 MCP Auth 配置： - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // 替换为你的发行者 (Issuer) 端点 -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oidc' }), -}); -``` - - - - -{props.showAlternative && } -{props.showAlternative && } - -现在，我们需要创建一个自定义访问令牌 (Access token) 校验器，用于通过 MCP inspector 提供的访问令牌 (Access token) 从授权服务器获取用户身份信息。 - - - - -```python -import pydantic -import requests -from mcpauth.exceptions import ( - MCPAuthTokenVerificationException, - MCPAuthTokenVerificationExceptionCode, -) -from mcpauth.types import AuthInfo - -def verify_access_token(token: str) -> AuthInfo: - """ - 通过从授权服务器获取用户信息来校验提供的 Bearer 令牌 (Access token)。 - 如果令牌有效，则返回包含用户信息的 `AuthInfo` 对象。 - - :param token: 从 MCP inspector 接收到的 Bearer 令牌 (Access token)。 - """ - - issuer = auth_server_config.metadata.issuer - endpoint = auth_server_config.metadata.userinfo_endpoint # 提供方应支持 userinfo endpoint - if not endpoint: - raise ValueError( - "Auth server metadata 中未配置 userinfo endpoint。" - ) - - try: - response = requests.get( - endpoint, - headers={"Authorization": f"Bearer {token}"}, # 标准 Bearer 令牌 (Access token) 头 - ) - response.raise_for_status() # 确保 HTTP 错误时抛出异常 - json = response.json() # 解析 JSON 响应 - return AuthInfo( - token=token, - subject=json.get("sub"), # 'sub' 是主体 (Subject)（用户 ID）的标准声明 (Claim) - issuer=issuer, # 使用元数据中的发行者 (Issuer) - claims=json, # 包含 userinfo endpoint 返回的所有声明 (Claims)（JSON 字段） - ) - # `AuthInfo` 是 Pydantic 模型，校验错误通常意味着响应结构不匹配预期 - except pydantic.ValidationError as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.INVALID_TOKEN, - cause=e, - ) - # 处理请求过程中可能发生的其他异常 - except Exception as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.TOKEN_VERIFICATION_FAILED, - cause=e, - ) -``` - - - - -```js -import { MCPAuthTokenVerificationError } from 'mcp-auth'; - -/** - * 通过从授权服务器获取用户信息来校验提供的 Bearer 令牌 (Access token)。 - * 如果令牌有效，则返回包含用户信息的 `AuthInfo` 对象。 - */ -const verifyToken = async (token) => { - const { issuer, userinfoEndpoint } = mcpAuth.config.server.metadata; - - if (!userinfoEndpoint) { - throw new Error('Server metadata 中未配置 userinfo endpoint'); - } - - const response = await fetch(userinfoEndpoint, { - headers: { Authorization: `Bearer ${token}` }, - }); - - if (!response.ok) { - throw new MCPAuthTokenVerificationError('token_verification_failed', response); - } - - const userInfo = await response.json(); - - if (typeof userInfo !== 'object' || userInfo === null || !('sub' in userInfo)) { - throw new MCPAuthTokenVerificationError('invalid_token', response); - } - - return { - token, - issuer, - subject: String(userInfo.sub), // 'sub' 是主体 (Subject)（用户 ID）的标准声明 (Claim) - clientId: '', // 本示例未使用 Client ID，如有需要可设置 - scopes: [], - claims: userInfo, - }; -}; -``` - - - diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_transpile-metadata.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_transpile-metadata.mdx deleted file mode 100644 index f0200fb..0000000 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_transpile-metadata.mdx +++ /dev/null @@ -1,31 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -在某些情况下，提供方的响应可能格式错误或不符合预期的元数据格式。如果你确信该提供方是合规的，你可以通过配置选项对元数据进行转译： - - - - -```python -mcp_auth = MCPAuth( - server=fetch_server_config( - # ...其他选项 - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { - // ...其他选项 - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1.json b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1.json deleted file mode 100644 index 17dfa6e..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1.json +++ /dev/null @@ -1,50 +0,0 @@ -{ - "sidebar.docsSidebar.category.Tutorials": { - "message": "教學", - "description": "The label for category Tutorials in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.Tutorials.link.generated-index.title": { - "message": "教學", - "description": "The generated-index page title for category Tutorials in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.Configure MCP server": { - "message": "設定 MCP 伺服器", - "description": "The label for category Configure MCP server in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.Configure MCP server.link.generated-index.title": { - "message": "設定 MCP 伺服器", - "description": "The generated-index page title for category Configure MCP server in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.SDK references": { - "message": "SDK 參考", - "description": "The label for category SDK references in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.SDK references.link.generated-index.title": { - "message": "MCP Auth SDK 參考", - "description": "The generated-index page title for category SDK references in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.SDK references.link.generated-index.description": { - "message": "從 MCP Auth SDK 中擷取的類別、方法和屬性資訊。\n", - "description": "The generated-index page description for category SDK references in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.Node.js SDK": { - "message": "Node.js SDK", - "description": "The label for category Node.js SDK in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.classes": { - "message": "類別", - "description": "The label for category classes in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.functions": { - "message": "函式", - "description": "The label for category functions in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.type-aliases": { - "message": "型別別名", - "description": "The label for category type-aliases in sidebar docsSidebar" - }, - "sidebar.docsSidebar.category.variables": { - "message": "變數", - "description": "The label for category variables in sidebar docsSidebar" - } -} diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/README.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/README.mdx deleted file mode 100644 index fb42c69..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/README.mdx +++ /dev/null @@ -1,242 +0,0 @@ ---- -sidebar_position: 1 -sidebar_label: 快速開始 ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -# 快速開始 - -## 選擇相容的 OAuth 2.1 或 OpenID Connect 提供者 \{#choose-a-compatible-oauth-2-1-or-openid-connect-provider} - -MCP 規範對授權 (Authorization) 有一些[特定要求](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization#1-3-standards-compliance)： - -- [OAuth 2.1 IETF DRAFT](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12) -- OAuth 2.0 授權伺服器中繼資料 (Authorization Server Metadata)（[RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)） -- OAuth 2.0 動態用戶端註冊協議（Dynamic Client Registration Protocol，[RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)） - -雖然後兩者不是強制性的，但第一項是確保安全且合規實作所必需的。 - -:::note -在新的 MCP 草案中，RFC 8414 將成為授權伺服器（提供者）的強制要求。待新草案定稿後，我們會更新文件。 -::: - -你可以查看 [MCP 相容提供者清單](/provider-list)來確認你的提供者是否受支援。 - -## 安裝 MCP Auth SDK \{#install-mcp-auth-sdk} - -MCP Auth 同時支援 Python 與 TypeScript。如果你需要其他語言或框架的支援，歡迎告訴我們！ - - - - -```bash -pip install mcpauth -``` - -或使用你偏好的其他套件管理工具，例如 pipenv 或 poetry。 - - - - -```bash -npm install mcp-auth -``` - -或使用你偏好的其他套件管理工具，例如 pnpm 或 yarn。 - - - - -## 初始化 MCP Auth \{#init-mcp-auth} - -第一步是用你的提供者授權伺服器中繼資料初始化 MCP Auth 實例。如果你的提供者符合下列其中一項： - -- [OAuth 2.0 授權伺服器中繼資料 (Authorization Server Metadata)](https://datatracker.ietf.org/doc/html/rfc8414) -- [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) - -你可以使用內建函式來擷取中繼資料並初始化 MCP Auth 實例： - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -mcp_auth = MCPAuth( - server=fetch_server_config( - '', - type=AuthServerType.OIDC # 或 AuthServerType.OAUTH - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { type: 'oidc' }), // 或 'oauth' -}); -``` - - - - -如果你需要手動指定中繼資料 URL 或端點，請參考 [其他初始化 MCP Auth 的方式](./configure-server/mcp-auth.mdx#other-ways)。 - -## 掛載中繼資料端點 \{#mount-the-metadata-endpoint} - -為符合現行 MCP 規範，MCP Auth 會將 OAuth 2.0 授權伺服器中繼資料端點（`/.well-known/oauth-authorization-server`）掛載到你的 MCP 伺服器： - - - - -```python -from starlette.applications import Starlette - -app = Starlette(routes=[ - mcp_auth.metadata_route(), -]) -``` - - - - -```ts -import express from 'express'; - -const app = express(); -app.use(mcpAuth.delegatedRouter()); -``` - - - - -中繼資料中的 URL 會保持原樣，因此授權伺服器的角色完全委託給提供者。你可以在 MCP 伺服器上造訪 `/.well-known/oauth-authorization-server` 測試中繼資料端點。 - -### 為什麼只掛載中繼資料端點？ \{#why-only-the-metadata-endpoint} - -你可能會看到官方 SDK 提供一個 auth router，會掛載 `/authorize`、`/token` 等授權端點。我們不這麼做的原因如下： - -1. 僅掛載中繼資料端點，讓你能充分利用提供者的所有能力，無需「重新造輪子」並為 MCP 伺服器引入不必要的複雜度。 -2. 目前也正推動將 [MCP 伺服器角色轉為資源伺服器 (resource server)](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/205)，並要求支援 OAuth 2.0 受保護資源中繼資料（Protected Resource Metadata，[RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728)）。這代表 MCP 伺服器將**不再處理任何授權邏輯**（包含中繼資料端點），僅作為資源伺服器，並依賴提供者進行驗證 (Authentication) 與授權 (Authorization)。 - -:::note -當新 MCP 規範定稿後，我們會更新 MCP Auth 以支援新版規範。在此之前，你可以繼續使用目前版本，與現行規範相容。 -::: - -## 使用 Bearer 驗證中介軟體 \{#use-the-bearer-auth-middleware} - -初始化 MCP Auth 實例後，你可以套用 Bearer 驗證中介軟體來保護你的 MCP 路由： - - - - -```python -from starlette.applications import Starlette -from starlette.middleware import Middleware -from starlette.routing import Mount -from mcpauth import MCPAuth -from mcp.server.fastmcp import FastMCP - -mcp = FastMCP() -mcp_auth = MCPAuth( - # 用你的授權伺服器設定初始化 -) -bearer_auth = mcp_auth.bearer_auth_middleware( - "jwt", required_scopes=["read", "write"] -) - -app = Starlette(routes=[ - mcp_auth.metadata_route(), - Mount( - "/", - app=mcp.sse_app(), - middleware=[Middleware(bearer_auth)], - ), -]) -``` - - - - -```ts -import express from 'express'; -import { MCPAuth } from 'mcp-auth'; - -const app = express(); -const server = new McpServer(/* ... */); -const mcpAuth = new MCPAuth({ - /* ... */ -}); - -app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] })); -``` - - - - -在上述範例中，我們指定了 `jwt` 權杖類型，並要求 `read` 和 `write` 權限範圍 (scopes)。這會自動驗證 JWT (JSON Web Token)，並將驗證後的使用者資訊填入物件中。 - -:::info -沒聽過 JWT (JSON Web Token) 嗎？別擔心，繼續閱讀文件，我們會在需要時說明。你也可以參考 [Auth Wiki](https://auth.wiki/jwt) 取得快速介紹。 -::: - -更多 Bearer 驗證設定資訊，請參考 [設定 Bearer 驗證](./configure-server/bearer-auth.mdx)。 - -## 在 MCP 實作中取得驗證資訊 \{#retrieve-the-auth-info-in-your-mcp-implementation} - -套用 Bearer 驗證中介軟體後，你可以在 MCP 實作中存取已驗證使用者（或身分）的資訊： - - - - -套用 Bearer 驗證中介軟體後，MCP Auth 會將已驗證使用者資訊存入 context 變數。你可以在 MCP 工具處理函式中這樣存取： - -```python -from mcp.server.fastmcp import FastMCP - -mcp = FastMCP() -mcp_auth = MCPAuth( - # 用你的授權伺服器設定初始化 -) - -@mcp.tool() -def add(a: int, b: int): - """ - 一個加總兩數的工具。 - 已驗證使用者資訊會在 context 中可用。 - """ - auth_info = mcp_auth.auth_info # 於目前 context 取得驗證資訊 - if auth_info: - print(f"Authenticated user: {auth_info.claims}") - return a + b -``` - - - - -工具處理函式的第二個參數會包含 `authInfo` 物件，其中包含已驗證使用者資訊： - -```ts -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; -import { z } from 'zod'; - -const server = new McpServer(/* ... */); -server.tool('add', { a: z.number(), b: z.number() }, async ({ a, b }, { authInfo }) => { - // 現在你可以使用 `authInfo` 物件存取驗證資訊 -}); -``` - - - - -## 下一步 \{#next-steps} - -繼續閱讀，學習如何將 MCP Auth 與你的 MCP 伺服器整合的端到端範例，以及如何在 MCP 用戶端處理驗證流程。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/comparison.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/comparison.mdx deleted file mode 100644 index 8a104bf..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/comparison.mdx +++ /dev/null @@ -1,80 +0,0 @@ ---- -sidebar_position: 101 -sidebar_label: 比較 (Comparison) ---- - -# 在 MCP Auth 與其他解決方案之間的選擇 - -MCP 生態系正在演進。隨著 Model Context Protocol (MCP) 規範從「授權伺服器」模式轉向全新的「資源伺服器 + 第三方身分提供者 (IdP, Identity Provider)」模型，了解不同整合方案目前與未來的適用情境變得格外重要。 - -本頁將概述 mcp-auth 與其他主流解決方案的主要差異，協助你為專案選擇最佳方案。 - -## 背景：代理 (Proxy) 模式 vs. IdP 整合 \{#background-proxy-approach-vs-idp-integration} - -現有多數 MCP 驗證 (Authentication) 解決方案採用「代理 (Proxy) 模式」。在此模型下，MCP 伺服器會將授權 (Authorization) 請求代理給第三方身分提供者 (IdP)，實際上充當用戶端與 IdP 之間的中介。 - -**代理 (Proxy) 模式（[03-26 規範](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization)）** - -```mermaid -sequenceDiagram - participant Client as 用戶端 (Client) - participant MCP_Server as MCP 伺服器 (MCP server) - participant ThirdParty_IdP as 第三方 IdP (Third-party IdP) - - Client->>MCP_Server: 授權請求 (Authorization request) - MCP_Server->>ThirdParty_IdP: 代理請求 (Proxies request) - ThirdParty_IdP->>MCP_Server: 回應 (Response) - MCP_Server->>Client: 回應 (Response) - Client->>MCP_Server: 存取資源 (Access resource) - alt 遠端驗證 (Remote validation) - MCP_Server->>ThirdParty_IdP: 驗證權杖 (Validate token) - ThirdParty_IdP->>MCP_Server: 權杖有效 (Token valid) - else 本地驗證 (Local validation) - MCP_Server->>MCP_Server: 本地驗證權杖（例如快取 JWK）(Validate token locally (e.g., cached JWK)) - end - MCP_Server->>Client: 資源資料 (Resource data) -``` - -雖然這種方式符合現行（2025-03-26）MCP 規範，但本質上是一種權宜之計。它假設 MCP 伺服器同時扮演授權伺服器角色，這並非最新草案規範的發展方向。 - -**MCP Auth / 未來規範（資源伺服器 + 第三方 IdP）** - -```mermaid -sequenceDiagram - participant Client as 用戶端 (Client) - participant MCP_Server as MCP 伺服器 (MCP server) - participant ThirdParty_IdP as 第三方 IdP (Third-party IdP) - - Client->>ThirdParty_IdP: 授權請求 (Authorization request) - ThirdParty_IdP->>Client: 權杖 (Token) - Client->>MCP_Server: 存取資源（附帶權杖）(Access resource (with token)) - alt 遠端驗證 (Remote validation) - MCP_Server->>ThirdParty_IdP: 驗證權杖 (Validate token) - ThirdParty_IdP->>MCP_Server: 權杖有效 (Token valid) - else 本地驗證 (Local validation) - MCP_Server->>MCP_Server: 本地驗證權杖（例如快取 JWK）(Validate token locally (e.g., cached JWK)) - end - MCP_Server->>Client: 資源資料 (Resource data) -``` - -即將到來的 MCP 規範[將授權責任轉移給專責的第三方 IdP](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/205)。在此模型下，MCP 伺服器僅作為資源伺服器，所有授權端點皆直接來自第三方 IdP。 - -## 為什麼選擇 MCP Auth？\{#why-choose-mcp-auth} - -- 規範對齊：MCP Auth 直接遵循最新草案方向，是唯一同時相容 03-26 規範與未來規範的解決方案。 -- 不再需要權宜之計：MCP Auth 讓第三方 IdP 處理所有授權，無需再讓 MCP 伺服器充當授權伺服器代理，完全符合新規範設計初衷。 -- 不綁定特定供應商：MCP Auth 可搭配任何符合標準的 OAuth 2.0 / OIDC 供應商。 -- 平順轉換：MCP Auth 透過 OAuth 2.0 授權伺服器中繼資料，原樣返回所有第三方端點，讓整合現在簡單、未來也能無縫銜接。 -- 開發者體驗：提供教學、工具，以及即將推出的 [OAuth 2.0 受保護資源中繼資料 (Protected Resource Metadata)](https://auth.wiki/protected-resource-metadata) 等功能，讓 MCP 伺服器開發更輕鬆。 - -| 功能 (Feature) | 代理解決方案 (Proxy solutions) | MCP Auth | -| ---------------------------------- | ----------------------------- | -------- | -| 相容 03-26 規範 | ✅ | ✅ | -| 相容未來規範 | ❌ | ✅ | -| 直接支援第三方 IdP | ❌（僅權宜之計） | ✅ | -| 不綁定特定供應商 | 受限[^1] | 是 | -| 隨時可轉換 | ❌ | ✅ | - -如果你現在就需要支援第三方 IdP，並希望未來能無縫銜接新規範，MCP Auth 是推薦方案。基於代理的做法可能很快就會被棄用，或需大幅重構。 - -[^1]: 某些代理解決方案可能硬編碼特定參數或端點，降低彈性。 \ No newline at end of file diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/configure-server/bearer-auth.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/configure-server/bearer-auth.mdx deleted file mode 100644 index dbf60b7..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/configure-server/bearer-auth.mdx +++ /dev/null @@ -1,250 +0,0 @@ ---- -sidebar_position: 2 -sidebar_label: Bearer auth ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -# 在 MCP 伺服器中設定 Bearer 驗證 (Authentication) - -MCP Auth 提供多種方式，讓你在 MCP 伺服器中設定 Bearer 授權 (Authorization)： - -- [JWT (JSON Web Token)](https://auth.wiki/jwt) 模式：內建授權方法，透過宣告 (Claims) 驗證 JWT。 -- 自訂模式：允許你實作自己的授權邏輯。 - -## 使用 JWT 模式設定 Bearer 驗證 (Authentication) \{#configure-bearer-auth-with-jwt-mode} - -如果你的 OAuth / OIDC 提供者發行用於授權 (Authorization) 的 JWT，你可以在 MCP Auth 中使用內建的 JWT 模式。它會驗證 JWT 的簽章、過期時間，以及你指定的其他宣告 (Claims)；然後將驗證資訊填入請求上下文，供 MCP 實作進一步處理。 - -### 權限範圍 (Scope) 驗證 \{#scope-validation} - -以下是基本權限範圍驗證的範例： - - - - -```python -from mcpauth import MCPAuth -from starlette.applications import Starlette -from starlette.middleware import Middleware -from starlette.routing import Mount -from mcp.server.fastmcp import FastMCP - -mcp = FastMCP("MyMCPServer") -mcp_auth = MCPAuth( - # Initialize with your auth server config -) -bearer_auth = mcp_auth.bearer_auth_middleware("jwt", required_scopes=["read", "write"]) # [!code highlight] - -app = Starlette( - routes=[Mount('/', app=mcp.sse_app(), middleware=[Middleware(bearer_auth)])] -) -``` - - - - -```ts -import express from 'express'; -import { MCPAuth } from 'mcp-auth'; - -const app = express(); -const mcpAuth = new MCPAuth({ - /* ... */ -}); -const bearerAuth = mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }); // [!code highlight] - -app.use('/mcp', bearerAuth, (req, res) => { - // Now `req.auth` contains the auth info - console.log(req.auth); -}); -``` - - - - -在上述範例中，我們指定 JWT 需要包含 `read` 與 `write` 權限範圍 (Scopes)。如果 JWT 未包含**任一**這些權限範圍，請求將被拒絕並回傳 403 Forbidden 錯誤。 - -### 資源標示符 (Resource indicator) 驗證（RFC 8707）\{#resource-indicator-validation-rfc-8707} - -如果你的提供者基於 OIDC，或支援 [Resource Indicator](https://datatracker.ietf.org/doc/html/rfc8707) 擴充，你也可以指定 `audience` 選項來驗證 JWT 中的 `aud`（受眾 (Audience)）宣告 (Claim)。這有助於確保 JWT 是發給你的 MCP 伺服器。 - -請查閱你的提供者文件，確認是否支援 Resource Indicator 擴充及其設定方式。有些提供者可能會用「audience」、「API 資源 (API resource)」、「API indicator」等詞彙描述相同概念。 - -設定好資源標示符後，你可以在 `bearerAuth` middleware 中指定： - - - - -```python -bearer_auth = mcp_auth.bearer_auth_middleware( - "jwt", - audience="https://api.example.com/mcp", # JWT 預期的受眾 (Audience) [!code highlight] - required_scopes=["read", "write"] -) -``` - - - - -```ts -const bearerAuth = mcpAuth.bearerAuth('jwt', { - audience: 'https://api.example.com/mcp', // JWT 預期的受眾 (Audience) [!code highlight] - requiredScopes: ['read', 'write'], -}); -``` - - - - -在上述範例中，MCP Auth 會同時驗證 JWT 的 `aud` 宣告 (Claim) 與所需權限範圍 (Scopes)。 - -### 提供自訂選項給 JWT 驗證 \{#provide-custom-options-to-the-jwt-verification} - -你也可以為底層的 JWT 驗證函式庫提供自訂選項： - - - - -在 Python SDK 中，我們使用 [PyJWT](https://pyjwt.readthedocs.io/en/stable/) 進行 JWT 驗證。你可以設定以下選項： - -- `leeway`：驗證 JWT 過期時間時允許的寬限秒數，預設為 60 秒。 - -```python -bearer_auth = mcp_auth.bearer_auth_middleware( - "jwt", - audience="https://api.example.com/mcp", - required_scopes=["read", "write"] - leeway=10, # 允許 10 秒寬限，減少時鐘誤差 [!code highlight] -) -``` - - - - -在 Node.js SDK 中，我們使用 [jose](https://github.com/panva/jose) 函式庫進行 JWT 驗證。你可以提供以下選項： - -- `jwtVerify`：JWT 驗證流程的選項（`jose` 的 `jwtVerify` 函式）。 -- `remoteJwtSet`：遠端 JWT set 取得的選項（`jose` 的 `createRemoteJWKSet` 函式）。 - -```ts {4-9} -const bearerAuth = mcpAuth.bearerAuth('jwt', { - audience: 'https://api.example.com/mcp', - requiredScopes: ['read', 'write'], - jwtVerify: { - clockTolerance: 60, // 允許 60 秒時鐘誤差 - }, - remoteJwtSet: { - timeoutDuration: 10 * 1000, // 取得遠端 JWT set 的逾時為 10 秒 - }, -}); -``` - - - - -## 使用自訂驗證設定 Bearer 驗證 (Authentication) \{#configure-bearer-auth-with-custom-verification} - -如果你的 OAuth / OIDC 提供者不發行 JWT，或你想實作自己的授權 (Authorization) 邏輯，MCP Auth 允許你建立自訂驗證函式： - -:::info -由於 Bearer 驗證 (Authentication) middleware 會根據驗證結果自動檢查簽發者 (`iss`)、受眾 (`aud`) 及所需權限範圍 (`scope`)，你無需在自訂驗證函式中重複這些檢查。你只需專注於驗證權杖（如簽章、過期等）並回傳驗證資訊物件即可。 -::: - - - - -```python -from mcpauth.exceptions import MCPAuthJwtVerificationException, MCPAuthJwtVerificationExceptionCode -from mcpauth.types import AuthInfo - -async def custom_verification(token: str) -> AuthInfo: - # 在此實作你的自訂驗證邏輯 - info = await verify_token(token) - if not info: - raise MCPAuthJwtVerificationException( - MCPAuthJwtVerificationExceptionCode.JWT_VERIFICATION_FAILED - ) - return info # 回傳驗證資訊物件 - -bearer_auth = mcp_auth.bearer_auth_middleware( - custom_verification, - required_scopes=["read", "write"] -) -``` - - - - -```ts -const bearerAuth = mcpAuth.bearerAuth( - async (token) => { - // 在此實作你的自訂驗證邏輯 - const info = await verifyToken(token); - if (!info) { - throw new MCPAuthJwtVerificationError('jwt_verification_failed'); - } - return info; // 回傳驗證資訊物件 - }, - { requiredScopes: ['read', 'write'] } -); -``` - - - - -## 在 MCP 伺服器中套用 Bearer 驗證 (Authentication) \{#apply-bearer-auth-in-your-mcp-server} - -要用 Bearer 驗證 (Authentication) 保護你的 MCP 伺服器，你需要將 Bearer 驗證 (Authentication) middleware 套用到 MCP 伺服器實例。 - - - - -```python -bearer_auth = mcp_auth.bearer_auth_middleware("jwt", required_scopes=["read", "write"]) -app = Starlette( - routes=[Mount('/', app=mcp.sse_app(), middleware=[Middleware(bearer_auth)])] -) -``` - - - - -```js -const app = express(); -app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] })); -``` - - - - -這將確保所有進入的請求都會根據設定的 Bearer 驗證 (Authentication) 規則進行驗證與授權 (Authorization)，且驗證資訊會存於請求上下文中。 - -你可以在 MCP 伺服器實作中存取這些資訊： - - - - -```python -@mcp.tool() -async def whoami() -> dict: - # `mcp_auth.auth_info` 是目前請求的驗證資訊物件 - auth_info = mcp_auth.auth_info - print(f"Authenticated user: {auth_info.subject}") - return {"subject": auth_info.subject} -``` - - - - -```js -// `authInfo` 會從 `req.auth` 物件帶入 -server.tool('whoami', ({ authInfo }) => { - console.log(`Authenticated user: ${authInfo.subject}`); - return { subject: authInfo.subject }; -}); -``` - - - diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/configure-server/mcp-auth.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/configure-server/mcp-auth.mdx deleted file mode 100644 index 4d8c063..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/configure-server/mcp-auth.mdx +++ /dev/null @@ -1,208 +0,0 @@ ---- -sidebar_position: 1 -sidebar_label: MCP Auth ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -# 在 MCP 伺服器中設定 MCP Auth - -若要將你的 MCP 伺服器連接至 OAuth 2.1 或 OpenID Connect 提供者，你需要設定 MCP Auth 實例。這包含以提供者的授權伺服器中繼資料初始化實例，並設置必要的授權流程。 - -## 初始化 MCP Auth \{#init-mcp-auth} - -### 自動抓取中繼資料 \{#automatic-metadata-fetching} - -初始化 MCP Auth 實例最簡單的方法，是使用內建函式從 well-known URL 抓取中繼資料。如果你的提供者符合下列標準之一： - -- [OAuth 2.0 授權伺服器中繼資料 (Authorization Server Metadata)](https://datatracker.ietf.org/doc/html/rfc8414) -- [OpenID Connect 探索 (Discovery)](https://openid.net/specs/openid-connect-discovery-1_0.html) - -你可以使用 `fetchServerConfig`，只需提供 `issuer` URL，即可自動取得中繼資料： - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType, fetch_server_config - -mcp_auth = MCPAuth( - server=fetch_server_config( - '', - type=AuthServerType.OIDC # 或 AuthServerType.OAUTH - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { type: 'oidc' }), // 或 'oauth' -}); -``` - - - - -如果你的 issuer 包含路徑，OAuth 2.0 與 OpenID Connect 的行為略有不同： - -- **OAuth 2.0**：well-known URL 會附加在 issuer 的**網域**後。例如，若 issuer 為 `https://my-project.logto.app/oauth`，well-known URL 會是 `https://auth.logto.io/.well-known/oauth-authorization-server/oauth`。 -- **OpenID Connect**：well-known URL 會直接附加在**issuer**後。例如，若 issuer 為 `https://my-project.logto.app/oidc`，well-known URL 會是 `https://auth.logto.io/oidc/.well-known/openid-configuration`。 - -### 其他初始化 MCP Auth 的方式 \{#other-ways} - -#### 自訂資料轉換 \{#custom-data-transpilation} - -有時，提供者回傳的中繼資料格式可能不符預期。如果你確信該提供者是合規的，可以使用 `transpile_data` 選項，在資料被使用前進行修改： - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -mcp_auth = MCPAuth( - server=fetch_server_config( - '', - type=AuthServerType.OIDC, - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { - type: 'oidc', - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - - -這讓你能在 MCP Auth 使用前，先修改中繼資料物件。例如，你可以新增或移除欄位、變更其值，或轉換成不同格式。 - -#### 從特定 URL 抓取中繼資料 \{#fetch-metadata-from-a-specific-url} - -如果你的提供者有專屬的中繼資料 URL（而非標準 URL），也可以這樣使用： - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config_by_well_known_url - -mcp_auth = MCPAuth( - server=fetch_server_config_by_well_known_url( - '', - type=AuthServerType.OIDC # 或 AuthServerType.OAUTH - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfigByWellKnownUrl } from 'mcp-auth'; - -const mcpAuth = new MCPAuth({ - server: await fetchServerConfigByWellKnownUrl('', { type: 'oidc' }), // 或 'oauth' -}); -``` - - - - -#### 從特定 URL 抓取並自訂資料轉換 \{#fetch-metadata-from-a-specific-url-with-custom-data-transpilation} - -有時，提供者回應的資料格式可能有誤或不符預期。如果你確信該提供者是合規的，可以透過 config 選項進行資料轉換： - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType, fetch_server_config_by_well_known_url - -mcp_auth = MCPAuth( - server=fetch_server_config_by_well_known_url( - '', - type=AuthServerType.OIDC, - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: await fetchServerConfigByWellKnownUrl('', { - type: 'oidc', - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - - -#### 手動提供中繼資料 \{#manually-provide-metadata} - -如果你的提供者不支援自動抓取中繼資料，你可以手動提供中繼資料物件： - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerConfig, AuthServerType, AuthorizationServerMetadata - -mcp_auth = MCPAuth( - server=AuthServerConfig( - type=AuthServerType.OIDC, # 或 AuthServerType.OAUTH - metadata=AuthorizationServerMetadata( - issuer='', - authorization_endpoint='', - # ... 其他中繼資料欄位 - ), - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: { - metadata: { - issuer: '', - // Metadata 欄位應為 camelCase - authorizationEndpoint: '', - // ... 其他中繼資料欄位 - }, - type: 'oidc', // 或 'oauth' - }, -}); -``` - - - diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/README.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/README.md deleted file mode 100644 index a4ea9fe..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/README.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -sidebar_label: Node.js SDK ---- - -# MCP Auth Node.js SDK 參考文件 - -## 類別 (Classes) {#classes} - -- [MCPAuth](/references/js/classes/MCPAuth.md) -- [MCPAuthAuthServerError](/references/js/classes/MCPAuthAuthServerError.md) -- [MCPAuthBearerAuthError](/references/js/classes/MCPAuthBearerAuthError.md) -- [MCPAuthConfigError](/references/js/classes/MCPAuthConfigError.md) -- [MCPAuthError](/references/js/classes/MCPAuthError.md) -- [MCPAuthTokenVerificationError](/references/js/classes/MCPAuthTokenVerificationError.md) - -## 型別別名 (Type Aliases) {#type-aliases} - -- [AuthorizationServerMetadata](/references/js/type-aliases/AuthorizationServerMetadata.md) -- [AuthServerConfig](/references/js/type-aliases/AuthServerConfig.md) -- [AuthServerConfigError](/references/js/type-aliases/AuthServerConfigError.md) -- [AuthServerConfigErrorCode](/references/js/type-aliases/AuthServerConfigErrorCode.md) -- [AuthServerConfigWarning](/references/js/type-aliases/AuthServerConfigWarning.md) -- [AuthServerConfigWarningCode](/references/js/type-aliases/AuthServerConfigWarningCode.md) -- [AuthServerErrorCode](/references/js/type-aliases/AuthServerErrorCode.md) -- [AuthServerSuccessCode](/references/js/type-aliases/AuthServerSuccessCode.md) -- [AuthServerType](/references/js/type-aliases/AuthServerType.md) -- [BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) -- [BearerAuthErrorCode](/references/js/type-aliases/BearerAuthErrorCode.md) -- [BearerAuthJwtConfig](/references/js/type-aliases/BearerAuthJwtConfig.md) -- [CamelCaseAuthorizationServerMetadata](/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md) -- [MCPAuthBearerAuthErrorDetails](/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md) -- [MCPAuthConfig](/references/js/type-aliases/MCPAuthConfig.md) -- [MCPAuthTokenVerificationErrorCode](/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md) -- [VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) -- [VerifyAccessTokenMode](/references/js/type-aliases/VerifyAccessTokenMode.md) - -## 變數 (Variables) {#variables} - -- [authorizationServerMetadataSchema](/references/js/variables/authorizationServerMetadataSchema.md) -- [authServerErrorDescription](/references/js/variables/authServerErrorDescription.md) -- [bearerAuthErrorDescription](/references/js/variables/bearerAuthErrorDescription.md) -- [camelCaseAuthorizationServerMetadataSchema](/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md) -- [serverMetadataPaths](/references/js/variables/serverMetadataPaths.md) -- [tokenVerificationErrorDescription](/references/js/variables/tokenVerificationErrorDescription.md) -- [validateServerConfig](/references/js/variables/validateServerConfig.md) - -## 函式 (Functions) {#functions} - -- [createVerifyJwt](/references/js/functions/createVerifyJwt.md) -- [fetchServerConfig](/references/js/functions/fetchServerConfig.md) -- [fetchServerConfigByWellKnownUrl](/references/js/functions/fetchServerConfigByWellKnownUrl.md) -- [handleBearerAuth](/references/js/functions/handleBearerAuth.md) diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuth.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuth.md deleted file mode 100644 index e4480d1..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuth.md +++ /dev/null @@ -1,196 +0,0 @@ ---- -sidebar_label: MCPAuth ---- - -# 類別：MCPAuth - -mcp-auth 函式庫的主要類別，提供在 MCP 伺服器中建立路由器及實用的驗證 (Authentication) 與授權 (Authorization) 處理器方法。 - -## 參見 \{#see} - -更多有關此函式庫及其用法，請參閱 [MCP Auth](https://mcp-auth.dev)。 - -## 範例 \{#example} - -與遠端 OIDC 提供者整合的範例： - -```ts -import express from 'express'; -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const app = express(); -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig( - 'https://auth.logto.io/oidc', - { type: 'oidc' } - ), -}); - -// 掛載路由器以處理 OAuth 2.0 授權伺服器中繼資料 -app.use(mcpAuth.delegatedRouter()); - -// 在 MCP 路由上使用 Bearer 驗證 (Authentication) 處理器 -app.get( - '/mcp', - mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }), - (req, res) => { - console.log('Auth info:', req.auth); - // 在此處理 MCP 請求 - }, -); - -// 在 MCP 回呼中使用驗證 (Authentication) 資訊 -server.tool( - 'add', - { a: z.number(), b: z.number() }, - async ({ a, b }, { authInfo }) => { - console.log('Auth Info:', authInfo); - // ... - }, -); -``` - -## 建構子 \{#constructors} - -### 建構子 \{#constructor} - -```ts -new MCPAuth(config: MCPAuthConfig): MCPAuth; -``` - -#### 參數 \{#parameters} - -##### config \{#config} - -[`MCPAuthConfig`](/references/js/type-aliases/MCPAuthConfig.md) - -#### 回傳值 \{#returns} - -`MCPAuth` - -## 屬性 \{#properties} - -### config \{#config} - -```ts -readonly config: MCPAuthConfig; -``` - -## 方法 \{#methods} - -### bearerAuth() \{#bearerauth} - -#### 呼叫簽章 \{#call-signature} - -```ts -bearerAuth(verifyAccessToken: VerifyAccessTokenFunction, config?: Omit): RequestHandler; -``` - -建立一個 Bearer 驗證 (Authentication) 處理器（Express 中介軟體），用於驗證請求 `Authorization` 標頭中的存取權杖 (Access token)。 - -##### 參數 \{#parameters} - -###### verifyAccessToken \{#verifyaccesstoken} - -[`VerifyAccessTokenFunction`](/references/js/type-aliases/VerifyAccessTokenFunction.md) - -一個驗證存取權杖 (Access token) 的函式。應接受字串型態的存取權杖，並回傳一個 promise（或值），解析為驗證結果。 - -**參見** - -[VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) 以瞭解 `verifyAccessToken` 函式的型別定義。 - -###### config? \{#config} - -`Omit`\<[`BearerAuthConfig`](/references/js/type-aliases/BearerAuthConfig.md), `"verifyAccessToken"` \| `"issuer"`\> - -Bearer 驗證 (Authentication) 處理器的選用設定。 - -**參見** - -[BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) 以瞭解可用的設定選項（不含 `verifyAccessToken` 與 `issuer`）。 - -##### 回傳值 \{#returns} - -`RequestHandler` - -一個 Express 中介軟體函式，會驗證存取權杖 (Access token) 並將驗證結果加入請求物件（`req.auth`）。 - -##### 參見 \{#see} - -[handleBearerAuth](/references/js/functions/handleBearerAuth.md) 以瞭解實作細節與 `req.auth`（`AuthInfo`）物件的擴充型別。 - -#### 呼叫簽章 \{#call-signature} - -```ts -bearerAuth(mode: "jwt", config?: Omit & BearerAuthJwtConfig): RequestHandler; -``` - -建立一個 Bearer 驗證 (Authentication) 處理器（Express 中介軟體），使用預設的驗證模式來驗證請求 `Authorization` 標頭中的存取權杖 (Access token)。 - -在 `'jwt'` 模式下，處理器會使用授權伺服器 JWKS URI 的 JWK Set 建立 JWT 驗證函式。 - -##### 參數 \{#parameters} - -###### mode \{#mode} - -`"jwt"` - -存取權杖 (Access token) 的驗證模式。目前僅支援 'jwt'。 - -**參見** - -[VerifyAccessTokenMode](/references/js/type-aliases/VerifyAccessTokenMode.md) 以瞭解可用模式。 - -###### config? \{#config} - -`Omit`\<[`BearerAuthConfig`](/references/js/type-aliases/BearerAuthConfig.md), `"verifyAccessToken"` \| `"issuer"`\> & [`BearerAuthJwtConfig`](/references/js/type-aliases/BearerAuthJwtConfig.md) - -Bearer 驗證 (Authentication) 處理器的選用設定，包含 JWT 驗證選項與遠端 JWK set 選項。 - -**參見** - - - [BearerAuthJwtConfig](/references/js/type-aliases/BearerAuthJwtConfig.md) 以瞭解 JWT 驗證可用設定選項。 - - [BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) 以瞭解可用設定選項（不含 `verifyAccessToken` 與 `issuer`）。 - -##### 回傳值 \{#returns} - -`RequestHandler` - -一個 Express 中介軟體函式，會驗證存取權杖 (Access token) 並將驗證結果加入請求物件（`req.auth`）。 - -##### 參見 \{#see} - -[handleBearerAuth](/references/js/functions/handleBearerAuth.md) 以瞭解實作細節與 `req.auth`（`AuthInfo`）物件的擴充型別。 - -##### 例外拋出 \{#throws} - -當使用 `'jwt'` 模式且伺服器中繼資料未提供 JWKS URI 時會拋出例外。 - -*** - -### delegatedRouter() \{#delegatedrouter} - -```ts -delegatedRouter(): Router; -``` - -建立一個代理路由器，服務 OAuth 2.0 授權伺服器中繼資料端點 -（`/.well-known/oauth-authorization-server`），並提供給此實例的中繼資料。 - -#### 回傳值 \{#returns} - -`Router` - -一個路由器，服務 OAuth 2.0 授權伺服器中繼資料端點，並提供給此實例的中繼資料。 - -#### 範例 \{#example} - -```ts -import express from 'express'; -import { MCPAuth } from 'mcp-auth'; - -const app = express(); -const mcpAuth: MCPAuth; // 假設已初始化 -app.use(mcpAuth.delegatedRouter()); -``` diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthAuthServerError.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthAuthServerError.md deleted file mode 100644 index f7f85fe..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthAuthServerError.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -sidebar_label: MCPAuthAuthServerError ---- - -# 類別：MCPAuthAuthServerError - -當遠端授權 (Authorization) 伺服器發生問題時所拋出的錯誤。 - -## 繼承自 {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## 建構子 {#constructors} - -### 建構子 {#constructor} - -```ts -new MCPAuthAuthServerError(code: AuthServerErrorCode, cause?: unknown): MCPAuthAuthServerError; -``` - -#### 參數 {#parameters} - -##### code {#code} - -[`AuthServerErrorCode`](/references/js/type-aliases/AuthServerErrorCode.md) - -##### cause? {#cause} - -`unknown` - -#### 回傳值 {#returns} - -`MCPAuthAuthServerError` - -#### 覆寫自 {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## 屬性 {#properties} - -### cause? {#cause} - -```ts -readonly optional cause: unknown; -``` - -#### 繼承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: AuthServerErrorCode; -``` - -錯誤代碼，採用 snake_case 格式。 - -#### 繼承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### 繼承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthAuthServerError'; -``` - -#### 覆寫自 {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### 繼承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -可選的堆疊追蹤格式化覆寫方法 - -#### 參數 {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### 回傳值 {#returns} - -`any` - -#### 參考 {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### 繼承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### 繼承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## 方法 {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -將錯誤轉換為適合 HTTP 回應的 JSON 格式。 - -#### 參數 {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -是否在 JSON 回應中包含錯誤原因。 -預設為 `false`。 - -#### 回傳值 {#returns} - -`Record`\<`string`, `unknown`\> - -#### 繼承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -在目標物件上建立 .stack 屬性 - -#### 參數 {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### 回傳值 {#returns} - -`void` - -#### 繼承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthBearerAuthError.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthBearerAuthError.md deleted file mode 100644 index b56e24a..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthBearerAuthError.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -sidebar_label: MCPAuthBearerAuthError ---- - -# 類別：MCPAuthBearerAuthError - -當使用 Bearer 權杖進行驗證 (Authentication) 時發生問題時所拋出的錯誤。 - -## 繼承 {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## 建構子 {#constructors} - -### 建構子 {#constructor} - -```ts -new MCPAuthBearerAuthError(code: BearerAuthErrorCode, cause?: MCPAuthBearerAuthErrorDetails): MCPAuthBearerAuthError; -``` - -#### 參數 {#parameters} - -##### code {#code} - -[`BearerAuthErrorCode`](/references/js/type-aliases/BearerAuthErrorCode.md) - -##### cause? {#cause} - -[`MCPAuthBearerAuthErrorDetails`](/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md) - -#### 回傳值 {#returns} - -`MCPAuthBearerAuthError` - -#### 覆寫 {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## 屬性 {#properties} - -### cause? {#cause} - -```ts -readonly optional cause: MCPAuthBearerAuthErrorDetails; -``` - -#### 繼承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: BearerAuthErrorCode; -``` - -錯誤代碼，採用 snake_case 格式。 - -#### 繼承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### 繼承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthBearerAuthError'; -``` - -#### 覆寫 {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### 繼承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -可選的堆疊追蹤格式化覆寫方法 - -#### 參數 {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### 回傳值 {#returns} - -`any` - -#### 參見 {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### 繼承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### 繼承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## 方法 {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -將錯誤轉換為適合 HTTP 回應的 JSON 格式。 - -#### 參數 {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -是否在 JSON 回應中包含錯誤原因。 -預設為 `false`。 - -#### 回傳值 {#returns} - -`Record`\<`string`, `unknown`\> - -#### 覆寫 {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -在目標物件上建立 .stack 屬性 - -#### 參數 {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### 回傳值 {#returns} - -`void` - -#### 繼承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthConfigError.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthConfigError.md deleted file mode 100644 index ba9804c..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthConfigError.md +++ /dev/null @@ -1,202 +0,0 @@ ---- -sidebar_label: MCPAuthConfigError ---- - -# 類別：MCPAuthConfigError - -當 mcp-auth 配置出現問題時所拋出的錯誤。 - -## 繼承自 {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## 建構子 {#constructors} - -### 建構子 {#constructor} - -```ts -new MCPAuthConfigError(code: string, message: string): MCPAuthConfigError; -``` - -#### 參數 {#parameters} - -##### code {#code} - -`string` - -以 snake_case 格式表示的錯誤代碼。 - -##### message {#message} - -`string` - -易於理解的錯誤描述。 - -#### 回傳值 {#returns} - -`MCPAuthConfigError` - -#### 繼承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## 屬性 {#properties} - -### cause? {#cause} - -```ts -optional cause: unknown; -``` - -#### 繼承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: string; -``` - -以 snake_case 格式表示的錯誤代碼。 - -#### 繼承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### 繼承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthConfigError'; -``` - -#### 覆寫自 {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### 繼承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -可選的堆疊追蹤格式化覆寫 - -#### 參數 {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### 回傳值 {#returns} - -`any` - -#### 參見 {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### 繼承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### 繼承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## 方法 {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -將錯誤轉換為適合 HTTP 回應的 JSON 格式。 - -#### 參數 {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -是否在 JSON 回應中包含錯誤原因。 -預設為 `false`。 - -#### 回傳值 {#returns} - -`Record`\<`string`, `unknown`\> - -#### 繼承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -在目標物件上建立 .stack 屬性 - -#### 參數 {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### 回傳值 {#returns} - -`void` - -#### 繼承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthError.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthError.md deleted file mode 100644 index 8000a61..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthError.md +++ /dev/null @@ -1,219 +0,0 @@ ---- -sidebar_label: MCPAuthError ---- - -# 類別：MCPAuthError - -所有 mcp-auth 錯誤的基礎類別。 - -它提供一種標準化方式來處理與 MCP 驗證 (Authentication) 和授權 (Authorization) 相關的錯誤。 - -## 繼承自 {#extends} - -- `Error` - -## 被繼承於 {#extended-by} - -- [`MCPAuthConfigError`](/references/js/classes/MCPAuthConfigError.md) -- [`MCPAuthAuthServerError`](/references/js/classes/MCPAuthAuthServerError.md) -- [`MCPAuthBearerAuthError`](/references/js/classes/MCPAuthBearerAuthError.md) -- [`MCPAuthTokenVerificationError`](/references/js/classes/MCPAuthTokenVerificationError.md) - -## 建構子 {#constructors} - -### 建構子 {#constructor} - -```ts -new MCPAuthError(code: string, message: string): MCPAuthError; -``` - -#### 參數 {#parameters} - -##### code {#code} - -`string` - -錯誤代碼，採用 snake_case 格式。 - -##### message {#message} - -`string` - -錯誤的人類可讀描述。 - -#### 回傳值 {#returns} - -`MCPAuthError` - -#### 覆寫自 {#overrides} - -```ts -Error.constructor -``` - -## 屬性 {#properties} - -### cause? {#cause} - -```ts -optional cause: unknown; -``` - -#### 繼承自 {#inherited-from} - -```ts -Error.cause -``` - -*** - -### code {#code} - -```ts -readonly code: string; -``` - -錯誤代碼，採用 snake_case 格式。 - -*** - -### message {#message} - -```ts -message: string; -``` - -#### 繼承自 {#inherited-from} - -```ts -Error.message -``` - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthError'; -``` - -#### 覆寫自 {#overrides} - -```ts -Error.name -``` - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### 繼承自 {#inherited-from} - -```ts -Error.stack -``` - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -可選的堆疊追蹤格式化覆寫 - -#### 參數 {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### 回傳值 {#returns} - -`any` - -#### 參考 {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### 繼承自 {#inherited-from} - -```ts -Error.prepareStackTrace -``` - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### 繼承自 {#inherited-from} - -```ts -Error.stackTraceLimit -``` - -## 方法 {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -將錯誤轉換為適合 HTTP 回應的 JSON 格式。 - -#### 參數 {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -是否在 JSON 回應中包含錯誤原因。 -預設為 `false`。 - -#### 回傳值 {#returns} - -`Record`\<`string`, `unknown`\> - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -在目標物件上建立 .stack 屬性 - -#### 參數 {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### 回傳值 {#returns} - -`void` - -#### 繼承自 {#inherited-from} - -```ts -Error.captureStackTrace -``` diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthTokenVerificationError.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthTokenVerificationError.md deleted file mode 100644 index 586ae5f..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/classes/MCPAuthTokenVerificationError.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -sidebar_label: MCPAuthTokenVerificationError ---- - -# 類別：MCPAuthTokenVerificationError - -當驗證權杖時發生問題時所拋出的錯誤。 - -## 繼承自 {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## 建構子 {#constructors} - -### 建構子 {#constructor} - -```ts -new MCPAuthTokenVerificationError(code: MCPAuthTokenVerificationErrorCode, cause?: unknown): MCPAuthTokenVerificationError; -``` - -#### 參數 {#parameters} - -##### code {#code} - -[`MCPAuthTokenVerificationErrorCode`](/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md) - -##### cause? {#cause} - -`unknown` - -#### 回傳值 {#returns} - -`MCPAuthTokenVerificationError` - -#### 覆寫自 {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## 屬性 {#properties} - -### cause? {#cause} - -```ts -readonly optional cause: unknown; -``` - -#### 繼承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: MCPAuthTokenVerificationErrorCode; -``` - -錯誤代碼，採用 snake_case 格式。 - -#### 繼承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### 繼承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthTokenVerificationError'; -``` - -#### 覆寫自 {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### 繼承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -可選的堆疊追蹤格式化覆寫 - -#### 參數 {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### 回傳值 {#returns} - -`any` - -#### 參考 {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### 繼承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### 繼承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## 方法 {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -將錯誤轉換為適合 HTTP 回應的 JSON 格式。 - -#### 參數 {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -是否在 JSON 回應中包含錯誤原因。 -預設為 `false`。 - -#### 回傳值 {#returns} - -`Record`\<`string`, `unknown`\> - -#### 繼承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -在目標物件上建立 .stack 屬性 - -#### 參數 {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### 回傳值 {#returns} - -`void` - -#### 繼承自 {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/createVerifyJwt.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/createVerifyJwt.md deleted file mode 100644 index a403295..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/createVerifyJwt.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -sidebar_label: createVerifyJwt ---- - -# 函式：createVerifyJwt() - -```ts -function createVerifyJwt(getKey: JWTVerifyGetKey, options?: JWTVerifyOptions): VerifyAccessTokenFunction; -``` - -建立一個函式，使用提供的金鑰擷取函式與選項來驗證 JWT 存取權杖 (Access token)。 - -## 參數 {#parameters} - -### getKey {#getkey} - -`JWTVerifyGetKey` - -用於擷取驗證 JWT 所需金鑰的函式。 - -**參見** - -JWTVerifyGetKey 以取得金鑰擷取函式的型別定義。 - -### options? {#options} - -`JWTVerifyOptions` - -可選的 JWT 驗證選項。 - -**參見** - -JWTVerifyOptions 以取得選項的型別定義。 - -## 回傳值 {#returns} - -[`VerifyAccessTokenFunction`](/references/js/type-aliases/VerifyAccessTokenFunction.md) - -一個用於驗證 JWT 存取權杖 (Access token) 的函式，若權杖有效則回傳 AuthInfo 物件。此函式要求 JWT 的 payload 中必須包含 `iss`、`client_id` 與 `sub` 欄位，並可選擇性包含 `scope` 或 `scopes` 欄位。該函式底層使用 `jose` 函式庫進行 JWT 驗證。 - -## 參見 {#see} - -[VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) 以取得回傳函式的型別定義。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfig.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfig.md deleted file mode 100644 index a4e621d..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfig.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -sidebar_label: fetchServerConfig ---- - -# 函式：fetchServerConfig() - -```ts -function fetchServerConfig(issuer: string, config: ServerMetadataConfig): Promise; -``` - -根據簽發者（Issuer）與授權伺服器類型，擷取伺服器設定。 - -此函式會根據伺服器類型自動判斷 well-known URL，因為 OAuth 及 OpenID Connect 伺服器的中繼資料端點慣例不同。 - -## 參數 {#parameters} - -### issuer {#issuer} - -`string` - -授權伺服器的簽發者（Issuer）URL。 - -### config {#config} - -`ServerMetadataConfig` - -包含伺服器類型與可選轉換函式的設定物件。 - -## 回傳值 {#returns} - -`Promise`\<[`AuthServerConfig`](/references/js/type-aliases/AuthServerConfig.md)\> - -一個解析為伺服器設定的 Promise。 - -## 參考 {#see} - - - [fetchServerConfigByWellKnownUrl](/references/js/functions/fetchServerConfigByWellKnownUrl.md) 以瞭解底層實作。 - - [https://www.rfc-editor.org/rfc/rfc8414](https://www.rfc-editor.org/rfc/rfc8414) 參考 OAuth 2.0 授權伺服器中繼資料規範。 - - [https://openid.net/specs/openid-connect-discovery-1\_0.html](https://openid.net/specs/openid-connect-discovery-1_0.html) 參考 OpenID Connect 探索規範。 - -## 範例 {#example} - -```ts -import { fetchServerConfig } from 'mcp-auth'; -// 擷取 OAuth 伺服器設定 -// 這將從 `https://auth.logto.io/.well-known/oauth-authorization-server/oauth` 取得中繼資料 -const oauthConfig = await fetchServerConfig('https://auth.logto.io/oauth', { type: 'oauth' }); - -// 擷取 OpenID Connect 伺服器設定 -// 這將從 `https://auth.logto.io/oidc/.well-known/openid-configuration` 取得中繼資料 -const oidcConfig = await fetchServerConfig('https://auth.logto.io/oidc', { type: 'oidc' }); -``` - -## 例外 {#throws} - -若擷取操作失敗則會丟出例外。 - -## 例外 {#throws} - -若伺服器中繼資料無效或不符合 MCP 規範則會丟出例外。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfigByWellKnownUrl.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfigByWellKnownUrl.md deleted file mode 100644 index 5ab7816..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/fetchServerConfigByWellKnownUrl.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -sidebar_label: fetchServerConfigByWellKnownUrl ---- - -# 函式：fetchServerConfigByWellKnownUrl() - -```ts -function fetchServerConfigByWellKnownUrl(wellKnownUrl: string | URL, config: ServerMetadataConfig): Promise; -``` - -從提供的 well-known URL 取得伺服器設定，並依據 MCP 規範進行驗證。 - -如果伺服器中繼資料不符合預期的結構，但你確定其相容，你可以定義 `transpileData` 函式，將中繼資料轉換為預期格式。 - -## 參數 {#parameters} - -### wellKnownUrl {#wellknownurl} - -用於取得伺服器設定的 well-known URL。可以是字串或 URL 物件。 - -`string` | `URL` - -### config {#config} - -`ServerMetadataConfig` - -包含伺服器類型與可選轉換函式的設定物件。 - -## 回傳值 {#returns} - -`Promise`\<[`AuthServerConfig`](/references/js/type-aliases/AuthServerConfig.md)\> - -一個 promise，解析後得到伺服器設定。 - -## 例外 {#throws} - -當取得操作失敗時會丟出例外。 - -## 例外 {#throws} - -當伺服器中繼資料無效或不符合 MCP 規範時會丟出例外。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/handleBearerAuth.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/handleBearerAuth.md deleted file mode 100644 index 2336236..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/functions/handleBearerAuth.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -sidebar_label: handleBearerAuth ---- - -# 函式：handleBearerAuth() - -```ts -function handleBearerAuth(param0: BearerAuthConfig): RequestHandler; -``` - -建立一個用於在 Express 應用程式中處理 Bearer 驗證 (Authentication) 的中介軟體函式。 - -此中介軟體會從 `Authorization` 標頭中擷取 Bearer 存取權杖 (Access token)，使用提供的 `verifyAccessToken` 函式進行驗證，並檢查簽發者 (Issuer)、受眾 (Audience) 以及所需權限範圍 (Scopes)。 - -- 如果權杖有效，會將驗證資訊加入 `request.auth` 屬性； - 若無效，則回應相應的錯誤訊息。 -- 若存取權杖 (Access token) 驗證失敗，會回應 401 未授權 (Unauthorized) 錯誤。 -- 若權杖未包含所需權限範圍 (Scopes)，會回應 403 禁止存取 (Forbidden) 錯誤。 -- 若驗證 (Authentication) 流程中發生非預期錯誤，中介軟體會重新拋出錯誤。 - -**注意：** `request.auth` 物件會包含比 `@modelcontextprotocol/sdk` 模組中標準 AuthInfo 介面更多的擴充欄位。詳細內容請參閱本檔案中的擴充介面。 - -## 參數 {#parameters} - -### param0 {#param0} - -[`BearerAuthConfig`](/references/js/type-aliases/BearerAuthConfig.md) - -Bearer 驗證 (Authentication) 處理器的設定。 - -## 回傳值 {#returns} - -`RequestHandler` - -一個用於 Express 的中介軟體函式，負責處理 Bearer 驗證 (Authentication)。 - -## 參見 {#see} - -[BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) 以瞭解設定選項。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfig.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfig.md deleted file mode 100644 index 38509e7..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfig.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -sidebar_label: AuthServerConfig ---- - -# 型別別名：AuthServerConfig - -```ts -type AuthServerConfig = { - metadata: CamelCaseAuthorizationServerMetadata; - type: AuthServerType; -}; -``` - -與 MCP 伺服器整合的遠端授權伺服器（Authorization Server）設定。 - -## 屬性 {#properties} - -### metadata {#metadata} - -```ts -metadata: CamelCaseAuthorizationServerMetadata; -``` - -授權伺服器（Authorization Server）的中繼資料，需符合 MCP 規範 -（基於 OAuth 2.0 授權伺服器中繼資料）。 - -這些中繼資料通常從伺服器的 well-known endpoint（OAuth 2.0 -授權伺服器中繼資料或 OpenID Connect Discovery）取得；若伺服器不支援這類 endpoint，也可直接在設定中提供。 - -**注意：** 中繼資料需為 camelCase 格式，符合 mcp-auth 函式庫的偏好。 - -#### 參考 {#see} - - - [OAuth 2.0 授權伺服器中繼資料 (Authorization Server Metadata)](https://datatracker.ietf.org/doc/html/rfc8414) - - [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) - -*** - -### type {#type} - -```ts -type: AuthServerType; -``` - -授權伺服器（Authorization Server）的類型。 - -#### 參考 {#see} - -[AuthServerType](/references/js/type-aliases/AuthServerType.md) 以瞭解可能的值。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigError.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigError.md deleted file mode 100644 index 87d6db5..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigError.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -sidebar_label: AuthServerConfigError ---- - -# 型別別名：AuthServerConfigError (Type Alias: AuthServerConfigError) - -```ts -type AuthServerConfigError = { - cause?: Error; - code: AuthServerConfigErrorCode; - description: string; -}; -``` - -表示在驗證授權伺服器中繼資料時發生的錯誤。 - -## 屬性 {#properties} - -### cause? {#cause} - -```ts -optional cause: Error; -``` - -錯誤的可選原因，通常為 `Error` 實例，用於提供更多背景資訊。 - -*** - -### code {#code} - -```ts -code: AuthServerConfigErrorCode; -``` - -代表特定驗證錯誤的代碼。 - -*** - -### description {#description} - -```ts -description: string; -``` - -錯誤的人類可讀描述。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigErrorCode.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigErrorCode.md deleted file mode 100644 index 856f431..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigErrorCode.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_label: AuthServerConfigErrorCode ---- - -# 型別別名：AuthServerConfigErrorCode - -```ts -type AuthServerConfigErrorCode = - | "invalid_server_metadata" - | "code_response_type_not_supported" - | "authorization_code_grant_not_supported" - | "pkce_not_supported" - | "s256_code_challenge_method_not_supported"; -``` - -驗證授權伺服器（authorization server）中繼資料時可能發生的錯誤代碼。 \ No newline at end of file diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarning.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarning.md deleted file mode 100644 index 37c2826..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarning.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -sidebar_label: AuthServerConfigWarning ---- - -# 型別別名：AuthServerConfigWarning (Type Alias: AuthServerConfigWarning) - -```ts -type AuthServerConfigWarning = { - code: AuthServerConfigWarningCode; - description: string; -}; -``` - -表示在驗證授權伺服器中繼資料時發生的警告。 - -## 屬性 (Properties) {#properties} - -### code {#code} - -```ts -code: AuthServerConfigWarningCode; -``` - -代表特定驗證警告的代碼。 - -*** - -### description {#description} - -```ts -description: string; -``` - -對警告的人類可讀描述。 \ No newline at end of file diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarningCode.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarningCode.md deleted file mode 100644 index e141dc2..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarningCode.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -sidebar_label: AuthServerConfigWarningCode ---- - -# 型別別名：AuthServerConfigWarningCode (Type Alias: AuthServerConfigWarningCode) - -```ts -type AuthServerConfigWarningCode = "dynamic_registration_not_supported"; -``` - -驗證授權伺服器中繼資料時可能出現的警告代碼。 \ No newline at end of file diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerErrorCode.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerErrorCode.md deleted file mode 100644 index f90473a..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerErrorCode.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_label: AuthServerErrorCode ---- - -# 型別別名：AuthServerErrorCode (Type Alias: AuthServerErrorCode) - -```ts -type AuthServerErrorCode = - | "invalid_server_metadata" - | "invalid_server_config" - | "missing_jwks_uri"; -``` diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerSuccessCode.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerSuccessCode.md deleted file mode 100644 index 7266723..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerSuccessCode.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -sidebar_label: AuthServerSuccessCode ---- - -# 型別別名：AuthServerSuccessCode - -```ts -type AuthServerSuccessCode = - | "server_metadata_valid" - | "dynamic_registration_supported" - | "pkce_supported" - | "s256_code_challenge_method_supported" - | "authorization_code_grant_supported" - | "code_response_type_supported"; -``` - -授權伺服器中繼資料驗證成功時所使用的代碼。 \ No newline at end of file diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerType.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerType.md deleted file mode 100644 index c372f2b..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthServerType.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -sidebar_label: AuthServerType ---- - -# 型別別名：AuthServerType - -```ts -type AuthServerType = "oauth" | "oidc"; -``` - -授權伺服器 (Authorization server) 的型別。此資訊應由伺服器設定提供，用以指示該伺服器是 OAuth 2.0 還是 OpenID Connect (OIDC) 授權伺服器 (Authorization server)。 \ No newline at end of file diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthorizationServerMetadata.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthorizationServerMetadata.md deleted file mode 100644 index 4db2d74..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/AuthorizationServerMetadata.md +++ /dev/null @@ -1,219 +0,0 @@ ---- -sidebar_label: AuthorizationServerMetadata ---- - -# 型別別名：AuthorizationServerMetadata - -```ts -type AuthorizationServerMetadata = { - authorization_endpoint: string; - code_challenge_methods_supported?: string[]; - grant_types_supported?: string[]; - introspection_endpoint?: string; - introspection_endpoint_auth_methods_supported?: string[]; - introspection_endpoint_auth_signing_alg_values_supported?: string[]; - issuer: string; - jwks_uri?: string; - op_policy_uri?: string; - op_tos_uri?: string; - registration_endpoint?: string; - response_modes_supported?: string[]; - response_types_supported: string[]; - revocation_endpoint?: string; - revocation_endpoint_auth_methods_supported?: string[]; - revocation_endpoint_auth_signing_alg_values_supported?: string[]; - scope_supported?: string[]; - service_documentation?: string; - token_endpoint: string; - token_endpoint_auth_methods_supported?: string[]; - token_endpoint_auth_signing_alg_values_supported?: string[]; - ui_locales_supported?: string[]; - userinfo_endpoint?: string; -}; -``` - -OAuth 2.0 授權伺服器中繼資料（Authorization Server Metadata）的結構，依據 RFC 8414 定義。 - -## 型別宣告 {#type-declaration} - -### authorization\_endpoint {#authorization-endpoint} - -```ts -authorization_endpoint: string; -``` - -授權伺服器的授權端點（authorization endpoint）URL [[RFC6749](https://rfc-editor.org/rfc/rfc6749)]。 -除非不支援任何使用授權端點的授權類型（grant types），否則此欄位為必填。 - -#### 參見 {#see} - -https://rfc-editor.org/rfc/rfc6749#section-3.1 - -### code\_challenge\_methods\_supported? {#code-challenge-methods-supported} - -```ts -optional code_challenge_methods_supported: string[]; -``` - -JSON 陣列，包含此授權伺服器支援的 PKCE（Proof Key for Code Exchange）[[RFC7636](https://www.rfc-editor.org/rfc/rfc7636)] code challenge 方法列表。 - -### grant\_types\_supported? {#grant-types-supported} - -```ts -optional grant_types_supported: string[]; -``` - -JSON 陣列，包含此授權伺服器支援的 OAuth 2.0 授權類型（grant type）值。陣列值與「OAuth 2.0 動態用戶端註冊協議」[[RFC7591](https://www.rfc-editor.org/rfc/rfc7591)] 中 `grant_types` 參數所用值相同。 -若省略，預設值為 `["authorization_code", "implicit"]`。 - -### introspection\_endpoint? {#introspection-endpoint} - -```ts -optional introspection_endpoint: string; -``` - -授權伺服器的 OAuth 2.0 introspection 端點 URL [[RFC7662](https://www.rfc-editor.org/rfc/rfc7662)]。 - -### introspection\_endpoint\_auth\_methods\_supported? {#introspection-endpoint-auth-methods-supported} - -```ts -optional introspection_endpoint_auth_methods_supported: string[]; -``` - -### introspection\_endpoint\_auth\_signing\_alg\_values\_supported? {#introspection-endpoint-auth-signing-alg-values-supported} - -```ts -optional introspection_endpoint_auth_signing_alg_values_supported: string[]; -``` - -### issuer {#issuer} - -```ts -issuer: string; -``` - -授權伺服器的簽發者（Issuer）識別符，為一個使用 `https` 協定且無查詢或片段組件的 URL。 - -### jwks\_uri? {#jwks-uri} - -```ts -optional jwks_uri: string; -``` - -授權伺服器的 JWK Set [[JWK](https://www.rfc-editor.org/rfc/rfc8414.html#ref-JWK)] 文件 URL。該文件包含用戶端用來驗證授權伺服器簽章的簽名金鑰。此 URL 必須使用 `https` 協定。 - -### op\_policy\_uri? {#op-policy-uri} - -```ts -optional op_policy_uri: string; -``` - -### op\_tos\_uri? {#op-tos-uri} - -```ts -optional op_tos_uri: string; -``` - -### registration\_endpoint? {#registration-endpoint} - -```ts -optional registration_endpoint: string; -``` - -授權伺服器的 OAuth 2.0 動態用戶端註冊端點 URL [[RFC7591](https://www.rfc-editor.org/rfc/rfc7591)]。 - -### response\_modes\_supported? {#response-modes-supported} - -```ts -optional response_modes_supported: string[]; -``` - -JSON 陣列，包含此授權伺服器支援的 OAuth 2.0 `response_mode` 值，詳見「OAuth 2.0 多重回應型態編碼實踐」 -[[OAuth.Responses](https://datatracker.ietf.org/doc/html/rfc8414#ref-OAuth.Responses)]。 - -若省略，預設為 `["query", "fragment"]`。回應模式值 `"form_post"` 亦定義於「OAuth 2.0 表單回傳回應模式」 -[[OAuth.FormPost](https://datatracker.ietf.org/doc/html/rfc8414#ref-OAuth.Post)]。 - -### response\_types\_supported {#response-types-supported} - -```ts -response_types_supported: string[]; -``` - -JSON 陣列，包含此授權伺服器支援的 OAuth 2.0 `response_type` 值。陣列值與「OAuth 2.0 動態用戶端註冊協議」[[RFC7591](https://www.rfc-editor.org/rfc/rfc7591)] 中 `response_types` 參數所用值相同。 - -### revocation\_endpoint? {#revocation-endpoint} - -```ts -optional revocation_endpoint: string; -``` - -授權伺服器的 OAuth 2.0 撤銷端點（revocation endpoint）URL [[RFC7009](https://www.rfc-editor.org/rfc/rfc7009)]。 - -### revocation\_endpoint\_auth\_methods\_supported? {#revocation-endpoint-auth-methods-supported} - -```ts -optional revocation_endpoint_auth_methods_supported: string[]; -``` - -### revocation\_endpoint\_auth\_signing\_alg\_values\_supported? {#revocation-endpoint-auth-signing-alg-values-supported} - -```ts -optional revocation_endpoint_auth_signing_alg_values_supported: string[]; -``` - -### scope\_supported? {#scope-supported} - -```ts -optional scope_supported: string[]; -``` - -### service\_documentation? {#service-documentation} - -```ts -optional service_documentation: string; -``` - -### token\_endpoint {#token-endpoint} - -```ts -token_endpoint: string; -``` - -授權伺服器的權杖端點（token endpoint）URL [[RFC6749](https://rfc-editor.org/rfc/rfc6749)]。 -除非僅支援 implicit 授權類型，否則此欄位為必填。 - -#### 參見 {#see} - -https://rfc-editor.org/rfc/rfc6749#section-3.2 - -### token\_endpoint\_auth\_methods\_supported? {#token-endpoint-auth-methods-supported} - -```ts -optional token_endpoint_auth_methods_supported: string[]; -``` - -### token\_endpoint\_auth\_signing\_alg\_values\_supported? {#token-endpoint-auth-signing-alg-values-supported} - -```ts -optional token_endpoint_auth_signing_alg_values_supported: string[]; -``` - -### ui\_locales\_supported? {#ui-locales-supported} - -```ts -optional ui_locales_supported: string[]; -``` - -### userinfo\_endpoint? {#userinfo-endpoint} - -```ts -optional userinfo_endpoint: string; -``` - -OpenID Connect [userinfo 端點](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 的 URL。 -此端點用於取得已驗證使用者的相關資訊。 - -## 參見 {#see} - -https://datatracker.ietf.org/doc/html/rfc8414 \ No newline at end of file diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthConfig.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthConfig.md deleted file mode 100644 index ade712e..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthConfig.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -sidebar_label: BearerAuthConfig ---- - -# 型別別名：BearerAuthConfig - -```ts -type BearerAuthConfig = { - audience?: string; - issuer: string; - requiredScopes?: string[]; - showErrorDetails?: boolean; - verifyAccessToken: VerifyAccessTokenFunction; -}; -``` - -## 屬性 {#properties} - -### audience? {#audience} - -```ts -optional audience: string; -``` - -存取權杖 (Access token) 預期的受眾 (Audience)（`aud` 宣告 (claim)）。這通常是該權杖預期要存取的資源伺服器（API）。如果未提供，則會略過受眾檢查。 - -**注意：** 如果你的授權伺服器 (Authorization server) 不支援資源標示符 (Resource Indicators, RFC 8707)，你可以省略此欄位，因為受眾可能不適用。 - -#### 參考 {#see} - -https://datatracker.ietf.org/doc/html/rfc8707 - -*** - -### issuer {#issuer} - -```ts -issuer: string; -``` - -存取權杖 (Access token) 預期的簽發者 (Issuer)（`iss` 宣告 (claim)）。這應該是簽發該權杖的授權伺服器 (Authorization server) 的 URL。 - -*** - -### requiredScopes? {#requiredscopes} - -```ts -optional requiredScopes: string[]; -``` - -存取權杖 (Access token) 必須具備的權限範圍 (Scopes) 陣列。如果權杖未包含所有這些權限範圍，將會拋出錯誤。 - -**注意：** 處理器會檢查權杖中的 `scope` 宣告 (claim)，其內容可能是以空格分隔的字串，或是字串陣列，這取決於授權伺服器的實作方式。如果 `scope` 宣告不存在，則會檢查 `scopes` 宣告（若有的話）。 - -*** - -### showErrorDetails? {#showerrordetails} - -```ts -optional showErrorDetails: boolean; -``` - -是否在回應中顯示詳細錯誤資訊。這對於開發期間除錯很有幫助，但在生產環境中應關閉，以避免洩漏敏感資訊。 - -#### 預設值 {#default} - -```ts -false -``` - -*** - -### verifyAccessToken {#verifyaccesstoken} - -```ts -verifyAccessToken: VerifyAccessTokenFunction; -``` - -用於驗證存取權杖 (Access token) 的函式型別。 - -此函式若權杖無效，應拋出 [MCPAuthTokenVerificationError](/references/js/classes/MCPAuthTokenVerificationError.md)；若權杖有效，則回傳 AuthInfo 物件。 - -#### 參考 {#see} - -[VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) 以取得更多細節。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthErrorCode.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthErrorCode.md deleted file mode 100644 index 2fc8402..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthErrorCode.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_label: BearerAuthErrorCode ---- - -# 型別別名：BearerAuthErrorCode (Type Alias: BearerAuthErrorCode) - -```ts -type BearerAuthErrorCode = - | "missing_auth_header" - | "invalid_auth_header_format" - | "missing_bearer_token" - | "invalid_issuer" - | "invalid_audience" - | "missing_required_scopes" - | "invalid_token"; -``` diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthJwtConfig.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthJwtConfig.md deleted file mode 100644 index 0b3b79d..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/BearerAuthJwtConfig.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -sidebar_label: BearerAuthJwtConfig ---- - -# 型別別名：BearerAuthJwtConfig (Type Alias: BearerAuthJwtConfig) - -```ts -type BearerAuthJwtConfig = { - jwtVerify?: JWTVerifyOptions; - remoteJwkSet?: RemoteJWKSetOptions; -}; -``` - -使用 JWT 驗證時，Bearer 驗證 (Bearer auth) 處理器的設定。 - -## 屬性 (Properties) {#properties} - -### jwtVerify? {#jwtverify} - -```ts -optional jwtVerify: JWTVerifyOptions; -``` - -傳遞給 `jose` 函式庫 `jwtVerify` 函式的選項。 - -#### 參見 (See) {#see} - -JWTVerifyOptions，該選項的型別定義。 - -*** - -### remoteJwkSet? {#remotejwkset} - -```ts -optional remoteJwkSet: RemoteJWKSetOptions; -``` - -傳遞給 `jose` 函式庫 `createRemoteJWKSet` 函式的選項。 - -#### 參見 (See) {#see} - -RemoteJWKSetOptions，該選項的型別定義。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md deleted file mode 100644 index f83d990..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -sidebar_label: CamelCaseAuthorizationServerMetadata ---- - -# 型別別名：CamelCaseAuthorizationServerMetadata - -```ts -type CamelCaseAuthorizationServerMetadata = { - authorizationEndpoint: string; - codeChallengeMethodsSupported?: string[]; - grantTypesSupported?: string[]; - introspectionEndpoint?: string; - introspectionEndpointAuthMethodsSupported?: string[]; - introspectionEndpointAuthSigningAlgValuesSupported?: string[]; - issuer: string; - jwksUri?: string; - opPolicyUri?: string; - opTosUri?: string; - registrationEndpoint?: string; - responseModesSupported?: string[]; - responseTypesSupported: string[]; - revocationEndpoint?: string; - revocationEndpointAuthMethodsSupported?: string[]; - revocationEndpointAuthSigningAlgValuesSupported?: string[]; - scopeSupported?: string[]; - serviceDocumentation?: string; - tokenEndpoint: string; - tokenEndpointAuthMethodsSupported?: string[]; - tokenEndpointAuthSigningAlgValuesSupported?: string[]; - uiLocalesSupported?: string[]; - userinfoEndpoint?: string; -}; -``` - -OAuth 2.0 授權伺服器中繼資料（Authorization Server Metadata）型別的 camelCase 版本。 - -## 型別宣告 {#type-declaration} - -### authorizationEndpoint {#authorizationendpoint} - -```ts -authorizationEndpoint: string; -``` - -### codeChallengeMethodsSupported? {#codechallengemethodssupported} - -```ts -optional codeChallengeMethodsSupported: string[]; -``` - -### grantTypesSupported? {#granttypessupported} - -```ts -optional grantTypesSupported: string[]; -``` - -### introspectionEndpoint? {#introspectionendpoint} - -```ts -optional introspectionEndpoint: string; -``` - -### introspectionEndpointAuthMethodsSupported? {#introspectionendpointauthmethodssupported} - -```ts -optional introspectionEndpointAuthMethodsSupported: string[]; -``` - -### introspectionEndpointAuthSigningAlgValuesSupported? {#introspectionendpointauthsigningalgvaluessupported} - -```ts -optional introspectionEndpointAuthSigningAlgValuesSupported: string[]; -``` - -### issuer {#issuer} - -```ts -issuer: string; -``` - -### jwksUri? {#jwksuri} - -```ts -optional jwksUri: string; -``` - -### opPolicyUri? {#oppolicyuri} - -```ts -optional opPolicyUri: string; -``` - -### opTosUri? {#optosuri} - -```ts -optional opTosUri: string; -``` - -### registrationEndpoint? {#registrationendpoint} - -```ts -optional registrationEndpoint: string; -``` - -### responseModesSupported? {#responsemodessupported} - -```ts -optional responseModesSupported: string[]; -``` - -### responseTypesSupported {#responsetypessupported} - -```ts -responseTypesSupported: string[]; -``` - -### revocationEndpoint? {#revocationendpoint} - -```ts -optional revocationEndpoint: string; -``` - -### revocationEndpointAuthMethodsSupported? {#revocationendpointauthmethodssupported} - -```ts -optional revocationEndpointAuthMethodsSupported: string[]; -``` - -### revocationEndpointAuthSigningAlgValuesSupported? {#revocationendpointauthsigningalgvaluessupported} - -```ts -optional revocationEndpointAuthSigningAlgValuesSupported: string[]; -``` - -### scopeSupported? {#scopesupported} - -```ts -optional scopeSupported: string[]; -``` - -### serviceDocumentation? {#servicedocumentation} - -```ts -optional serviceDocumentation: string; -``` - -### tokenEndpoint {#tokenendpoint} - -```ts -tokenEndpoint: string; -``` - -### tokenEndpointAuthMethodsSupported? {#tokenendpointauthmethodssupported} - -```ts -optional tokenEndpointAuthMethodsSupported: string[]; -``` - -### tokenEndpointAuthSigningAlgValuesSupported? {#tokenendpointauthsigningalgvaluessupported} - -```ts -optional tokenEndpointAuthSigningAlgValuesSupported: string[]; -``` - -### uiLocalesSupported? {#uilocalessupported} - -```ts -optional uiLocalesSupported: string[]; -``` - -### userinfoEndpoint? {#userinfoendpoint} - -```ts -optional userinfoEndpoint: string; -``` - -## 參見 {#see} - -[AuthorizationServerMetadata](/references/js/type-aliases/AuthorizationServerMetadata.md) 以取得原始型別與欄位資訊。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md deleted file mode 100644 index 9ac67d2..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -sidebar_label: MCPAuthBearerAuthErrorDetails ---- - -# 型別別名：MCPAuthBearerAuthErrorDetails (Type Alias: MCPAuthBearerAuthErrorDetails) - -```ts -type MCPAuthBearerAuthErrorDetails = { - actual?: unknown; - cause?: unknown; - expected?: unknown; - missingScopes?: string[]; - uri?: URL; -}; -``` - -## 屬性 (Properties) {#properties} - -### actual? {#actual} - -```ts -optional actual: unknown; -``` - -*** - -### cause? {#cause} - -```ts -optional cause: unknown; -``` - -*** - -### expected? {#expected} - -```ts -optional expected: unknown; -``` - -*** - -### missingScopes? {#missingscopes} - -```ts -optional missingScopes: string[]; -``` - -*** - -### uri? {#uri} - -```ts -optional uri: URL; -``` diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthConfig.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthConfig.md deleted file mode 100644 index b6c7523..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthConfig.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -sidebar_label: MCPAuthConfig ---- - -# 型別別名：MCPAuthConfig (Type Alias: MCPAuthConfig) - -```ts -type MCPAuthConfig = { - server: AuthServerConfig; -}; -``` - -[MCPAuth](/references/js/classes/MCPAuth.md) 類別的設定。 - -## 屬性 (Properties) {#properties} - -### server {#server} - -```ts -server: AuthServerConfig; -``` - -遠端授權伺服器的設定。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md deleted file mode 100644 index 6038b98..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: MCPAuthTokenVerificationErrorCode ---- - -# 型別別名：MCPAuthTokenVerificationErrorCode (Type Alias: MCPAuthTokenVerificationErrorCode) - -```ts -type MCPAuthTokenVerificationErrorCode = "invalid_token" | "token_verification_failed"; -``` diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenFunction.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenFunction.md deleted file mode 100644 index 1270359..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenFunction.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -sidebar_label: VerifyAccessTokenFunction ---- - -# 型別別名：VerifyAccessTokenFunction() - -```ts -type VerifyAccessTokenFunction = (token: string) => MaybePromise; -``` - -用於驗證存取權杖 (Access token) 的函式型別。 - -此函式應在權杖無效時拋出 [MCPAuthTokenVerificationError](/references/js/classes/MCPAuthTokenVerificationError.md)， -若權杖有效則回傳 AuthInfo 物件。 - -例如，若你有一個 JWT 驗證函式，至少應檢查權杖的簽章、驗證其過期時間，並擷取必要的宣告 (Claims) 以回傳 `AuthInfo` 物件。 - -**注意：** 無需驗證權杖中的以下欄位，這些將由處理器自動檢查： - -- `iss`（簽發者 (Issuer)） -- `aud`（受眾 (Audience)） -- `scope`（權限範圍 (Scopes)） - -## 參數 {#parameters} - -### token {#token} - -`string` - -要驗證的存取權杖 (Access token) 字串。 - -## 回傳值 {#returns} - -`MaybePromise`\<`AuthInfo`\> - -一個 Promise，若權杖有效則解析為 AuthInfo 物件，或同步回傳該物件。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenMode.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenMode.md deleted file mode 100644 index b249f81..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenMode.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: VerifyAccessTokenMode ---- - -# 型別別名：VerifyAccessTokenMode (Type Alias: VerifyAccessTokenMode) - -```ts -type VerifyAccessTokenMode = "jwt"; -``` diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authServerErrorDescription.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authServerErrorDescription.md deleted file mode 100644 index 91f5bfc..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authServerErrorDescription.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: authServerErrorDescription ---- - -# 變數：authServerErrorDescription (authServerErrorDescription) - -```ts -const authServerErrorDescription: Readonly>; -``` diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authorizationServerMetadataSchema.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authorizationServerMetadataSchema.md deleted file mode 100644 index 17346ff..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/authorizationServerMetadataSchema.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: authorizationServerMetadataSchema ---- - -# 變數：authorizationServerMetadataSchema - -```ts -const authorizationServerMetadataSchema: ZodObject; -``` - -RFC 8414 所定義的 OAuth 2.0 授權伺服器中繼資料（Authorization Server Metadata）之 Zod schema。 - -## 參考 {#see} - -https://datatracker.ietf.org/doc/html/rfc8414 \ No newline at end of file diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/bearerAuthErrorDescription.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/bearerAuthErrorDescription.md deleted file mode 100644 index ef9c398..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/bearerAuthErrorDescription.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: bearerAuthErrorDescription ---- - -# 變數：bearerAuthErrorDescription (bearerAuthErrorDescription) - -```ts -const bearerAuthErrorDescription: Readonly>; -``` diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md deleted file mode 100644 index d6feacb..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: camelCaseAuthorizationServerMetadataSchema ---- - -# 變數：camelCaseAuthorizationServerMetadataSchema - -```ts -const camelCaseAuthorizationServerMetadataSchema: ZodObject; -``` - -OAuth 2.0 授權伺服器中繼資料（Authorization Server Metadata）Zod schema 的 camelCase 版本。 - -## 參見 {#see} - -請參閱 [authorizationServerMetadataSchema](/references/js/variables/authorizationServerMetadataSchema.md) 以取得原始 schema 與欄位資訊。 \ No newline at end of file diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/serverMetadataPaths.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/serverMetadataPaths.md deleted file mode 100644 index ff1fe69..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/serverMetadataPaths.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_label: serverMetadataPaths ---- - -# 變數：serverMetadataPaths (serverMetadataPaths) - -```ts -const serverMetadataPaths: Readonly<{ - oauth: "/.well-known/oauth-authorization-server"; - oidc: "/.well-known/openid-configuration"; -}>; -``` diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/tokenVerificationErrorDescription.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/tokenVerificationErrorDescription.md deleted file mode 100644 index db59562..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/tokenVerificationErrorDescription.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: tokenVerificationErrorDescription ---- - -# 變數：tokenVerificationErrorDescription (tokenVerificationErrorDescription) - -```ts -const tokenVerificationErrorDescription: Readonly>; -``` diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/validateServerConfig.md b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/validateServerConfig.md deleted file mode 100644 index 5c85420..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/references/js/variables/validateServerConfig.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: validateServerConfig ---- - -# 變數：validateServerConfig (validateServerConfig) - -```ts -const validateServerConfig: ValidateServerConfig; -``` diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/snippets/_get-started-code.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/snippets/_get-started-code.mdx deleted file mode 100644 index 87c7b46..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/snippets/_get-started-code.mdx +++ /dev/null @@ -1,41 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - - - - - -```python -mcp = FastMCP("MyMCPServer") -mcp_auth = MCPAuth(server=fetch_server_config('', type=AuthServerType.OIDC)) -app = Starlette( - # ... 你的 MCP 伺服器設定 - middleware=[Middleware( - mcp_auth.bearer_auth_middleware("jwt", required_scopes=["read", "write"]) - )] -) - -# 使用 `mcp_auth.auth_info` 來存取當前請求的驗證 (Authentication) 資訊 -@mcp.tool() -def whoami() -> dict[str, Any]: - return mcp_auth.auth_info.claims -``` - - - - -```ts -const server = new McpServer(/* ... */); -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { type: 'oidc' }), -}); -const app = express(); - -app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] })); -server.tool('whoami', ({ authInfo }) => { - // 使用 `authInfo` 來存取從 `req.auth` 帶來的驗證 (Authentication) 資訊 -}); -``` - - - diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/README.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/README.mdx deleted file mode 100644 index ba22af5..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/README.mdx +++ /dev/null @@ -1,1149 +0,0 @@ ---- -sidebar_position: 2 -sidebar_label: '教學：打造待辦事項管理器 (Tutorial: Build a todo manager)' ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import SetupOauthOrOidc from './_setup-oauth-or-oidc.mdx'; -import SetupOidc from './_setup-oidc.mdx'; - -# 教學：打造待辦事項管理器 (Tutorial: Build a todo manager) - -在本教學中，我們將建立一個具備使用者驗證 (Authentication) 與授權 (Authorization) 的 todo manager MCP 伺服器。 - -完成本教學後，你將會： - -- ✅ 基本瞭解如何在 MCP 伺服器中設定角色型存取控制 (RBAC, Role-based Access Control) -- ✅ 擁有一個可以管理個人待辦清單的 MCP 伺服器 - -:::note -在開始之前，如果你對 MCP 伺服器與 OAuth 2 不熟悉，強烈建議先閱讀 [Who am I 教學](./whoami)。 -::: - -## 概覽 (Overview) \{#overview} - -本教學將包含以下元件： - -- **MCP 伺服器**：一個簡單的 MCP 伺服器，使用 MCP 官方 SDK 處理請求，並整合 Todo 服務來管理使用者的待辦事項。 -- **MCP inspector**：一個 MCP 伺服器的視覺化測試工具，同時作為 OAuth / OIDC 用戶端，啟動授權流程並取得存取權杖 (Access token)。 -- **授權伺服器 (Authorization server)**：一個 OAuth 2.1 或 OpenID Connect 提供者，負責管理使用者身分並簽發存取權杖 (Access token)。 - -以下是這些元件間互動的高階圖示： - -```mermaid -sequenceDiagram - participant Client as MCP Inspector - participant Server as MCP Server - participant Auth as 授權伺服器 (Authorization Server) - - Client->>Server: 請求待辦事項操作 (Request todo operation) - Server->>Client: 回傳 401 未授權 (Return 401 Unauthorized) - Client->>Auth: 啟動授權流程 (Initiate authorization flow) - Auth->>Auth: 完成授權流程 (Complete authorization flow) - Auth->>Client: 帶授權碼重導回來 (Redirect back with authorization code) - Client->>Auth: 用授權碼換取存取權杖 (Exchange code for access token) - Auth->>Client: 回傳存取權杖 (Return access token) - Client->>Server: 攜帶存取權杖請求待辦事項操作 (Request todo operation with access token) - Server->>Server: 驗證存取權杖並取得使用者權限範圍 (Validate access token and get user scopes form access token) - Note over Server: 執行待辦事項操作 (Execute todo operation) - Server->>Client: 回傳操作結果 (Return todo operation result) -``` - -## 瞭解你的授權伺服器 (Understand your authorization server) \{#understand-your-authorization-server} - -### 具有權限範圍 (Scopes) 的存取權杖 (Access tokens) \{#access-tokens-with-scopes} - -要在 MCP 伺服器中實作 [角色型存取控制 (RBAC, Role-based Access Control)](https://auth.wiki/rbac)，你的授權伺服器需支援簽發帶有權限範圍 (Scopes) 的存取權杖 (Access tokens)。權限範圍 (Scopes) 代表使用者被授予的權限。 - - - - -[Logto](https://logto.io) 透過 API 資源 (API resources)（符合 [RFC 8707: Resource Indicators for OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)）與角色 (Roles) 功能支援 RBAC。設定方式如下： - -1. 登入 [Logto Console](https://cloud.logto.io)（或你的自架 Logto Console） - -2. 建立 API 資源與權限範圍 (Scopes)： - - - 前往「API 資源 (API Resources)」 - - 建立一個名為「Todo Manager」的新 API 資源 - - 新增以下權限範圍： - - `create:todos`：「建立新待辦事項」 - - `read:todos`：「讀取所有待辦事項」 - - `delete:todos`：「刪除任一待辦事項」 - -3. 建立角色（建議以便管理）： - - - 前往「角色 (Roles)」 - - 建立「Admin」角色並指派所有權限範圍（`create:todos`、`read:todos`、`delete:todos`） - - 建立「User」角色並僅指派 `create:todos` 權限範圍 - -4. 指派權限： - - 前往「使用者 (Users)」 - - 選擇一位使用者 - - 你可以： - - 在「角色 (Roles)」分頁指派角色（建議） - - 或直接在「權限 (Permissions)」分頁指派權限範圍 - -這些權限範圍會以空格分隔字串的形式包含在 JWT 存取權杖的 `scope` 宣告 (Claim) 中。 - - - - -OAuth 2.0 / OIDC 提供者通常支援基於權限範圍 (Scope) 的存取控制。實作 RBAC 時： - -1. 在授權伺服器中定義所需的權限範圍 -2. 設定用戶端在授權流程中請求這些權限範圍 -3. 確保授權伺服器將授予的權限範圍包含在存取權杖中 -4. 權限範圍通常會包含在 JWT 存取權杖的 `scope` 宣告 (Claim) 中 - -請查閱你的提供者文件以瞭解： - -- 如何定義與管理權限範圍 -- 權限範圍如何包含在存取權杖中 -- 是否有額外的 RBAC 功能如角色管理 - - - - -### 權杖驗證與權限檢查 (Validating tokens and checking permissions) \{#validating-tokens-and-checking-permissions} - -當 MCP 伺服器收到請求時，需執行： - -1. 驗證存取權杖的簽章與有效期限 -2. 從驗證後的權杖中擷取權限範圍 (Scopes) -3. 檢查權杖是否具備執行該操作所需的權限範圍 - -例如，若使用者要建立新待辦事項，其存取權杖必須包含 `create:todos` 權限範圍。流程如下： - -```mermaid -sequenceDiagram - participant Client - participant MCP Server - participant Auth Server - - Client->>MCP Server: 攜帶存取權杖請求 (Request with access token) - - alt JWT 驗證 (JWT Validation) - MCP Server->>Auth Server: 取得 JWKS (Fetch JWKS) - Auth Server-->>MCP Server: 回傳 JWKS (Return JWKS) - MCP Server->>MCP Server: 本地驗證 JWT (Validate JWT locally) - else 權杖內省 (Token Introspection) - MCP Server->>Auth Server: POST /introspect
(token=access_token) - Auth Server-->>MCP Server: 回傳權杖資訊
(active, scope, etc.) - end - - MCP Server->>MCP Server: 擷取並檢查權限範圍 (Extract & check scopes) - - alt 具備所需權限範圍 (Has required scopes) - MCP Server->>Client: 允許操作 (Allow operation) - else 欠缺權限範圍 (Missing scopes) - MCP Server->>Client: 回傳 403 禁止 (Return 403 Forbidden) - end -``` - -### 動態用戶端註冊 (Dynamic Client Registration) \{#dynamic-client-registration} - -本教學不強制需要動態用戶端註冊，但若你想自動化 MCP 用戶端註冊流程，可參考 [是否需要 Dynamic Client Registration?](/provider-list#is-dcr-required)。 - -## 瞭解 todo manager 的 RBAC (Understand RBAC in todo manager) \{#understand-rbac-in-todo-manager} - -為了示範，我們會在 todo manager MCP 伺服器中實作一個簡單的角色型存取控制 (RBAC) 系統，讓你瞭解 RBAC 的基本原則，同時保持實作簡單。 - -:::note -雖然本教學以 RBAC 權限範圍管理為例，但並非所有驗證 (Authentication) 提供者都透過角色 (Role) 來管理權限範圍 (Scope)。有些提供者可能有自己獨特的存取控制與權限管理機制。 -::: - -### 工具與權限範圍 (Tools and scopes) \{#tools-and-scopes} - -我們的 todo manager MCP 伺服器提供三個主要工具： - -- `create-todo`：建立新待辦事項 -- `get-todos`：列出所有待辦事項 -- `delete-todo`：依 ID 刪除待辦事項 - -為了控制這些工具的存取，我們定義以下權限範圍： - -- `create:todos`：允許建立新待辦事項 -- `delete:todos`：允許刪除現有待辦事項 -- `read:todos`：允許查詢並取得所有待辦事項清單 - -### 角色與權限 (Roles and permissions) \{#roles-and-permissions} - -我們將定義兩個不同存取層級的角色： - -| 角色 (Role) | create:todos | read:todos | delete:todos | -| ----------- | ------------ | ---------- | ------------ | -| Admin | ✅ | ✅ | ✅ | -| User | ✅ | | | - -- **User**：一般使用者，可建立待辦事項，僅能檢視或刪除自己的待辦事項 -- **Admin**：管理員，可建立、檢視及刪除所有待辦事項，不論擁有者為誰 - -### 資源擁有權 (Resource ownership) \{#resource-ownership} - -雖然上表顯示每個角色明確被指派的權限範圍，但還有一個重要的「資源擁有權」原則： - -- **User** 沒有 `read:todos` 或 `delete:todos` 權限範圍，但仍可： - - 讀取自己的待辦事項 - - 刪除自己的待辦事項 -- **Admin** 擁有完整權限（`read:todos` 與 `delete:todos`），可： - - 檢視系統中所有待辦事項 - - 刪除任何待辦事項，不論擁有者 - -這展現了 RBAC 系統中常見的模式：資源擁有權會隱含授予使用者對自己資源的權限，而管理角色則獲得對所有資源的明確權限。 - -:::tip 進一步瞭解 -想深入瞭解 RBAC 概念與最佳實踐，請參閱 [精通 RBAC：完整實例解析 (Mastering RBAC: A Comprehensive Real-World Example)](https://blog.logto.io/mastering-rbac)。 -::: - -## 在你的提供者中設定授權 (Configure authorization in your provider) \{#configure-authorization-in-your-provider} - -要實作上述存取控制系統，你需要在授權伺服器中設定所需的權限範圍。以下是不同提供者的設定方式： - - - - -[Logto](https://logto.io) 透過 API 資源 (API resources) 與角色 (Roles) 功能支援 RBAC。設定方式如下： - -1. 登入 [Logto Console](https://cloud.logto.io)（或你的自架 Logto Console） - -2. 建立 API 資源與權限範圍： - - - 前往「API 資源 (API Resources)」 - - 建立一個名為「Todo Manager」的新 API 資源，並以 `https://todo.mcp-server.app`（僅供示範）作為資源標示符 (indicator)。 - - 建立以下權限範圍： - - `create:todos`：「建立新待辦事項」 - - `read:todos`：「讀取所有待辦事項」 - - `delete:todos`：「刪除任一待辦事項」 - -3. 建立角色（建議以便管理）： - - - 前往「角色 (Roles)」 - - 建立「Admin」角色並指派所有權限範圍（`create:todos`、`read:todos`、`delete:todos`） - - 建立「User」角色並僅指派 `create:todos` 權限範圍 - - 在「User」角色詳細頁切換到「一般 (General)」分頁，將「User」設為「預設角色 (Default role)」 - -4. 管理使用者角色與權限： - - 新使用者： - - 會自動獲得「User」角色（因已設為預設角色） - - 現有使用者： - - 前往「使用者管理 (User management)」 - - 選擇一位使用者 - - 在「角色 (Roles)」分頁指派角色 - -:::tip 程式化角色管理 (Programmatic Role Management) -你也可以透過 Logto 的 [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api) 程式化管理使用者角色。這對自動化使用者管理或建立管理後台特別有用。 -::: - -請求存取權杖時，Logto 會根據使用者角色權限將權限範圍包含在權杖的 `scope` 宣告中。 - - - - -在 [Keycloak](https://www.keycloak.org) 中，你可以透過 client scopes 設定所需權限： - -1. 建立 client scopes： - - - 在你的 realm 中，前往「Client scopes」 - - 建立三個新 client scopes： - - `create:todos` - - `read:todos` - - `delete:todos` - -2. 設定用戶端： - - - 前往你的 client 設定 - - 在「Client scopes」分頁新增所有已建立的 scopes - - 確認 token mapper 已設定為包含 scopes - -3. 選用：使用角色方便管理 - - 若偏好角色型管理： - - 建立不同存取層級的 realm roles - - 將 scopes 映射到角色 - - 指派角色給使用者 - - 否則可直接指派 scopes 給使用者或透過 client-level permissions - -Keycloak 會將授予的 scopes 包含在存取權杖的 `scope` 宣告中。 - - - - -對於 OAuth 2.0 或 OpenID Connect 提供者，你需要設定代表不同權限的 scopes。具體步驟依提供者而異，但一般流程如下： - -1. 定義 scopes： - - - 設定授權伺服器支援： - - `create:todos` - - `read:todos` - - `delete:todos` - -2. 設定用戶端： - - - 註冊或更新用戶端以請求這些 scopes - - 確認 scopes 會包含在存取權杖中 - -3. 指派權限： - - 透過提供者介面授予使用者適當的 scopes - - 有些提供者支援角色型管理，有些則直接指派 scopes - - 請查閱提供者文件以獲得建議做法 - -:::tip -大多數提供者會將授予的 scopes 包含在存取權杖的 `scope` 宣告中，格式通常為空格分隔的 scope 字串。 -::: - - - - -設定好授權伺服器後，使用者將取得包含其授權 scopes 的存取權杖。MCP 伺服器會根據這些 scopes 判斷： - -- 使用者是否能建立新待辦事項（`create:todos`） -- 使用者是否能檢視所有待辦事項（`read:todos`）或僅能檢視自己的 -- 使用者是否能刪除任一待辦事項（`delete:todos`）或僅能刪除自己的 - -## 設定 MCP 伺服器 (Set up the MCP server) \{#set-up-the-mcp-server} - -我們將使用 [MCP 官方 SDK](https://github.com/modelcontextprotocol) 建立 todo manager MCP 伺服器。 - -### 建立新專案 (Create a new project) \{#create-a-new-project} - - - - -```bash -mkdir mcp-server -cd mcp-server -uv init # 或使用 `pipenv` 或 `poetry` 建立新虛擬環境 -``` - - - - -建立新的 Node.js 專案： - -```bash -mkdir mcp-server -cd mcp-server -npm init -y # 或使用 `pnpm init` -npm pkg set type="module" -npm pkg set main="todo-manager.ts" -npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts" -``` - -:::note -我們範例中使用 TypeScript，因為 Node.js v22.6.0+ 原生支援 `--experimental-strip-types` 執行 TypeScript。如果你用 JavaScript，程式碼也很類似——只要確保 Node.js 版本為 v22.6.0 或以上。詳情請參閱 Node.js 文件。 -::: - - - - -### 安裝 MCP SDK 與相依套件 (Install the MCP SDK and dependencies) \{#install-the-mcp-sdk-and-dependencies} - - - - -```bash -pip install "mcp[cli]" starlette uvicorn -``` - -或你偏好的其他套件管理工具，如 `uv` 或 `poetry`。 - - - - -```bash -npm install @modelcontextprotocol/sdk express zod -``` - -或你偏好的其他套件管理工具，如 `pnpm` 或 `yarn`。 - - - - -### 建立 MCP 伺服器 (Create the MCP server) \{#create-the-mcp-server} - -首先，建立一個基本的 MCP 伺服器並定義工具： - - - - -建立 `todo-manager.py` 檔案並加入以下程式碼： - -```python -from typing import Any -from mcp.server.fastmcp import FastMCP -from starlette.applications import Starlette -from starlette.routing import Mount - -mcp = FastMCP("Todo Manager") - -@mcp.tool() -def create_todo(content: str) -> dict[str, Any]: - """Create a new todo.""" - return {"error": "Not implemented"} - -@mcp.tool() -def get_todos() -> dict[str, Any]: - """List all todos.""" - return {"error": "Not implemented"} - -@mcp.tool() -def delete_todo(id: str) -> dict[str, Any]: - """Delete a todo by id.""" - return {"error": "Not implemented"} - -app = Starlette( - routes=[Mount('/', app=mcp.sse_app())] -) -``` - -啟動伺服器： - -```bash -uvicorn todo_manager:app --host 0.0.0.0 --port 3001 -``` - - - - -:::note -目前 MCP inspector 尚未支援授權流程，因此我們採用 SSE 方式設定 MCP 伺服器。待 MCP inspector 支援授權流程後會更新此處程式碼。 -::: - -你也可以用 `pnpm` 或 `yarn`。 - -建立 `todo-manager.ts` 檔案並加入以下程式碼： - -```ts -// todo-manager.ts - -import { z } from 'zod'; -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; -import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'; -import express from 'express'; - -// 建立 MCP 伺服器 -const server = new McpServer({ - name: 'Todo Manager', - version: '0.0.0', -}); - -server.tool('create-todo', 'Create a new todo', { content: z.string() }, async ({ content }) => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }], - }; -}); - -server.tool('get-todos', 'List all todos', async () => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }], - }; -}); - -server.tool('delete-todo', 'Delete a todo by id', { id: z.string() }, async ({ id }) => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }], - }; -}); - -// 以下為 MCP SDK 文件範例樣板 -const PORT = 3001; -const app = express(); - -const transports = {}; - -app.get('/sse', async (_req, res) => { - const transport = new SSEServerTransport('/messages', res); - transports[transport.sessionId] = transport; - - res.on('close', () => { - delete transports[transport.sessionId]; - }); - - await server.connect(transport); -}); - -app.post('/messages', async (req, res) => { - const sessionId = String(req.query.sessionId); - const transport = transports[sessionId]; - if (transport) { - await transport.handlePostMessage(req, res, req.body); - } else { - res.status(400).send('No transport found for sessionId'); - } -}); - -app.listen(PORT); -``` - -啟動伺服器： - -```bash -npm start -``` - - - - -## 檢查 MCP 伺服器 (Inspect the MCP server) \{#inspect-the-mcp-server} - -### 複製並執行 MCP inspector \{#clone-and-run-mcp-inspector} - -現在 MCP 伺服器已啟動，可以用 MCP inspector 檢查 `whoami` 工具是否可用。 - -由於現有實作限制，我們 fork 了 [MCP inspector](https://github.com/mcp-auth/inspector) 以提升其彈性與可擴展性，並已向原專案提交 PR。 - -執行 MCP inspector： - -```bash -git clone https://github.com/mcp-auth/inspector.git -cd inspector -npm install -npm run dev -``` - -然後在瀏覽器開啟 `http://localhost:6274/`（或終端機顯示的其他網址）即可存取 MCP inspector。 - -### 連接 MCP inspector 與 MCP 伺服器 \{#connect-mcp-inspector-to-the-mcp-server} - -繼續前請檢查 MCP inspector 設定： - -- **Transport Type**：設為 `SSE` -- **URL**：設為 MCP 伺服器的 URL，本例為 `http://localhost:3001/sse` - -現在點擊「Connect」按鈕，檢查 MCP inspector 是否能連上 MCP 伺服器。若一切正常，應會看到 MCP inspector 顯示「Connected」狀態。 - -### 檢查點：執行 todo manager 工具 \{#checkpoint-run-todo-manager-tools} - -1. 在 MCP inspector 頂部選單點選「Tools」分頁 -2. 點擊「List Tools」按鈕 -3. 應會看到 `create-todo`、`get-todos`、`delete-todo` 工具列於頁面，點擊可檢視工具詳情 -4. 右側會有「Run Tool」按鈕，點擊並輸入必要參數執行工具 -5. 應會看到工具回傳結果為 `{"error": "Not implemented"}` 的 JSON - -![MCP inspector 首次執行畫面](/docs-assets/images/tutorials/todo-manager/inspector-first-run.png) - -## 與授權伺服器整合 (Integrate with your authorization server) \{#integrate-with-your-authorization-server} - -完成本節需考慮以下幾點： - -
-**你的授權伺服器的簽發者 (Issuer) URL** - -通常是授權伺服器的基礎網址，如 `https://auth.example.com`。有些提供者可能會是 `https://example.logto.app/oidc` 這類路徑，請查閱提供者文件。 - -
- -
-**如何取得授權伺服器 metadata** - -- 若你的授權伺服器符合 [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) 或 [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)，可用 MCP Auth 內建工具自動抓取 metadata。 -- 若不符合，需手動指定 metadata URL 或端點於 MCP 伺服器設定，請查閱提供者文件。 - -
- -
-**如何將 MCP inspector 註冊為授權伺服器用戶端** - -- 若授權伺服器支援 [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591)，MCP inspector 會自動註冊為用戶端，可略過此步驟。 -- 若不支援，需手動將 MCP inspector 註冊為用戶端。 - -
- -
-**瞭解權杖請求參數** - -向不同授權伺服器請求存取權杖時，指定目標資源與權限的方式可能不同，主要有： - -- **基於資源標示符 (Resource indicator based)**： - - - 使用 `resource` 參數指定目標 API（參見 [RFC 8707: Resource Indicators for OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)） - - 現代 OAuth 2.0 常見 - - 範例請求： - ```json - { - "resource": "https://todo.mcp-server.app", - "scope": "create:todos read:todos" - } - ``` - - 伺服器會簽發專屬於該資源的權杖 - -- **基於受眾 (Audience based)**： - - - 使用 `audience` 參數指定權杖預期接收者 - - 與資源標示符類似但語意不同 - - 範例請求： - ```json - { - "audience": "todo-api", - "scope": "create:todos read:todos" - } - ``` - -- **純權限範圍 (Pure scope based)**： - - 僅依 scopes，不帶 resource/audience 參數 - - 傳統 OAuth 2.0 作法 - - 範例請求： - ```json - { - "scope": "todo-api:create todo-api:read openid profile" - } - ``` - - 常用前綴命名空間權限 - - 簡單 OAuth 2.0 常見 - -:::tip 最佳實踐 (Best Practices) - -- 查閱提供者文件確認支援哪些參數 -- 有些提供者同時支援多種方式 -- 資源標示符可提升安全性（限制受眾） -- 建議有支援時優先採用資源標示符 - ::: - -
- -每個提供者細節不同，以下步驟可協助你依提供者設定 MCP inspector 與 MCP 伺服器。 - -### 註冊 MCP inspector 為用戶端 \{#register-mcp-inspector-as-a-client} - - - - -將 todo manager 與 [Logto](https://logto.io) 整合很簡單，因為它是支援資源標示符與權限範圍的 OpenID Connect 提供者，可用 `https://todo.mcp-server.app` 作為資源標示符保護 todo API。 - -Logto 尚未支援 Dynamic Client Registration，因此需手動將 MCP inspector 註冊為用戶端： - -1. 開啟 MCP inspector，點擊「OAuth Configuration」按鈕，複製 **Redirect URL (auto-populated)**，應類似 `http://localhost:6274/oauth/callback` -2. 登入 [Logto Console](https://cloud.logto.io)（或你的自架 Logto Console） -3. 前往「應用程式 (Applications)」分頁，點擊「建立應用程式 (Create application)」，頁面底部點「Create app without framework」 -4. 填寫應用程式資訊後點「建立應用程式 (Create application)」： - - **選擇應用程式類型**：選「單頁應用程式 (Single-page application)」 - - **應用程式名稱**：如「MCP Inspector」 -5. 在「設定 / Redirect URIs」區塊貼上剛才複製的 Redirect URL，然後點底部「儲存變更 (Save changes)」 -6. 頂部卡片會顯示「App ID」，複製它 -7. 回到 MCP inspector，將「App ID」貼到「OAuth Configuration」的「Client ID」 -8. 在「Auth Params」欄位輸入 `{"scope": "create:todos read:todos delete:todos", "resource": "https://todo.mcp-server.app"}`，確保 Logto 回傳的存取權杖包含存取 todo manager 所需的權限範圍 - - - - -:::note -這是通用 OAuth 2.0 / OpenID Connect 提供者整合指引。兩者步驟類似，因 OIDC 建立於 OAuth 2.0 之上。請查閱你的提供者文件以獲得細節。 -::: - -若你的提供者支援 Dynamic Client Registration，可直接跳到第 8 步設定 MCP inspector；否則需手動註冊 MCP inspector 為用戶端： - -1. 開啟 MCP inspector，點擊「OAuth Configuration」按鈕，複製 **Redirect URL (auto-populated)**，應類似 `http://localhost:6274/oauth/callback` - -2. 登入你的提供者管理後台 - -3. 前往「應用程式 (Applications)」或「用戶端 (Clients)」區塊，建立新應用程式或用戶端 - -4. 若需選擇用戶端類型，請選「單頁應用程式 (Single-page application)」或「公開用戶端 (Public client)」 - -5. 建立應用程式後，需設定 redirect URI，貼上剛才複製的 Redirect URL - -6. 找到新應用程式的「Client ID」或「Application ID」並複製 - -7. 回到 MCP inspector，將「Client ID」貼到「OAuth Configuration」的「Client ID」 - -8. 在「Auth Params」欄位輸入以下內容以請求 todo 操作所需權限範圍： - -```json -{ "scope": "create:todos read:todos delete:todos" } -``` - - - - -### 設定 MCP Auth \{#set-up-mcp-auth} - -在 MCP 伺服器專案中，需安裝 MCP Auth SDK 並設定使用你的授權伺服器 metadata。 - - - - -先安裝 `mcpauth` 套件： - -```bash -pip install mcpauth -``` - -或你偏好的其他套件管理工具，如 `uv` 或 `poetry`。 - - - - -先安裝 `mcp-auth` 套件： - -```bash -npm install mcp-auth -``` - - - - -MCP Auth 需要授權伺服器 metadata 來初始化。依你的提供者而定： - - - - - -簽發者 (Issuer) URL 可在 Logto Console 應用程式詳情頁「Endpoints & Credentials / Issuer endpoint」區塊找到，格式如 `https://my-project.logto.app/oidc`。 - - - - - - - -對於 OAuth 2.0 提供者，你需要： - -1. 查閱提供者文件取得授權伺服器 URL（常稱 issuer URL 或 base URL） -2. 有些提供者會在 `https://{your-domain}/.well-known/oauth-authorization-server` 提供 -3. 也可在管理後台 OAuth/API 設定中找到 - - - - - - - - - - - -更新 `todo-manager.py` 加入 MCP Auth 設定： - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # 請替換為你的 issuer endpoint -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -更新 `todo-manager.ts` 加入 MCP Auth 設定： - -```ts -// todo-manager.ts - -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // 請替換為你的 issuer endpoint -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oidc' }), -}); -``` - - - - -### 更新 MCP 伺服器 (Update MCP server) \{#update-mcp-server} - -快完成了！現在要更新 MCP 伺服器，套用 MCP Auth 路由與中介軟體，並根據使用者權限範圍實作 todo manager 工具的權限存取控制。 - - - - -```python -@mcp.tool() -def create_todo(content: str) -> dict[str, Any]: - """Create a new todo.""" - return ( - mcp_auth.auth_info.scopes - if mcp_auth.auth_info # 這會由 Bearer auth middleware 填入 - else {"error": "Not authenticated"} - ) - -# ... - -bearer_auth = Middleware(mcp_auth.bearer_auth_middleware("jwt")) -app = Starlette( - routes=[ - # 加入 metadata 路由 (`/.well-known/oauth-authorization-server`) - mcp_auth.metadata_route(), - # 用 Bearer auth middleware 保護 MCP 伺服器 - Mount('/', app=mcp.sse_app(), middleware=[bearer_auth]), - ], -) -``` - - - - -```js -server.tool( - 'create-todo', - 'Create a new todo', - { content: z.string() }, - async ({ content, authInfo }) => { - return { - content: [ - { type: 'text', text: JSON.stringify(authInfo?.scopes ?? { error: 'Not authenticated' }) }, - ], - }; - } -); - -// ... - -app.use(mcpAuth.delegatedRouter()); -app.use(mcpAuth.bearerAuth('jwt')); -``` - - - - -接下來實作具體工具。 - -首先建立一個簡單的 todo 服務，提供記憶體內的 CRUD 操作。 - - - -```python -# service.py - -""" -簡易 Todo 服務，僅供示範。 -以記憶體清單儲存 todos。 -""" - -from datetime import datetime -from typing import List, Optional, Dict, Any -import random -import string - -class Todo: -"""代表一個 todo 項目。""" - - def __init__(self, id: str, content: str, owner_id: str, created_at: str): - self.id = id - self.content = content - self.owner_id = owner_id - self.created_at = created_at - - def to_dict(self) -> Dict[str, Any]: - """轉換為 dict 以便 JSON 序列化。""" - return { - "id": self.id, - "content": self.content, - "ownerId": self.owner_id, - "createdAt": self.created_at - } - -class TodoService: -"""簡易 Todo 服務，僅供示範。""" - - def __init__(self): - self._todos: List[Todo] = [] - - def get_all_todos(self, owner_id: Optional[str] = None) -> List[Dict[str, Any]]: - """ - 取得所有 todos，可選擇依 owner_id 過濾。 - - Args: - owner_id: 若有，僅回傳該使用者的 todos - - Returns: - todo dict 清單 - """ - if owner_id: - filtered_todos = [todo for todo in self._todos if todo.owner_id == owner_id] - return [todo.to_dict() for todo in filtered_todos] - return [todo.to_dict() for todo in self._todos] - - def get_todo_by_id(self, todo_id: str) -> Optional[Todo]: - """ - 依 ID 取得 todo。 - - Args: - todo_id: 欲取得的 todo ID - - Returns: - 找到則回傳 Todo 物件，否則 None - """ - for todo in self._todos: - if todo.id == todo_id: - return todo - return None - - def create_todo(self, content: str, owner_id: str) -> Dict[str, Any]: - """ - 建立新 todo。 - - Args: - content: todo 內容 - owner_id: 擁有者 ID - - Returns: - 建立的 todo dict - """ - todo = Todo( - id=self._generate_id(), - content=content, - owner_id=owner_id, - created_at=datetime.now().isoformat() - ) - self._todos.append(todo) - return todo.to_dict() - - def delete_todo(self, todo_id: str) -> Optional[Dict[str, Any]]: - """ - 依 ID 刪除 todo。 - - Args: - todo_id: 欲刪除的 todo ID - - Returns: - 若找到則回傳被刪除的 todo dict，否則 None - """ - for i, todo in enumerate(self._todos): - if todo.id == todo_id: - deleted_todo = self._todos.pop(i) - return deleted_todo.to_dict() - return None - - def _generate_id(self) -> str: - """產生隨機 todo ID。""" - return ''.join(random.choices(string.ascii_lowercase + string.digits, k=8)) - -```` - - - - - -```ts -// todo-service.ts - -type Todo = { - id: string; - content: string; - ownerId: string; - createdAt: string; -}; - -/** - * 簡易 Todo 服務，僅供示範。 - * 以記憶體陣列儲存 todos - */ -export class TodoService { - private readonly todos: Todo[] = []; - - getAllTodos(ownerId?: string): Todo[] { - if (ownerId) { - return this.todos.filter((todo) => todo.ownerId === ownerId); - } - return this.todos; - } - - getTodoById(id: string): Todo | undefined { - return this.todos.find((todo) => todo.id === id); - } - - createTodo({ content, ownerId }: { content: string; ownerId: string }): Todo { - const todo: Todo = { - id: this.genId(), - content, - ownerId, - createdAt: new Date().toISOString(), - }; - - // eslint-disable-next-line @silverhand/fp/no-mutating-methods - this.todos.push(todo); - return todo; - } - - deleteTodo(id: string): Todo | undefined { - const index = this.todos.findIndex((todo) => todo.id === id); - - if (index === -1) { - return undefined; - } - - // eslint-disable-next-line @silverhand/fp/no-mutating-methods - const [deleted] = this.todos.splice(index, 1); - return deleted; - } - - private genId(): string { - return Math.random().toString(36).slice(2, 10); - } -} -```` - - - - -然後在工具層根據使用者權限範圍判斷是否允許操作： - - - - -```python -# todo-manager.py - -from typing import Any, Optional -from mcpauth.errors import MCPAuthBearerAuthError - -def assert_user_id(auth_info: Optional[dict]) -> str: - """從 auth info 擷取並驗證 user ID。""" - subject = auth_info.get('subject') if auth_info else None - if not subject: - raise ValueError('Invalid auth info') - return subject - -def has_required_scopes(user_scopes: list[str], required_scopes: list[str]) -> bool: - """檢查使用者是否擁有所有必要權限範圍。""" - return all(scope in user_scopes for scope in required_scopes) - -# 建立 TodoService 實例 -todo_service = TodoService() - -@mcp.tool() -def create_todo(content: str) -> dict[str, Any]: - """建立新 todo。 - - 只有擁有 'create:todos' 權限範圍的使用者才能建立 todo。 - """ - # 取得驗證資訊 - auth_info = mcp_auth.auth_info - - # 驗證 user ID - try: - user_id = assert_user_id(auth_info) - except ValueError as e: - return {"error": str(e)} - - # 檢查是否有必要權限 - if not has_required_scopes(auth_info.scopes if auth_info else [], ['create:todos']): - raise MCPAuthBearerAuthError('missing_required_scopes') - - # 建立新 todo - created_todo = todo_service.create_todo(content=content, owner_id=user_id) - - # 回傳建立的 todo - return created_todo.__dict__ - -# ... -``` - -你可以參考我們的 [範例程式碼](https://github.com/mcp-auth/python/tree/master/samples/server) 取得完整實作。 - - - - -```ts -// todo-manager.ts - -// ... 其他 import -import assert from 'node:assert'; -import { type AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js'; -import { TodoService } from './todo-service.js'; - -const todoService = new TodoService(); - -const assertUserId = (authInfo?: AuthInfo) => { - const { subject } = authInfo ?? {}; - assert(subject, 'Invalid auth info'); - return subject; -}; - -/** - * 檢查使用者是否擁有所有必要權限範圍 - */ -const hasRequiredScopes = (userScopes: string[], requiredScopes: string[]): boolean => { - return requiredScopes.every((scope) => userScopes.includes(scope)); -}; - -server.tool( - 'create-todo', - 'Create a new todo', - { content: z.string() }, - ({ content }: { content: string }, { authInfo }) => { - const userId = assertUserId(authInfo); - - /** - * 只有擁有 'create:todos' 權限範圍的使用者才能建立 todo - */ - if (!hasRequiredScopes(authInfo?.scopes ?? [], ['create:todos'])) { - throw new MCPAuthBearerAuthError('missing_required_scopes'); - } - - const createdTodo = todoService.createTodo({ content, ownerId: userId }); - - return { - content: [{ type: 'text', text: JSON.stringify(createdTodo) }], - }; - } -); - -// ... -``` - -你可以參考我們的 [範例程式碼](https://github.com/mcp-auth/js/tree/master/packages/sample-servers/src/todo-manager) 取得完整實作。 - - - - -## 檢查點：執行 `todo-manager` 工具 \{#checkpoint-run-the-todo-manager-tools} - -重啟 MCP 伺服器並在瀏覽器開啟 MCP inspector。點擊「Connect」後，應會被導向授權伺服器登入頁。 - -登入並返回 MCP inspector 後，重複前述步驟執行 todo manager 工具。這次你將以已驗證的使用者身分操作，工具行為會依你被指派的角色與權限而異： - -- 若以 **User**（僅有 `create:todos` 權限範圍）登入： - - - 可用 `create-todo` 工具建立新待辦事項 - - 只能檢視與刪除自己的待辦事項 - - 無法看到或刪除其他使用者的待辦事項 - -- 若以 **Admin**（擁有所有權限範圍：`create:todos`、`read:todos`、`delete:todos`）登入： - - 可建立新待辦事項 - - 可用 `get-todos` 工具檢視系統所有待辦事項 - - 可用 `delete-todo` 工具刪除任何待辦事項，不論擁有者 - -你可以這樣測試不同權限層級： - -1. 登出目前會話（點 MCP inspector 的「Disconnect」） -2. 以不同角色／權限的帳號登入 -3. 重複操作觀察工具行為如何隨使用者權限變化 - -這展示了角色型存取控制 (RBAC) 的實際運作，不同使用者對系統功能有不同存取層級。 - -![MCP inspector todo manager 工具結果](/docs-assets/images/tutorials/todo-manager/result.png) - - - - -:::info -完整 MCP 伺服器（OIDC 版）程式碼請參考 [MCP Auth Python SDK repository](https://github.com/mcp-auth/python/blob/master/samples/server/todo-manager/server.py)。 -::: - - - - -:::info -完整 MCP 伺服器（OIDC 版）程式碼請參考 [MCP Auth Node.js SDK repository](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src)。 -::: - - - - -## 結語 (Closing notes) \{#closing-notes} - -🎊 恭喜你！已順利完成本教學。讓我們回顧一下： - -- 建立具備 todo 管理工具（`create-todo`、`get-todos`、`delete-todo`）的基本 MCP 伺服器 -- 實作不同使用者與管理員權限層級的角色型存取控制 (RBAC) -- 透過 MCP Auth 將 MCP 伺服器與授權伺服器整合 -- 設定 MCP Inspector 以驗證使用者並用帶權限範圍的存取權杖呼叫工具 - -歡迎參閱其他教學與文件，充分發揮 MCP Auth 的強大功能。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_manual-metadata-fetching.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_manual-metadata-fetching.mdx deleted file mode 100644 index c15ebb5..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_manual-metadata-fetching.mdx +++ /dev/null @@ -1,3 +0,0 @@ -:::note -如果你的提供者不支援 {props.oidc ? 'OpenID Connect Discovery' : 'OAuth 2.0 授權伺服器中繼資料 (Authorization Server Metadata)' }，你可以手動指定中繼資料 URL 或端點。詳情請參閱 [其他初始化 MCP Auth 的方式](../../configure-server/mcp-auth.mdx#other-ways)。 -::: \ No newline at end of file diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oauth-or-oidc.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oauth-or-oidc.mdx deleted file mode 100644 index 7f61a3f..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oauth-or-oidc.mdx +++ /dev/null @@ -1,41 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -將 `todo-manager.py` 更新以加入 MCP Auth 設定： - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # 請替換為你的簽發者 (Issuer) 端點 -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OAUTH) # 或 AuthServerType.OIDC -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -將 `todo-manager.ts` 更新以加入 MCP Auth 設定： - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // 請替換為你的簽發者 (Issuer) 端點 -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oauth' }), // 或 { type: 'oidc' } -}); -``` - - - - - - \ No newline at end of file diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oidc.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oidc.mdx deleted file mode 100644 index 75adf35..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_setup-oidc.mdx +++ /dev/null @@ -1,41 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -將 `todo-manager.py` 更新，加入 MCP Auth 設定： - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # 請替換為你的簽發者端點 -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -將 `todo-manager.ts` 更新，加入 MCP Auth 設定： - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // 請替換為你的簽發者端點 -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oidc' }), -}); -``` - - - - -{props.showAlternative && } -{props.showAlternative && } \ No newline at end of file diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_transpile-metadata.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_transpile-metadata.mdx deleted file mode 100644 index e228ed8..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/tutorials/todo-manager/_transpile-metadata.mdx +++ /dev/null @@ -1,31 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -在某些情況下，提供者的回應可能格式錯誤或不符合預期的中繼資料格式。如果你確信該提供者是相容的，可以透過設定選項轉譯中繼資料： - - - - -```python -mcp_auth = MCPAuth( - server=fetch_server_config( - # ...other options - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { - // ...other options - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/README.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/README.mdx deleted file mode 100644 index 5efdbf6..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/README.mdx +++ /dev/null @@ -1,611 +0,0 @@ ---- -sidebar_position: 1 -sidebar_label: '教學：我是誰？' ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import SetupOauth from './_setup-oauth.mdx'; -import SetupOidc from './_setup-oidc.mdx'; - -# 教學：我是誰？ (Tutorial: Who am I?) - -本教學將引導你設定 MCP Auth，以驗證 (Authentication) 使用者並從授權 (Authorization) 伺服器取得其身分資訊。 - -完成本教學後，你將會： - -- ✅ 基本瞭解如何使用 MCP Auth 進行使用者驗證 (Authentication)。 -- ✅ 擁有一個 MCP 伺服器，並能提供工具來取得使用者身分資訊。 - -## 概覽 (Overview) \{#overview} - -本教學將涉及以下元件： - -- **MCP 伺服器**：一個簡單的 MCP 伺服器，使用 MCP 官方 SDK 處理請求。 -- **MCP inspector**：MCP 伺服器的視覺化測試工具，同時作為 OAuth / OIDC 用戶端，啟動授權流程並取得存取權杖 (Access token)。 -- **授權伺服器 (Authorization server)**：一個 OAuth 2.1 或 OpenID Connect 提供者，負責管理使用者身分並簽發存取權杖 (Access token)。 - -以下是這些元件間互動的高階圖示： - -```mermaid -sequenceDiagram - participant Client as MCP Inspector - participant Server as MCP Server - participant Auth as 授權伺服器 (Authorization Server) - - Client->>Server: 請求工具 `whoami` - Server->>Client: 回傳 401 未授權 (Unauthorized) - Client->>Auth: 啟動授權流程 - Auth->>Auth: 完成授權流程 - Auth->>Client: 帶授權碼重導回來 - Client->>Auth: 用授權碼換取存取權杖 (Access token) - Auth->>Client: 回傳存取權杖 (Access token) - Client->>Server: 以存取權杖 (Access token) 請求 `whoami` - Server->>Auth: 以存取權杖 (Access token) 取得使用者身分 - Auth->>Server: 回傳使用者身分 - Server->>Client: 回傳使用者身分 -``` - -## 瞭解你的授權伺服器 (Understand your authorization server) \{#understand-your-authorization-server} - -### 取得使用者身分資訊 (Retrieving user identity information) \{#retrieving-user-identity-information} - -為完成本教學，你的授權伺服器應提供 API 以取得使用者身分資訊： - - - - -[Logto](https://logto.io) 是一個 OpenID Connect 提供者，支援標準的 [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 來取得使用者身分資訊。 - -要取得可用於 userinfo endpoint 的存取權杖 (Access token)，至少需兩個權限範圍 (Scopes)：`openid` 與 `profile`。你可以繼續閱讀，稍後會介紹權限範圍設定。 - - - - -[Keycloak](https://www.keycloak.org) 是一個開源身分與存取管理解決方案，支援多種協議，包括 OpenID Connect (OIDC)。作為 OIDC 提供者，它實作了標準的 [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 以取得使用者身分資訊。 - -要取得可用於 userinfo endpoint 的存取權杖 (Access token)，至少需兩個權限範圍 (Scopes)：`openid` 與 `profile`。你可以繼續閱讀，稍後會介紹權限範圍設定。 - - - - -大多數 OpenID Connect 提供者都支援 [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 以取得使用者身分資訊。 - -請查閱你的提供者文件，確認是否支援此 endpoint。如果你的提供者支援 [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)，也可檢查 discovery 文件（`.well-known/openid-configuration` 回應）中是否包含 `userinfo_endpoint`。 - -要取得可用於 userinfo endpoint 的存取權杖 (Access token)，至少需兩個權限範圍 (Scopes)：`openid` 與 `profile`。請查閱你的提供者文件，瞭解權限範圍與使用者身分宣告 (Claims) 的對應關係。 - - - - -雖然 OAuth 2.0 沒有定義標準方式來取得使用者身分資訊，許多提供者會實作自有 endpoint。請查閱你的提供者文件，瞭解如何使用存取權杖 (Access token) 取得使用者身分資訊，以及在啟動授權流程時需帶哪些參數來取得該存取權杖。 - - - - -### 動態用戶端註冊 (Dynamic Client Registration) \{#dynamic-client-registration} - -本教學不強制需要動態用戶端註冊，但如果你想自動化 MCP 用戶端在授權伺服器的註冊流程，這會很有幫助。詳情請參閱 [是否需要動態用戶端註冊？](/provider-list#is-dcr-required)。 - -## 設定 MCP 伺服器 (Set up the MCP server) \{#set-up-the-mcp-server} - -我們將使用 [MCP 官方 SDK](https://github.com/modelcontextprotocol) 建立一個 MCP 伺服器，並實作一個 `whoami` 工具，從授權伺服器取得使用者身分資訊。 - -### 建立新專案 (Create a new project) \{#create-a-new-project} - - - - -```bash -mkdir mcp-server -cd mcp-server -uv init # 或使用 `pipenv` 或 `poetry` 建立新虛擬環境 -``` - - - - -建立新的 Node.js 專案： - -```bash -mkdir mcp-server -cd mcp-server -npm init -y # 或使用 `pnpm init` -npm pkg set type="module" -npm pkg set main="whoami.js" -npm pkg set scripts.start="node whoami.js" -``` - - - - -### 安裝 MCP SDK 與相依套件 (Install the MCP SDK and dependencies) \{#install-the-mcp-sdk-and-dependencies} - - - - -```bash -pip install "mcp[cli]" starlette uvicorn -``` - -或使用你偏好的套件管理工具，如 `uv` 或 `poetry`。 - - - - -```bash -npm install @modelcontextprotocol/sdk express -``` - -或使用你偏好的套件管理工具，如 `pnpm` 或 `yarn`。 - - - - -### 建立 MCP 伺服器 (Create the MCP server) \{#create-the-mcp-server} - -首先，讓我們建立一個實作 `whoami` 工具的 MCP 伺服器。 - - - - -建立名為 `whoami.py` 的檔案，並加入以下程式碼： - -```python -from mcp.server.fastmcp import FastMCP -from starlette.applications import Starlette -from starlette.routing import Mount -from typing import Any - -mcp = FastMCP("WhoAmI") - -@mcp.tool() -def whoami() -> dict[str, Any]: - """回傳目前使用者資訊的工具。""" - return {"error": "Not authenticated"} - -app = Starlette( - routes=[Mount('/', app=mcp.sse_app())] -) -``` - -以以下指令啟動伺服器： - -```bash -uvicorn whoami:app --host 0.0.0.0 --port 3001 -``` - - - - -:::note -由於目前 MCP inspector 尚未支援授權流程，我們將採用 SSE 方式設定 MCP 伺服器。待 MCP inspector 支援授權流程後，會更新此處程式碼。 -::: - -你也可以選擇使用 `pnpm` 或 `yarn`。 - -建立名為 `whoami.js` 的檔案，並加入以下程式碼： - -```js -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; -import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'; -import express from 'express'; - -// 建立 MCP 伺服器 -const server = new McpServer({ - name: 'WhoAmI', - version: '0.0.0', -}); - -// 新增一個回傳目前使用者資訊的工具 -server.tool('whoami', async () => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Not authenticated' }) }], - }; -}); - -// 以下為 MCP SDK 文件的樣板程式碼 -const PORT = 3001; -const app = express(); - -const transports = {}; - -app.get('/sse', async (_req, res) => { - const transport = new SSEServerTransport('/messages', res); - transports[transport.sessionId] = transport; - - res.on('close', () => { - delete transports[transport.sessionId]; - }); - - await server.connect(transport); -}); - -app.post('/messages', async (req, res) => { - const sessionId = String(req.query.sessionId); - const transport = transports[sessionId]; - if (transport) { - await transport.handlePostMessage(req, res, req.body); - } else { - res.status(400).send('No transport found for sessionId'); - } -}); - -app.listen(PORT); -``` - -以以下指令啟動伺服器： - -```bash -npm start -``` - - - - -## 檢查 MCP 伺服器 (Inspect the MCP server) \{#inspect-the-mcp-server} - -### 下載並執行 MCP inspector (Clone and run MCP inspector) \{#clone-and-run-mcp-inspector} - -現在 MCP 伺服器已啟動，我們可以使用 MCP inspector 檢查 `whoami` 工具是否可用。 - -由於目前實作上的限制，我們 fork 了 [MCP inspector](https://github.com/mcp-auth/inspector)，讓其在驗證 (Authentication) 與授權 (Authorization) 上更靈活且可擴展。我們也已向原始倉庫提交 pull request。 - -執行 MCP inspector，請使用以下指令（需安裝 Node.js）： - -```bash -git clone https://github.com/mcp-auth/inspector.git -cd inspector -npm install -npm run dev -``` - -然後在瀏覽器開啟 `http://localhost:6274/`（或終端機顯示的其他網址）以進入 MCP inspector。 - -### 連接 MCP inspector 與 MCP 伺服器 (Connect MCP inspector to the MCP server) \{#connect-mcp-inspector-to-the-mcp-server} - -在繼續之前，請檢查 MCP inspector 的以下設定： - -- **Transport Type**：設為 `SSE`。 -- **URL**：設為你的 MCP 伺服器網址，本例應為 `http://localhost:3001/sse`。 - -現在你可以點擊「Connect」按鈕，檢查 MCP inspector 是否能連接 MCP 伺服器。如果一切正常，應會看到 MCP inspector 顯示「Connected」狀態。 - -### 檢查點：執行 `whoami` 工具 (Checkpoint: Run the `whoami` tool) \{#checkpoint-run-the-whoami-tool} - -1. 在 MCP inspector 上方選單點選「Tools」分頁。 -2. 點擊「List Tools」按鈕。 -3. 你應該會在頁面上看到 `whoami` 工具，點擊它以開啟工具詳情。 -4. 右側會出現「Run Tool」按鈕，點擊執行工具。 -5. 你應該會看到工具回傳結果為 JSON：`{"error": "Not authenticated"}`。 - -![MCP inspector 首次執行畫面](/docs-assets/images/tutorials/whoami/inspector-first-run.png) - -## 與授權伺服器整合 (Integrate with your authorization server) \{#integrate-with-your-authorization-server} - -完成本節需考慮以下幾點： - -
-**你的授權伺服器簽發者 (Issuer) URL** - -通常是你的授權伺服器基礎網址，例如 `https://auth.example.com`。有些提供者可能會有路徑，如 `https://example.logto.app/oidc`，請參閱你的提供者文件。 - -
- -
-**如何取得授權伺服器中繼資料 (Metadata)** - -- 若你的授權伺服器符合 [OAuth 2.0 授權伺服器中繼資料 (RFC 8414)](https://datatracker.ietf.org/doc/html/rfc8414) 或 [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)，可直接用 MCP Auth 內建工具自動取得中繼資料。 -- 若不符合上述標準，需手動在 MCP 伺服器設定中指定中繼資料網址或 endpoint，請查閱你的提供者文件。 - -
- -
-**如何將 MCP inspector 註冊為授權伺服器用戶端** - -- 若你的授權伺服器支援 [動態用戶端註冊 (Dynamic Client Registration)](https://datatracker.ietf.org/doc/html/rfc7591)，可略過此步驟，MCP inspector 會自動註冊。 -- 若不支援，需手動將 MCP inspector 註冊為用戶端。 - -
- -
-**如何取得使用者身分資訊，以及如何設定授權請求參數** - -- 對於 OpenID Connect 提供者：通常需在授權流程請求至少 `openid` 與 `profile` 權限範圍 (Scopes)。這可確保授權伺服器回傳的存取權杖 (Access token) 具備存取 [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 所需權限。 - - 注意：部分提供者可能不支援 userinfo endpoint。 - -- 對於 OAuth 2.0 / OAuth 2.1 提供者：請查閱你的提供者文件，瞭解如何用存取權杖 (Access token) 取得使用者身分資訊，以及啟動授權流程時需帶哪些參數。 - -
- -雖然每個提供者可能有不同需求，以下步驟將引導你整合 MCP inspector 與 MCP 伺服器，並進行提供者專屬設定。 - -### 註冊 MCP inspector 為用戶端 (Register MCP inspector as a client) \{#register-mcp-inspector-as-a-client} - - - - -與 [Logto](https://logto.io) 整合非常簡單，因為它是支援標準 [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 的 OpenID Connect 提供者。 - -由於 Logto 尚未支援動態用戶端註冊，你需手動將 MCP inspector 註冊為 Logto 租戶的用戶端： - -1. 開啟 MCP inspector，點擊「OAuth Configuration」按鈕。複製 **Redirect URL (auto-populated)**，例如 `http://localhost:6274/oauth/callback`。 -2. 登入 [Logto Console](https://cloud.logto.io)（或你的自架 Logto Console）。 -3. 進入「應用程式」分頁，點擊「建立應用程式」。頁面底部點「不使用框架建立應用程式」。 -4. 填寫應用程式資訊，然後點擊「建立應用程式」： - - **選擇應用程式類型**：選「單頁應用程式」。 - - **應用程式名稱**：如「MCP Inspector」。 -5. 在「設定 / Redirect URIs」區塊，貼上剛才複製的 **Redirect URL (auto-populated)**，然後點擊底部「儲存變更」。 -6. 頁面上方會看到「App ID」，請複製。 -7. 回到 MCP inspector，將「App ID」貼到「OAuth Configuration」的「Client ID」欄位。 -8. 在「Auth Params」欄位輸入 `{"scope": "openid profile email"}`，確保 Logto 回傳的存取權杖 (Access token) 具備存取 userinfo endpoint 所需權限。 - - - - -[Keycloak](https://www.keycloak.org) 是一個開源身分與存取管理解決方案，支援 OpenID Connect 協議。 - -雖然 Keycloak 支援動態用戶端註冊，但其註冊 endpoint 不支援 CORS，導致大多數 MCP 用戶端無法直接註冊。因此需手動註冊。 - -:::note -Keycloak 可用多種方式安裝（[官方說明](https://www.keycloak.org/guides#getting-started)），本教學以 Docker 快速安裝為例。 -::: - -設定 Keycloak 並進行相關配置： - -1. 依 [官方文件](https://www.keycloak.org/getting-started/getting-started-docker) 用 Docker 啟動 Keycloak： - -```bash -docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.2.4 start-dev -``` - -2. 進入 Keycloak 管理後台 (http://localhost:8080/admin)，以以下帳密登入： - - - 使用者名稱：`admin` - - 密碼：`admin` - -3. 建立新 Realm： - - - 左上角點「Create Realm」 - - 「Realm name」填入 `mcp-realm` - - 點「Create」 - -4. 建立測試使用者： - - - 左側選單點「Users」 - - 點「Create new user」 - - 填寫使用者資訊： - - Username：`testuser` - - 名字與姓氏可任意填 - - 點「Create」 - - 在「Credentials」分頁設定密碼並取消「Temporary」 - -5. 註冊 MCP Inspector 為用戶端： - - - 開啟 MCP inspector，點擊「OAuth Configuration」按鈕。複製 **Redirect URL (auto-populated)**，如 `http://localhost:6274/oauth/callback`。 - - 在 Keycloak 管理後台，左側選單點「Clients」 - - 點「Create client」 - - 填寫用戶端資訊： - - Client type：選「OpenID Connect」 - - Client ID：填 `mcp-inspector` - - 點「Next」 - - 「Capability config」頁面： - - 確認「Standard flow」已啟用 - - 點「Next」 - - 「Login settings」頁面： - - 貼上 MCP Inspector callback URL 至「Valid redirect URIs」 - - 「Web origins」填入 `http://localhost:6274` - - 點「Save」 - - 複製「Client ID」（即 `mcp-inspector`） - -6. 回到 MCP Inspector： - - 將複製的 Client ID 貼到「OAuth Configuration」的「Client ID」欄位 - - 「Auth Params」欄位輸入以下內容以請求必要權限範圍： - -```json -{ "scope": "openid profile email" } -``` - - - - -:::note -這是通用 OpenID Connect 提供者整合指引，請查閱你的提供者文件以獲得細節。 -::: - -若你的 OpenID Connect 提供者支援動態用戶端註冊，可直接跳至第 8 步設定 MCP inspector；否則需手動註冊： - -1. 開啟 MCP inspector，點擊「OAuth Configuration」按鈕。複製 **Redirect URL (auto-populated)**，如 `http://localhost:6274/oauth/callback`。 -2. 登入你的 OpenID Connect 提供者後台。 -3. 進入「應用程式」或「用戶端」區塊，建立新應用程式或用戶端。 -4. 若需選擇用戶端類型，請選「單頁應用程式」或「公開用戶端」。 -5. 建立應用程式後，設定 redirect URI，貼上 MCP inspector 的 **Redirect URL (auto-populated)**。 -6. 找到新應用程式的「Client ID」或「Application ID」並複製。 -7. 回到 MCP inspector，將「Client ID」貼到「OAuth Configuration」的「Client ID」欄位。 -8. 標準 OIDC 提供者可在「Auth Params」欄位輸入以下內容，以請求 userinfo endpoint 所需權限範圍： - -```json -{ "scope": "openid profile email" } -``` - - - - -:::note -這是通用 OAuth 2.0 / OAuth 2.1 提供者整合指引，請查閱你的提供者文件以獲得細節。 -::: - -若你的 OAuth 2.0 / OAuth 2.1 提供者支援動態用戶端註冊，可直接跳至第 8 步設定 MCP inspector；否則需手動註冊： - -1. 開啟 MCP inspector，點擊「OAuth Configuration」按鈕。複製 **Redirect URL (auto-populated)**，如 `http://localhost:6274/oauth/callback`。 -2. 登入你的 OAuth 2.0 / OAuth 2.1 提供者後台。 -3. 進入「應用程式」或「用戶端」區塊，建立新應用程式或用戶端。 -4. 若需選擇用戶端類型，請選「單頁應用程式」或「公開用戶端」。 -5. 建立應用程式後，設定 redirect URI，貼上 MCP inspector 的 **Redirect URL (auto-populated)**。 -6. 找到新應用程式的「Client ID」或「Application ID」並複製。 -7. 回到 MCP inspector，將「Client ID」貼到「OAuth Configuration」的「Client ID」欄位。 -8. 請查閱你的提供者文件，瞭解如何取得用於身分資訊的存取權杖 (Access token)。你可能需指定權限範圍或參數。例如，若需 `profile` 權限範圍，可在「Auth Params」欄位輸入： - -```json -{ "scope": "profile" } -``` - - - - -### 設定 MCP Auth (Set up MCP auth) \{#set-up-mcp-auth} - -在你的 MCP 伺服器專案中，需安裝 MCP Auth SDK 並設定使用你的授權伺服器中繼資料。 - - - - -首先安裝 `mcpauth` 套件： - -```bash -pip install mcpauth -``` - -或使用你偏好的套件管理工具，如 `uv` 或 `poetry`。 - - - - -首先安裝 `mcp-auth` 套件： - -```bash -npm install mcp-auth -``` - - - - -MCP Auth 需要授權伺服器中繼資料才能初始化。根據你的提供者： - - - - - -簽發者 (Issuer) URL 可在 Logto Console 的應用程式詳情頁「Endpoints & Credentials / Issuer endpoint」區塊找到，格式類似 `https://my-project.logto.app/oidc`。 - - - - - - - -簽發者 (Issuer) URL 可在 Keycloak 管理後台的「mcp-realm」下「Realm settings / Endpoints」區塊，點選「OpenID Endpoint Configuration」連結。JSON 文件中的 `issuer` 欄位即為你的 issuer URL，格式類似 `http://localhost:8080/realms/mcp-realm`。 - - - - - - - -以下程式碼假設授權伺服器支援 [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 以取得使用者身分資訊。若你的提供者不支援，請查閱文件並以正確 URL 取代 userinfo endpoint 變數。 - - - - - - -如前所述，OAuth 2.0 沒有定義標準方式來取得使用者身分資訊。以下程式碼假設你的提供者有特定 endpoint 可用存取權杖 (Access token) 取得身分資訊。請查閱文件並以正確 URL 取代 userinfo endpoint 變數。 - - - - - - -### 更新 MCP 伺服器 (Update MCP server) \{#update-mcp-server} - -快完成了！現在要更新 MCP 伺服器，套用 MCP Auth 路由與中介軟體，並讓 `whoami` 工具回傳實際的使用者身分資訊。 - - - - -```python -@mcp.tool() -def whoami() -> dict[str, Any]: - """回傳目前使用者資訊的工具。""" - return ( - mcp_auth.auth_info.claims - if mcp_auth.auth_info # 由 Bearer auth middleware 填入 - else {"error": "Not authenticated"} - ) - -# ... - -bearer_auth = Middleware(mcp_auth.bearer_auth_middleware(verify_access_token)) -app = Starlette( - routes=[ - # 加入 metadata 路由 (`/.well-known/oauth-authorization-server`) - mcp_auth.metadata_route(), - # 以 Bearer auth middleware 保護 MCP 伺服器 - Mount('/', app=mcp.sse_app(), middleware=[bearer_auth]), - ], -) -``` - - - - -```js -server.tool('whoami', ({ authInfo }) => { - return { - content: [ - { type: 'text', text: JSON.stringify(authInfo?.claims ?? { error: 'Not authenticated' }) }, - ], - }; -}); - -// ... - -app.use(mcpAuth.delegatedRouter()); -app.use(mcpAuth.bearerAuth(verifyToken)); -``` - - - - -## 檢查點：以驗證 (Authentication) 執行 `whoami` 工具 (Checkpoint: Run the `whoami` tool with authentication) \{#checkpoint-run-the-whoami-tool-with-authentication} - -重新啟動 MCP 伺服器，並在瀏覽器開啟 MCP inspector。當你點擊「Connect」按鈕時，應會被導向授權伺服器的登入頁面。 - -登入後回到 MCP inspector，重複前述步驟執行 `whoami` 工具。這次你應該會看到授權伺服器回傳的使用者身分資訊。 - -![MCP inspector whoami 工具結果](/docs-assets/images/tutorials/whoami/result.png) - - - - -:::info -完整 MCP 伺服器（OIDC 版本）程式碼請參考 [MCP Auth Python SDK repository](https://github.com/mcp-auth/python/blob/master/samples/server/whoami.py)。 -::: - - - - -:::info -完整 MCP 伺服器（OIDC 版本）程式碼請參考 [MCP Auth Node.js SDK repository](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src)。該目錄同時包含 TypeScript 與 JavaScript 版本。 -::: - - - - -## 結語 (Closing notes) \{#closing-notes} - -🎊 恭喜你！已成功完成本教學。讓我們回顧一下： - -- 建立具備 `whoami` 工具的基本 MCP 伺服器 -- 透過 MCP Auth 將 MCP 伺服器與授權伺服器整合 -- 設定 MCP Inspector 以驗證 (Authentication) 使用者並取得其身分資訊 - -你也可以進一步探索進階主題，包括： - -- 使用 [JWT (JSON Web Token)](https://auth.wiki/jwt) 進行驗證 (Authentication) 與授權 (Authorization) -- 利用 [資源標示符 (Resource indicators, RFC 8707)](https://auth-wiki.logto.io/resource-indicator) 指定存取資源 -- 實作自訂存取控制機制，如 [基於角色的存取控制 (RBAC, Role-based access control)](https://auth.wiki/rbac) 或 [屬性型存取控制 (ABAC, Attribute-based access control)](https://auth.wiki/abac) - -歡迎參閱其他教學與文件，充分發揮 MCP Auth 的效能。 \ No newline at end of file diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_manual-metadata-fetching.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_manual-metadata-fetching.mdx deleted file mode 100644 index c15ebb5..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_manual-metadata-fetching.mdx +++ /dev/null @@ -1,3 +0,0 @@ -:::note -如果你的提供者不支援 {props.oidc ? 'OpenID Connect Discovery' : 'OAuth 2.0 授權伺服器中繼資料 (Authorization Server Metadata)' }，你可以手動指定中繼資料 URL 或端點。詳情請參閱 [其他初始化 MCP Auth 的方式](../../configure-server/mcp-auth.mdx#other-ways)。 -::: \ No newline at end of file diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oauth.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oauth.mdx deleted file mode 100644 index 9246aba..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oauth.mdx +++ /dev/null @@ -1,138 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -更新 `whoami.py`，加入 MCP Auth 設定： - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # 請替換為你的簽發者 (Issuer) 端點 -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OAUTH) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -更新 `whoami.js`，加入 MCP Auth 設定： - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // 請替換為你的簽發者 (Issuer) 端點 -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oauth' }), -}); -``` - - - - - - - -接下來，我們需要建立一個自訂的存取權杖 (Access token) 驗證器，該驗證器會使用 MCP inspector 提供的存取權杖，從授權伺服器取得使用者身分資訊。 - - - - -```python -import pydantic -import requests -from mcpauth.exceptions import ( - MCPAuthTokenVerificationException, - MCPAuthTokenVerificationExceptionCode, -) -from mcpauth.types import AuthInfo - -def verify_access_token(token: str) -> AuthInfo: - """ - 透過向授權伺服器取得使用者資訊來驗證提供的 Bearer 權杖 (Token)。 - 若權杖有效，將回傳包含使用者資訊的 `AuthInfo` 物件。 - - :param token: 從 MCP inspector 接收到的 Bearer 權杖 (Token)。 - """ - - try: - # 以下程式碼假設你的授權伺服器有一個可用於存取權杖 (Access token) 查詢使用者資訊的端點。 - # 請依據你的服務提供者 API 調整 URL 與 headers。 - response = requests.get( - "https://your-authorization-server.com/userinfo", - headers={"Authorization": f"Bearer {token}"}, - ) - response.raise_for_status() # 確保 HTTP 錯誤時會拋出例外 - json = response.json() # 解析 JSON 回應 - - # 以下程式碼假設 user info 回應物件中有一個 'sub' 欄位用於識別使用者。 - # 你可能需要根據服務提供者 API 調整這部分。 - return AuthInfo( - token=token, - subject=json.get("sub"), - issuer=auth_issuer, # 使用已設定的簽發者 (Issuer) - claims=json, # 包含端點回傳的所有宣告 (Claims/JSON 欄位) - ) - # `AuthInfo` 是 Pydantic 模型，驗證錯誤通常代表回應結構不符預期 - except pydantic.ValidationError as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.INVALID_TOKEN, - cause=e, - ) - # 處理請求過程中可能發生的其他例外 - except Exception as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.TOKEN_VERIFICATION_FAILED, - cause=e, - ) -``` - - - - -```js -import { MCPAuthTokenVerificationError } from 'mcp-auth'; - -/** - * 透過向授權伺服器取得使用者資訊來驗證提供的 Bearer 權杖 (Token)。 - * 若權杖有效，將回傳包含使用者資訊的 `AuthInfo` 物件。 - */ -const verifyToken = async (token) => { - // 以下程式碼假設你的授權伺服器有一個可用於存取權杖 (Access token) 查詢使用者資訊的端點。 - // 請依據你的服務提供者 API 調整 URL 與 headers。 - const response = await fetch('https://your-authorization-server.com/userinfo', { - headers: { Authorization: `Bearer ${token}` }, - }); - - if (!response.ok) { - throw new MCPAuthTokenVerificationError('token_verification_failed', response); - } - - const userInfo = await response.json(); - - // 以下程式碼假設 user info 回應物件中有一個 'sub' 欄位用於識別使用者。 - // 你可能需要根據服務提供者 API 調整這部分。 - if (typeof userInfo !== 'object' || userInfo === null || !('sub' in userInfo)) { - throw new MCPAuthTokenVerificationError('invalid_token', response); - } - - return { - token, - issuer: authIssuer, - subject: String(userInfo.sub), // 根據服務提供者的使用者 ID 欄位調整 - clientId: '', // 此範例未使用 Client ID，如有需要可設定 - scopes: [], - claims: userInfo, - }; -}; -``` - - - diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oidc.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oidc.mdx deleted file mode 100644 index 0a16722..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_setup-oidc.mdx +++ /dev/null @@ -1,142 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -將 `whoami.py` 更新，加入 MCP Auth 設定： - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # 請替換為你的簽發者 (Issuer) 端點 -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -將 `whoami.js` 更新，加入 MCP Auth 設定： - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // 請替換為你的簽發者 (Issuer) 端點 -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oidc' }), -}); -``` - - - - -{props.showAlternative && } -{props.showAlternative && } - -接下來，我們需要建立一個自訂的存取權杖 (Access token) 驗證器，該驗證器會使用 MCP inspector 提供的存取權杖，從授權伺服器 (Authorization server) 取得使用者身分資訊。 - - - - -```python -import pydantic -import requests -from mcpauth.exceptions import ( - MCPAuthTokenVerificationException, - MCPAuthTokenVerificationExceptionCode, -) -from mcpauth.types import AuthInfo - -def verify_access_token(token: str) -> AuthInfo: - """ - 透過從授權伺服器 (Authorization server) 取得使用者資訊，驗證所提供的 Bearer 權杖 (Token)。 - 若權杖有效，將回傳包含使用者資訊的 `AuthInfo` 物件。 - - :param token: 從 MCP inspector 接收到的 Bearer 權杖 (Token)。 - """ - - issuer = auth_server_config.metadata.issuer - endpoint = auth_server_config.metadata.userinfo_endpoint # 提供者應支援 userinfo endpoint - if not endpoint: - raise ValueError( - "auth server metadata 中未設定 userinfo endpoint。" - ) - - try: - response = requests.get( - endpoint, - headers={"Authorization": f"Bearer {token}"}, # 標準 Bearer 權杖標頭 - ) - response.raise_for_status() # 確保 HTTP 錯誤時會拋出例外 - json = response.json() # 解析 JSON 回應 - return AuthInfo( - token=token, - subject=json.get("sub"), # 'sub' 是主體 (Subject, 使用者 ID) 的標準宣告 (Claim) - issuer=issuer, # 使用 metadata 中的簽發者 (Issuer) - claims=json, # 包含 userinfo endpoint 回傳的所有宣告 (Claims) - ) - # `AuthInfo` 是 Pydantic 模型，驗證錯誤通常代表回應結構不符預期 - except pydantic.ValidationError as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.INVALID_TOKEN, - cause=e, - ) - # 處理請求過程中可能發生的其他例外 - except Exception as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.TOKEN_VERIFICATION_FAILED, - cause=e, - ) -``` - - - - -```js -import { MCPAuthTokenVerificationError } from 'mcp-auth'; - -/** - * 透過從授權伺服器 (Authorization server) 取得使用者資訊，驗證所提供的 Bearer 權杖 (Token)。 - * 若權杖有效，將回傳包含使用者資訊的 `AuthInfo` 物件。 - */ -const verifyToken = async (token) => { - const { issuer, userinfoEndpoint } = mcpAuth.config.server.metadata; - - if (!userinfoEndpoint) { - throw new Error('server metadata 中未設定 userinfo endpoint'); - } - - const response = await fetch(userinfoEndpoint, { - headers: { Authorization: `Bearer ${token}` }, - }); - - if (!response.ok) { - throw new MCPAuthTokenVerificationError('token_verification_failed', response); - } - - const userInfo = await response.json(); - - if (typeof userInfo !== 'object' || userInfo === null || !('sub' in userInfo)) { - throw new MCPAuthTokenVerificationError('invalid_token', response); - } - - return { - token, - issuer, - subject: String(userInfo.sub), // 'sub' 是主體 (Subject, 使用者 ID) 的標準宣告 (Claim) - clientId: '', // 本範例未使用 Client ID，如有需要可設定 - scopes: [], - claims: userInfo, - }; -}; -``` - - - diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_transpile-metadata.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_transpile-metadata.mdx deleted file mode 100644 index feec908..0000000 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/version-0.1.1/tutorials/whoami/_transpile-metadata.mdx +++ /dev/null @@ -1,31 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -在某些情況下，provider 的回應可能格式錯誤或不符合預期的 metadata 格式。如果你確定 provider 是相容的，可以透過設定選項轉譯 metadata： - - - - -```python -mcp_auth = MCPAuth( - server=fetch_server_config( - # ...其他選項 - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { - // ...其他選項 - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - diff --git a/src/components/NpmLikeInstallation/index.tsx b/src/components/NpmLikeInstallation/index.tsx new file mode 100644 index 0000000..227b356 --- /dev/null +++ b/src/components/NpmLikeInstallation/index.tsx @@ -0,0 +1,30 @@ +import MDXCode from '@theme/MDXComponents/Code'; +import MDXPre from '@theme/MDXComponents/Pre'; +import TabItem from '@theme/TabItem'; +import Tabs from '@theme/Tabs'; + +type Props = { + readonly packageName: string; +}; + +export const NpmLikeInstallation = ({ packageName }: Props) => { + return ( + + + + {`pnpm add ${packageName}`} + + + + + {`npm install ${packageName}`} + + + + + {`yarn add ${packageName}`} + + + + ); +}; diff --git a/versioned_docs/version-0.1.1/README.mdx b/versioned_docs/version-0.1.1/README.mdx deleted file mode 100644 index a3d402e..0000000 --- a/versioned_docs/version-0.1.1/README.mdx +++ /dev/null @@ -1,242 +0,0 @@ ---- -sidebar_position: 1 -sidebar_label: Get started ---- - -import TabItem from '@theme/TabItem'; -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} - -MCP specification has some [specific requirements](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization#1-3-standards-compliance) for authorization: - -- [OAuth 2.1 IETF DRAFT](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12) -- OAuth 2.0 Authorization Server Metadata ([RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)) -- OAuth 2.0 Dynamic Client Registration Protocol ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) - -While the last two are not mandatory, the first one is necessary to ensure a secure and compliant implementation. - -:::note -In the new MCP draft, RFC 8414 will be mandated for authorization servers (providers). We'll update the documentation once the new draft is finalized. -::: - -You can check the [MCP-compatible provider list](/provider-list) to see if your provider is supported. - -## 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! - - - - -```bash -pip install mcpauth -``` - -Or any other package manager you prefer, such as pipenv or poetry. - - - - -```bash -npm install mcp-auth -``` - -Or any other package manager you prefer, such as pnpm or yarn. - - - - -## 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: - -- [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) -- [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) - -You can use the built-in function to fetch the metadata and initialize the MCP Auth instance: - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -mcp_auth = MCPAuth( - server=fetch_server_config( - '', - type=AuthServerType.OIDC # or AuthServerType.OAUTH - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { type: 'oidc' }), // or 'oauth' -}); -``` - - - - -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} - -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: - - - - -```python -from starlette.applications import Starlette - -app = Starlette(routes=[ - mcp_auth.metadata_route(), -]) -``` - - - - -```ts -import express from 'express'; - -const app = express(); -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} - -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: - -1. Mounting only the metadata endpoint allows you to leverage the full capabilities of your provider without "reinventing the wheel" and injecting unnecessary complexity into your MCP server. -2. There's also an ongoing effort to shift the [MCP server's role to a resource server](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/205) and requires OAuth 2.0 Protected Resource Metadata ([RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728)). Which means that the MCP server will **not handle any authorization logic anymore** (including the metadata endpoint), but only serve as a resource server that relies on the provider for authentication and authorization. - -:::note -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} - -Once the MCP Auth instance is initialized, you can apply the Bearer auth middleware to protect your MCP routes: - - - - -```python -from starlette.applications import Starlette -from starlette.middleware import Middleware -from starlette.routing import Mount -from mcpauth import MCPAuth -from mcp.server.fastmcp import FastMCP - -mcp = FastMCP() -mcp_auth = MCPAuth( - # Initialize with your auth server config -) -bearer_auth = mcp_auth.bearer_auth_middleware( - "jwt", required_scopes=["read", "write"] -) - -app = Starlette(routes=[ - mcp_auth.metadata_route(), - Mount( - "/", - app=mcp.sse_app(), - middleware=[Middleware(bearer_auth)], - ), -]) -``` - - - - -```ts -import express from 'express'; -import { MCPAuth } from 'mcp-auth'; - -const app = express(); -const server = new McpServer(/* ... */); -const mcpAuth = new MCPAuth({ - /* ... */ -}); - -app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] })); -``` - - - - -In the example above, we specified the `jwt` token type and required the `read` and `write` scopes. It will automatically validate the JWT (JSON Web Token) and populate an object with the authenticated user's information. - -:::info -Didn't hear about JWT (JSON Web Token) before? Don't worry, you can keep reading the documentation and we'll explain it when needed. You can also check [Auth Wiki](https://auth.wiki/jwt) for a quick introduction. -::: - -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} - -Once the Bearer auth middleware is applied, you can access the authenticated user's (or identity's) information in your MCP implementation: - - - - -MCP Auth will store the authenticated user's information in a context variable after successful authentication once the Bearer auth middleware is applied. You can access it in your MCP tool handlers like this: - -```python -from mcp.server.fastmcp import FastMCP - -mcp = FastMCP() -mcp_auth = MCPAuth( - # Initialize with your auth server config -) - -@mcp.tool() -def add(a: int, b: int): - """ - A tool that adds two numbers. - The authenticated user's information will be available in the context. - """ - auth_info = mcp_auth.auth_info # Access the auth info in the current context - if auth_info: - print(f"Authenticated user: {auth_info.claims}") - return a + b -``` - - - - -The second argument of the tool handler will contain the `authInfo` object, which includes the authenticated user's information: - -```ts -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; -import { z } from 'zod'; - -const server = new McpServer(/* ... */); -server.tool('add', { a: z.number(), b: z.number() }, async ({ a, b }, { authInfo }) => { - // Now you can use the `authInfo` object to access the authenticated information -}); -``` - - - - -## 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. diff --git a/versioned_docs/version-0.1.1/comparison.mdx b/versioned_docs/version-0.1.1/comparison.mdx deleted file mode 100644 index 9509cf1..0000000 --- a/versioned_docs/version-0.1.1/comparison.mdx +++ /dev/null @@ -1,80 +0,0 @@ ---- -sidebar_position: 101 -sidebar_label: Comparison ---- - -# Choosing between MCP Auth and other solutions - -The MCP ecosystem is evolving. As the Model Context Protocol (MCP) specification moves from the “authorization server” approach to the new “resource server + third-party IdP” model, it’s important to understand how different integration solutions fit, both now and in the future. - -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} - -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. - -**Proxy approach ([03-26 spec](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization))** - -```mermaid -sequenceDiagram - participant Client - participant MCP_Server as MCP server - participant ThirdParty_IdP as Third-party IdP - - Client->>MCP_Server: Authorization request - MCP_Server->>ThirdParty_IdP: Proxies request - ThirdParty_IdP->>MCP_Server: Response - MCP_Server->>Client: Response - Client->>MCP_Server: Access resource - alt Remote validation - MCP_Server->>ThirdParty_IdP: Validate token - ThirdParty_IdP->>MCP_Server: Token valid - else Local validation - MCP_Server->>MCP_Server: Validate token locally (e.g., cached JWK) - end - MCP_Server->>Client: Resource data -``` - -While this works with the current (2025-03-26) MCP spec, it’s essentially a workaround. It assumes the MCP server will also act as an authorization server, which is not the direction of the latest draft spec. - -**MCP Auth / future spec (resource server + third-party IdP)** - -```mermaid -sequenceDiagram - participant Client - participant MCP_Server as MCP server - participant ThirdParty_IdP as Third-party IdP - - Client->>ThirdParty_IdP: Authorization request - ThirdParty_IdP->>Client: Token - Client->>MCP_Server: Access resource (with token) - alt Remote validation - MCP_Server->>ThirdParty_IdP: Validate token - ThirdParty_IdP->>MCP_Server: Token valid - else Local validation - MCP_Server->>MCP_Server: Validate token locally (e.g., cached JWK) - end - MCP_Server->>Client: Resource data -``` - -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} - -- 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. -- Provider-agnostic: MCP Auth works with any standards-compliant OAuth 2.0 / OIDC provider. -- Smooth transition: MCP Auth returns all third-party endpoints as-is via OAuth 2.0 Authorization Server Metadata. This keeps integration simple now, and ready for future changes. -- Developer experience: Offers tutorials, utilities, and upcoming features like [OAuth 2.0 Protected Resource Metadata](https://auth.wiki/protected-resource-metadata) to make life easier for MCP server developers. - -| Feature | Proxy solutions | MCP Auth | -| ---------------------------------- | -------------------- | -------- | -| Works with 03-26 spec | ✅ | ✅ | -| Works with future spec | ❌ | ✅ | -| Supports third-party IdPs directly | ❌ (workaround only) | ✅ | -| Provider-agnostic | Limited[^1] | Yes | -| Transition-ready | ❌ | ✅ | - -If you need to support third-party IdPs now and want to be ready for the upcoming spec, MCP Auth is the recommended solution. Proxy-based approaches may soon be deprecated or require significant rework. - -[^1]: Some proxy solutions may hardcode specific parameters or endpoints, limiting flexibility. diff --git a/versioned_docs/version-0.1.1/configure-server/_category_.yml b/versioned_docs/version-0.1.1/configure-server/_category_.yml deleted file mode 100644 index 39830da..0000000 --- a/versioned_docs/version-0.1.1/configure-server/_category_.yml +++ /dev/null @@ -1,5 +0,0 @@ -position: 3 -label: Configure MCP server -link: - type: generated-index - title: Configure MCP server diff --git a/versioned_docs/version-0.1.1/configure-server/bearer-auth.mdx b/versioned_docs/version-0.1.1/configure-server/bearer-auth.mdx deleted file mode 100644 index 3887228..0000000 --- a/versioned_docs/version-0.1.1/configure-server/bearer-auth.mdx +++ /dev/null @@ -1,250 +0,0 @@ ---- -sidebar_position: 2 -sidebar_label: Bearer auth ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -# Configure Bearer auth in MCP server - -MCP Auth provides various ways to configure Bearer authorization in your MCP server: - -- [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} - -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} - -Here's an example of the basic scope validation: - - - - -```python -from mcpauth import MCPAuth -from starlette.applications import Starlette -from starlette.middleware import Middleware -from starlette.routing import Mount -from mcp.server.fastmcp import FastMCP - -mcp = FastMCP("MyMCPServer") -mcp_auth = MCPAuth( - # Initialize with your auth server config -) -bearer_auth = mcp_auth.bearer_auth_middleware("jwt", required_scopes=["read", "write"]) # [!code highlight] - -app = Starlette( - routes=[Mount('/', app=mcp.sse_app(), middleware=[Middleware(bearer_auth)])] -) -``` - - - - -```ts -import express from 'express'; -import { MCPAuth } from 'mcp-auth'; - -const app = express(); -const mcpAuth = new MCPAuth({ - /* ... */ -}); -const bearerAuth = mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }); // [!code highlight] - -app.use('/mcp', bearerAuth, (req, res) => { - // Now `req.auth` contains the auth info - console.log(req.auth); -}); -``` - - - - -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} - -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. - -Check your provider's documentation to see if it supports the Resource Indicator extension and how to configure it. Some providers may use other terms like "audience", "API resource", or "API indicator" to refer to the same concept. - -Once the resource indicator is configured, you can specify it in the `bearerAuth` middleware: - - - - -```python -bearer_auth = mcp_auth.bearer_auth_middleware( - "jwt", - audience="https://api.example.com/mcp", # The expected audience for the JWT [!code highlight] - required_scopes=["read", "write"] -) -``` - - - - -```ts -const bearerAuth = mcpAuth.bearerAuth('jwt', { - audience: 'https://api.example.com/mcp', // The expected audience for the JWT [!code highlight] - requiredScopes: ['read', 'write'], -}); -``` - - - - -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} - -You can also provide custom options to the underlying JWT verification library: - - - - -In Python SDK, we use [PyJWT](https://pyjwt.readthedocs.io/en/stable/) for JWT verification. You can the following options: - -- `leeway`: Allow a certain amount of leeway when verifying the JWT expiration time (in seconds). Default is 60 seconds. - -```python -bearer_auth = mcp_auth.bearer_auth_middleware( - "jwt", - audience="https://api.example.com/mcp", - required_scopes=["read", "write"] - leeway=10, # Reduce clock skew by allowing 10 seconds leeway [!code highlight] -) -``` - - - - -In Node.js SDK, we use [jose](https://github.com/panva/jose) library for JWT verification. You can provide the following options: - -- `jwtVerify`: Options for the JWT verification process (`jwtVerify` function from `jose`). -- `remoteJwtSet`: Options for fetching the remote JWT set (`createRemoteJWKSet` function from `jose`). - -```ts {4-9} -const bearerAuth = mcpAuth.bearerAuth('jwt', { - audience: 'https://api.example.com/mcp', - requiredScopes: ['read', 'write'], - jwtVerify: { - clockTolerance: 60, // Allow a 60 seconds clock skew - }, - remoteJwtSet: { - timeoutDuration: 10 * 1000, // 10 seconds timeout for remote JWT set fetching - }, -}); -``` - - - - -## 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: - -:::info -Since the Bearer auth middleware will check against issuer (`iss`), audience (`aud`), and required scopes (`scope`) with the given verification result, there's no need to implement these checks in your custom verification function. You can focus on verifying the token validity (e.g., signature, expiration, etc.) and returning the auth info object. -::: - - - - -```python -from mcpauth.exceptions import MCPAuthJwtVerificationException, MCPAuthJwtVerificationExceptionCode -from mcpauth.types import AuthInfo - -async def custom_verification(token: str) -> AuthInfo: - # Implement your custom verification logic here - info = await verify_token(token) - if not info: - raise MCPAuthJwtVerificationException( - MCPAuthJwtVerificationExceptionCode.JWT_VERIFICATION_FAILED - ) - return info # Return the auth info object - -bearer_auth = mcp_auth.bearer_auth_middleware( - custom_verification, - required_scopes=["read", "write"] -) -``` - - - - -```ts -const bearerAuth = mcpAuth.bearerAuth( - async (token) => { - // Implement your custom verification logic here - const info = await verifyToken(token); - if (!info) { - throw new MCPAuthJwtVerificationError('jwt_verification_failed'); - } - return info; // Return the auth info object - }, - { requiredScopes: ['read', 'write'] } -); -``` - - - - -## 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. - - - - -```python -bearer_auth = mcp_auth.bearer_auth_middleware("jwt", required_scopes=["read", "write"]) -app = Starlette( - routes=[Mount('/', app=mcp.sse_app(), middleware=[Middleware(bearer_auth)])] -) -``` - - - - -```js -const app = express(); -app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] })); -``` - - - - -This will ensure that all incoming requests are authenticated and authorized according to the configured Bearer auth settings, and the auth information will be available in the request context. - -You can then access the information in your MCP server implementation: - - - - -```python -@mcp.tool() -async def whoami() -> dict: - # `mcp_auth.auth_info` is the context object for the current request - auth_info = mcp_auth.auth_info - print(f"Authenticated user: {auth_info.subject}") - return {"subject": auth_info.subject} -``` - - - - -```js -// `authInfo` will be carried from the `req.auth` object -server.tool('whoami', ({ authInfo }) => { - console.log(`Authenticated user: ${authInfo.subject}`); - return { subject: authInfo.subject }; -}); -``` - - - diff --git a/versioned_docs/version-0.1.1/configure-server/mcp-auth.mdx b/versioned_docs/version-0.1.1/configure-server/mcp-auth.mdx deleted file mode 100644 index cb5b4cd..0000000 --- a/versioned_docs/version-0.1.1/configure-server/mcp-auth.mdx +++ /dev/null @@ -1,208 +0,0 @@ ---- -sidebar_position: 1 -sidebar_label: MCP Auth ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -# Configure MCP Auth in MCP server - -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} - -### 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: - -- [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) -- [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) - -You can use the `fetchServerConfig` to automatically retrieve the metadata by providing the `issuer` URL: - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType, fetch_server_config - -mcp_auth = MCPAuth( - server=fetch_server_config( - '', - type=AuthServerType.OIDC # or AuthServerType.OAUTH - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { type: 'oidc' }), // or 'oauth' -}); -``` - - - - -If your issuer includes a path, the behavior differs slightly between OAuth 2.0 and OpenID Connect: - -- **OAuth 2.0**: The well-known URL is appended to the **domain** of the issuer. For example, if your issuer is `https://my-project.logto.app/oauth`, the well-known URL will be `https://auth.logto.io/.well-known/oauth-authorization-server/oauth`. -- **OpenID Connect**: The well-known URL is appended directly to the **issuer**. For example, if your issuer is `https://my-project.logto.app/oidc`, the well-known URL will be `https://auth.logto.io/oidc/.well-known/openid-configuration`. - -### Other ways to initialize MCP Auth \{#other-ways} - -#### 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: - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -mcp_auth = MCPAuth( - server=fetch_server_config( - '', - type=AuthServerType.OIDC, - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { - type: 'oidc', - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - - -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} - -If your provider has a specific metadata URL rather than the standard ones, you can use it similarly: - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config_by_well_known_url - -mcp_auth = MCPAuth( - server=fetch_server_config_by_well_known_url( - '', - type=AuthServerType.OIDC # or AuthServerType.OAUTH - ) -) -``` - - - - -```ts -import { MCPAuth, fetchServerConfigByWellKnownUrl } from 'mcp-auth'; - -const mcpAuth = new MCPAuth({ - server: await fetchServerConfigByWellKnownUrl('', { type: 'oidc' }), // or 'oauth' -}); -``` - - - - -#### 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: - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType, fetch_server_config_by_well_known_url - -mcp_auth = MCPAuth( - server=fetch_server_config_by_well_known_url( - '', - type=AuthServerType.OIDC, - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: await fetchServerConfigByWellKnownUrl('', { - type: 'oidc', - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - - -#### Manually provide metadata \{#manually-provide-metadata} - -If your provider does not support metadata fetching, you can manually provide the metadata object: - - - - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerConfig, AuthServerType, AuthorizationServerMetadata - -mcp_auth = MCPAuth( - server=AuthServerConfig( - type=AuthServerType.OIDC, # or AuthServerType.OAUTH - metadata=AuthorizationServerMetadata( - issuer='', - authorization_endpoint='', - # ... other metadata fields - ), - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: { - metadata: { - issuer: '', - // Metadata fields should be camelCase - authorizationEndpoint: '', - // ... other metadata fields - }, - type: 'oidc', // or 'oauth' - }, -}); -``` - - - diff --git a/versioned_docs/version-0.1.1/references/_category_.yml b/versioned_docs/version-0.1.1/references/_category_.yml deleted file mode 100644 index bd1ab82..0000000 --- a/versioned_docs/version-0.1.1/references/_category_.yml +++ /dev/null @@ -1,7 +0,0 @@ -position: 100 -label: SDK references -link: - type: generated-index - title: MCP Auth SDK references - description: > - Information about classes, methods, and properties extracted from the MCP Auth SDKs. diff --git a/versioned_docs/version-0.1.1/references/js/README.md b/versioned_docs/version-0.1.1/references/js/README.md deleted file mode 100644 index f0875b7..0000000 --- a/versioned_docs/version-0.1.1/references/js/README.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -sidebar_label: Node.js SDK ---- - -# MCP Auth Node.js SDK reference - -## Classes {#classes} - -- [MCPAuth](/references/js/classes/MCPAuth.md) -- [MCPAuthAuthServerError](/references/js/classes/MCPAuthAuthServerError.md) -- [MCPAuthBearerAuthError](/references/js/classes/MCPAuthBearerAuthError.md) -- [MCPAuthConfigError](/references/js/classes/MCPAuthConfigError.md) -- [MCPAuthError](/references/js/classes/MCPAuthError.md) -- [MCPAuthTokenVerificationError](/references/js/classes/MCPAuthTokenVerificationError.md) - -## Type Aliases {#type-aliases} - -- [AuthorizationServerMetadata](/references/js/type-aliases/AuthorizationServerMetadata.md) -- [AuthServerConfig](/references/js/type-aliases/AuthServerConfig.md) -- [AuthServerConfigError](/references/js/type-aliases/AuthServerConfigError.md) -- [AuthServerConfigErrorCode](/references/js/type-aliases/AuthServerConfigErrorCode.md) -- [AuthServerConfigWarning](/references/js/type-aliases/AuthServerConfigWarning.md) -- [AuthServerConfigWarningCode](/references/js/type-aliases/AuthServerConfigWarningCode.md) -- [AuthServerErrorCode](/references/js/type-aliases/AuthServerErrorCode.md) -- [AuthServerSuccessCode](/references/js/type-aliases/AuthServerSuccessCode.md) -- [AuthServerType](/references/js/type-aliases/AuthServerType.md) -- [BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) -- [BearerAuthErrorCode](/references/js/type-aliases/BearerAuthErrorCode.md) -- [BearerAuthJwtConfig](/references/js/type-aliases/BearerAuthJwtConfig.md) -- [CamelCaseAuthorizationServerMetadata](/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md) -- [MCPAuthBearerAuthErrorDetails](/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md) -- [MCPAuthConfig](/references/js/type-aliases/MCPAuthConfig.md) -- [MCPAuthTokenVerificationErrorCode](/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md) -- [VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) -- [VerifyAccessTokenMode](/references/js/type-aliases/VerifyAccessTokenMode.md) - -## Variables {#variables} - -- [authorizationServerMetadataSchema](/references/js/variables/authorizationServerMetadataSchema.md) -- [authServerErrorDescription](/references/js/variables/authServerErrorDescription.md) -- [bearerAuthErrorDescription](/references/js/variables/bearerAuthErrorDescription.md) -- [camelCaseAuthorizationServerMetadataSchema](/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md) -- [serverMetadataPaths](/references/js/variables/serverMetadataPaths.md) -- [tokenVerificationErrorDescription](/references/js/variables/tokenVerificationErrorDescription.md) -- [validateServerConfig](/references/js/variables/validateServerConfig.md) - -## Functions {#functions} - -- [createVerifyJwt](/references/js/functions/createVerifyJwt.md) -- [fetchServerConfig](/references/js/functions/fetchServerConfig.md) -- [fetchServerConfigByWellKnownUrl](/references/js/functions/fetchServerConfigByWellKnownUrl.md) -- [handleBearerAuth](/references/js/functions/handleBearerAuth.md) diff --git a/versioned_docs/version-0.1.1/references/js/classes/MCPAuth.md b/versioned_docs/version-0.1.1/references/js/classes/MCPAuth.md deleted file mode 100644 index d6f82db..0000000 --- a/versioned_docs/version-0.1.1/references/js/classes/MCPAuth.md +++ /dev/null @@ -1,214 +0,0 @@ ---- -sidebar_label: MCPAuth ---- - -# Class: MCPAuth - -The main class for the mcp-auth library, which provides methods to create routers and useful -handlers for authentication and authorization in MCP servers. - -## See {#see} - -[MCP Auth](https://mcp-auth.dev) for more information about the library and its -usage. - -## Example {#example} - -An example integrating with a remote OIDC provider: - -```ts -import express from 'express'; -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const app = express(); -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig( - 'https://auth.logto.io/oidc', - { type: 'oidc' } - ), -}); - -// Mount the router to handle OAuth 2.0 Authorization Server Metadata -app.use(mcpAuth.delegatedRouter()); - -// Use the Bearer auth handler the MCP route -app.get( - '/mcp', - mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }), - (req, res) => { - console.log('Auth info:', req.auth); - // Handle the MCP request here - }, -); - -// Use the auth info in the MCP callback -server.tool( - 'add', - { a: z.number(), b: z.number() }, - async ({ a, b }, { authInfo }) => { - console.log('Auth Info:', authInfo); - // ... - }, -); -``` - -## Constructors {#constructors} - -### Constructor {#constructor} - -```ts -new MCPAuth(config: MCPAuthConfig): MCPAuth; -``` - -#### Parameters {#parameters} - -##### config {#config} - -[`MCPAuthConfig`](/references/js/type-aliases/MCPAuthConfig.md) - -#### Returns {#returns} - -`MCPAuth` - -## Properties {#properties} - -### config {#config} - -```ts -readonly config: MCPAuthConfig; -``` - -## Methods {#methods} - -### bearerAuth() {#bearerauth} - -#### Call Signature {#call-signature} - -```ts -bearerAuth(verifyAccessToken: VerifyAccessTokenFunction, config?: Omit): RequestHandler; -``` - -Creates a Bearer auth handler (Express middleware) that verifies the access token in the -`Authorization` header of the request. - -##### Parameters {#parameters} - -###### verifyAccessToken {#verifyaccesstoken} - -[`VerifyAccessTokenFunction`](/references/js/type-aliases/VerifyAccessTokenFunction.md) - -A function that verifies the access token. It should accept the -access token as a string and return a promise (or a value) that resolves to the -verification result. - -**See** - -[VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) for the type definition of the -`verifyAccessToken` function. - -###### config? {#config} - -`Omit`\<[`BearerAuthConfig`](/references/js/type-aliases/BearerAuthConfig.md), `"verifyAccessToken"` \| `"issuer"`\> - -Optional configuration for the Bearer auth handler. - -**See** - -[BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) for the available configuration options (excluding -`verifyAccessToken` and `issuer`). - -##### Returns {#returns} - -`RequestHandler` - -An Express middleware function that verifies the access token and adds the -verification result to the request object (`req.auth`). - -##### See {#see} - -[handleBearerAuth](/references/js/functions/handleBearerAuth.md) for the implementation details and the extended types of the -`req.auth` (`AuthInfo`) object. - -#### Call Signature {#call-signature} - -```ts -bearerAuth(mode: "jwt", config?: Omit & BearerAuthJwtConfig): RequestHandler; -``` - -Creates a Bearer auth handler (Express middleware) that verifies the access token in the -`Authorization` header of the request using a predefined mode of verification. - -In the `'jwt'` mode, the handler will create a JWT verification function using the JWK Set -from the authorization server's JWKS URI. - -##### Parameters {#parameters} - -###### mode {#mode} - -`"jwt"` - -The mode of verification for the access token. Currently, only 'jwt' is supported. - -**See** - -[VerifyAccessTokenMode](/references/js/type-aliases/VerifyAccessTokenMode.md) for the available modes. - -###### config? {#config} - -`Omit`\<[`BearerAuthConfig`](/references/js/type-aliases/BearerAuthConfig.md), `"verifyAccessToken"` \| `"issuer"`\> & [`BearerAuthJwtConfig`](/references/js/type-aliases/BearerAuthJwtConfig.md) - -Optional configuration for the Bearer auth handler, including JWT verification options and -remote JWK set options. - -**See** - - - [BearerAuthJwtConfig](/references/js/type-aliases/BearerAuthJwtConfig.md) for the available configuration options for JWT -verification. - - [BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) for the available configuration options (excluding -`verifyAccessToken` and `issuer`). - -##### Returns {#returns} - -`RequestHandler` - -An Express middleware function that verifies the access token and adds the -verification result to the request object (`req.auth`). - -##### See {#see} - -[handleBearerAuth](/references/js/functions/handleBearerAuth.md) for the implementation details and the extended types of the -`req.auth` (`AuthInfo`) object. - -##### Throws {#throws} - -if the JWKS URI is not provided in the server metadata when -using the `'jwt'` mode. - -*** - -### delegatedRouter() {#delegatedrouter} - -```ts -delegatedRouter(): Router; -``` - -Creates a delegated router that serves the OAuth 2.0 Authorization Server Metadata endpoint -(`/.well-known/oauth-authorization-server`) with the metadata provided to the instance. - -#### Returns {#returns} - -`Router` - -A router that serves the OAuth 2.0 Authorization Server Metadata endpoint with the -metadata provided to the instance. - -#### Example {#example} - -```ts -import express from 'express'; -import { MCPAuth } from 'mcp-auth'; - -const app = express(); -const mcpAuth: MCPAuth; // Assume this is initialized -app.use(mcpAuth.delegatedRouter()); -``` diff --git a/versioned_docs/version-0.1.1/references/js/classes/MCPAuthAuthServerError.md b/versioned_docs/version-0.1.1/references/js/classes/MCPAuthAuthServerError.md deleted file mode 100644 index 4b9c556..0000000 --- a/versioned_docs/version-0.1.1/references/js/classes/MCPAuthAuthServerError.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -sidebar_label: MCPAuthAuthServerError ---- - -# Class: MCPAuthAuthServerError - -Error thrown when there is an issue with the remote authorization server. - -## Extends {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## Constructors {#constructors} - -### Constructor {#constructor} - -```ts -new MCPAuthAuthServerError(code: AuthServerErrorCode, cause?: unknown): MCPAuthAuthServerError; -``` - -#### Parameters {#parameters} - -##### code {#code} - -[`AuthServerErrorCode`](/references/js/type-aliases/AuthServerErrorCode.md) - -##### cause? {#cause} - -`unknown` - -#### Returns {#returns} - -`MCPAuthAuthServerError` - -#### Overrides {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## Properties {#properties} - -### cause? {#cause} - -```ts -readonly optional cause: unknown; -``` - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: AuthServerErrorCode; -``` - -The error code in snake_case format. - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthAuthServerError'; -``` - -#### Overrides {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -Optional override for formatting stack traces - -#### Parameters {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### Returns {#returns} - -`any` - -#### See {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## Methods {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -Converts the error to a HTTP response friendly JSON format. - -#### Parameters {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -Whether to include the cause of the error in the JSON response. -Defaults to `false`. - -#### Returns {#returns} - -`Record`\<`string`, `unknown`\> - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -Create .stack property on a target object - -#### Parameters {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### Returns {#returns} - -`void` - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) diff --git a/versioned_docs/version-0.1.1/references/js/classes/MCPAuthBearerAuthError.md b/versioned_docs/version-0.1.1/references/js/classes/MCPAuthBearerAuthError.md deleted file mode 100644 index 7990bdc..0000000 --- a/versioned_docs/version-0.1.1/references/js/classes/MCPAuthBearerAuthError.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -sidebar_label: MCPAuthBearerAuthError ---- - -# Class: MCPAuthBearerAuthError - -Error thrown when there is an issue when authenticating with Bearer tokens. - -## Extends {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## Constructors {#constructors} - -### Constructor {#constructor} - -```ts -new MCPAuthBearerAuthError(code: BearerAuthErrorCode, cause?: MCPAuthBearerAuthErrorDetails): MCPAuthBearerAuthError; -``` - -#### Parameters {#parameters} - -##### code {#code} - -[`BearerAuthErrorCode`](/references/js/type-aliases/BearerAuthErrorCode.md) - -##### cause? {#cause} - -[`MCPAuthBearerAuthErrorDetails`](/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md) - -#### Returns {#returns} - -`MCPAuthBearerAuthError` - -#### Overrides {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## Properties {#properties} - -### cause? {#cause} - -```ts -readonly optional cause: MCPAuthBearerAuthErrorDetails; -``` - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: BearerAuthErrorCode; -``` - -The error code in snake_case format. - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthBearerAuthError'; -``` - -#### Overrides {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -Optional override for formatting stack traces - -#### Parameters {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### Returns {#returns} - -`any` - -#### See {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## Methods {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -Converts the error to a HTTP response friendly JSON format. - -#### Parameters {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -Whether to include the cause of the error in the JSON response. -Defaults to `false`. - -#### Returns {#returns} - -`Record`\<`string`, `unknown`\> - -#### Overrides {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -Create .stack property on a target object - -#### Parameters {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### Returns {#returns} - -`void` - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) diff --git a/versioned_docs/version-0.1.1/references/js/classes/MCPAuthConfigError.md b/versioned_docs/version-0.1.1/references/js/classes/MCPAuthConfigError.md deleted file mode 100644 index 8047fdd..0000000 --- a/versioned_docs/version-0.1.1/references/js/classes/MCPAuthConfigError.md +++ /dev/null @@ -1,202 +0,0 @@ ---- -sidebar_label: MCPAuthConfigError ---- - -# Class: MCPAuthConfigError - -Error thrown when there is a configuration issue with mcp-auth. - -## Extends {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## Constructors {#constructors} - -### Constructor {#constructor} - -```ts -new MCPAuthConfigError(code: string, message: string): MCPAuthConfigError; -``` - -#### Parameters {#parameters} - -##### code {#code} - -`string` - -The error code in snake_case format. - -##### message {#message} - -`string` - -A human-readable description of the error. - -#### Returns {#returns} - -`MCPAuthConfigError` - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## Properties {#properties} - -### cause? {#cause} - -```ts -optional cause: unknown; -``` - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: string; -``` - -The error code in snake_case format. - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthConfigError'; -``` - -#### Overrides {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -Optional override for formatting stack traces - -#### Parameters {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### Returns {#returns} - -`any` - -#### See {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## Methods {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -Converts the error to a HTTP response friendly JSON format. - -#### Parameters {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -Whether to include the cause of the error in the JSON response. -Defaults to `false`. - -#### Returns {#returns} - -`Record`\<`string`, `unknown`\> - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -Create .stack property on a target object - -#### Parameters {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### Returns {#returns} - -`void` - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) diff --git a/versioned_docs/version-0.1.1/references/js/classes/MCPAuthError.md b/versioned_docs/version-0.1.1/references/js/classes/MCPAuthError.md deleted file mode 100644 index 6bffab7..0000000 --- a/versioned_docs/version-0.1.1/references/js/classes/MCPAuthError.md +++ /dev/null @@ -1,219 +0,0 @@ ---- -sidebar_label: MCPAuthError ---- - -# Class: MCPAuthError - -Base class for all mcp-auth errors. - -It provides a standardized way to handle errors related to MCP authentication and authorization. - -## Extends {#extends} - -- `Error` - -## Extended by {#extended-by} - -- [`MCPAuthConfigError`](/references/js/classes/MCPAuthConfigError.md) -- [`MCPAuthAuthServerError`](/references/js/classes/MCPAuthAuthServerError.md) -- [`MCPAuthBearerAuthError`](/references/js/classes/MCPAuthBearerAuthError.md) -- [`MCPAuthTokenVerificationError`](/references/js/classes/MCPAuthTokenVerificationError.md) - -## Constructors {#constructors} - -### Constructor {#constructor} - -```ts -new MCPAuthError(code: string, message: string): MCPAuthError; -``` - -#### Parameters {#parameters} - -##### code {#code} - -`string` - -The error code in snake_case format. - -##### message {#message} - -`string` - -A human-readable description of the error. - -#### Returns {#returns} - -`MCPAuthError` - -#### Overrides {#overrides} - -```ts -Error.constructor -``` - -## Properties {#properties} - -### cause? {#cause} - -```ts -optional cause: unknown; -``` - -#### Inherited from {#inherited-from} - -```ts -Error.cause -``` - -*** - -### code {#code} - -```ts -readonly code: string; -``` - -The error code in snake_case format. - -*** - -### message {#message} - -```ts -message: string; -``` - -#### Inherited from {#inherited-from} - -```ts -Error.message -``` - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthError'; -``` - -#### Overrides {#overrides} - -```ts -Error.name -``` - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### Inherited from {#inherited-from} - -```ts -Error.stack -``` - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -Optional override for formatting stack traces - -#### Parameters {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### Returns {#returns} - -`any` - -#### See {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### Inherited from {#inherited-from} - -```ts -Error.prepareStackTrace -``` - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### Inherited from {#inherited-from} - -```ts -Error.stackTraceLimit -``` - -## Methods {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -Converts the error to a HTTP response friendly JSON format. - -#### Parameters {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -Whether to include the cause of the error in the JSON response. -Defaults to `false`. - -#### Returns {#returns} - -`Record`\<`string`, `unknown`\> - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -Create .stack property on a target object - -#### Parameters {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### Returns {#returns} - -`void` - -#### Inherited from {#inherited-from} - -```ts -Error.captureStackTrace -``` diff --git a/versioned_docs/version-0.1.1/references/js/classes/MCPAuthTokenVerificationError.md b/versioned_docs/version-0.1.1/references/js/classes/MCPAuthTokenVerificationError.md deleted file mode 100644 index 78be151..0000000 --- a/versioned_docs/version-0.1.1/references/js/classes/MCPAuthTokenVerificationError.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -sidebar_label: MCPAuthTokenVerificationError ---- - -# Class: MCPAuthTokenVerificationError - -Error thrown when there is an issue when verifying tokens. - -## Extends {#extends} - -- [`MCPAuthError`](/references/js/classes/MCPAuthError.md) - -## Constructors {#constructors} - -### Constructor {#constructor} - -```ts -new MCPAuthTokenVerificationError(code: MCPAuthTokenVerificationErrorCode, cause?: unknown): MCPAuthTokenVerificationError; -``` - -#### Parameters {#parameters} - -##### code {#code} - -[`MCPAuthTokenVerificationErrorCode`](/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md) - -##### cause? {#cause} - -`unknown` - -#### Returns {#returns} - -`MCPAuthTokenVerificationError` - -#### Overrides {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) - -## Properties {#properties} - -### cause? {#cause} - -```ts -readonly optional cause: unknown; -``` - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) - -*** - -### code {#code} - -```ts -readonly code: MCPAuthTokenVerificationErrorCode; -``` - -The error code in snake_case format. - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) - -*** - -### message {#message} - -```ts -message: string; -``` - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) - -*** - -### name {#name} - -```ts -name: string = 'MCPAuthTokenVerificationError'; -``` - -#### Overrides {#overrides} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) - -*** - -### stack? {#stack} - -```ts -optional stack: string; -``` - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) - -*** - -### prepareStackTrace()? {#preparestacktrace} - -```ts -static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; -``` - -Optional override for formatting stack traces - -#### Parameters {#parameters} - -##### err {#err} - -`Error` - -##### stackTraces {#stacktraces} - -`CallSite`[] - -#### Returns {#returns} - -`any` - -#### See {#see} - -https://v8.dev/docs/stack-trace-api#customizing-stack-traces - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) - -*** - -### stackTraceLimit {#stacktracelimit} - -```ts -static stackTraceLimit: number; -``` - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## Methods {#methods} - -### toJson() {#tojson} - -```ts -toJson(showCause: boolean): Record; -``` - -Converts the error to a HTTP response friendly JSON format. - -#### Parameters {#parameters} - -##### showCause {#showcause} - -`boolean` = `false` - -Whether to include the cause of the error in the JSON response. -Defaults to `false`. - -#### Returns {#returns} - -`Record`\<`string`, `unknown`\> - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) - -*** - -### captureStackTrace() {#capturestacktrace} - -```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -Create .stack property on a target object - -#### Parameters {#parameters} - -##### targetObject {#targetobject} - -`object` - -##### constructorOpt? {#constructoropt} - -`Function` - -#### Returns {#returns} - -`void` - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) diff --git a/versioned_docs/version-0.1.1/references/js/functions/createVerifyJwt.md b/versioned_docs/version-0.1.1/references/js/functions/createVerifyJwt.md deleted file mode 100644 index c7126e8..0000000 --- a/versioned_docs/version-0.1.1/references/js/functions/createVerifyJwt.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -sidebar_label: createVerifyJwt ---- - -# Function: createVerifyJwt() - -```ts -function createVerifyJwt(getKey: JWTVerifyGetKey, options?: JWTVerifyOptions): VerifyAccessTokenFunction; -``` - -Creates a function to verify JWT access tokens using the provided key retrieval function -and options. - -## Parameters {#parameters} - -### getKey {#getkey} - -`JWTVerifyGetKey` - -The function to retrieve the key used to verify the JWT. - -**See** - -JWTVerifyGetKey for the type definition of the key retrieval function. - -### options? {#options} - -`JWTVerifyOptions` - -Optional JWT verification options. - -**See** - -JWTVerifyOptions for the type definition of the options. - -## Returns {#returns} - -[`VerifyAccessTokenFunction`](/references/js/type-aliases/VerifyAccessTokenFunction.md) - -A function that verifies JWT access tokens and returns an AuthInfo object if -the token is valid. It requires the JWT to contain the fields `iss`, `client_id`, and `sub` in -its payload, and it can optionally contain `scope` or `scopes` fields. The function uses the -`jose` library under the hood to perform the JWT verification. - -## See {#see} - -[VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) for the type definition of the returned function. diff --git a/versioned_docs/version-0.1.1/references/js/functions/fetchServerConfig.md b/versioned_docs/version-0.1.1/references/js/functions/fetchServerConfig.md deleted file mode 100644 index 2c9f186..0000000 --- a/versioned_docs/version-0.1.1/references/js/functions/fetchServerConfig.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -sidebar_label: fetchServerConfig ---- - -# Function: fetchServerConfig() - -```ts -function fetchServerConfig(issuer: string, config: ServerMetadataConfig): Promise; -``` - -Fetches the server configuration according to the issuer and authorization server type. - -This function automatically determines the well-known URL based on the server type, as OAuth and -OpenID Connect servers have different conventions for their metadata endpoints. - -## Parameters {#parameters} - -### issuer {#issuer} - -`string` - -The issuer URL of the authorization server. - -### config {#config} - -`ServerMetadataConfig` - -The configuration object containing the server type and optional transpile function. - -## Returns {#returns} - -`Promise`\<[`AuthServerConfig`](/references/js/type-aliases/AuthServerConfig.md)\> - -A promise that resolves to the server configuration. - -## See {#see} - - - [fetchServerConfigByWellKnownUrl](/references/js/functions/fetchServerConfigByWellKnownUrl.md) for the underlying implementation. - - [https://www.rfc-editor.org/rfc/rfc8414](https://www.rfc-editor.org/rfc/rfc8414) for the OAuth 2.0 Authorization Server Metadata -specification. - - [https://openid.net/specs/openid-connect-discovery-1\_0.html](https://openid.net/specs/openid-connect-discovery-1_0.html) for the OpenID Connect -Discovery specification. - -## Example {#example} - -```ts -import { fetchServerConfig } from 'mcp-auth'; -// Fetching OAuth server configuration -// This will fetch the metadata from `https://auth.logto.io/.well-known/oauth-authorization-server/oauth` -const oauthConfig = await fetchServerConfig('https://auth.logto.io/oauth', { type: 'oauth' }); - -// Fetching OpenID Connect server configuration -// This will fetch the metadata from `https://auth.logto.io/oidc/.well-known/openid-configuration` -const oidcConfig = await fetchServerConfig('https://auth.logto.io/oidc', { type: 'oidc' }); -``` - -## Throws {#throws} - -if the fetch operation fails. - -## Throws {#throws} - -if the server metadata is invalid or does not match the -MCP specification. diff --git a/versioned_docs/version-0.1.1/references/js/functions/fetchServerConfigByWellKnownUrl.md b/versioned_docs/version-0.1.1/references/js/functions/fetchServerConfigByWellKnownUrl.md deleted file mode 100644 index 7ab45db..0000000 --- a/versioned_docs/version-0.1.1/references/js/functions/fetchServerConfigByWellKnownUrl.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -sidebar_label: fetchServerConfigByWellKnownUrl ---- - -# Function: fetchServerConfigByWellKnownUrl() - -```ts -function fetchServerConfigByWellKnownUrl(wellKnownUrl: string | URL, config: ServerMetadataConfig): Promise; -``` - -Fetches the server configuration from the provided well-known URL and validates it against the -MCP specification. - -If the server metadata does not conform to the expected schema, but you are sure that it is -compatible, you can define a `transpileData` function to transform the metadata into the -expected format. - -## Parameters {#parameters} - -### wellKnownUrl {#wellknownurl} - -The well-known URL to fetch the server configuration from. This can be a -string or a URL object. - -`string` | `URL` - -### config {#config} - -`ServerMetadataConfig` - -The configuration object containing the server type and optional transpile function. - -## Returns {#returns} - -`Promise`\<[`AuthServerConfig`](/references/js/type-aliases/AuthServerConfig.md)\> - -A promise that resolves to the server configuration. - -## Throws {#throws} - -if the fetch operation fails. - -## Throws {#throws} - -if the server metadata is invalid or does not match the -MCP specification. diff --git a/versioned_docs/version-0.1.1/references/js/functions/handleBearerAuth.md b/versioned_docs/version-0.1.1/references/js/functions/handleBearerAuth.md deleted file mode 100644 index ddb403e..0000000 --- a/versioned_docs/version-0.1.1/references/js/functions/handleBearerAuth.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -sidebar_label: handleBearerAuth ---- - -# Function: handleBearerAuth() - -```ts -function handleBearerAuth(param0: BearerAuthConfig): RequestHandler; -``` - -Creates a middleware function for handling Bearer auth in an Express application. - -This middleware extracts the Bearer token from the `Authorization` header, verifies it using the -provided `verifyAccessToken` function, and checks the issuer, audience, and required scopes. - -- If the token is valid, it adds the auth information to the `request.auth` property; -if not, it responds with an appropriate error message. -- If access token verification fails, it responds with a 401 Unauthorized error. -- If the token does not have the required scopes, it responds with a 403 Forbidden error. -- If unexpected errors occur during the auth process, the middleware will re-throw them. - -**Note:** The `request.auth` object will contain extended fields compared to the standard -AuthInfo interface defined in the `@modelcontextprotocol/sdk` module. See the extended -interface in this file for details. - -## Parameters {#parameters} - -### param0 {#param0} - -[`BearerAuthConfig`](/references/js/type-aliases/BearerAuthConfig.md) - -Configuration for the Bearer auth handler. - -## Returns {#returns} - -`RequestHandler` - -A middleware function for Express that handles Bearer auth. - -## See {#see} - -[BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) for the configuration options. diff --git a/versioned_docs/version-0.1.1/references/js/type-aliases/AuthServerConfig.md b/versioned_docs/version-0.1.1/references/js/type-aliases/AuthServerConfig.md deleted file mode 100644 index 8166bf3..0000000 --- a/versioned_docs/version-0.1.1/references/js/type-aliases/AuthServerConfig.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -sidebar_label: AuthServerConfig ---- - -# Type Alias: AuthServerConfig - -```ts -type AuthServerConfig = { - metadata: CamelCaseAuthorizationServerMetadata; - type: AuthServerType; -}; -``` - -Configuration for the remote authorization server integrated with the MCP server. - -## Properties {#properties} - -### metadata {#metadata} - -```ts -metadata: CamelCaseAuthorizationServerMetadata; -``` - -The metadata of the authorization server, which should conform to the MCP specification -(based on OAuth 2.0 Authorization Server Metadata). - -This metadata is typically fetched from the server's well-known endpoint (OAuth 2.0 -Authorization Server Metadata or OpenID Connect Discovery); it can also be provided -directly in the configuration if the server does not support such endpoints. - -**Note:** The metadata should be in camelCase format as per preferred by the mcp-auth -library. - -#### See {#see} - - - [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) - - [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) - -*** - -### type {#type} - -```ts -type: AuthServerType; -``` - -The type of the authorization server. - -#### See {#see} - -[AuthServerType](/references/js/type-aliases/AuthServerType.md) for the possible values. diff --git a/versioned_docs/version-0.1.1/references/js/type-aliases/AuthServerConfigError.md b/versioned_docs/version-0.1.1/references/js/type-aliases/AuthServerConfigError.md deleted file mode 100644 index 05371c1..0000000 --- a/versioned_docs/version-0.1.1/references/js/type-aliases/AuthServerConfigError.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -sidebar_label: AuthServerConfigError ---- - -# Type Alias: AuthServerConfigError - -```ts -type AuthServerConfigError = { - cause?: Error; - code: AuthServerConfigErrorCode; - description: string; -}; -``` - -Represents an error that occurs during the validation of the authorization server metadata. - -## Properties {#properties} - -### cause? {#cause} - -```ts -optional cause: Error; -``` - -An optional cause of the error, typically an instance of `Error` that provides more context. - -*** - -### code {#code} - -```ts -code: AuthServerConfigErrorCode; -``` - -The code representing the specific validation error. - -*** - -### description {#description} - -```ts -description: string; -``` - -A human-readable description of the error. diff --git a/versioned_docs/version-0.1.1/references/js/type-aliases/AuthServerConfigErrorCode.md b/versioned_docs/version-0.1.1/references/js/type-aliases/AuthServerConfigErrorCode.md deleted file mode 100644 index 9ba4f41..0000000 --- a/versioned_docs/version-0.1.1/references/js/type-aliases/AuthServerConfigErrorCode.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_label: AuthServerConfigErrorCode ---- - -# Type Alias: AuthServerConfigErrorCode - -```ts -type AuthServerConfigErrorCode = - | "invalid_server_metadata" - | "code_response_type_not_supported" - | "authorization_code_grant_not_supported" - | "pkce_not_supported" - | "s256_code_challenge_method_not_supported"; -``` - -The codes for errors that can occur when validating the authorization server metadata. diff --git a/versioned_docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarning.md b/versioned_docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarning.md deleted file mode 100644 index f093e35..0000000 --- a/versioned_docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarning.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -sidebar_label: AuthServerConfigWarning ---- - -# Type Alias: AuthServerConfigWarning - -```ts -type AuthServerConfigWarning = { - code: AuthServerConfigWarningCode; - description: string; -}; -``` - -Represents a warning that occurs during the validation of the authorization server metadata. - -## Properties {#properties} - -### code {#code} - -```ts -code: AuthServerConfigWarningCode; -``` - -The code representing the specific validation warning. - -*** - -### description {#description} - -```ts -description: string; -``` - -A human-readable description of the warning. diff --git a/versioned_docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarningCode.md b/versioned_docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarningCode.md deleted file mode 100644 index c5a297d..0000000 --- a/versioned_docs/version-0.1.1/references/js/type-aliases/AuthServerConfigWarningCode.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -sidebar_label: AuthServerConfigWarningCode ---- - -# Type Alias: AuthServerConfigWarningCode - -```ts -type AuthServerConfigWarningCode = "dynamic_registration_not_supported"; -``` - -The codes for warnings that can occur when validating the authorization server metadata. diff --git a/versioned_docs/version-0.1.1/references/js/type-aliases/AuthServerErrorCode.md b/versioned_docs/version-0.1.1/references/js/type-aliases/AuthServerErrorCode.md deleted file mode 100644 index 75701aa..0000000 --- a/versioned_docs/version-0.1.1/references/js/type-aliases/AuthServerErrorCode.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_label: AuthServerErrorCode ---- - -# Type Alias: AuthServerErrorCode - -```ts -type AuthServerErrorCode = - | "invalid_server_metadata" - | "invalid_server_config" - | "missing_jwks_uri"; -``` diff --git a/versioned_docs/version-0.1.1/references/js/type-aliases/AuthServerSuccessCode.md b/versioned_docs/version-0.1.1/references/js/type-aliases/AuthServerSuccessCode.md deleted file mode 100644 index 7bb5610..0000000 --- a/versioned_docs/version-0.1.1/references/js/type-aliases/AuthServerSuccessCode.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -sidebar_label: AuthServerSuccessCode ---- - -# Type Alias: AuthServerSuccessCode - -```ts -type AuthServerSuccessCode = - | "server_metadata_valid" - | "dynamic_registration_supported" - | "pkce_supported" - | "s256_code_challenge_method_supported" - | "authorization_code_grant_supported" - | "code_response_type_supported"; -``` - -The codes for successful validation of the authorization server metadata. diff --git a/versioned_docs/version-0.1.1/references/js/type-aliases/AuthServerType.md b/versioned_docs/version-0.1.1/references/js/type-aliases/AuthServerType.md deleted file mode 100644 index 21fa06b..0000000 --- a/versioned_docs/version-0.1.1/references/js/type-aliases/AuthServerType.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -sidebar_label: AuthServerType ---- - -# Type Alias: AuthServerType - -```ts -type AuthServerType = "oauth" | "oidc"; -``` - -The type of the authorization server. This information should be provided by the server -configuration and indicates whether the server is an OAuth 2.0 or OpenID Connect (OIDC) -authorization server. diff --git a/versioned_docs/version-0.1.1/references/js/type-aliases/AuthorizationServerMetadata.md b/versioned_docs/version-0.1.1/references/js/type-aliases/AuthorizationServerMetadata.md deleted file mode 100644 index 5b7f0a7..0000000 --- a/versioned_docs/version-0.1.1/references/js/type-aliases/AuthorizationServerMetadata.md +++ /dev/null @@ -1,235 +0,0 @@ ---- -sidebar_label: AuthorizationServerMetadata ---- - -# Type Alias: AuthorizationServerMetadata - -```ts -type AuthorizationServerMetadata = { - authorization_endpoint: string; - code_challenge_methods_supported?: string[]; - grant_types_supported?: string[]; - introspection_endpoint?: string; - introspection_endpoint_auth_methods_supported?: string[]; - introspection_endpoint_auth_signing_alg_values_supported?: string[]; - issuer: string; - jwks_uri?: string; - op_policy_uri?: string; - op_tos_uri?: string; - registration_endpoint?: string; - response_modes_supported?: string[]; - response_types_supported: string[]; - revocation_endpoint?: string; - revocation_endpoint_auth_methods_supported?: string[]; - revocation_endpoint_auth_signing_alg_values_supported?: string[]; - scope_supported?: string[]; - service_documentation?: string; - token_endpoint: string; - token_endpoint_auth_methods_supported?: string[]; - token_endpoint_auth_signing_alg_values_supported?: string[]; - ui_locales_supported?: string[]; - userinfo_endpoint?: string; -}; -``` - -Schema for OAuth 2.0 Authorization Server Metadata as defined in RFC 8414. - -## Type declaration {#type-declaration} - -### authorization\_endpoint {#authorization-endpoint} - -```ts -authorization_endpoint: string; -``` - -URL of the authorization server's authorization endpoint [[RFC6749](https://rfc-editor.org/rfc/rfc6749)]. -This is REQUIRED unless no grant types are supported that use the authorization endpoint. - -#### See {#see} - -https://rfc-editor.org/rfc/rfc6749#section-3.1 - -### code\_challenge\_methods\_supported? {#code-challenge-methods-supported} - -```ts -optional code_challenge_methods_supported: string[]; -``` - -JSON array containing a list of Proof Key for Code Exchange (PKCE) -[[RFC7636](https://www.rfc-editor.org/rfc/rfc7636)] code challenge methods supported by this -authorization server. - -### grant\_types\_supported? {#grant-types-supported} - -```ts -optional grant_types_supported: string[]; -``` - -JSON array containing a list of the OAuth 2.0 grant type values that this authorization server -supports. The array values used are the same as those used with the `grant_types` parameter -defined by "OAuth 2.0 Dynamic Client Registration Protocol" [[RFC7591](https://www.rfc-editor.org/rfc/rfc7591)]. -If omitted, the default value is `["authorization_code", "implicit"]`. - -### introspection\_endpoint? {#introspection-endpoint} - -```ts -optional introspection_endpoint: string; -``` - -URL of the authorization server's OAuth 2.0 introspection endpoint -[[RFC7662](https://www.rfc-editor.org/rfc/rfc7662)]. - -### introspection\_endpoint\_auth\_methods\_supported? {#introspection-endpoint-auth-methods-supported} - -```ts -optional introspection_endpoint_auth_methods_supported: string[]; -``` - -### introspection\_endpoint\_auth\_signing\_alg\_values\_supported? {#introspection-endpoint-auth-signing-alg-values-supported} - -```ts -optional introspection_endpoint_auth_signing_alg_values_supported: string[]; -``` - -### issuer {#issuer} - -```ts -issuer: string; -``` - -The authorization server's issuer identifier, which is a URL that uses the `https` scheme and -has no query or fragment components. - -### jwks\_uri? {#jwks-uri} - -```ts -optional jwks_uri: string; -``` - -URL of the authorization server's JWK Set [[JWK](https://www.rfc-editor.org/rfc/rfc8414.html#ref-JWK)] -document. The referenced document contains the signing key(s) the client uses to validate -signatures from the authorization server. This URL MUST use the `https` scheme. - -### op\_policy\_uri? {#op-policy-uri} - -```ts -optional op_policy_uri: string; -``` - -### op\_tos\_uri? {#op-tos-uri} - -```ts -optional op_tos_uri: string; -``` - -### registration\_endpoint? {#registration-endpoint} - -```ts -optional registration_endpoint: string; -``` - -URL of the authorization server's OAuth 2.0 Dynamic Client Registration endpoint -[[RFC7591](https://www.rfc-editor.org/rfc/rfc7591)]. - -### response\_modes\_supported? {#response-modes-supported} - -```ts -optional response_modes_supported: string[]; -``` - -JSON array containing a list of the OAuth 2.0 `response_mode` values that this -authorization server supports, as specified in "OAuth 2.0 Multiple Response -Type Encoding Practices" -[[OAuth.Responses](https://datatracker.ietf.org/doc/html/rfc8414#ref-OAuth.Responses)]. - -If omitted, the default is `["query", "fragment"]`. The response mode value `"form_post"` is -also defined in "OAuth 2.0 Form Post Response Mode" -[[OAuth.FormPost](https://datatracker.ietf.org/doc/html/rfc8414#ref-OAuth.Post)]. - -### response\_types\_supported {#response-types-supported} - -```ts -response_types_supported: string[]; -``` - -JSON array containing a list of the OAuth 2.0 `response_type` values that this authorization -server supports. The array values used are the same as those used with the `response_types` -parameter defined by "OAuth 2.0 Dynamic Client Registration Protocol" -[[RFC7591](https://www.rfc-editor.org/rfc/rfc7591)]. - -### revocation\_endpoint? {#revocation-endpoint} - -```ts -optional revocation_endpoint: string; -``` - -URL of the authorization server's OAuth 2.0 revocation endpoint -[[RFC7009](https://www.rfc-editor.org/rfc/rfc7009)]. - -### revocation\_endpoint\_auth\_methods\_supported? {#revocation-endpoint-auth-methods-supported} - -```ts -optional revocation_endpoint_auth_methods_supported: string[]; -``` - -### revocation\_endpoint\_auth\_signing\_alg\_values\_supported? {#revocation-endpoint-auth-signing-alg-values-supported} - -```ts -optional revocation_endpoint_auth_signing_alg_values_supported: string[]; -``` - -### scope\_supported? {#scope-supported} - -```ts -optional scope_supported: string[]; -``` - -### service\_documentation? {#service-documentation} - -```ts -optional service_documentation: string; -``` - -### token\_endpoint {#token-endpoint} - -```ts -token_endpoint: string; -``` - -URL of the authorization server's token endpoint [[RFC6749](https://rfc-editor.org/rfc/rfc6749)]. -This is REQUIRED unless only the implicit grant type is supported. - -#### See {#see} - -https://rfc-editor.org/rfc/rfc6749#section-3.2 - -### token\_endpoint\_auth\_methods\_supported? {#token-endpoint-auth-methods-supported} - -```ts -optional token_endpoint_auth_methods_supported: string[]; -``` - -### token\_endpoint\_auth\_signing\_alg\_values\_supported? {#token-endpoint-auth-signing-alg-values-supported} - -```ts -optional token_endpoint_auth_signing_alg_values_supported: string[]; -``` - -### ui\_locales\_supported? {#ui-locales-supported} - -```ts -optional ui_locales_supported: string[]; -``` - -### userinfo\_endpoint? {#userinfo-endpoint} - -```ts -optional userinfo_endpoint: string; -``` - -URL of the OpenID Connect [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo). -This endpoint is used to retrieve information about the authenticated user. - -## See {#see} - -https://datatracker.ietf.org/doc/html/rfc8414 diff --git a/versioned_docs/version-0.1.1/references/js/type-aliases/BearerAuthConfig.md b/versioned_docs/version-0.1.1/references/js/type-aliases/BearerAuthConfig.md deleted file mode 100644 index 50652be..0000000 --- a/versioned_docs/version-0.1.1/references/js/type-aliases/BearerAuthConfig.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -sidebar_label: BearerAuthConfig ---- - -# Type Alias: BearerAuthConfig - -```ts -type BearerAuthConfig = { - audience?: string; - issuer: string; - requiredScopes?: string[]; - showErrorDetails?: boolean; - verifyAccessToken: VerifyAccessTokenFunction; -}; -``` - -## Properties {#properties} - -### audience? {#audience} - -```ts -optional audience: string; -``` - -The expected audience of the access token (`aud` claim). This is typically the resource server -(API) that the token is intended for. If not provided, the audience check will be skipped. - -**Note:** If your authorization server does not support Resource Indicators (RFC 8707), -you can omit this field since the audience may not be relevant. - -#### See {#see} - -https://datatracker.ietf.org/doc/html/rfc8707 - -*** - -### issuer {#issuer} - -```ts -issuer: string; -``` - -The expected issuer of the access token (`iss` claim). This should be the URL of the -authorization server that issued the token. - -*** - -### requiredScopes? {#requiredscopes} - -```ts -optional requiredScopes: string[]; -``` - -An array of required scopes that the access token must have. If the token does not contain -all of these scopes, an error will be thrown. - -**Note:** The handler will check the `scope` claim in the token, which may be a space- -separated string or an array of strings, depending on the authorization server's -implementation. If the `scope` claim is not present, the handler will check the `scopes` claim -if available. - -*** - -### showErrorDetails? {#showerrordetails} - -```ts -optional showErrorDetails: boolean; -``` - -Whether to show detailed error information in the response. This is useful for debugging -during development, but should be disabled in production to avoid leaking sensitive -information. - -#### Default {#default} - -```ts -false -``` - -*** - -### verifyAccessToken {#verifyaccesstoken} - -```ts -verifyAccessToken: VerifyAccessTokenFunction; -``` - -Function type for verifying an access token. - -This function should throw an [MCPAuthTokenVerificationError](/references/js/classes/MCPAuthTokenVerificationError.md) if the token is invalid, -or return an AuthInfo object if the token is valid. - -#### See {#see} - -[VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) for more details. diff --git a/versioned_docs/version-0.1.1/references/js/type-aliases/BearerAuthErrorCode.md b/versioned_docs/version-0.1.1/references/js/type-aliases/BearerAuthErrorCode.md deleted file mode 100644 index 5887161..0000000 --- a/versioned_docs/version-0.1.1/references/js/type-aliases/BearerAuthErrorCode.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_label: BearerAuthErrorCode ---- - -# Type Alias: BearerAuthErrorCode - -```ts -type BearerAuthErrorCode = - | "missing_auth_header" - | "invalid_auth_header_format" - | "missing_bearer_token" - | "invalid_issuer" - | "invalid_audience" - | "missing_required_scopes" - | "invalid_token"; -``` diff --git a/versioned_docs/version-0.1.1/references/js/type-aliases/BearerAuthJwtConfig.md b/versioned_docs/version-0.1.1/references/js/type-aliases/BearerAuthJwtConfig.md deleted file mode 100644 index 175bb01..0000000 --- a/versioned_docs/version-0.1.1/references/js/type-aliases/BearerAuthJwtConfig.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -sidebar_label: BearerAuthJwtConfig ---- - -# Type Alias: BearerAuthJwtConfig - -```ts -type BearerAuthJwtConfig = { - jwtVerify?: JWTVerifyOptions; - remoteJwkSet?: RemoteJWKSetOptions; -}; -``` - -Configuration for the Bearer auth handler when using JWT verification. - -## Properties {#properties} - -### jwtVerify? {#jwtverify} - -```ts -optional jwtVerify: JWTVerifyOptions; -``` - -Options to pass to the `jose` library's `jwtVerify` function. - -#### See {#see} - -JWTVerifyOptions for the type definition of the options. - -*** - -### remoteJwkSet? {#remotejwkset} - -```ts -optional remoteJwkSet: RemoteJWKSetOptions; -``` - -Options to pass to the `jose` library's `createRemoteJWKSet` function. - -#### See {#see} - -RemoteJWKSetOptions for the type definition of the options. diff --git a/versioned_docs/version-0.1.1/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md b/versioned_docs/version-0.1.1/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md deleted file mode 100644 index 637138a..0000000 --- a/versioned_docs/version-0.1.1/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -sidebar_label: CamelCaseAuthorizationServerMetadata ---- - -# Type Alias: CamelCaseAuthorizationServerMetadata - -```ts -type CamelCaseAuthorizationServerMetadata = { - authorizationEndpoint: string; - codeChallengeMethodsSupported?: string[]; - grantTypesSupported?: string[]; - introspectionEndpoint?: string; - introspectionEndpointAuthMethodsSupported?: string[]; - introspectionEndpointAuthSigningAlgValuesSupported?: string[]; - issuer: string; - jwksUri?: string; - opPolicyUri?: string; - opTosUri?: string; - registrationEndpoint?: string; - responseModesSupported?: string[]; - responseTypesSupported: string[]; - revocationEndpoint?: string; - revocationEndpointAuthMethodsSupported?: string[]; - revocationEndpointAuthSigningAlgValuesSupported?: string[]; - scopeSupported?: string[]; - serviceDocumentation?: string; - tokenEndpoint: string; - tokenEndpointAuthMethodsSupported?: string[]; - tokenEndpointAuthSigningAlgValuesSupported?: string[]; - uiLocalesSupported?: string[]; - userinfoEndpoint?: string; -}; -``` - -The camelCase version of the OAuth 2.0 Authorization Server Metadata type. - -## Type declaration {#type-declaration} - -### authorizationEndpoint {#authorizationendpoint} - -```ts -authorizationEndpoint: string; -``` - -### codeChallengeMethodsSupported? {#codechallengemethodssupported} - -```ts -optional codeChallengeMethodsSupported: string[]; -``` - -### grantTypesSupported? {#granttypessupported} - -```ts -optional grantTypesSupported: string[]; -``` - -### introspectionEndpoint? {#introspectionendpoint} - -```ts -optional introspectionEndpoint: string; -``` - -### introspectionEndpointAuthMethodsSupported? {#introspectionendpointauthmethodssupported} - -```ts -optional introspectionEndpointAuthMethodsSupported: string[]; -``` - -### introspectionEndpointAuthSigningAlgValuesSupported? {#introspectionendpointauthsigningalgvaluessupported} - -```ts -optional introspectionEndpointAuthSigningAlgValuesSupported: string[]; -``` - -### issuer {#issuer} - -```ts -issuer: string; -``` - -### jwksUri? {#jwksuri} - -```ts -optional jwksUri: string; -``` - -### opPolicyUri? {#oppolicyuri} - -```ts -optional opPolicyUri: string; -``` - -### opTosUri? {#optosuri} - -```ts -optional opTosUri: string; -``` - -### registrationEndpoint? {#registrationendpoint} - -```ts -optional registrationEndpoint: string; -``` - -### responseModesSupported? {#responsemodessupported} - -```ts -optional responseModesSupported: string[]; -``` - -### responseTypesSupported {#responsetypessupported} - -```ts -responseTypesSupported: string[]; -``` - -### revocationEndpoint? {#revocationendpoint} - -```ts -optional revocationEndpoint: string; -``` - -### revocationEndpointAuthMethodsSupported? {#revocationendpointauthmethodssupported} - -```ts -optional revocationEndpointAuthMethodsSupported: string[]; -``` - -### revocationEndpointAuthSigningAlgValuesSupported? {#revocationendpointauthsigningalgvaluessupported} - -```ts -optional revocationEndpointAuthSigningAlgValuesSupported: string[]; -``` - -### scopeSupported? {#scopesupported} - -```ts -optional scopeSupported: string[]; -``` - -### serviceDocumentation? {#servicedocumentation} - -```ts -optional serviceDocumentation: string; -``` - -### tokenEndpoint {#tokenendpoint} - -```ts -tokenEndpoint: string; -``` - -### tokenEndpointAuthMethodsSupported? {#tokenendpointauthmethodssupported} - -```ts -optional tokenEndpointAuthMethodsSupported: string[]; -``` - -### tokenEndpointAuthSigningAlgValuesSupported? {#tokenendpointauthsigningalgvaluessupported} - -```ts -optional tokenEndpointAuthSigningAlgValuesSupported: string[]; -``` - -### uiLocalesSupported? {#uilocalessupported} - -```ts -optional uiLocalesSupported: string[]; -``` - -### userinfoEndpoint? {#userinfoendpoint} - -```ts -optional userinfoEndpoint: string; -``` - -## See {#see} - -[AuthorizationServerMetadata](/references/js/type-aliases/AuthorizationServerMetadata.md) for the original type and field information. diff --git a/versioned_docs/version-0.1.1/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md b/versioned_docs/version-0.1.1/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md deleted file mode 100644 index 9961d48..0000000 --- a/versioned_docs/version-0.1.1/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -sidebar_label: MCPAuthBearerAuthErrorDetails ---- - -# Type Alias: MCPAuthBearerAuthErrorDetails - -```ts -type MCPAuthBearerAuthErrorDetails = { - actual?: unknown; - cause?: unknown; - expected?: unknown; - missingScopes?: string[]; - uri?: URL; -}; -``` - -## Properties {#properties} - -### actual? {#actual} - -```ts -optional actual: unknown; -``` - -*** - -### cause? {#cause} - -```ts -optional cause: unknown; -``` - -*** - -### expected? {#expected} - -```ts -optional expected: unknown; -``` - -*** - -### missingScopes? {#missingscopes} - -```ts -optional missingScopes: string[]; -``` - -*** - -### uri? {#uri} - -```ts -optional uri: URL; -``` diff --git a/versioned_docs/version-0.1.1/references/js/type-aliases/MCPAuthConfig.md b/versioned_docs/version-0.1.1/references/js/type-aliases/MCPAuthConfig.md deleted file mode 100644 index 1d06689..0000000 --- a/versioned_docs/version-0.1.1/references/js/type-aliases/MCPAuthConfig.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -sidebar_label: MCPAuthConfig ---- - -# Type Alias: MCPAuthConfig - -```ts -type MCPAuthConfig = { - server: AuthServerConfig; -}; -``` - -Config for the [MCPAuth](/references/js/classes/MCPAuth.md) class. - -## Properties {#properties} - -### server {#server} - -```ts -server: AuthServerConfig; -``` - -Config for the remote authorization server. diff --git a/versioned_docs/version-0.1.1/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md b/versioned_docs/version-0.1.1/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md deleted file mode 100644 index e3d2754..0000000 --- a/versioned_docs/version-0.1.1/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: MCPAuthTokenVerificationErrorCode ---- - -# Type Alias: MCPAuthTokenVerificationErrorCode - -```ts -type MCPAuthTokenVerificationErrorCode = "invalid_token" | "token_verification_failed"; -``` diff --git a/versioned_docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenFunction.md b/versioned_docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenFunction.md deleted file mode 100644 index 2bb7325..0000000 --- a/versioned_docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenFunction.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -sidebar_label: VerifyAccessTokenFunction ---- - -# Type Alias: VerifyAccessTokenFunction() - -```ts -type VerifyAccessTokenFunction = (token: string) => MaybePromise; -``` - -Function type for verifying an access token. - -This function should throw an [MCPAuthTokenVerificationError](/references/js/classes/MCPAuthTokenVerificationError.md) if the token is invalid, -or return an AuthInfo object if the token is valid. - -For example, if you have a JWT verification function, it should at least check the token's -signature, validate its expiration, and extract the necessary claims to return an `AuthInfo` -object. - -**Note:** There's no need to verify the following fields in the token, as they will be checked -by the handler: - -- `iss` (issuer) -- `aud` (audience) -- `scope` (scopes) - -## Parameters {#parameters} - -### token {#token} - -`string` - -The access token string to verify. - -## Returns {#returns} - -`MaybePromise`\<`AuthInfo`\> - -A promise that resolves to an AuthInfo object or a synchronous value if the -token is valid. diff --git a/versioned_docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenMode.md b/versioned_docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenMode.md deleted file mode 100644 index 74e60ac..0000000 --- a/versioned_docs/version-0.1.1/references/js/type-aliases/VerifyAccessTokenMode.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: VerifyAccessTokenMode ---- - -# Type Alias: VerifyAccessTokenMode - -```ts -type VerifyAccessTokenMode = "jwt"; -``` diff --git a/versioned_docs/version-0.1.1/references/js/variables/authServerErrorDescription.md b/versioned_docs/version-0.1.1/references/js/variables/authServerErrorDescription.md deleted file mode 100644 index b4726e8..0000000 --- a/versioned_docs/version-0.1.1/references/js/variables/authServerErrorDescription.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: authServerErrorDescription ---- - -# Variable: authServerErrorDescription - -```ts -const authServerErrorDescription: Readonly>; -``` diff --git a/versioned_docs/version-0.1.1/references/js/variables/authorizationServerMetadataSchema.md b/versioned_docs/version-0.1.1/references/js/variables/authorizationServerMetadataSchema.md deleted file mode 100644 index 2b10818..0000000 --- a/versioned_docs/version-0.1.1/references/js/variables/authorizationServerMetadataSchema.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: authorizationServerMetadataSchema ---- - -# Variable: authorizationServerMetadataSchema - -```ts -const authorizationServerMetadataSchema: ZodObject; -``` - -Zod schema for OAuth 2.0 Authorization Server Metadata as defined in RFC 8414. - -## See {#see} - -https://datatracker.ietf.org/doc/html/rfc8414 diff --git a/versioned_docs/version-0.1.1/references/js/variables/bearerAuthErrorDescription.md b/versioned_docs/version-0.1.1/references/js/variables/bearerAuthErrorDescription.md deleted file mode 100644 index ed1a931..0000000 --- a/versioned_docs/version-0.1.1/references/js/variables/bearerAuthErrorDescription.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: bearerAuthErrorDescription ---- - -# Variable: bearerAuthErrorDescription - -```ts -const bearerAuthErrorDescription: Readonly>; -``` diff --git a/versioned_docs/version-0.1.1/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md b/versioned_docs/version-0.1.1/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md deleted file mode 100644 index daaa358..0000000 --- a/versioned_docs/version-0.1.1/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: camelCaseAuthorizationServerMetadataSchema ---- - -# Variable: camelCaseAuthorizationServerMetadataSchema - -```ts -const camelCaseAuthorizationServerMetadataSchema: ZodObject; -``` - -The camelCase version of the OAuth 2.0 Authorization Server Metadata Zod schema. - -## See {#see} - -[authorizationServerMetadataSchema](/references/js/variables/authorizationServerMetadataSchema.md) for the original schema and field information. diff --git a/versioned_docs/version-0.1.1/references/js/variables/serverMetadataPaths.md b/versioned_docs/version-0.1.1/references/js/variables/serverMetadataPaths.md deleted file mode 100644 index 68cbf41..0000000 --- a/versioned_docs/version-0.1.1/references/js/variables/serverMetadataPaths.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_label: serverMetadataPaths ---- - -# Variable: serverMetadataPaths - -```ts -const serverMetadataPaths: Readonly<{ - oauth: "/.well-known/oauth-authorization-server"; - oidc: "/.well-known/openid-configuration"; -}>; -``` diff --git a/versioned_docs/version-0.1.1/references/js/variables/tokenVerificationErrorDescription.md b/versioned_docs/version-0.1.1/references/js/variables/tokenVerificationErrorDescription.md deleted file mode 100644 index 3d6e760..0000000 --- a/versioned_docs/version-0.1.1/references/js/variables/tokenVerificationErrorDescription.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: tokenVerificationErrorDescription ---- - -# Variable: tokenVerificationErrorDescription - -```ts -const tokenVerificationErrorDescription: Readonly>; -``` diff --git a/versioned_docs/version-0.1.1/references/js/variables/validateServerConfig.md b/versioned_docs/version-0.1.1/references/js/variables/validateServerConfig.md deleted file mode 100644 index e60de41..0000000 --- a/versioned_docs/version-0.1.1/references/js/variables/validateServerConfig.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_label: validateServerConfig ---- - -# Variable: validateServerConfig - -```ts -const validateServerConfig: ValidateServerConfig; -``` diff --git a/versioned_docs/version-0.1.1/snippets/_get-started-code.mdx b/versioned_docs/version-0.1.1/snippets/_get-started-code.mdx deleted file mode 100644 index 249b02f..0000000 --- a/versioned_docs/version-0.1.1/snippets/_get-started-code.mdx +++ /dev/null @@ -1,41 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - - - - - -```python -mcp = FastMCP("MyMCPServer") -mcp_auth = MCPAuth(server=fetch_server_config('', type=AuthServerType.OIDC)) -app = Starlette( - # ... your MCP server setup - middleware=[Middleware( - mcp_auth.bearer_auth_middleware("jwt", required_scopes=["read", "write"]) - )] -) - -# Use `mcp_auth.auth_info` to access the auth information for the current request -@mcp.tool() -def whoami() -> dict[str, Any]: - return mcp_auth.auth_info.claims -``` - - - - -```ts -const server = new McpServer(/* ... */); -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig('', { type: 'oidc' }), -}); -const app = express(); - -app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] })); -server.tool('whoami', ({ authInfo }) => { - // Use `authInfo` to access the auth information carried from `req.auth` -}); -``` - - - diff --git a/versioned_docs/version-0.1.1/tutorials/_category_.yml b/versioned_docs/version-0.1.1/tutorials/_category_.yml deleted file mode 100644 index fb577fb..0000000 --- a/versioned_docs/version-0.1.1/tutorials/_category_.yml +++ /dev/null @@ -1,5 +0,0 @@ -position: 2 -label: Tutorials -link: - type: generated-index - title: Tutorials diff --git a/versioned_docs/version-0.1.1/tutorials/todo-manager/README.mdx b/versioned_docs/version-0.1.1/tutorials/todo-manager/README.mdx deleted file mode 100644 index bbdf721..0000000 --- a/versioned_docs/version-0.1.1/tutorials/todo-manager/README.mdx +++ /dev/null @@ -1,1279 +0,0 @@ ---- -sidebar_position: 2 -sidebar_label: 'Tutorial: Build a todo manager' ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import SetupOauthOrOidc from './_setup-oauth-or-oidc.mdx'; -import SetupOidc from './_setup-oidc.mdx'; - -# Tutorial: Build a todo manager - -In this tutorial, we will build a todo manager MCP server with user authentication and authorization. - -After completing this tutorial, you will have: - -- ✅ A basic understanding of how to set up role-based access control (RBAC) in your MCP server. -- ✅ A MCP server that can manage personal todo lists. - -:::note -Before you start, we strongly recommend you to go through the [Who am I tutorial](./whoami) first if you are not familiar with MCP server and OAuth 2. -::: - -## Overview \{#overview} - -The tutorial will involve the following components: - -- **MCP server**: A simple MCP server that uses MCP official SDKs to handle requests, with an integrated Todo service for managing user's todo items. -- **MCP inspector**: A visual testing tool for MCP servers. It also acts as an OAuth / OIDC client to initiate the authorization flow and retrieve access tokens. -- **Authorization server**: An OAuth 2.1 or OpenID Connect provider that manages user identities and issues access tokens. - -Here's a high-level diagram of the interaction between these components: - -```mermaid -sequenceDiagram - participant Client as MCP Inspector - participant Server as MCP Server - participant Auth as Authorization Server - - Client->>Server: Request todo operation - Server->>Client: Return 401 Unauthorized - Client->>Auth: Initiate authorization flow - Auth->>Auth: Complete authorization flow - Auth->>Client: Redirect back with authorization code - Client->>Auth: Exchange code for access token - Auth->>Client: Return access token - Client->>Server: Request todo operation with access token - Server->>Server: Validate access token and get user scopes form access token - Note over Server: Execute todo operation - Server->>Client: Return todo operation result -``` - -## Understand your authorization server \{#understand-your-authorization-server} - -### Access tokens with scopes \{#access-tokens-with-scopes} - -To implement [role-based access control (RBAC)](https://auth.wiki/rbac) in your MCP server, your authorization server needs to support issuing access tokens with scopes. Scopes represent the permissions that a user has been granted. - - - - -[Logto](https://logto.io) provides RBAC support through its API resources (conforming [RFC 8707: Resource Indicators for OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)) and roles features. Here's how to set it up: - -1. Sign in to [Logto Console](https://cloud.logto.io) (or your self-hosted Logto Console) - -2. Create API resource and scopes: - - - Go to "API Resources" - - Create a new API resource named "Todo Manager" - - Add the following scopes: - - `create:todos`: "Create new todo items" - - `read:todos`: "Read all todo items" - - `delete:todos`: "Delete any todo item" - -3. Create roles (recommended for easier management): - - - Go to "Roles" - - Create an "Admin" role and assign all scopes (`create:todos`, `read:todos`, `delete:todos`) - - Create a "User" role and assign only the `create:todos` scope - -4. Assign permissions: - - Go to "Users" - - Select a user - - You can either: - - Assign roles in the "Roles" tab (recommended) - - Or directly assign scopes in the "Permissions" tab - -The scopes will be included in the JWT access token's `scope` claim as a space-separated string. - - - - [Asgardeo](https://wso2.com/asgardeo) supports Role-Based Access Control (RBAC) and fine-grained authorization using API resources and scopes. Here's how to configure it: - - 1. Sign in to the [Asgardeo Console](https://console.asgardeo.io) - - 2. Define your API resource and scopes: - - Go to **API Resources** - - Click **"New API Resource"** - - Set the **Identifier** to `https://todo.mcp-server.app` (or your desired URL) - - Let the **Display Name** be `Todo Manager` - - Add the following scopes: - - `create:todos` : "Create new todo items" - - `read:todos` : "Read all todo items" - - `delete:todos` : "Delete any todo item" - - Create the resource - - 3. Create roles: - - Use the **User Management > Roles** to create roles and assign scopes directly. - - Click **New Role** - - Provide the role name (e.g., `Admin` or `User`) in **Basic Details** section - - Let the role audience be `Application` and select the `MCP Inspector Application` as the **Assigned Application** - - In **Permission Selection** section, choose the API resource you created earlier (e.g., `Todo Manager`) - - Select the scopes you want to assign to this role (e.g., `create:todos`, `read:todos`, `delete:todos`) - - Click **Finish** to create the role - - If you have already created the application - - Navigate to **Application > MCP Inspector Application > Roles tab** - - Select **Application Role** as the audience type, then click **New Role** - - Create an `Admin` role and attach all three scopes - - Create a `User` role and attach only the `create:todos` scope - - 4. Assign roles to users: - - Go to **User Management > Roles** - - Select the role you created (e.g., `Admin` or `User`) and move to **Users** tab - - Select **Assign User** and choose the users you want to assign this role to and save. - - The scopes will be included in the JWT access token's `scope` claim as a space-separated string. - - - - -OAuth 2.0 / OIDC providers typically support scope-based access control. When implementing RBAC: - -1. Define your required scopes in your authorization server -2. Configure your client to request these scopes during the authorization flow -3. Ensure your authorization server includes the granted scopes in the access token -4. The scopes are usually included in the JWT access token's `scope` claim - -Check your provider's documentation for specific details on: - -- How to define and manage scopes -- How scopes are included in the access token -- Any additional RBAC features like role management - - - - -### Validating tokens and checking permissions \{#validating-tokens-and-checking-permissions} - -When your MCP server receives a request, it needs to: - -1. Validate the access token's signature and expiration -2. Extract the scopes from the validated token -3. Check if the token has the required scopes for the requested operation - -For example, if a user wants to create a new todo item, their access token must include the `create:todos` scope. Here's how the flow works: - -```mermaid -sequenceDiagram - participant Client - participant MCP Server - participant Auth Server - - Client->>MCP Server: Request with access token - - alt JWT Validation - MCP Server->>Auth Server: Fetch JWKS - Auth Server-->>MCP Server: Return JWKS - MCP Server->>MCP Server: Validate JWT locally - else Token Introspection - MCP Server->>Auth Server: POST /introspect
(token=access_token) - Auth Server-->>MCP Server: Return token info
(active, scope, etc.) - end - - MCP Server->>MCP Server: Extract & check scopes - - alt Has required scopes - MCP Server->>Client: Allow operation - else Missing scopes - MCP Server->>Client: Return 403 Forbidden - end -``` - -### Dynamic Client Registration \{#dynamic-client-registration} - -Dynamic Client Registration is not required for this tutorial, but it can be useful if you want to automate the MCP client registration process with your authorization server. Check [Is Dynamic Client Registration required?](/provider-list#is-dcr-required) for more details. - -## Understand RBAC in todo manager \{#understand-rbac-in-todo-manager} - -For demonstration purposes, we'll implement a simple role-based access control (RBAC) system in our todo manager MCP server. This will show you the basic principles of RBAC while keeping the implementation straightforward. - -:::note -While this tutorial demonstrates RBAC-based scope management, it's important to note that not all authentication providers implement scope management through roles. Some providers may have their own unique implementations and mechanisms for managing access control and permissions. -::: - -### Tools and scopes \{#tools-and-scopes} - -Our todo manager MCP server provides three main tools: - -- `create-todo`: Create a new todo item -- `get-todos`: List all todos -- `delete-todo`: Delete a todo by ID - -To control access to these tools, we define the following scopes: - -- `create:todos`: Allows creating new todo items -- `delete:todos`: Allows deleting existing todo items -- `read:todos`: Allows querying and retrieving the list of all todo items - -### Roles and permissions \{#roles-and-permissions} - -We'll define two roles with different levels of access: - -| Role | create:todos | read:todos | delete:todos | -| ----- | ------------ | ---------- | ------------ | -| Admin | ✅ | ✅ | ✅ | -| User | ✅ | | | - -- **User**: A regular user who can create todo items and view or delete only their own todos -- **Admin**: An administrator who can create, view, and delete all todo items, regardless of ownership - -### Resource ownership \{#resource-ownership} - -While the permission table above shows the explicit scopes assigned to each role, there's an important principle of resource ownership to consider: - -- **Users** don't have the `read:todos` or `delete:todos` scopes, but they can still: - - Read their own todo items - - Delete their own todo items -- **Admins** have full permissions (`read:todos` and `delete:todos`), allowing them to: - - View all todo items in the system - - Delete any todo item, regardless of ownership - -This demonstrates a common pattern in RBAC systems where resource ownership grants implicit permissions to users for their own resources, while administrative roles receive explicit permissions for all resources. - -:::tip Learn More -To dive deeper into RBAC concepts and best practices, check out [Mastering RBAC: A Comprehensive Real-World Example](https://blog.logto.io/mastering-rbac). -::: - -## Configure authorization in your provider \{#configure-authorization-in-your-provider} - -To implement the access control system we described earlier, you'll need to configure your authorization server to support the required scopes. Here's how to do it with different providers: - - - - -[Logto](https://logto.io) provides RBAC support through its API resources and roles features. Here's how to set it up: - -1. Sign in to [Logto Console](https://cloud.logto.io) (or your self-hosted Logto Console) - -2. Create API resource and scopes: - - - Go to "API Resources" - - Create a new API resource named "Todo Manager" and using `https://todo.mcp-server.app` (demo purpose) as the indicator. - - Create the following scopes: - - `create:todos`: "Create new todo items" - - `read:todos`: "Read all todo items" - - `delete:todos`: "Delete any todo item" - -3. Create roles (recommended for easier management): - - - Go to "Roles" - - Create an "Admin" role and assign all scopes (`create:todos`, `read:todos`, `delete:todos`) - - Create a "User" role and assign only the `create:todos` scope - - In the "User" role's details page, switch to the "General" tab, and set the "User" role as the "Default role". - -4. Manage user roles and permissions: - - For new users: - - They will automatically get the "User" role since we set it as the default role - - For existing users: - - Go to "User management" - - Select a user - - Assign roles for the user in the "Roles" tab - -:::tip Programmatic Role Management -You can also use Logto's [Management API](https://docs.logto.io/integrate-logto/interact-with-management-api) to programmatically manage user roles. This is particularly useful for automated user management or when building admin panels. -::: - -When requesting an access token, Logto will include scopes in the token's `scope` claim based on the user's role permissions. - - - - -In [Keycloak](https://www.keycloak.org), you can set up the required permissions using client scopes: - -1. Create client scopes: - - - In your realm, go to "Client scopes" - - Create three new client scopes: - - `create:todos` - - `read:todos` - - `delete:todos` - -2. Configure the client: - - - Go to your client settings - - In the "Client scopes" tab, add all the scopes you created - - Make sure the token mapper is configured to include scopes - -3. Optional: Use roles for easier management - - If you prefer role-based management: - - Create realm roles for different access levels - - Map scopes to roles - - Assign roles to users - - Otherwise, you can directly assign scopes to users or through client-level permissions - -Keycloak will include the granted scopes in the access token's `scope` claim. - - - - -[Asgardeo](https://wso2.com/asgardeo) supports Role-Based Access Control (RBAC) and fine-grained authorization using API resources and scopes. Here's how to configure it: - -1. Sign in to the [Asgardeo Console](https://console.asgardeo.io) - -2. Define your API resource and scopes: - - Go to **API Resources** - - Click **"New API Resource"** - - Set the **Identifier** to `https://todo.mcp-server.app` (or your desired URL) - - Let the **Display Name** be `Todo Manager` - - Add the following scopes: - - `create:todos` : "Create new todo items" - - `read:todos` : "Read all todo items" - - `delete:todos` : "Delete any todo item" - - Create the resource - -3. Create roles: - - Use the **User Management > Roles** to create roles and assign scopes directly. - - Click **New Role** - - Provide the role name (e.g., `Admin` or `User`) in **Basic Details** section - - Let the role audience be `Application` and select the `MCP Inspector Application` as the **Assigned Application** - - In **Permission Selection** section, choose the API resource you created earlier (e.g., `Todo Manager`) - - Select the scopes you want to assign to this role (e.g., `create:todos`, `read:todos`, `delete:todos`) - - Click **Finish** to create the role - - If you have already created the application - - Navigate to **Application > MCP Inspector Application > Roles tab** - - Select **Application Role** as the audience type, then click **New Role** - - Create an `Admin` role and attach all three scopes - - Create a `User` role and attach only the `create:todos` scope - -4. Assign roles to users: - - Go to **User Management > Roles** - - Select the role you created (e.g., `Admin` or `User`) and move to **Users** tab - - Select **Assign User** and choose the users you want to assign this role to and save. - -The scopes will be included in the JWT access token's `scope` claim as a space-separated string. -After configuring your authorization server, users will receive access tokens containing their granted scopes. The MCP server will use these scopes to determine: - -Whether a user can create new todos (`create:todos`) -Whether a user can view all todos (`read:todos`) or only their own -Whether a user can delete any todo (`delete:todos`) or only their own - -For more details on configuring Asgardeo, refer to the following resources: -- [API Resources Guide](https://wso2.com/asgardeo/docs/guides/authorization/api-authorization) -- [Role Management](https://wso2.com/asgardeo/docs/guides/users/manage-roles) - - - -For OAuth 2.0 or OpenID Connect providers, you'll need to configure the scopes that represent different permissions. The exact steps will depend on your provider, but generally: - -1. Define scopes: - - - Configure your authorization server to support: - - `create:todos` - - `read:todos` - - `delete:todos` - -2. Configure client: - - - Register or update your client to request these scopes - - Ensure the scopes are included in the access token - -3. Assign permissions: - - Use your provider's interface to grant appropriate scopes to users - - Some providers may support role-based management, while others might use direct scope assignments - - Check your provider's documentation for the recommended approach - -:::tip -Most providers will include the granted scopes in the access token's `scope` claim. The format is typically a space-separated string of scope values. -::: - - - - -After configuring your authorization server, users will receive access tokens containing their granted scopes. The MCP server will use these scopes to determine: - -- Whether a user can create new todos (`create:todos`) -- Whether a user can view all todos (`read:todos`) or only their own -- Whether a user can delete any todo (`delete:todos`) or only their own - -## Set up the MCP server \{#set-up-the-mcp-server} - -We will use the [MCP official SDKs](https://github.com/modelcontextprotocol) to create our todo manager MCP server. - -### Create a new project \{#create-a-new-project} - - - - -```bash -mkdir mcp-server -cd mcp-server -uv init # Or use `pipenv` or `poetry` to create a new virtual environment -``` - - - - -Set up a new Node.js project: - -```bash -mkdir mcp-server -cd mcp-server -npm init -y # Or use `pnpm init` -npm pkg set type="module" -npm pkg set main="todo-manager.ts" -npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts" -``` - -:::note -We're using TypeScript in our examples as Node.js v22.6.0+ supports running TypeScript natively using the `--experimental-strip-types` flag. If you're using JavaScript, the code will be similar - just ensure you're using Node.js v22.6.0 or later. See Node.js docs for details. -::: - - - - -### Install the MCP SDK and dependencies \{#install-the-mcp-sdk-and-dependencies} - - - - -```bash -pip install "mcp[cli]" starlette uvicorn -``` - -Or any other package manager you prefer, such as `uv` or `poetry`. - - - - -```bash -npm install @modelcontextprotocol/sdk express zod -``` - -Or any other package manager you prefer, such as `pnpm` or `yarn`. - - - - -### Create the MCP server \{#create-the-mcp-server} - -First, let's create a basic MCP server with the tool definitions: - - - - -Create a file named `todo-manager.py` and add the following code: - -```python -from typing import Any -from mcp.server.fastmcp import FastMCP -from starlette.applications import Starlette -from starlette.routing import Mount - -mcp = FastMCP("Todo Manager") - -@mcp.tool() -def create_todo(content: str) -> dict[str, Any]: - """Create a new todo.""" - return {"error": "Not implemented"} - -@mcp.tool() -def get_todos() -> dict[str, Any]: - """List all todos.""" - return {"error": "Not implemented"} - -@mcp.tool() -def delete_todo(id: str) -> dict[str, Any]: - """Delete a todo by id.""" - return {"error": "Not implemented"} - -app = Starlette( - routes=[Mount('/', app=mcp.sse_app())] -) -``` - -Run the server with: - -```bash -uvicorn todo_manager:app --host 0.0.0.0 --port 3001 -``` - - - - -:::note -Since the current MCP inspector implementation does not handle authorization flows, we will use the SSE approach to set up the MCP server. We'll update the code here once the MCP inspector supports authorization flows. -::: - -You can also use `pnpm` or `yarn` if you prefer. - -Create a file named `todo-manager.ts` and add the following code: - -```ts -// todo-manager.ts - -import { z } from 'zod'; -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; -import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'; -import express from 'express'; - -// Create an MCP server -const server = new McpServer({ - name: 'Todo Manager', - version: '0.0.0', -}); - -server.tool('create-todo', 'Create a new todo', { content: z.string() }, async ({ content }) => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }], - }; -}); - -server.tool('get-todos', 'List all todos', async () => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }], - }; -}); - -server.tool('delete-todo', 'Delete a todo by id', { id: z.string() }, async ({ id }) => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }], - }; -}); - -// Below is the boilerplate code from MCP SDK documentation -const PORT = 3001; -const app = express(); - -const transports = {}; - -app.get('/sse', async (_req, res) => { - const transport = new SSEServerTransport('/messages', res); - transports[transport.sessionId] = transport; - - res.on('close', () => { - delete transports[transport.sessionId]; - }); - - await server.connect(transport); -}); - -app.post('/messages', async (req, res) => { - const sessionId = String(req.query.sessionId); - const transport = transports[sessionId]; - if (transport) { - await transport.handlePostMessage(req, res, req.body); - } else { - res.status(400).send('No transport found for sessionId'); - } -}); - -app.listen(PORT); -``` - -Run the server with: - -```bash -npm start -``` - - - - -## Inspect the MCP server \{#inspect-the-mcp-server} - -### Clone and run MCP inspector \{#clone-and-run-mcp-inspector} - -Now that we have the MCP server running, we can use the MCP inspector to see if the `whoami` tool is available. - -Due to the limit of the current implementation, we've forked the [MCP inspector](https://github.com/mcp-auth/inspector) to make it more flexible and scalable for authentication and authorization. We've also submitted a pull request to the original repository to include our changes. - -To run the MCP inspector, you can use the following command (Node.js is required): - -```bash -git clone https://github.com/mcp-auth/inspector.git -cd inspector -npm install -npm run dev -``` - -Then, open your browser and navigate to `http://localhost:6274/` (or other URL shown in the terminal) to access the MCP inspector. - -### Connect MCP inspector to the MCP server \{#connect-mcp-inspector-to-the-mcp-server} - -Before we proceed, check the following configuration in MCP inspector: - -- **Transport Type**: Set to `SSE`. -- **URL**: Set to the URL of your MCP server. In our case, it should be `http://localhost:3001/sse`. - -Now you can click the "Connect" button to see if the MCP inspector can connect to the MCP server. If everything is okay, you should see the "Connected" status in the MCP inspector. - -### Checkpoint: Run todo manager tools \{#checkpoint-run-todo-manager-tools} - -1. In the top menu of the MCP inspector, click on the "Tools" tab. -2. Click on the "List Tools" button. -3. You should see the `create-todo`, `get-todos`, and `delete-todo` tools listed on the page. Click on it to open the tool details. -4. You should see the "Run Tool" button in the right side. Click on it and enter required parameters to run the tool. -5. You should see the tool result with the JSON response `{"error": "Not implemented"}`. - -![MCP inspector first run](/docs-assets/images/tutorials/todo-manager/inspector-first-run.png) - -## Integrate with your authorization server \{#integrate-with-your-authorization-server} - -To complete this section, there are several considerations to take into account: - -
-**The issuer URL of your authorization server** - -This is usually the base URL of your authorization server, such as `https://auth.example.com`. Some providers may have a path like `https://example.logto.app/oidc`, so make sure to check your provider's documentation. - -
- -
-**How to retrieve the authorization server metadata** - -- If your authorization server conforms to the [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) or [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html), you can use the MCP Auth built-in utilities to fetch the metadata automatically. -- If your authorization server does not conform to these standards, you will need to manually specify the metadata URL or endpoints in the MCP server configuration. Check your provider's documentation for the specific endpoints. - -
- -
-**How to register the MCP inspector as a client in your authorization server** - -- If your authorization server supports [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591), you can skip this step as the MCP inspector will automatically register itself as a client. -- If your authorization server does not support Dynamic Client Registration, you will need to manually register the MCP inspector as a client in your authorization server. - -
- -
-**Understand token request parameters** - -When requesting access tokens from different authorization servers, you'll encounter various approaches for specifying the target resource and permissions. Here are the main patterns: - -- **Resource indicator based**: - - - Uses the `resource` parameter to specify the target API (see [RFC 8707: Resource Indicators for OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc8707)) - - Common in modern OAuth 2.0 implementations - - Example request: - ```json - { - "resource": "https://todo.mcp-server.app", - "scope": "create:todos read:todos" - } - ``` - - The server issues tokens specifically bound to the requested resource - -- **Audience based**: - - - Uses the `audience` parameter to specify the intended token recipient - - Similar to resource indicators but with different semantics - - Example request: - ```json - { - "audience": "todo-api", - "scope": "create:todos read:todos" - } - ``` - -- **Pure scope based**: - - Relies solely on scopes without resource/audience parameters - - Traditional OAuth 2.0 approach - - Example request: - ```json - { - "scope": "todo-api:create todo-api:read openid profile" - } - ``` - - Often uses prefixed scopes to namespace permissions - - Common in simpler OAuth 2.0 implementations - -:::tip Best Practices - -- Check your provider's documentation for supported parameters -- Some providers support multiple approaches simultaneously -- Resource indicators provide better security through audience restriction -- Consider using resource indicators when available for better access control - ::: - -
- -While each provider may have its own specific requirements, the following steps will guide you through the process of integrating the MCP inspector and MCP server with provider-specific configurations. - -### Register MCP inspector as a client \{#register-mcp-inspector-as-a-client} - - - - -Integrating the todo manager with [Logto](https://logto.io) is straightforward as it's an OpenID Connect provider that supports resource indicators and scopes, allowing you to secure your todo API with `https://todo.mcp-server.app` as the resource indicator. - -Since Logto does not support Dynamic Client Registration yet, you will need to manually register the MCP inspector as a client in your Logto tenant: - -1. Open your MCP inspector, click on the "OAuth Configuration" button. Copy the **Redirect URL (auto-populated)** value, which should be something like `http://localhost:6274/oauth/callback`. -2. Sign in to [Logto Console](https://cloud.logto.io) (or your self-hosted Logto Console). -3. Navigate to the "Applications" tab, click on "Create application". In the bottom of the page, click on "Create app without framework". -4. Fill in the application details, then click on "Create application": - - **Select an application type**: Choose "Single-page application". - - **Application name**: Enter a name for your application, e.g., "MCP Inspector". -5. In the "Settings / Redirect URIs" section, paste the **Redirect URL (auto-populated)** value you copied from the MCP inspector. Then click on "Save changes" in the bottom bar. -6. In the top card, you will see the "App ID" value. Copy it. -7. Go back to the MCP inspector and paste the "App ID" value in the "OAuth Configuration" section under "Client ID". -8. Enter the value `{"scope": "create:todos read:todos delete:todos", "resource": "https://todo.mcp-server.app"}` in the "Auth Params" field. This will ensure that the access token returned by Logto contains the necessary scopes to access the todo manager. - - - - - While Asgardeo supports dynamic client registration via a standard API, the endpoint is protected and requires an access token with the necessary permissions. In this tutorial, we’ll register the client manually through the Asgardeo Console. - - :::note - If you don’t have an Asgardeo account, you can [sign up for free](https://asgardeo.io). - ::: - - Follow these steps to configure Asgardeo for MCP Inspector: - - 1. Log in to the [Asgardeo Console](https://console.asgardeo.io) and select your organization. - - 2. Create a new application: - - Go to **Applications** → **New Application** - - Choose **Single-Page Application** - - Enter an application name like `MCP Inspector` - - In the **Authorized Redirect URLs** field, paste the **Redirect URL** copied from MCP Inspector client application (e.g.: `http://localhost:6274/oauth/callback`) - - Click **Create** - - 3. Configure the protocol settings: - - Under the **Protocol** tab: - - Copy the **Client ID** that was auto generated. - - Ensure switching to `JWT` for the `Token Type` in **Access Token** section - - Click **Update** - - 4. In MCP Inspector client application: - - Open the **OAuth Configuration** section - - Paste the copied **Client ID** - - Enter the following in the **Auth Params** field to request the necessary scopes: - - ```json - { "scope": "openid profile email" } - ``` - - - -:::note -This is a generic OAuth 2.0 / OpenID Connect provider integration guide. Both OAuth 2.0 and OIDC follow similar steps as OIDC is built on top of OAuth 2.0. Check your provider's documentation for specific details. -::: - -If your provider supports Dynamic Client Registration, you can directly go to step 8 below to configure the MCP inspector; otherwise, you will need to manually register the MCP inspector as a client: - -1. Open your MCP inspector, click on the "OAuth Configuration" button. Copy the **Redirect URL (auto-populated)** value, which should be something like `http://localhost:6274/oauth/callback`. - -2. Sign in to your provider's console. - -3. Navigate to the "Applications" or "Clients" section, then create a new application or client. - -4. If your provider requires a client type, select "Single-page application" or "Public client". - -5. After creating the application, you will need to configure the redirect URI. Paste the **Redirect URL (auto-populated)** value you copied from the MCP inspector. - -6. Find the "Client ID" or "Application ID" of the newly created application and copy it. - -7. Go back to the MCP inspector and paste the "Client ID" value in the "OAuth Configuration" section under "Client ID". - -8. Enter the following value in the "Auth Params" field to request the necessary scopes for todo operations: - -```json -{ "scope": "create:todos read:todos delete:todos" } -``` - - - - -### Set up MCP auth \{#set-up-mcp-auth} - -In your MCP server project, you need to install the MCP Auth SDK and configure it to use your authorization server metadata. - - - - -First, install the `mcpauth` package: - -```bash -pip install mcpauth -``` - -Or any other package manager you prefer, such as `uv` or `poetry`. - - - - -First, install the `mcp-auth` package: - -```bash -npm install mcp-auth -``` - - - - -MCP Auth requires the authorization server metadata to be able to initialize. Depending on your provider: - - - - - -The issuer URL can be found in your application details page in Logto Console, in the "Endpoints & Credentials / Issuer endpoint" section. It should look like `https://my-project.logto.app/oidc`. - - - - - - - - You can find the issuer URL in the Asgardeo Console. Navigate to the created application, and open the **Info** tab. The **Issuer** field will be displayed there and should look like: - `https://api.asgardeo.io/t//oauth2/token` - - - - - - - -For OAuth 2.0 providers, you'll need to: - -1. Check your provider's documentation for the authorization server URL (often called issuer URL or base URL) -2. Some providers may expose this at `https://{your-domain}/.well-known/oauth-authorization-server` -3. Look in your provider's admin console under OAuth/API settings - - - - - - - - - - - -Update the `todo-manager.py` to include the MCP Auth configuration: - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # Replace with your issuer endpoint -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -Update the `todo-manager.ts` to include the MCP Auth configuration: - -```ts -// todo-manager.ts - -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // Replace with your issuer endpoint -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oidc' }), -}); -``` - - - - -### Update MCP server \{#update-mcp-server} - -We are almost done! It's time to update the MCP server to apply the MCP Auth route and middleware function, then implement the permission-based access control for the todo manager tools based on the user's scopes. - - - - -```python -@mcp.tool() -def create_todo(content: str) -> dict[str, Any]: - """Create a new todo.""" - return ( - mcp_auth.auth_info.scopes - if mcp_auth.auth_info # This will be populated by the Bearer auth middleware - else {"error": "Not authenticated"} - ) - -# ... - -bearer_auth = Middleware(mcp_auth.bearer_auth_middleware("jwt")) -app = Starlette( - routes=[ - # Add the metadata route (`/.well-known/oauth-authorization-server`) - mcp_auth.metadata_route(), - # Protect the MCP server with the Bearer auth middleware - Mount('/', app=mcp.sse_app(), middleware=[bearer_auth]), - ], -) -``` - - - - -```js -server.tool( - 'create-todo', - 'Create a new todo', - { content: z.string() }, - async ({ content, authInfo }) => { - return { - content: [ - { type: 'text', text: JSON.stringify(authInfo?.scopes ?? { error: 'Not authenticated' }) }, - ], - }; - } -); - -// ... - -app.use(mcpAuth.delegatedRouter()); -app.use(mcpAuth.bearerAuth('jwt')); -``` - - - - -Next, let's implement the specific tools. - -First, let's create a simple todo service to provide basic CRUD operations for managing todo items in memory. - - - -```python -# service.py - -""" -A simple Todo service for demonstration purposes. -Uses an in-memory list to store todos. -""" - -from datetime import datetime -from typing import List, Optional, Dict, Any -import random -import string - -class Todo: -"""Represents a todo item.""" - - def __init__(self, id: str, content: str, owner_id: str, created_at: str): - self.id = id - self.content = content - self.owner_id = owner_id - self.created_at = created_at - - def to_dict(self) -> Dict[str, Any]: - """Convert todo to dictionary for JSON serialization.""" - return { - "id": self.id, - "content": self.content, - "ownerId": self.owner_id, - "createdAt": self.created_at - } - -class TodoService: -"""A simple Todo service for demonstration purposes.""" - - def __init__(self): - self._todos: List[Todo] = [] - - def get_all_todos(self, owner_id: Optional[str] = None) -> List[Dict[str, Any]]: - """ - Get all todos, optionally filtered by owner_id. - - Args: - owner_id: If provided, only return todos owned by this user - - Returns: - List of todo dictionaries - """ - if owner_id: - filtered_todos = [todo for todo in self._todos if todo.owner_id == owner_id] - return [todo.to_dict() for todo in filtered_todos] - return [todo.to_dict() for todo in self._todos] - - def get_todo_by_id(self, todo_id: str) -> Optional[Todo]: - """ - Get a todo by its ID. - - Args: - todo_id: The ID of the todo to retrieve - - Returns: - Todo object if found, None otherwise - """ - for todo in self._todos: - if todo.id == todo_id: - return todo - return None - - def create_todo(self, content: str, owner_id: str) -> Dict[str, Any]: - """ - Create a new todo. - - Args: - content: The content of the todo - owner_id: The ID of the user who owns this todo - - Returns: - Dictionary representation of the created todo - """ - todo = Todo( - id=self._generate_id(), - content=content, - owner_id=owner_id, - created_at=datetime.now().isoformat() - ) - self._todos.append(todo) - return todo.to_dict() - - def delete_todo(self, todo_id: str) -> Optional[Dict[str, Any]]: - """ - Delete a todo by its ID. - - Args: - todo_id: The ID of the todo to delete - - Returns: - Dictionary representation of the deleted todo if found, None otherwise - """ - for i, todo in enumerate(self._todos): - if todo.id == todo_id: - deleted_todo = self._todos.pop(i) - return deleted_todo.to_dict() - return None - - def _generate_id(self) -> str: - """Generate a random ID for a todo.""" - return ''.join(random.choices(string.ascii_lowercase + string.digits, k=8)) - -```` - - - - - -```ts -// todo-service.ts - -type Todo = { - id: string; - content: string; - ownerId: string; - createdAt: string; -}; - -/** - * A simple Todo service for demonstration purposes. - * Use an in-memory array to store todos - */ -export class TodoService { - private readonly todos: Todo[] = []; - - getAllTodos(ownerId?: string): Todo[] { - if (ownerId) { - return this.todos.filter((todo) => todo.ownerId === ownerId); - } - return this.todos; - } - - getTodoById(id: string): Todo | undefined { - return this.todos.find((todo) => todo.id === id); - } - - createTodo({ content, ownerId }: { content: string; ownerId: string }): Todo { - const todo: Todo = { - id: this.genId(), - content, - ownerId, - createdAt: new Date().toISOString(), - }; - - // eslint-disable-next-line @silverhand/fp/no-mutating-methods - this.todos.push(todo); - return todo; - } - - deleteTodo(id: string): Todo | undefined { - const index = this.todos.findIndex((todo) => todo.id === id); - - if (index === -1) { - return undefined; - } - - // eslint-disable-next-line @silverhand/fp/no-mutating-methods - const [deleted] = this.todos.splice(index, 1); - return deleted; - } - - private genId(): string { - return Math.random().toString(36).slice(2, 10); - } -} -```` - - - - -then in the tools layer, we'll determine whether operations are allowed based on the user's scopes: - - - - -```python -# todo-manager.py - -from typing import Any, Optional -from mcpauth.errors import MCPAuthBearerAuthError - -def assert_user_id(auth_info: Optional[dict]) -> str: - """Extract and validate user ID from auth info.""" - subject = auth_info.get('subject') if auth_info else None - if not subject: - raise ValueError('Invalid auth info') - return subject - -def has_required_scopes(user_scopes: list[str], required_scopes: list[str]) -> bool: - """Check if user has all required scopes.""" - return all(scope in user_scopes for scope in required_scopes) - -# Create an instance of TodoService -todo_service = TodoService() - -@mcp.tool() -def create_todo(content: str) -> dict[str, Any]: - """Create a new todo. - - Only users with 'create:todos' scope can create todos. - """ - # Get authentication info - auth_info = mcp_auth.auth_info - - # Validate user ID - try: - user_id = assert_user_id(auth_info) - except ValueError as e: - return {"error": str(e)} - - # Check if user has the required permissions - if not has_required_scopes(auth_info.scopes if auth_info else [], ['create:todos']): - raise MCPAuthBearerAuthError('missing_required_scopes') - - # Create new todo - created_todo = todo_service.create_todo(content=content, owner_id=user_id) - - # Return the created todo - return created_todo.__dict__ - -# ... -``` - -You can check our [sample code](https://github.com/mcp-auth/python/tree/master/samples/server) for all other detailed implementations. - - - - -```ts -// todo-manager.ts - -// ... other imports -import assert from 'node:assert'; -import { type AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js'; -import { TodoService } from './todo-service.js'; - -const todoService = new TodoService(); - -const assertUserId = (authInfo?: AuthInfo) => { - const { subject } = authInfo ?? {}; - assert(subject, 'Invalid auth info'); - return subject; -}; - -/** - * Check if user has all the required scopes for an operation - */ -const hasRequiredScopes = (userScopes: string[], requiredScopes: string[]): boolean => { - return requiredScopes.every((scope) => userScopes.includes(scope)); -}; - -server.tool( - 'create-todo', - 'Create a new todo', - { content: z.string() }, - ({ content }: { content: string }, { authInfo }) => { - const userId = assertUserId(authInfo); - - /** - * Only users with 'create:todos' scope can create todos - */ - if (!hasRequiredScopes(authInfo?.scopes ?? [], ['create:todos'])) { - throw new MCPAuthBearerAuthError('missing_required_scopes'); - } - - const createdTodo = todoService.createTodo({ content, ownerId: userId }); - - return { - content: [{ type: 'text', text: JSON.stringify(createdTodo) }], - }; - } -); - -// ... -``` - -You can check our [sample code](https://github.com/mcp-auth/js/tree/master/packages/sample-servers/src/todo-manager) for all other detailed implementations. - - - - -## Checkpoint: Run the `todo-manager` tools \{#checkpoint-run-the-todo-manager-tools} - -Restart your MCP server and open the MCP inspector in your browser. When you click the "Connect" button, you should be redirected to your authorization server's sign-in page. - -Once you sign in and back to the MCP inspector, repeat the actions we did in the previous checkpoint to run todo manager tools. This time, you can use these tools with your authenticated user identity. The behavior of the tools will depend on the roles and permissions assigned to your user: - -- If you're logged in as a **User** (with only `create:todos` scope): - - - You can create new todos using the `create-todo` tool - - You can only view and delete your own todos - - You won't be able to see or delete other users' todos - -- If you're logged in as an **Admin** (with all scopes: `create:todos`, `read:todos`, `delete:todos`): - - You can create new todos - - You can view all todos in the system using the `get-todos` tool - - You can delete any todo using the `delete-todo` tool, regardless of who created it - -You can test these different permission levels by: - -1. Signing out of the current session (click the "Disconnect" button in MCP inspector) -2. Signing in with a different user account that has different roles/permissions -3. Trying the same tools again to observe how the behavior changes based on the user's permissions - -This demonstrates how role-based access control (RBAC) works in practice, where different users have different levels of access to the system's functionality. - -![MCP inspector todo manager tool result](/docs-assets/images/tutorials/todo-manager/result.png) - - - - -:::info -Check out the [MCP Auth Python SDK repository](https://github.com/mcp-auth/python/blob/master/samples/server/todo-manager/server.py) for the complete code of the MCP server (OIDC version). -::: - - - - -:::info -Check out the [MCP Auth Node.js SDK repository](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) for the complete code of the MCP server (OIDC version). -::: - - - - -## Closing notes \{#closing-notes} - -🎊 Congratulations! You have successfully completed the tutorial. Let's recap what we've done: - -- Setting up a basic MCP server with todo management tools (`create-todo`, `get-todos`, `delete-todo`) -- Implementing role-based access control (RBAC) with different permission levels for users and admins -- Integrating the MCP server with an authorization server using MCP Auth -- Configuring the MCP Inspector to authenticate users and use access tokens with scopes to call tools - -Be sure to check out other tutorials and documentation to make the most of MCP Auth. diff --git a/versioned_docs/version-0.1.1/tutorials/todo-manager/_manual-metadata-fetching.mdx b/versioned_docs/version-0.1.1/tutorials/todo-manager/_manual-metadata-fetching.mdx deleted file mode 100644 index 78bfbcb..0000000 --- a/versioned_docs/version-0.1.1/tutorials/todo-manager/_manual-metadata-fetching.mdx +++ /dev/null @@ -1,3 +0,0 @@ -:::note -If your provider does not support {props.oidc ? 'OpenID Connect Discovery' : 'OAuth 2.0 Authorization Server Metadata'}, you can manually specify the metadata URL or endpoints. Check [Other ways to initialize MCP Auth](../../configure-server/mcp-auth.mdx#other-ways) for more details. -::: diff --git a/versioned_docs/version-0.1.1/tutorials/todo-manager/_setup-oauth-or-oidc.mdx b/versioned_docs/version-0.1.1/tutorials/todo-manager/_setup-oauth-or-oidc.mdx deleted file mode 100644 index a648043..0000000 --- a/versioned_docs/version-0.1.1/tutorials/todo-manager/_setup-oauth-or-oidc.mdx +++ /dev/null @@ -1,41 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -Update the `todo-manager.py` to include the MCP Auth configuration: - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # Replace with your issuer endpoint -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OAUTH) # or AuthServerType.OIDC -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -Update the `todo-manager.ts` to include the MCP Auth configuration: - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // Replace with your issuer endpoint -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oauth' }), // or { type: 'oidc' } -}); -``` - - - - - - diff --git a/versioned_docs/version-0.1.1/tutorials/todo-manager/_setup-oidc.mdx b/versioned_docs/version-0.1.1/tutorials/todo-manager/_setup-oidc.mdx deleted file mode 100644 index f0ccb7d..0000000 --- a/versioned_docs/version-0.1.1/tutorials/todo-manager/_setup-oidc.mdx +++ /dev/null @@ -1,41 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -Update the `todo-manager.py` to include the MCP Auth configuration: - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # Replace with your issuer endpoint -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -Update the `todo-manager.ts` to include the MCP Auth configuration: - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // Replace with your issuer endpoint -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oidc' }), -}); -``` - - - - -{props.showAlternative && } -{props.showAlternative && } diff --git a/versioned_docs/version-0.1.1/tutorials/todo-manager/_transpile-metadata.mdx b/versioned_docs/version-0.1.1/tutorials/todo-manager/_transpile-metadata.mdx deleted file mode 100644 index d13ff01..0000000 --- a/versioned_docs/version-0.1.1/tutorials/todo-manager/_transpile-metadata.mdx +++ /dev/null @@ -1,31 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -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: - - - - -```python -mcp_auth = MCPAuth( - server=fetch_server_config( - # ...other options - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { - // ...other options - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - diff --git a/versioned_docs/version-0.1.1/tutorials/todo-manager/assets/inspector-first-run.png b/versioned_docs/version-0.1.1/tutorials/todo-manager/assets/inspector-first-run.png deleted file mode 100644 index 4a72d83..0000000 Binary files a/versioned_docs/version-0.1.1/tutorials/todo-manager/assets/inspector-first-run.png and /dev/null differ diff --git a/versioned_docs/version-0.1.1/tutorials/todo-manager/assets/result.png b/versioned_docs/version-0.1.1/tutorials/todo-manager/assets/result.png deleted file mode 100644 index 5c29786..0000000 Binary files a/versioned_docs/version-0.1.1/tutorials/todo-manager/assets/result.png and /dev/null differ diff --git a/versioned_docs/version-0.1.1/tutorials/whoami/README.mdx b/versioned_docs/version-0.1.1/tutorials/whoami/README.mdx deleted file mode 100644 index f2445df..0000000 --- a/versioned_docs/version-0.1.1/tutorials/whoami/README.mdx +++ /dev/null @@ -1,665 +0,0 @@ ---- -sidebar_position: 1 -sidebar_label: 'Tutorial: Who am I?' ---- - -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import SetupOauth from './_setup-oauth.mdx'; -import SetupOidc from './_setup-oidc.mdx'; - -# Tutorial: Who am I? - -This tutorial will guide you through the process of setting up MCP Auth to authenticate users and retrieve their identity information from the authorization server. - -After completing this tutorial, you will have: - -- ✅ A basic understanding of how to use MCP Auth to authenticate users. -- ✅ A MCP server that offers a tool to retrieve user identity information. - -## Overview \{#overview} - -The tutorial will involve the following components: - -- **MCP server**: A simple MCP server that uses MCP official SDKs to handle requests. -- **MCP inspector**: A visual testing tool for MCP servers. It also acts as an OAuth / OIDC client to initiate the authorization flow and retrieve access tokens. -- **Authorization server**: An OAuth 2.1 or OpenID Connect provider that manages user identities and issues access tokens. - -Here's a high-level diagram of the interaction between these components: - -```mermaid -sequenceDiagram - participant Client as MCP Inspector - participant Server as MCP Server - participant Auth as Authorization Server - - Client->>Server: Request tool `whoami` - Server->>Client: Return 401 Unauthorized - Client->>Auth: Initiate authorization flow - Auth->>Auth: Complete authorization flow - Auth->>Client: Redirect back with authorization code - Client->>Auth: Exchange code for access token - Auth->>Client: Return access token - Client->>Server: Request `whoami` with access token - Server->>Auth: Fetch user identity with access token - Auth->>Server: Return user identity - Server->>Client: Return user identity -``` - -## Understand your authorization server \{#understand-your-authorization-server} - -### Retrieving user identity information \{#retrieving-user-identity-information} - -To complete this tutorial, your authorization server should offer an API to retrieve user identity information: - - - - -[Logto](https://logto.io) is an OpenID Connect provider that supports the standard [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) to retrieve user identity information. - -To fetch an access token that can be used to access the userinfo endpoint, at least two scopes are required: `openid` and `profile`. You can continue reading as we'll cover the scope configuration later. - - - - -[Keycloak](https://www.keycloak.org) is an open-source identity and access management solution that supports multiple protocols, including OpenID Connect (OIDC). As an OIDC provider, it implements the standard [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) to retrieve user identity information. - -To fetch an access token that can be used to access the userinfo endpoint, at least two scopes are required: `openid` and `profile`. You can continue reading as we'll cover the scope configuration later. - - - - - -[Asgardeo](https://wso2.com/asgardeo) is a cloud-native identity as a service (IDaaS) platform that supports OAuth 2.0 and OpenID Connect (OIDC), providing robust identity and access management for modern applications. - -User information is encoded inside the ID token returned along with the access token. But as an OIDC provider, Asgardeo exposes a [UserInfo endpoint](https://wso2.com/asgardeo/docs/guides/authentication/oidc/request-user-info/) that allows applications to retrieve claims about the authenticated user in the payload. - -You can also discover this endpoint dynamically via the [OIDC discovery endpoint](https://wso2.com/asgardeo/docs/guides/authentication/oidc/discover-oidc-configs) or by navigating to the application's 'Info' tab in the Asgardeo Console. - -To fetch an access token that can be used to access the userinfo endpoint, at least two scopes are required: `openid` and `profile`. - - - -Most OpenID Connect providers support the [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) to retrieve user identity information. - -Check your provider's documentation to see if it supports this endpoint. If your provider supports [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html), you can also check if the `userinfo_endpoint` is included in the discovery document (response from the `.well-known/openid-configuration` endpoint). - -To fetch an access token that can be used to access the userinfo endpoint, at least two scopes are required: `openid` and `profile`. Check your provider's documentation to see the mapping of scopes to user identity claims. - - - - -While OAuth 2.0 does not define a standard way to retrieve user identity information, many providers implement their own endpoints to do so. Check your provider's documentation to see how to retrieve user identity information using an access token and what parameters are required to fetch such access token when invoking the authorization flow. - - - - -### Dynamic Client Registration \{#dynamic-client-registration} - -Dynamic Client Registration is not required for this tutorial, but it can be useful if you want to automate the MCP client registration process with your authorization server. Check [Is Dynamic Client Registration required?](/provider-list#is-dcr-required) for more details. - -## Set up the MCP server \{#set-up-the-mcp-server} - -We will use the [MCP official SDKs](https://github.com/modelcontextprotocol) to create a MCP server with a `whoami` tool that retrieves user identity information from the authorization server. - -### Create a new project \{#create-a-new-project} - - - - -```bash -mkdir mcp-server -cd mcp-server -uv init # Or use `pipenv` or `poetry` to create a new virtual environment -``` - - - - -Set up a new Node.js project: - -```bash -mkdir mcp-server -cd mcp-server -npm init -y # Or use `pnpm init` -npm pkg set type="module" -npm pkg set main="whoami.js" -npm pkg set scripts.start="node whoami.js" -``` - - - - -### Install the MCP SDK and dependencies \{#install-the-mcp-sdk-and-dependencies} - - - - -```bash -pip install "mcp[cli]" starlette uvicorn -``` - -Or any other package manager you prefer, such as `uv` or `poetry`. - - - - -```bash -npm install @modelcontextprotocol/sdk express -``` - -Or any other package manager you prefer, such as `pnpm` or `yarn`. - - - - -### Create the MCP server \{#create-the-mcp-server} - -First, let's create an MCP server that implements a `whoami` tool. - - - - -Create a file named `whoami.py` and add the following code: - -```python -from mcp.server.fastmcp import FastMCP -from starlette.applications import Starlette -from starlette.routing import Mount -from typing import Any - -mcp = FastMCP("WhoAmI") - -@mcp.tool() -def whoami() -> dict[str, Any]: - """A tool that returns the current user's information.""" - return {"error": "Not authenticated"} - -app = Starlette( - routes=[Mount('/', app=mcp.sse_app())] -) -``` - -Run the server with: - -```bash -uvicorn whoami:app --host 0.0.0.0 --port 3001 -``` - - - - -:::note -Since the current MCP inspector implementation does not handle authorization flows, we will use the SSE approach to set up the MCP server. We'll update the code here once the MCP inspector supports authorization flows. -::: - -You can also use `pnpm` or `yarn` if you prefer. - -Create a file named `whoami.js` and add the following code: - -```js -import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; -import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'; -import express from 'express'; - -// Create an MCP server -const server = new McpServer({ - name: 'WhoAmI', - version: '0.0.0', -}); - -// Add a tool to the server that returns the current user's information -server.tool('whoami', async () => { - return { - content: [{ type: 'text', text: JSON.stringify({ error: 'Not authenticated' }) }], - }; -}); - -// Below is the boilerplate code from MCP SDK documentation -const PORT = 3001; -const app = express(); - -const transports = {}; - -app.get('/sse', async (_req, res) => { - const transport = new SSEServerTransport('/messages', res); - transports[transport.sessionId] = transport; - - res.on('close', () => { - delete transports[transport.sessionId]; - }); - - await server.connect(transport); -}); - -app.post('/messages', async (req, res) => { - const sessionId = String(req.query.sessionId); - const transport = transports[sessionId]; - if (transport) { - await transport.handlePostMessage(req, res, req.body); - } else { - res.status(400).send('No transport found for sessionId'); - } -}); - -app.listen(PORT); -``` - -Run the server with: - -```bash -npm start -``` - - - - -## Inspect the MCP server \{#inspect-the-mcp-server} - -### Clone and run MCP inspector \{#clone-and-run-mcp-inspector} - -Now that we have the MCP server running, we can use the MCP inspector to see if the `whoami` tool is available. - -Due to the limit of the current implementation, we've forked the [MCP inspector](https://github.com/mcp-auth/inspector) to make it more flexible and scalable for authentication and authorization. We've also submitted a pull request to the original repository to include our changes. - -To run the MCP inspector, you can use the following command (Node.js is required): - -```bash -git clone https://github.com/mcp-auth/inspector.git -cd inspector -npm install -npm run dev -``` - -Then, open your browser and navigate to `http://localhost:6274/` (or other URL shown in the terminal) to access the MCP inspector. - -### Connect MCP inspector to the MCP server \{#connect-mcp-inspector-to-the-mcp-server} - -Before we proceed, check the following configuration in MCP inspector: - -- **Transport Type**: Set to `SSE`. -- **URL**: Set to the URL of your MCP server. In our case, it should be `http://localhost:3001/sse`. - -Now you can click the "Connect" button to see if the MCP inspector can connect to the MCP server. If everything is okay, you should see the "Connected" status in the MCP inspector. - -### Checkpoint: Run the `whoami` tool \{#checkpoint-run-the-whoami-tool} - -1. In the top menu of the MCP inspector, click on the "Tools" tab. -2. Click on the "List Tools" button. -3. You should see the `whoami` tool listed on the page. Click on it to open the tool details. -4. You should see the "Run Tool" button in the right side. Click on it to run the tool. -5. You should see the tool result with the JSON response `{"error": "Not authenticated"}`. - -![MCP inspector first run](/docs-assets/images/tutorials/whoami/inspector-first-run.png) - -## Integrate with your authorization server \{#integrate-with-your-authorization-server} - -To complete this section, there are several considerations to take into account: - -
-**The issuer URL of your authorization server** - -This is usually the base URL of your authorization server, such as `https://auth.example.com`. Some providers may have a path like `https://example.logto.app/oidc`, so make sure to check your provider's documentation. - -
- -
-**How to retrieve the authorization server metadata** - -- If your authorization server conforms to the [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) or [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html), you can use the MCP Auth built-in utilities to fetch the metadata automatically. -- If your authorization server does not conform to these standards, you will need to manually specify the metadata URL or endpoints in the MCP server configuration. Check your provider's documentation for the specific endpoints. - -
- -
-**How to register the MCP inspector as a client in your authorization server** - -- If your authorization server supports [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591), you can skip this step as the MCP inspector will automatically register itself as a client. -- If your authorization server does not support Dynamic Client Registration, you will need to manually register the MCP inspector as a client in your authorization server. - -
- -
-**How to retrieve user identity information and how to configure the authorization request parameters** - -- For OpenID Connect providers: usually you need to request at least the `openid` and `profile` scopes when initiating the authorization flow. This will ensure that the access token returned by the authorization server contains the necessary scopes to access the [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) to retrieve user identity information. - - Note: Some of the providers may not support the userinfo endpoint. - -- For OAuth 2.0 / OAuth 2.1 providers: check your provider's documentation to see how to retrieve user identity information using an access token and what parameters are required to fetch such access token when invoking the authorization flow. - -
- -While each provider may have its own specific requirements, the following steps will guide you through the process of integrating the MCP inspector and MCP server with provider-specific configurations. - -### Register MCP inspector as a client \{#register-mcp-inspector-as-a-client} - - - - -Integrating with [Logto](https://logto.io) is straightforward as it's an OpenID Connect provider that supports the standard [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) to retrieve user identity information. - -Since Logto does not support Dynamic Client Registration yet, you will need to manually register the MCP inspector as a client in your Logto tenant: - -1. Open your MCP inspector, click on the "OAuth Configuration" button. Copy the **Redirect URL (auto-populated)** value, which should be something like `http://localhost:6274/oauth/callback`. -2. Sign in to [Logto Console](https://cloud.logto.io) (or your self-hosted Logto Console). -3. Navigate to the "Applications" tab, click on "Create application". In the bottom of the page, click on "Create app without framework". -4. Fill in the application details, then click on "Create application": - - **Select an application type**: Choose "Single-page application". - - **Application name**: Enter a name for your application, e.g., "MCP Inspector". -5. In the "Settings / Redirect URIs" section, paste the **Redirect URL (auto-populated)** value you copied from the MCP inspector. Then click on "Save changes" in the bottom bar. -6. In the top card, you will see the "App ID" value. Copy it. -7. Go back to the MCP inspector and paste the "App ID" value in the "OAuth Configuration" section under "Client ID". -8. Enter the value `{"scope": "openid profile email"}` in the "Auth Params" field. This will ensure that the access token returned by Logto contains the necessary scopes to access the userinfo endpoint. - - - - -[Keycloak](https://www.keycloak.org) is an open-source identity and access management solution that supports OpenID Connect protocol. - -While Keycloak supports dynamic client registration, its client registration endpoint does not support CORS, preventing most MCP clients from registering directly. Therefore, we'll need to manually register our client. - -:::note -Although Keycloak can be installed in [various ways](https://www.keycloak.org/guides#getting-started) (bare metal, kubernetes, etc.), for this tutorial, we'll use Docker for a quick and straightforward setup. -::: - -Let's set up a Keycloak instance and configure it for our needs: - -1. First, run a Keycloak instance using Docker following the [official documentation](https://www.keycloak.org/getting-started/getting-started-docker): - -```bash -docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.2.4 start-dev -``` - -2. Access the Keycloak Admin Console (http://localhost:8080/admin) and log in with these credentials: - - - Username: `admin` - - Password: `admin` - -3. Create a new Realm: - - - Click "Create Realm" in the top-left corner - - Enter `mcp-realm` in the "Realm name" field - - Click "Create" - -4. Create a test user: - - - Click "Users" in the left menu - - Click "Create new user" - - Fill in the user details: - - Username: `testuser` - - First name and Last name can be any values - - Click "Create" - - In the "Credentials" tab, set a password and uncheck "Temporary" - -5. Register MCP Inspector as a client: - - - Open your MCP inspector, click on the "OAuth Configuration" button. Copy the **Redirect URL (auto-populated)** value, which should be something like `http://localhost:6274/oauth/callback`. - - In the Keycloak Admin Console, click "Clients" in the left menu - - Click "Create client" - - Fill in the client details: - - Client type: Select "OpenID Connect" - - Client ID: Enter `mcp-inspector` - - Click "Next" - - On the "Capability config" page: - - Ensure "Standard flow" is enabled - - Click "Next" - - On the "Login settings" page: - - Paste the previously copied MCP Inspector callback URL into "Valid redirect URIs" - - Enter `http://localhost:6274` in "Web origins" - - Click "Save" - - Copy the "Client ID" (which is `mcp-inspector`) - -6. Back in the MCP Inspector: - - Paste the copied Client ID into the "Client ID" field in the "OAuth Configuration" section - - Enter the following value in the "Auth Params" field to request the necessary scopes: - -```json -{ "scope": "openid profile email" } -``` - - - - -While Asgardeo supports dynamic client registration via a standard API, the endpoint is protected and requires an access token with the necessary permissions. In this tutorial, we’ll register the client manually through the Asgardeo Console. - -:::note -If you don’t have an Asgardeo account, you can [sign up for free](https://asgardeo.io). -::: - -Follow these steps to configure Asgardeo for MCP Inspector: - -1. Log in to the [Asgardeo Console](https://console.asgardeo.io) and select your organization. - -2. Create a new application: - - Go to **Applications** → **New Application** - - Choose **Single-Page Application** - - Enter an application name like `MCP Inspector` - - In the **Authorized Redirect URLs** field, paste the **Redirect URL** copied from MCP Inspector client application (e.g.: `http://localhost:6274/oauth/callback`) - - Click **Create** - -3. Configure the protocol settings: - - Under the **Protocol** tab: - - Copy the **Client ID** that was auto generated. - - Ensure switching to `JWT` for the `Token Type` in **Access Token** section - - Click **Update** - -4. In MCP Inspector client application: - - Open the **OAuth Configuration** section - - Paste the copied **Client ID** - - Enter the following in the **Auth Params** field to request the necessary scopes: - -```json -{ "scope": "openid profile email" } -``` - - - -:::note -This is a generic OpenID Connect provider integration guide. Check your provider's documentation for specific details. -::: - -If your OpenID Connect provider supports Dynamic Client Registration, you can directly go to step 8 below to configure the MCP inspector; otherwise, you will need to manually register the MCP inspector as a client in your OpenID Connect provider: - -1. Open your MCP inspector, click on the "OAuth Configuration" button. Copy the **Redirect URL (auto-populated)** value, which should be something like `http://localhost:6274/oauth/callback`. -2. Sign in to your OpenID Connect provider's console. -3. Navigate to the "Applications" or "Clients" section, then create a new application or client. -4. If your provider requires a client type, select "Single-page application" or "Public client". -5. After creating the application, you will need to configure the redirect URI. Paste the **Redirect URL (auto-populated)** value you copied from the MCP inspector. -6. Find the "Client ID" or "Application ID" of the newly created application and copy it. -7. Go back to the MCP inspector and paste the "Client ID" value in the "OAuth Configuration" section under "Client ID". -8. For standard OpenID Connect providers, you can enter the following value in the "Auth Params" field to request the necessary scopes to access the userinfo endpoint: - -```json -{ "scope": "openid profile email" } -``` - - - - -:::note -This is a generic OAuth 2.0 / OAuth 2.1 provider integration guide. Check your provider's documentation for specific details. -::: - -If your OAuth 2.0 / OAuth 2.1 provider supports Dynamic Client Registration, you can directly go to step 8 below to configure the MCP inspector; otherwise, you will need to manually register the MCP inspector as a client in your OAuth 2.0 / OAuth 2.1 provider: - -1. Open your MCP inspector, click on the "OAuth Configuration" button. Copy the **Redirect URL (auto-populated)** value, which should be something like `http://localhost:6274/oauth/callback`. -2. Sign in to your OAuth 2.0 / OAuth 2.1 provider's console. -3. Navigate to the "Applications" or "Clients" section, then create a new application or client. -4. If your provider requires a client type, select "Single-page application" or "Public client". -5. After creating the application, you will need to configure the redirect URI. Paste the **Redirect URL (auto-populated)** value you copied from the MCP inspector. -6. Find the "Client ID" or "Application ID" of the newly created application and copy it. -7. Go back to the MCP inspector and paste the "Client ID" value in the "OAuth Configuration" section under "Client ID". -8. Read your provider's documentation to see how to retrieve access tokens for user identity information. You may need to specify the scopes or parameters required to fetch the access token. For example, if your provider requires the `profile` scope to access user identity information, you can enter the following value in the "Auth Params" field: - -```json -{ "scope": "profile" } -``` - - - - -### Set up MCP auth \{#set-up-mcp-auth} - -In your MCP server project, you need to install the MCP Auth SDK and configure it to use your authorization server metadata. - - - - -First, install the `mcpauth` package: - -```bash -pip install mcpauth -``` - -Or any other package manager you prefer, such as `uv` or `poetry`. - - - - -First, install the `mcp-auth` package: - -```bash -npm install mcp-auth -``` - - - - -MCP Auth requires the authorization server metadata to be able to initialize. Depending on your provider: - - - - - -The issuer URL can be found in your application details page in Logto Console, in the "Endpoints & Credentials / Issuer endpoint" section. It should look like `https://my-project.logto.app/oidc`. - - - - - - - -The issuer URL can be found in your Keycloak Admin Console. In your 'mcp-realm', navigate to "Realm settings / Endpoints" section and click on "OpenID Endpoint Configuration" link. The `issuer` field in the JSON document will contain your issuer URL, which should look like `http://localhost:8080/realms/mcp-realm`. - - - - - - - - You can find the issuer URL in the Asgardeo Console. Navigate to the created application, and open the **Info** tab. The **Issuer** field will be displayed there and should look like: - `https://api.asgardeo.io/t//oauth2/token` - - - - - - - -The following code also assumes that the authorization server supports the [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) to retrieve user identity information. If your provider does not support this endpoint, you will need to check your provider's documentation for the specific endpoint and replace the userinfo endpoint variable with the correct URL. - - - - - - -As we mentioned earlier, OAuth 2.0 does not define a standard way to retrieve user identity information. The following code assumes that your provider has a specific endpoint to retrieve user identity information using an access token. You will need to check your provider's documentation for the specific endpoint and replace the userinfo endpoint variable with the correct URL. - - - - - - -### Update MCP server \{#update-mcp-server} - -We are almost done! It's time to update the MCP server to apply the MCP Auth route and middleware function, then make the `whoami` tool return the actual user identity information. - - - - -```python -@mcp.tool() -def whoami() -> dict[str, Any]: - """A tool that returns the current user's information.""" - return ( - mcp_auth.auth_info.claims - if mcp_auth.auth_info # This will be populated by the Bearer auth middleware - else {"error": "Not authenticated"} - ) - -# ... - -bearer_auth = Middleware(mcp_auth.bearer_auth_middleware(verify_access_token)) -app = Starlette( - routes=[ - # Add the metadata route (`/.well-known/oauth-authorization-server`) - mcp_auth.metadata_route(), - # Protect the MCP server with the Bearer auth middleware - Mount('/', app=mcp.sse_app(), middleware=[bearer_auth]), - ], -) -``` - - - - -```js -server.tool('whoami', ({ authInfo }) => { - return { - content: [ - { type: 'text', text: JSON.stringify(authInfo?.claims ?? { error: 'Not authenticated' }) }, - ], - }; -}); - -// ... - -app.use(mcpAuth.delegatedRouter()); -app.use(mcpAuth.bearerAuth(verifyToken)); -``` - - - - -## Checkpoint: Run the `whoami` tool with authentication \{#checkpoint-run-the-whoami-tool-with-authentication} - -Restart your MCP server and open the MCP inspector in your browser. When you click the "Connect" button, you should be redirected to your authorization server's sign-in page. - -Once you sign in and back to the MCP inspector, repeat the actions we did in the previous checkpoint to run the `whoami` tool. This time, you should see the user identity information returned by the authorization server. - -![MCP inspector whoami tool result](/docs-assets/images/tutorials/whoami/result.png) - - - - -:::info -Check out the [MCP Auth Python SDK repository](https://github.com/mcp-auth/python/blob/master/samples/server/whoami.py) for the complete code of the MCP server (OIDC version). -::: - - - - -:::info -Check out the [MCP Auth Node.js SDK repository](https://github.com/mcp-auth/js/blob/master/packages/sample-servers/src) for the complete code of the MCP server (OIDC version). This directory contains both TypeScript and JavaScript versions of the code. -::: - - - - -## Closing notes \{#closing-notes} - -🎊 Congratulations! You have successfully completed the tutorial. Let's recap what we've done: - -- Setting up a basic MCP server with the `whoami` tool -- Integrating the MCP server with an authorization server using MCP Auth -- Configuring the MCP Inspector to authenticate users and retrieve their identity information - -You may also want to explore some advanced topics, including: - -- Using [JWT (JSON Web Token)](https://auth.wiki/jwt) for authentication and authorization -- Leveraging [resource indicators (RFC 8707)](https://auth-wiki.logto.io/resource-indicator) to specify the resources being accessed -- Implementing custom access control mechanisms, such as [role-based access control (RBAC)](https://auth.wiki/rbac) or [attribute-based access control (ABAC)](https://auth.wiki/abac) - -Be sure to check out other tutorials and documentation to make the most of MCP Auth. diff --git a/versioned_docs/version-0.1.1/tutorials/whoami/_manual-metadata-fetching.mdx b/versioned_docs/version-0.1.1/tutorials/whoami/_manual-metadata-fetching.mdx deleted file mode 100644 index 78bfbcb..0000000 --- a/versioned_docs/version-0.1.1/tutorials/whoami/_manual-metadata-fetching.mdx +++ /dev/null @@ -1,3 +0,0 @@ -:::note -If your provider does not support {props.oidc ? 'OpenID Connect Discovery' : 'OAuth 2.0 Authorization Server Metadata'}, you can manually specify the metadata URL or endpoints. Check [Other ways to initialize MCP Auth](../../configure-server/mcp-auth.mdx#other-ways) for more details. -::: diff --git a/versioned_docs/version-0.1.1/tutorials/whoami/_setup-oauth.mdx b/versioned_docs/version-0.1.1/tutorials/whoami/_setup-oauth.mdx deleted file mode 100644 index 40a172b..0000000 --- a/versioned_docs/version-0.1.1/tutorials/whoami/_setup-oauth.mdx +++ /dev/null @@ -1,141 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -Update the `whoami.py` to include the MCP Auth configuration: - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # Replace with your issuer endpoint -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OAUTH) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -Update the `whoami.js` to include the MCP Auth configuration: - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // Replace with your issuer endpoint -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oauth' }), -}); -``` - - - - - - - -Now, we need to create a custom access token verifier that will fetch the user identity information from the authorization server using the access token provided by the MCP inspector. - - - - -```python -import pydantic -import requests -from mcpauth.exceptions import ( - MCPAuthTokenVerificationException, - MCPAuthTokenVerificationExceptionCode, -) -from mcpauth.types import AuthInfo - -def verify_access_token(token: str) -> AuthInfo: - """ - Verifies the provided Bearer token by fetching user information from the authorization server. - If the token is valid, it returns an `AuthInfo` object containing the user's information. - - :param token: The Bearer token to received from the MCP inspector. - """ - - try: - # The following code assumes your authorization server has an endpoint for fetching user info - # using the access token issued by the authorization flow. - # Adjust the URL and headers as needed based on your provider's API. - response = requests.get( - "https://your-authorization-server.com/userinfo", - headers={"Authorization": f"Bearer {token}"}, - ) - response.raise_for_status() # Ensure we raise an error for HTTP errors - json = response.json() # Parse the JSON response - - # The following code assumes the user info response is an object with a 'sub' field that - # identifies the user. You may need to adjust this based on your provider's API. - return AuthInfo( - token=token, - subject=json.get("sub"), - issuer=auth_issuer, # Use the configured issuer - claims=json, # Include all claims (JSON fields) returned by the endpoint - ) - # `AuthInfo` is a Pydantic model, so validation errors usually mean the response didn't match - # the expected structure - except pydantic.ValidationError as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.INVALID_TOKEN, - cause=e, - ) - # Handle other exceptions that may occur during the request - except Exception as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.TOKEN_VERIFICATION_FAILED, - cause=e, - ) -``` - - - - -```js -import { MCPAuthTokenVerificationError } from 'mcp-auth'; - -/** - * Verifies the provided Bearer token by fetching user information from the authorization server. - * If the token is valid, it returns an `AuthInfo` object containing the user's information. - */ -const verifyToken = async (token) => { - // The following code assumes your authorization server has an endpoint for fetching user info - // using the access token issued by the authorization flow. - // Adjust the URL and headers as needed based on your provider's API. - const response = await fetch('https://your-authorization-server.com/userinfo', { - headers: { Authorization: `Bearer ${token}` }, - }); - - if (!response.ok) { - throw new MCPAuthTokenVerificationError('token_verification_failed', response); - } - - const userInfo = await response.json(); - - // The following code assumes the user info response is an object with a 'sub' field that - // identifies the user. You may need to adjust this based on your provider's API. - if (typeof userInfo !== 'object' || userInfo === null || !('sub' in userInfo)) { - throw new MCPAuthTokenVerificationError('invalid_token', response); - } - - return { - token, - issuer: authIssuer, - subject: String(userInfo.sub), // Adjust this based on your provider's user ID field - clientId: '', // Client ID is not used in this example, but can be set if needed - scopes: [], - claims: userInfo, - }; -}; -``` - - - diff --git a/versioned_docs/version-0.1.1/tutorials/whoami/_setup-oidc.mdx b/versioned_docs/version-0.1.1/tutorials/whoami/_setup-oidc.mdx deleted file mode 100644 index 8a35bf1..0000000 --- a/versioned_docs/version-0.1.1/tutorials/whoami/_setup-oidc.mdx +++ /dev/null @@ -1,143 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -import ManualMetadataFetching from './_manual-metadata-fetching.mdx'; -import MalformedMetadataTranspilation from './_transpile-metadata.mdx'; - - - - - -Update the `whoami.py` to include the MCP Auth configuration: - -```python -from mcpauth import MCPAuth -from mcpauth.config import AuthServerType -from mcpauth.utils import fetch_server_config - -auth_issuer = '' # Replace with your issuer endpoint -auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC) -mcp_auth = MCPAuth(server=auth_server_config) -``` - - - - -Update the `whoami.js` to include the MCP Auth configuration: - -```js -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; - -const authIssuer = ''; // Replace with your issuer endpoint -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { type: 'oidc' }), -}); -``` - - - - -{props.showAlternative && } -{props.showAlternative && } - -Now, we need to create a custom access token verifier that will fetch the user identity information from the authorization server using the access token provided by the MCP inspector. - - - - -```python -import pydantic -import requests -from mcpauth.exceptions import ( - MCPAuthTokenVerificationException, - MCPAuthTokenVerificationExceptionCode, -) -from mcpauth.types import AuthInfo - -def verify_access_token(token: str) -> AuthInfo: - """ - Verifies the provided Bearer token by fetching user information from the authorization server. - If the token is valid, it returns an `AuthInfo` object containing the user's information. - - :param token: The Bearer token to received from the MCP inspector. - """ - - issuer = auth_server_config.metadata.issuer - endpoint = auth_server_config.metadata.userinfo_endpoint # The provider should support the userinfo endpoint - if not endpoint: - raise ValueError( - "Userinfo endpoint is not configured in the auth server metadata." - ) - - try: - response = requests.get( - endpoint, - headers={"Authorization": f"Bearer {token}"}, # Standard Bearer token header - ) - response.raise_for_status() # Ensure we raise an error for HTTP errors - json = response.json() # Parse the JSON response - return AuthInfo( - token=token, - subject=json.get("sub"), # 'sub' is a standard claim for the subject (user's ID) - issuer=issuer, # Use the issuer from the metadata - claims=json, # Include all claims (JSON fields) returned by the userinfo endpoint - ) - # `AuthInfo` is a Pydantic model, so validation errors usually mean the response didn't match - # the expected structure - except pydantic.ValidationError as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.INVALID_TOKEN, - cause=e, - ) - # Handle other exceptions that may occur during the request - except Exception as e: - raise MCPAuthTokenVerificationException( - MCPAuthTokenVerificationExceptionCode.TOKEN_VERIFICATION_FAILED, - cause=e, - ) -``` - - - - -```js -import { MCPAuthTokenVerificationError } from 'mcp-auth'; - -/** - * Verifies the provided Bearer token by fetching user information from the authorization server. - * If the token is valid, it returns an `AuthInfo` object containing the user's information. - */ -const verifyToken = async (token) => { - const { issuer, userinfoEndpoint } = mcpAuth.config.server.metadata; - - if (!userinfoEndpoint) { - throw new Error('Userinfo endpoint is not configured in the server metadata'); - } - - const response = await fetch(userinfoEndpoint, { - headers: { Authorization: `Bearer ${token}` }, - }); - - if (!response.ok) { - throw new MCPAuthTokenVerificationError('token_verification_failed', response); - } - - const userInfo = await response.json(); - - if (typeof userInfo !== 'object' || userInfo === null || !('sub' in userInfo)) { - throw new MCPAuthTokenVerificationError('invalid_token', response); - } - - return { - token, - issuer, - subject: String(userInfo.sub), // 'sub' is a standard claim for the subject (user's ID) - clientId: '', // Client ID is not used in this example, but can be set if needed - scopes: [], - claims: userInfo, - }; -}; -``` - - - diff --git a/versioned_docs/version-0.1.1/tutorials/whoami/_transpile-metadata.mdx b/versioned_docs/version-0.1.1/tutorials/whoami/_transpile-metadata.mdx deleted file mode 100644 index d13ff01..0000000 --- a/versioned_docs/version-0.1.1/tutorials/whoami/_transpile-metadata.mdx +++ /dev/null @@ -1,31 +0,0 @@ -import TabItem from '@theme/TabItem'; -import Tabs from '@theme/Tabs'; - -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: - - - - -```python -mcp_auth = MCPAuth( - server=fetch_server_config( - # ...other options - transpile_data=lambda data: {**data, 'response_types_supported': ['code']} # [!code highlight] - ) -) -``` - - - - -```ts -const mcpAuth = new MCPAuth({ - server: await fetchServerConfig(authIssuer, { - // ...other options - transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), // [!code highlight] - }), -}); -``` - - - diff --git a/versioned_docs/version-0.1.1/tutorials/whoami/assets/inspector-first-run.png b/versioned_docs/version-0.1.1/tutorials/whoami/assets/inspector-first-run.png deleted file mode 100644 index e5e0502..0000000 Binary files a/versioned_docs/version-0.1.1/tutorials/whoami/assets/inspector-first-run.png and /dev/null differ diff --git a/versioned_docs/version-0.1.1/tutorials/whoami/assets/result.png b/versioned_docs/version-0.1.1/tutorials/whoami/assets/result.png deleted file mode 100644 index b7cded5..0000000 Binary files a/versioned_docs/version-0.1.1/tutorials/whoami/assets/result.png and /dev/null differ diff --git a/versioned_sidebars/version-0.1.1-sidebars.json b/versioned_sidebars/version-0.1.1-sidebars.json deleted file mode 100644 index 39332bf..0000000 --- a/versioned_sidebars/version-0.1.1-sidebars.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "docsSidebar": [ - { - "type": "autogenerated", - "dirName": "." - } - ] -} diff --git a/versions.json b/versions.json deleted file mode 100644 index 5dbdc69..0000000 --- a/versions.json +++ /dev/null @@ -1,3 +0,0 @@ -[ - "0.1.1" -]