diff --git a/artifacts/attributes.adoc b/artifacts/attributes.adoc index 7aea302480..817bb489d9 100644 --- a/artifacts/attributes.adoc +++ b/artifacts/attributes.adoc @@ -168,3 +168,6 @@ :upgrading-book-title: Upgrading {product} :using-dynamic-plugins-book-link: {product-docs-link}/html-single/installing_and_viewing_plugins_in_red_hat_developer_hub/index :using-dynamic-plugins-book-title: Using dynamic plugins + +:model-context-protocol-link: {product-docs-link}/html-single/interacting_with_model_context_protocol_tools_for_red_hat_developer_hub/index +:model-context-protocol-title: Interacting with Model Context Protocol tools for {product} \ No newline at end of file diff --git a/artifacts/snip-developer-preview.adoc b/artifacts/snip-developer-preview-lightspeed.adoc similarity index 100% rename from artifacts/snip-developer-preview.adoc rename to artifacts/snip-developer-preview-lightspeed.adoc diff --git a/artifacts/snip-developer-preview-mcp.adoc b/artifacts/snip-developer-preview-mcp.adoc new file mode 100644 index 0000000000..03906f2a67 --- /dev/null +++ b/artifacts/snip-developer-preview-mcp.adoc @@ -0,0 +1,6 @@ +[IMPORTANT] +==== +This section describes Developer Preview features in the Model Context Protocol plugin. Developer Preview features are not supported by Red Hat in any way and are not functionally complete or production-ready. Do not use Developer Preview features for production or business-critical workloads. Developer Preview features provide early access to functionality in advance of possible inclusion in a Red Hat product offering. Customers can use these features to test functionality and provide feedback during the development process. Developer Preview features might not have any documentation, are subject to change or removal at any time, and have received limited testing. Red Hat might provide ways to submit feedback on Developer Preview features without an associated SLA. + +For more information about the support scope of Red Hat Developer Preview features, see https://access.redhat.com/support/offerings/devpreview/[Developer Preview Support Scope]. +==== diff --git a/assemblies/assembly-model-context-protocol-tools.adoc b/assemblies/assembly-model-context-protocol-tools.adoc new file mode 100644 index 0000000000..9c6e8958fd --- /dev/null +++ b/assemblies/assembly-model-context-protocol-tools.adoc @@ -0,0 +1,17 @@ +:_mod-docs-content-type: ASSEMBLY + +[id="assembly-model-context-protocol-tools"] += Interacting with Model Context Protocol tools for {product} +:context: assembly-model-context-protocol-tools + +include::modules/model-context-protocol-tools/con-understanding-model-context-protocol.adoc[leveloffset=+1] + +include::modules/model-context-protocol-tools/proc-installing-the-mcp-server-and-tool-plugins.adoc[leveloffset=+1] + +include::modules/model-context-protocol-tools/proc-configuring-model-context-protocol.adoc[leveloffset=+1] + +include::modules/model-context-protocol-tools/proc-configuring-mcp-clients-to-access-the-rhdh-server.adoc[leveloffset=+2] + +include::assembly-using-the-mcp-tools-to-access-data.adoc[leveloffset=+1] + +include::assembly-troubleshooting-mcp-server-and-client-problems.adoc[leveloffset=+1] \ No newline at end of file diff --git a/assemblies/assembly-troubleshooting-mcp-server-and-client-problems.adoc b/assemblies/assembly-troubleshooting-mcp-server-and-client-problems.adoc new file mode 100644 index 0000000000..e1eee3aa91 --- /dev/null +++ b/assemblies/assembly-troubleshooting-mcp-server-and-client-problems.adoc @@ -0,0 +1,19 @@ +:_mod-docs-content-type: ASSEMBLY + +[id="assembly-troubleshooting-mcp-server-and-client-problems"] += Troubleshooting MCP server and client problems +:context: assembly-troubleshooting-mcp-server-and-client-problems + +The following procedures guide you through resolving common issues when using a Model Communication Protocol (MCP) server and tool. + +include::modules/model-context-protocol-tools/proc-verifying-successful-installation-of-mcp-plugins.adoc[leveloffset=+1] + +include::modules/model-context-protocol-tools/proc-checking-logs-for-mcp-tool-execution-and-errors.adoc[leveloffset=+1] + +include::modules/model-context-protocol-tools/con-understand-and-respond-to-mcp-tool-error-messages.adoc[leveloffset=+1] + +include::modules/model-context-protocol-tools/proc-resolving-the-model-does-not-support-tool-calling-error.adoc[leveloffset=+1] + +include::modules/model-context-protocol-tools/proc-resolving-authentication-issues-when-tool-are-not-found.adoc[leveloffset=+1] + +include::modules/model-context-protocol-tools/proc-nonsensical-mcp-tool-output.adoc[leveloffset=+1] \ No newline at end of file diff --git a/assemblies/assembly-using-the-mcp-tools-to-access-data.adoc b/assemblies/assembly-using-the-mcp-tools-to-access-data.adoc new file mode 100644 index 0000000000..f92c4bf476 --- /dev/null +++ b/assemblies/assembly-using-the-mcp-tools-to-access-data.adoc @@ -0,0 +1,17 @@ +:_mod-docs-content-type: ASSEMBLY + +[id="assembly-using-the-mcp-tools-to-access-data"] += Using the MCP tools to access data from {product} +:context: assembly-using-the-mcp-tools-to-access-data + +MCP tool plugins enable seamless integration with the Software Catalog and TechDocs. + +include::modules/model-context-protocol-tools/proc-retrieving-software-catalog-data-through-mcp-tool.adoc[leveloffset=+1] + +include::modules/model-context-protocol-tools/proc-accessing-and-analyzing-doc-using-techdocs-mcp-tools.adoc[leveloffset=+1] + +include::modules/model-context-protocol-tools/proc-retrieving-techdocs-urls-and-metadata-using-fetch-techdocs.adoc[leveloffset=+2] + +include::modules/model-context-protocol-tools/proc-measuring-doc-gaps-using-analyze-techdocs-coverage.adoc[leveloffset=+2] + +include::modules/model-context-protocol-tools/proc-finding-a-specific-techdoc-using-retrieve-techdocs-content.adoc[leveloffset=+2] \ No newline at end of file diff --git a/modules/developer-lightspeed/con-about-developer-lightspeed.adoc b/modules/developer-lightspeed/con-about-developer-lightspeed.adoc index 3d2d966ea7..fb440177e3 100644 --- a/modules/developer-lightspeed/con-about-developer-lightspeed.adoc +++ b/modules/developer-lightspeed/con-about-developer-lightspeed.adoc @@ -3,7 +3,7 @@ [id="con-about-developer-lightspeed_{context}"] = About {ls-short} -include::{docdir}/artifacts/snip-developer-preview.adoc[] +include::{docdir}/artifacts/snip-developer-preview-lightspeed.adoc[] This early access program enables customers to share feedback on the user experience, features, capabilities, and any issues encountered. Your input helps ensure that {ls-short} better meets your needs when it is officially released and made generally available. diff --git a/modules/model-context-protocol-tools/artifacts/snip-developer-preview.adoc b/modules/model-context-protocol-tools/artifacts/snip-developer-preview.adoc new file mode 100644 index 0000000000..03906f2a67 --- /dev/null +++ b/modules/model-context-protocol-tools/artifacts/snip-developer-preview.adoc @@ -0,0 +1,6 @@ +[IMPORTANT] +==== +This section describes Developer Preview features in the Model Context Protocol plugin. Developer Preview features are not supported by Red Hat in any way and are not functionally complete or production-ready. Do not use Developer Preview features for production or business-critical workloads. Developer Preview features provide early access to functionality in advance of possible inclusion in a Red Hat product offering. Customers can use these features to test functionality and provide feedback during the development process. Developer Preview features might not have any documentation, are subject to change or removal at any time, and have received limited testing. Red Hat might provide ways to submit feedback on Developer Preview features without an associated SLA. + +For more information about the support scope of Red Hat Developer Preview features, see https://access.redhat.com/support/offerings/devpreview/[Developer Preview Support Scope]. +==== diff --git a/modules/model-context-protocol-tools/con-understand-and-respond-to-mcp-tool-error-messages.adoc b/modules/model-context-protocol-tools/con-understand-and-respond-to-mcp-tool-error-messages.adoc new file mode 100644 index 0000000000..1eadb292f1 --- /dev/null +++ b/modules/model-context-protocol-tools/con-understand-and-respond-to-mcp-tool-error-messages.adoc @@ -0,0 +1,6 @@ +:_mod-docs-content-type: CONCEPT + +[id="con-understand-and-respond-to-mcp-tool-error-messages.adoc_{context}"] += Understand and respond to MCP tool error messages + +The MCP tools response provides an optional error message that communicates any issues encountered during the use of the tool, including potential input validation errors. \ No newline at end of file diff --git a/modules/model-context-protocol-tools/con-understanding-model-context-protocol.adoc b/modules/model-context-protocol-tools/con-understanding-model-context-protocol.adoc new file mode 100644 index 0000000000..3f8039a3d5 --- /dev/null +++ b/modules/model-context-protocol-tools/con-understanding-model-context-protocol.adoc @@ -0,0 +1,10 @@ +:_mod-docs-content-type: CONCEPT + +[id="understanding-model-context-protocol"] += Understanding Model Context Protocol + +include::{docdir}/artifacts/snip-developer-preview-mcp.adoc[] + +Model Context Protocol (MCP) offers a standardized method for linking AI models and applications (MCP clients) with external systems. This connection facilitates access to information and workflows residing on those systems. MCP servers are responsible for defining the tools that AI applications can utilize to retrieve this data. + +{product} supports running MCP tools through the `mcp-actions-backend` plugin available in {backstage} 1.40 or later. \ No newline at end of file diff --git a/modules/model-context-protocol-tools/proc-accessing-and-analyzing-doc-using-techdocs-mcp-tools.adoc b/modules/model-context-protocol-tools/proc-accessing-and-analyzing-doc-using-techdocs-mcp-tools.adoc new file mode 100644 index 0000000000..246b6121a8 --- /dev/null +++ b/modules/model-context-protocol-tools/proc-accessing-and-analyzing-doc-using-techdocs-mcp-tools.adoc @@ -0,0 +1,11 @@ +:_mod-docs-content-type: PROCEDURE + +[id="proc-accessing-and-analyzing-doc-using-techdocs-mcp-tools_{context}"] += Accessing and analyzing documentation using the TechDocs MCP tools + +The TechDocs Model Context Protocol (MCP) tool enables AI clients to search and retrieve documentation directly from {product-very-short} TechDocs instances. Use this tool to query documentation content and integrate it as context into your AI applications. + +The following TechDocs MCP tools are supported: +* `fetch-techdocs` +* `analyze-techdocs-coverage` +* `retrieve-techdocs-content` \ No newline at end of file diff --git a/modules/model-context-protocol-tools/proc-checking-logs-for-mcp-tool-execution-and-errors.adoc b/modules/model-context-protocol-tools/proc-checking-logs-for-mcp-tool-execution-and-errors.adoc new file mode 100644 index 0000000000..da743e7f3f --- /dev/null +++ b/modules/model-context-protocol-tools/proc-checking-logs-for-mcp-tool-execution-and-errors.adoc @@ -0,0 +1,12 @@ +:_mod-docs-content-type: PROCEDURE + +[id="proc-checking-logs-for-mcp-tool-execution-and-errors.adoc_{context}"] += Checking MCP tool logs for status and errors + +The {backstage} `LoggerService` target name starts with the name of the MCP tool (either `software-catalog-mcp-tool` or `techdocs-mcp-tool`). The MCP tools generate a log by default. For example: + +[source,terminal] +---- +`[backend]: 2025-09-25T16:24:22.660Z software-catalog-mcp-tool info fetch-catalog-entities: Fetching catalog entities with options: kind="Component"` +---- +If any errors occur in the MCP tools, check the logs. diff --git a/modules/model-context-protocol-tools/proc-configuring-mcp-clients-to-access-the-rhdh-server.adoc b/modules/model-context-protocol-tools/proc-configuring-mcp-clients-to-access-the-rhdh-server.adoc new file mode 100644 index 0000000000..9db64a3299 --- /dev/null +++ b/modules/model-context-protocol-tools/proc-configuring-mcp-clients-to-access-the-rhdh-server.adoc @@ -0,0 +1,130 @@ +:_mod-docs-content-type: PROCEDURE + +[id="proc-configuring-mpc-clients-to-access-the-rhdh-server_{context}"] += Configuring MCP clients to access the {product-very-short} server + +You must configure an MCP client to interact with the MCP server. For more information on the list of clients and their respective configurations, see https://modelcontextprotocol.io/clients[Example Clients]. + +.Prerequisites + +* You have configured one of the following endpoints as the server URL, where `<{product-very-short}_HOST>` is the hostname of your {product-very-short} instance. + +** Streamable: https://<{product-very-short}_HOST>/api/mcp-actions/v1 +** SSE (Legacy): https://<{product-very-short}_HOST>/api/mcp-actions/v1/sse ++ +[NOTE] +==== +Some clients do not yet support the Streamable endpoint, and you might need to use the SSE endpoint instead. +==== + +.Procedure + +. Set the ${MCP_TOKEN} in your MCP server configuration as the bearer token when authenticating with the MCP server by completing the following steps: +.. In the {ocp-short} web console, go to *Secrets*. +.. Click *Create > Key/value secret*. +.. In the *Create key/value secret* page, select the *YAML view* option in *Configure via*, and add the following example: ++ +[source,yaml] +---- +kind: Secret +apiVersion: v1 +metadata: + name: MCP_TOKEN + namespace: __ # +stringData: + LLM_SERVER_ID: __ + LLM_SERVER_TOKEN: __ + LLM_SERVER_URL: __ +type: Opaque +---- +.. Click *Create*. + +. Configure the *Cursor* client. +.. From your Desktop app, navigate to *Cursor Settings* and select *MCP Tools > New MCP Server*. +.. Add the following configuration: ++ +[source,yaml,subs="+attributes,+quotes"] +---- +{ + "mcpServers": { + "backstage-actions": { + "url": "https://<{product-very-short}_HOST>/api/mcp-actions/v1", + "headers": { + "Authorization": "Bearer " + } + } + } +} +---- +where: + +``:: Enter the previously configured static token +`<{product-very-short}_HOST>`:: Enter the hostname of your {product-very-short} instance + +. Configure the *Continue* client. + +.. In your agent yaml configuration file, add the following configuration: ++ +[source,yaml,subs="+attributes,+quotes"] +---- +mcpServers: + - name: backstage-actions + type: sse + url: https://<{product-very-short}_HOST>/api/mcp-actions/v1/sse + requestOptions: + headers: + Authorization: "Bearer " +---- ++ +where: + +``:: Enter the previously configured static token +`<{product-very-short}_HOST>`:: Enter the hostname of your {product-very-short} instance + +. Configure the *Lightspeed Plugin/Lightspeed Core (LCS)* client. +.. In the `lightspeed-stack.yaml` configuration, add the following configuration for `mcp_servers`: ++ +[source,yaml,subs="+attributes,+quotes"] +---- +mcp_servers: + - name: mcp::backstage + provider_id: model-context-protocol + url: https://<{product-very-short}_HOST>/api/mcp-actions/v1 +---- +where: + +`model-context-protocol`:: This is the tool runtime provider defined and configured in the llama-stack `run.yaml` configuration for use in LCS. + +.. Optional: If you want to use your own Llama Stack configuration, add the following code to your Llama Stack configuration file (`run.yaml`). ++ +[source,yaml] +---- +providers: + tool_runtime: + - provider_id: model-context-protocol + provider_type: remote::model-context-protocol + config: {} +---- +.. To authorize requests to the MCP endpoint using ``, add it in the {ls-short} {my-app-config-file}` file, to make POST requests to the LCS `/v1/streaming_query` endpoint, as shown in the following code: ++ +[source,yaml] +---- +lightspeed: + mcpServers: + - name: mcp::backstage + token: ${MCP_TOKEN} +---- +.. Optional: You can query the LCS `/v1/streaming_query` endpoint directly by providing the `MCP_TOKEN` in the header, as shown in the following code: ++ +[source,yaml] +---- +curl -X POST \ + -H `Content-Type: application/json` \ + -H `MCP-HEADERS: {"mcp::backstage": {"Authorization": "Bearer "}}` \ + -d `{"query": "Can you give me all catalog templates of type 'service', "model": "gpt-4o-mini", "provider": "openai"}` \ + __/v1/streaming_query +---- + +where: + +``:: Enter the LCS endpoint. You can use localhost(<{product-very-short}_servicename>.<{product-very-short}-namespace>.svc.cluster.local:8080) or the service name for this field if you are inside the {backstage} container. \ No newline at end of file diff --git a/modules/model-context-protocol-tools/proc-configuring-model-context-protocol.adoc b/modules/model-context-protocol-tools/proc-configuring-model-context-protocol.adoc new file mode 100644 index 0000000000..92f31ee4b1 --- /dev/null +++ b/modules/model-context-protocol-tools/proc-configuring-model-context-protocol.adoc @@ -0,0 +1,82 @@ +:_mod-docs-content-type: PROCEDURE + +[id="proc-configuring-model-context-protocol_{context}"] += Configuring Model Context Protocol in {product} + +You can enable your AI client applications to access {product-very-short} information and workflows. This configuration is a prerequisite for AI clients to use the defined MCP tools and leverage {product-very-short} data. + +.Prerequisite + +* You have {model-context-protocol-link}#proc-installing-the-mcp-server-and-tool-plugins[installed the MCP server and tool plugins in {product}]. + +.Procedure + +. In your {product} {my-app-config-file}` file, configure a static token for authentication against the MCP server endpoint. MCP clients (such as `Cursor`, `Continue`, or `Lightspeed Core`) use these tokens to authenticate against the {backstage} MCP server. For example: ++ +[source,yaml] +---- +backend: + auth: + externalAccess: + - type: static + options: + token: ${MCP_TOKEN} + subject: mcp-clients +---- +where: + +`${MCP_TOKEN}`:: Set the token value that you generate. ++ +[NOTE] +==== +Tokens must be long and complex strings without whitespace to prevent brute-force guessing. + +To generate a sample token, use the following command: +[source,bash] +---- +node -p `require("crypto").randomBytes(24).toString("base64")` +---- +==== + +. Register the MCP tools that you install as a plugin source, as shown in the following example: ++ +[source,yaml,subs="+attributes,+quotes"] +---- +backend: + actions: + pluginSources: + - software-catalog-mcp-tool + - techdocs-mcp-tool +---- ++ +.`{my-app-config-file}` file with MCP configuration example +[source,yaml,subs="+attributes,+quotes"] +---- +app: + title: AI Dev Developer Hub + baseUrl: "${{product-very-short}_BASE_URL}" +auth: + environment: development + session: + secret: "${BACKEND_SECRET}" + providers: + guest: + dangerouslyAllowOutsideDevelopment: true +backend: + actions: + pluginSources: + - 'software-catalog-mcp-tool' + - 'techdocs-mcp-tool' + auth: + externalAccess: + - type: static + options: + token: ${MCP_TOKEN} + subject: mcp-clients + keys: + - secret: "${BACKEND_SECRET}" + baseUrl: "${{product-very-short}_BASE_URL}" + cors: + origin: "${{product-very-short}_BASE_URL}" +signInPage: oidc +---- \ No newline at end of file diff --git a/modules/model-context-protocol-tools/proc-finding-a-specific-techdoc-using-retrieve-techdocs-content.adoc b/modules/model-context-protocol-tools/proc-finding-a-specific-techdoc-using-retrieve-techdocs-content.adoc new file mode 100644 index 0000000000..3887007358 --- /dev/null +++ b/modules/model-context-protocol-tools/proc-finding-a-specific-techdoc-using-retrieve-techdocs-content.adoc @@ -0,0 +1,27 @@ +:_mod-docs-content-type: PROCEDURE + +[id="proc-finding-a-specific-techdoc-using-retrieve-techdocs-content_{context}"] += Finding a specific TechDoc using `retrieve-techdocs-content` + +The `retrieve-techdocs-content` TechDocs MCP tool retrieves the content of a TechDocs resource, enabling AI clients to access documentation content for specific Software Catalog entities. By default, the tool returns a JSON entity with the following fields: `entityRef`, `name`, `title`, `kind`, `namespace`, `content`, `path`, `contentType`, `lastModified`, and `metadata`. + +The following examples show common queries: + +* “Fetch techdoc with reference component:default/my-service” +* “Fetch page about.html from techdoc with reference component:default/my-service” + +.Procedure +* Use the parameters as shown in the following table to configure your `retrieve-techdocs-content` TechDocs MCP tool. + +|=== +| Name | Description | Example + +| `entityRef` +| Specifies the entity to retrieve using the `kind:namespace/name` format. +| "component:default/my-service" + +| `pagePath` +| Specifies the path to a specific documentation page. Defaults to `index.html` +| "index.html" + +|=== diff --git a/modules/model-context-protocol-tools/proc-installing-the-mcp-server-and-tool-plugins.adoc b/modules/model-context-protocol-tools/proc-installing-the-mcp-server-and-tool-plugins.adoc new file mode 100644 index 0000000000..4afbb44569 --- /dev/null +++ b/modules/model-context-protocol-tools/proc-installing-the-mcp-server-and-tool-plugins.adoc @@ -0,0 +1,39 @@ +:_mod-docs-content-type: PROCEDURE + +[id="proc-installing-the-mcp-server-and-tool-plugins_{context}"] += Installing the MCP server and tool plugins in {product} + +To enable MCP support in {product}, you need to install the following components: + +Backend MCP server plugin:: Runs the MCP tools. +MCP tool plugins:: Facilitates integration with the Software Catalog and TechDocs. + +.Prerequisites + +* Your {product-very-short} instance is installed and running. + +.Procedure + +. Install the backend MCP server plugin: In your dynamic plugins ConfigMap (for example, `dynamic-plugins-rhdh.yaml`), add the MCP server plugin as shown in the following example: ++ +[source,yaml] +---- +plugins: + - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-plugin-mcp-actions-backend:bs_1.42.5__0.1.2!backstage-plugin-mcp-actions-backend + disabled: false +---- +. Install any of the following MCP tools that you would like to use: +** To install the Software Catalog MCP tool, in your dynamic plugins ConfigMap (for example, `dynamic-plugins-rhdh.yaml`), add the Software Catalog MCP tool plugin as shown in the following example: ++ +[source,yaml] +---- + - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool:bs_1.42.5__0.2.3!red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool + disabled: false +---- +** To install the TechDocs MCP tool, in your dynamic plugins ConfigMap (for example, `dynamic-plugins-rhdh.yaml`), add the TechDocs MCP tool plugin as shown in the following example: ++ +[source,yaml] +---- +- package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-techdocs-mcp-tool:bs_1.42.5__0.3.0!red-hat-developer-hub-backstage-plugin-techdocs-mcp-tool + disabled: false +---- \ No newline at end of file diff --git a/modules/model-context-protocol-tools/proc-measuring-doc-gaps-using-analyze-techdocs-coverage.adoc b/modules/model-context-protocol-tools/proc-measuring-doc-gaps-using-analyze-techdocs-coverage.adoc new file mode 100644 index 0000000000..be01626499 --- /dev/null +++ b/modules/model-context-protocol-tools/proc-measuring-doc-gaps-using-analyze-techdocs-coverage.adoc @@ -0,0 +1,39 @@ +:_mod-docs-content-type: PROCEDURE + +[id="proc-measuring-doc-gaps-using-analyze-techdocs-coverage_{context}"] += Measuring documentation gaps using `analyze-techdocs-coverage` + +The `analyze-techdocs-coverage` TechDocs MCP tool calculates the percentage of entities that have TechDocs configured. This tool identifies documentation gaps and improve overall documentation coverage. This tool supports filtering by entity type, namespace, owner, lifecycle, and tags to analyze coverage for specific subsets of entities. By default, it returns a JSON entity that includes the fields `totalEntities`, `entitiesWithDocs`, and `coveragePercentage`. + +The following examples show common queries: + +* “What is the coverage of techdocs in the backstage server” +* “What is the coverage of techdocs in the default namespace” + +.Procedure +* Use the parameters as shown in the following table to configure your `analyze-techdocs-coverage` TechDocs MCP tool. + +|=== +| Name | Description | Example + +| `entityType` +| Filters entities by their type. +| "Component" + +| `namespace` +| Filter entities by their namespace. +| "default" + +| `owner` +| Filters entities by owner. +| "user:john.doe" + +| `lifecycle` +| Filters entities by their lifecycle. +| "development" + +| `tags` +| Filters entities by their tags. +| ["genai, "ibm", "llm", "granite", "conversational", "task-text-generation"] + +|=== diff --git a/modules/model-context-protocol-tools/proc-nonsensical-mcp-tool-output.adoc b/modules/model-context-protocol-tools/proc-nonsensical-mcp-tool-output.adoc new file mode 100644 index 0000000000..98cdc8ff39 --- /dev/null +++ b/modules/model-context-protocol-tools/proc-nonsensical-mcp-tool-output.adoc @@ -0,0 +1,17 @@ +:_mod-docs-content-type: PROCEDURE + +[id="proc-nonsensical-mcp-tool-output.adoc_{context}"] += Resolve nonsensical MCP tool output + +Nonsensical output often occurs when smaller models or models with smaller context sizes cannot effectively manage repeated tool calls within the same context window. + +.Procedure + +To improve the quality of the tool output, take the following actions: + +. Select an appropriate model for tool calling. +.. Verify that the model has good support for tool calling. +.. Make sure your model is not too small. We recommend a model with at least 7 billion parameters and a context window of 32k. +. Refine your queries. +.. Use more well-defined queries that limit the amount of data returned in the response from the tool. +. If possible, increase the context window size of the model. We recommend at least 32k for these MCP tools. \ No newline at end of file diff --git a/modules/model-context-protocol-tools/proc-resolving-authentication-issues-when-tool-are-not-found.adoc b/modules/model-context-protocol-tools/proc-resolving-authentication-issues-when-tool-are-not-found.adoc new file mode 100644 index 0000000000..f6b3307a57 --- /dev/null +++ b/modules/model-context-protocol-tools/proc-resolving-authentication-issues-when-tool-are-not-found.adoc @@ -0,0 +1,18 @@ +:_mod-docs-content-type: PROCEDURE + +[id="proc-resolving-authentication-issues-when-tool-are-not-found.adoc_{context}"] += Resolving authentication issues when tools are not found + +If your MCP client connects to the server but cannot find deployed tools, an authentication or configuration issue is likely. + +.Procedure + +. Verify the authentication token. +.. Configure a static token for the {product-very-short} MCP server. +.. Set this token as the bearer token in your MCP client and make sure the authorization header is the configuration that specifies `Bearer` before the token, for example, `Bearer `. +. Check the MCP endpoint configuration. +.. Confirm that the MCP server URL properly resolves, particularly if you are using a desktop client. +.. Use *legacy SSE endpoint* if your MCP client requires it instead of the Streamable endpoint. (For more details, see the *Configuration* topic). +. Verify your {product-very-short} `{my-app-config-file}` file for duplicate backend entries and make sure that the indentation is accurate. +.. Make sure that the configuration for the static token and MCP plugin sources go under an existing backend field, if one is present. +.. If you are unsure, see {model-context-protocol-link}#proc-configuring-model-context-protocol[the sample app configuration provided in the reference procedure]. \ No newline at end of file diff --git a/modules/model-context-protocol-tools/proc-resolving-the-model-does-not-support-tool-calling-error.adoc b/modules/model-context-protocol-tools/proc-resolving-the-model-does-not-support-tool-calling-error.adoc new file mode 100644 index 0000000000..65c588826f --- /dev/null +++ b/modules/model-context-protocol-tools/proc-resolving-the-model-does-not-support-tool-calling-error.adoc @@ -0,0 +1,11 @@ +:_mod-docs-content-type: PROCEDURE + +[id="proc-resolving-the-model-does-not-support-tool-calling-error.adoc_{context}"] += Resolving the `Model does not support tool calling` error + +This error indicates that the model configured in your MCP client lacks the required functionality to handle tool calls. The error message appears similar to: `Invalid request: model gemma3:27b does not support tool calls`. + +.Procedure + +. Consult your model documentation to confirm its support for tool calling. +. If the current model does not support tool calling, change the model that your MCP client uses to a tool-calling compatible model. \ No newline at end of file diff --git a/modules/model-context-protocol-tools/proc-retrieving-software-catalog-data-through-mcp-tool.adoc b/modules/model-context-protocol-tools/proc-retrieving-software-catalog-data-through-mcp-tool.adoc new file mode 100644 index 0000000000..b604a17e2d --- /dev/null +++ b/modules/model-context-protocol-tools/proc-retrieving-software-catalog-data-through-mcp-tool.adoc @@ -0,0 +1,52 @@ +:_mod-docs-content-type: PROCEDURE + +[id="proc-retrieving-software-catalog-data-through-mcp-tool_{context}"] += Retrieving Software Catalog data through the MCP tool + +The Software Catalog MCP lists Backstage entities, such as *Components*, *Systems*, *Resources*, *APIs*, *Locations*, *Users*, and *Groups*. + +By default, the tool returns results in a JSON array format. Each entry in the JSON array contains an entity with the following fields: `name`, `description`,`type`, `owner`, `tags`, `dependsOn`, and `kind`. + +The optional `verbose` parameter returns the entire {backstage} entity object(s). + +The following examples show common queries: + +* “Fetch all ai-model resources in the {backstage} catalog” +* “Fetch the API definition for the beneficiary-management-api API” +* “Construct a curl command based on the API definition for the “insert beneficiary” endpoint in the beneficiary-management-api” + +.Procedure +* Use the parameters as shown in the following table to configure your Software Catalog MCP tool plugin. + +|=== +| Name | Description | Example + +| `kind` +| Filters entities by their {backstage} kind. +| "Component" + +| `type` +| Filter entities by their {backstage} type. (Requires the `kind` parameter) +| "model-server" + +| `name` +| Specifies the name of the {backstage} entity to retrieve. +| "vllm-model-server" + +| `owner` +| Filters entities by their owner. +| "test-platform" + +| `lifecycle` +| Filters entities by their lifecycle. +| "development" + +| `tags` +| Filters entities by their tags. +| ["genai, "ibm", "llm", ...] + +| `verbose` +| If set to `true`, the system returns the full {backstage} entity object instead of the shortened output. +| `true` + +|=== diff --git a/modules/model-context-protocol-tools/proc-retrieving-techdocs-urls-and-metadata-using-fetch-techdocs.adoc b/modules/model-context-protocol-tools/proc-retrieving-techdocs-urls-and-metadata-using-fetch-techdocs.adoc new file mode 100644 index 0000000000..ecbdde5a97 --- /dev/null +++ b/modules/model-context-protocol-tools/proc-retrieving-techdocs-urls-and-metadata-using-fetch-techdocs.adoc @@ -0,0 +1,42 @@ +:_mod-docs-content-type: PROCEDURE + +[id="proc-retrieving-techdocs-urls-and-metadata-using-fetch-techdocs_{context}"] += Retrieving TechDocs URLs and metadata using `fetch-techdocs` + +The `fetch-techdocs` TechDocs MCP tool lists all {backstage} entities with TechDocs. By default, the tool returns results in a JSON array format. Each entry includes entity details and TechDocs metadata, like last update timestamp and build information. + +By default, each entry in the JSON array is an entity with the following fields: `name`, `title`, `tags`, `description`, `owner`, `lifecycle`, `namespace`, `kind`, `techDocsUrl`, `matadataUrl` and `metadata`. + +The following examples show common queries: + +* “Fetch all techdocs from the {backstage} server” +* “Fetch all techdocs of the default namespace” +* “Fetch all techdocs created by user:john.doe” + +.Procedure +* Use the parameters as shown in the following table to configure your `fetch-techdocs` TechDocs MCP tool. + +|=== +| Name | Description | Example + +| `entityType` +| Filters entities by their type. +| "Component" + +| `namespace` +| Filter entities by their namespace. +| "default" + +| `owner` +| Filters entities by owner. +| "user:john.doe" + +| `lifecycle` +| Filters entities by their lifecycle. +| "development" + +| `tags` +| Filters entities by their tags. +| ["genai, "ibm", "llm", "granite", "conversational", "task-text-generation"] + +|=== diff --git a/modules/model-context-protocol-tools/proc-verifying-successful-installation-of-mcp-plugins.adoc b/modules/model-context-protocol-tools/proc-verifying-successful-installation-of-mcp-plugins.adoc new file mode 100644 index 0000000000..f880363121 --- /dev/null +++ b/modules/model-context-protocol-tools/proc-verifying-successful-installation-of-mcp-plugins.adoc @@ -0,0 +1,40 @@ +:_mod-docs-content-type: PROCEDURE + +[id="proc-verifying-successful-installation-of-mcp-plugins.adoc_{context}"] += Verifying successful installation of MCP plugins + +.Procedure + +. Log in to the OCP cluster running {product-very-short} and go to your {product-very-short} project using the following code: ++ +[source,subs="+attributes] +---- +oc project {my-product-namespace} +---- +. Inspect the logs for the installation of the {product-very-short} dynamic plugins using the following code: ++ +[source] +---- +oc logs -c install-dynamic-plugins deployment/ +---- + +.Verification + +. You must see an entry for the MCP backend server plugin as shown in the following code: ++ +[source] +---- +..... prior logs .... +======= Installing dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-plugin-mcp-actions-backend:bs_1.42.5__0.1.2!backstage-plugin-mcp-actions-backend + ==> Copying image oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-plugin-mcp-actions-backend:next__0.2.0 to local filesystem + ==> Successfully installed dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-plugin-mcp-actions-backend:bs_1.42.5__0.1.2!backstage-plugin-mcp-actions-backend +---- +. You must see entries for any of the MCP tool plugins you installed as shown in the following code: ++ +[source] +---- +..... prior logs .... +======= Installing dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool:bs_1.42.5__0.2.3!red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool + ==> Copying image oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool:bs_1.42.5__0.2.3!red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool to local filesystem + ==> Successfully installed dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool:bs_1.42.5__0.2.3!red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool +---- \ No newline at end of file diff --git a/titles/model-context-protocol-tools/artifacts b/titles/model-context-protocol-tools/artifacts new file mode 120000 index 0000000000..f30b6dea60 --- /dev/null +++ b/titles/model-context-protocol-tools/artifacts @@ -0,0 +1 @@ +../../artifacts \ No newline at end of file diff --git a/titles/model-context-protocol-tools/assemblies b/titles/model-context-protocol-tools/assemblies new file mode 120000 index 0000000000..91646274db --- /dev/null +++ b/titles/model-context-protocol-tools/assemblies @@ -0,0 +1 @@ +../../assemblies \ No newline at end of file diff --git a/titles/model-context-protocol-tools/docinfo.xml b/titles/model-context-protocol-tools/docinfo.xml new file mode 100644 index 0000000000..5f7fe2ebac --- /dev/null +++ b/titles/model-context-protocol-tools/docinfo.xml @@ -0,0 +1,11 @@ +{title} +{product} +{product-version} +{subtitle} + + {abstract} + + + {company-name} Customer Content Services + + diff --git a/titles/model-context-protocol-tools/images b/titles/model-context-protocol-tools/images new file mode 120000 index 0000000000..5fa6987088 --- /dev/null +++ b/titles/model-context-protocol-tools/images @@ -0,0 +1 @@ +../../images \ No newline at end of file diff --git a/titles/model-context-protocol-tools/master.adoc b/titles/model-context-protocol-tools/master.adoc new file mode 100644 index 0000000000..e47e3df2e7 --- /dev/null +++ b/titles/model-context-protocol-tools/master.adoc @@ -0,0 +1,9 @@ +include::artifacts/attributes.adoc[] +:context: title-model-context-protocol-tools +:imagesdir: images +:title: Interacting with Model Context Protocol tools for {product} +:subtitle: Leveraging the Model Context Protocol (MCP) server to integrate {product} ({product-very-short}) with AI clients +:abstract: Leverage the Model Context Protocol (MCP) server to integrate {product} ({product-very-short}) with AI clients. This connection provides a standardized method for AI applications to access {product-very-short} information and workflows through defined MCP tools. += {title} + +include::assemblies/assembly-model-context-protocol-tools.adoc[leveloffset=+1] diff --git a/titles/model-context-protocol-tools/modules b/titles/model-context-protocol-tools/modules new file mode 120000 index 0000000000..36719b9de7 --- /dev/null +++ b/titles/model-context-protocol-tools/modules @@ -0,0 +1 @@ +../../modules/ \ No newline at end of file