@pagopa/dx-mcpserver 0.0.1

package/README.md

@@ -0,0 +1,104 @@
+# @pagopa/dx-mcpserver
+
+> An MCP server that support developers using DX tools.
+
+This package contains the implementation of a Model Context Protocol (MCP) server.
+
+## Architecture
+
+The architecture allows any Model Context Protocol (MCP) compliant client (such as GitHub Copilot) to query the [PagoPA DX technical documentation](https://dx.pagopa.it/) in natural language, receiving contextualized and up-to-date answers.
+
+1.  **Content Upload**: On each release of the documentation website, Markdown and text files (`.md`, `.txt`) are uploaded to an S3 bucket.
+2.  **Indexing**: From there, the documents are processed by **Amazon Bedrock Knowledge Bases**, which handles the embedding and semantic indexing process.
+3.  **Vector Storage**: The resulting embeddings are saved in a Vector Bucket (an S3-based vector database), enabling efficient and persistent semantic search.
+4.  **Query and Retrieval**: When an MCP client sends a query, an **AWS Lambda** function implementing the MCP Server queries the Knowledge Base to retrieve the most relevant content and returns the response to the client.
+
+This approach allows AI agents like Copilot to access the documentation context in a structured way, keeping the orchestration, storage, and semantic retrieval layers separate.
+
+## Features
+
+The server currently exposes the following capabilities:
+
+- **Tools**:
+  - `QueryPagoPADXDocumentation`: Queries Amazon Bedrock Knowledge Bases to retrieve relevant content from the [DX documentation](https://dx.pagopa.it/).
+  - `SearchGitHubCode`: Searches for code snippets in specified GitHub organization (defaults to pagopa), allowing users to find real-world examples of code usage.
+- **Prompts**:
+  - `GenerateTerraformConfiguration`: Guides the generation of Terraform configurations following PagoPA DX best practices.
+
+## How to use it
+
+This server can be used by any MCP-compliant client.
+
+<details>
+<summary><b>VS Code</b></summary>
+
+Update your configuration file with the following. See [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more info.
+
+#### VS Code Remote Server Connection
+
+```json
+{
+  "servers": {
+    "dx-docs": {
+      "url": "https://api.dev.dx.pagopa.it/mcp",
+      "type": "http",
+      "headers": {
+        "x-gh-pat": "${env:GH_PAT}"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>GitHub Copilot Coding Agent</b></summary>
+You need to configure it in the repository settings. See [GitHub Copilot MCP docs](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/extend-coding-agent-with-mcp) for more info.
+
+1.  **Declare the MCP Server**: In the "Copilot" >> "Coding agent" panel of your repository settings, add an MCP Server declaration as follows:
+
+```json
+{
+  "mcpServers": {
+    "pagopa-dx": {
+      "url": "https://api.dev.dx.pagopa.it/mcp",
+      "type": "http",
+      "tools": ["*"],
+      "headers": {
+        "x-gh-pat": "$COPILOT_MCP_BOT_GH_PAT"
+      }
+    }
+  }
+}
+```
+
+2.  **Configure Authentication**: Add any necessary tokens or secrets (e.g., `COPILOT_MCP_BOT_GH_PAT`) as secrets in the repository's Copilot configuration. This allows the coding agent to use them when querying the server.
+
+Once configured, Copilot can autonomously invoke the MCP server's tools during task execution, using it to access documentation context and improve the quality of its code generation.
+
+</details>
+
+## Development
+
+This is a standard TypeScript project. To get started:
+
+```bash
+pnpm install
+pnpm --filter @pagopa/dx-mcpserver build
+```
+
+You can run the following scripts:
+
+- `pnpm --filter @pagopa/dx-mcpserver lint`: Lints the code.
+- `pnpm --filter @pagopa/dx-mcpserver format`: Formats the code.
+- `pnpm --filter @pagopa/dx-mcpserver test`: Runs tests.
+- `pnpm --filter @pagopa/dx-mcpserver typecheck`: Checks types.
+
+### Docker
+
+To build the Docker container for this application, run the following command from the root of the monorepo:
+
+```bash
+docker build -t dx/mcp-server -f ./apps/mcpserver/Dockerfile .
+```

package/dist/auth/__tests__/githubAuth.test.js

@@ -0,0 +1,56 @@
+import { Octokit } from "@octokit/rest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { logger } from "../../utils/logger.js";
+import * as githubAuth from "../github.js";
+vi.mock("@octokit/rest");
+describe("verifyGithubUser", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        process.env.REQUIRED_ORGANIZATIONS = "pagopa";
+    });
+    it("returns false if no token is provided", async () => {
+        const result = await githubAuth.verifyGithubUser("");
+        expect(result).toBe(false);
+    });
+    it("returns false if Octokit throws", async () => {
+        vi.mocked(Octokit).mockImplementation(() => ({
+            rest: {
+                orgs: {
+                    listForAuthenticatedUser: vi
+                        .fn()
+                        .mockRejectedValue(new Error("fail")),
+                },
+            },
+        }));
+        const errorLog = vi.spyOn(logger, "error");
+        const result = await githubAuth.verifyGithubUser("token");
+        expect(result).toBe(false);
+        expect(errorLog).toHaveBeenCalledWith(expect.any(Error), "Error verifying GitHub organization membership:");
+    });
+    it("returns false if user is not member of required org", async () => {
+        vi.mocked(Octokit).mockImplementation(() => ({
+            rest: {
+                orgs: {
+                    listForAuthenticatedUser: vi.fn().mockResolvedValue({
+                        data: [{ login: "otherorg" }],
+                    }),
+                },
+            },
+        }));
+        const result = await githubAuth.verifyGithubUser("token");
+        expect(result).toBe(false);
+    });
+    it("returns true if user is member of required org", async () => {
+        vi.mocked(Octokit).mockImplementation(() => ({
+            rest: {
+                orgs: {
+                    listForAuthenticatedUser: vi.fn().mockResolvedValue({
+                        data: [{ login: "pagopa" }],
+                    }),
+                },
+            },
+        }));
+        const result = await githubAuth.verifyGithubUser("token");
+        expect(result).toBe(true);
+    });
+});

package/dist/auth/github.js

@@ -0,0 +1,37 @@
+import { Octokit } from "@octokit/rest";
+import { z } from "zod/v4";
+import { logger } from "../utils/logger.js";
+const organizationsSchema = z
+    .array(z.string().nonempty())
+    .nonempty()
+    .transform((orgs) => orgs.map((org) => org.trim()))
+    .catch(["pagopa"]);
+const REQUIRED_ORGANIZATIONS = organizationsSchema.parse(process.env.REQUIRED_ORGANIZATIONS);
+/**
+ * Verifies that a user, identified by a GitHub personal access token, is a member
+ * of at least one of the required GitHub organizations.
+ * @param token The user's GitHub personal access token.
+ * @returns A boolean indicating whether the user is a member of a required organization.
+ */
+export async function verifyGithubUser(token) {
+    if (!token) {
+        return false;
+    }
+    const octokit = new Octokit({ auth: token });
+    try {
+        // Fetches the user's organization memberships using Octokit.
+        const { data: organizations } = await octokit.rest.orgs.listForAuthenticatedUser();
+        const isMember = organizations.some((org) => REQUIRED_ORGANIZATIONS.includes(org.login));
+        if (isMember) {
+            logger.info(`User is a member of one of the required organizations: ${REQUIRED_ORGANIZATIONS.join(", ")}`);
+        }
+        else {
+            logger.warn(`User is not a member of any of the required organizations: ${REQUIRED_ORGANIZATIONS.join(", ")}`);
+        }
+        return isMember;
+    }
+    catch (error) {
+        logger.error(error, "Error verifying GitHub organization membership:");
+        return false;
+    }
+}

package/dist/config/__tests__/awsConfig.test.js

@@ -0,0 +1,24 @@
+import { describe, expect, it, vi } from "vitest";
+vi.mock("../../utils/logger", () => ({
+    logger: {
+        error: vi.fn(),
+        info: vi.fn(),
+        warn: vi.fn(),
+    },
+}));
+import * as awsConfig from "../aws.js";
+describe("aws config", () => {
+    it("should export kbRerankingEnabled as boolean", () => {
+        expect(typeof awsConfig.kbRerankingEnabled).toBe("boolean");
+    });
+    it("should export knowledgeBaseId as string", () => {
+        expect(typeof awsConfig.knowledgeBaseId).toBe("string");
+    });
+    it("should export region as string", () => {
+        expect(typeof awsConfig.region).toBe("string");
+    });
+    it("should export kbRuntimeClient as object", () => {
+        expect(typeof awsConfig.kbRuntimeClient).toBe("object");
+        expect(awsConfig.kbRuntimeClient).toHaveProperty("send");
+    });
+});

package/dist/config/aws.js

@@ -0,0 +1,26 @@
+import { BedrockAgentRuntimeClient } from "@aws-sdk/client-bedrock-agent-runtime";
+import { logger } from "../utils/logger.js";
+// When true, enables reranking for the Bedrock knowledge base queries.
+export const kbRerankingEnabled = (process.env.BEDROCK_KB_RERANKING_ENABLED || "true").trim().toLowerCase() ===
+    "true";
+export const knowledgeBaseId = process.env.BEDROCK_KNOWLEDGE_BASE_ID || "";
+logger.info(`Default reranking enabled: ${kbRerankingEnabled} (from BEDROCK_KB_RERANKING_ENABLED)`);
+export const region = process.env.AWS_REGION || "eu-central-1";
+// List of AWS regions that support reranking
+export const rerankingSupportedRegions = [
+    "ap-northeast-1",
+    "ca-central-1",
+    "eu-central-1",
+    "us-east-1",
+    "us-west-2",
+];
+let kbRuntimeClient;
+try {
+    // Initializes the Bedrock Agent Runtime client with the specified region.
+    kbRuntimeClient = new BedrockAgentRuntimeClient({ region });
+}
+catch (e) {
+    logger.error(e, "Error getting bedrock agent client");
+    process.exit(1);
+}
+export { kbRuntimeClient };

package/dist/config/server.js

@@ -0,0 +1,4 @@
+/**
+ * The main instruction for the MCP server, defining its purpose.
+ */
+export const serverInstructions = `Use this Server as the source for everything related to PagoPA Developer Experience (DX/DevEx/Platform).`;

package/dist/index.js

@@ -0,0 +1,44 @@
+import { FastMCP } from "fastmcp";
+import { verifyGithubUser } from "./auth/github.js";
+import { serverInstructions } from "./config/server.js";
+import { GenerateTerraformConfigurationPrompt } from "./prompts/GenerateTerraformConfiguration.js";
+import { QueryPagoPADXDocumentationTool } from "./tools/QueryPagoPADXDocumentation.js";
+import { SearchGitHubCodeTool } from "./tools/SearchGitHubCode.js";
+import { logger } from "./utils/logger.js";
+// Authentication is enabled based on the AUTH_REQUIRED environment variable.
+const server = new FastMCP({
+    authenticate: async (request) => {
+        const authHeader = request.headers["x-gh-pat"];
+        const apiKey = typeof authHeader === "string"
+            ? authHeader
+            : Array.isArray(authHeader)
+                ? authHeader[0]
+                : undefined;
+        if (!apiKey || !(await verifyGithubUser(apiKey))) {
+            throw new Response(null, {
+                status: 401,
+                statusText: "Unauthorized",
+            });
+        }
+        // The returned object is accessible in the `context.session`.
+        return {
+            id: 1,
+            token: apiKey,
+        };
+    },
+    instructions: serverInstructions,
+    name: "PagoPA DX Knowledge Retrieval MCP Server",
+    version: "0.0.0",
+});
+logger.debug(`Server instructions: \n\n${serverInstructions}`);
+server.addPrompt(GenerateTerraformConfigurationPrompt);
+server.addTool(QueryPagoPADXDocumentationTool);
+server.addTool(SearchGitHubCodeTool);
+// Starts the server in HTTP Stream mode.
+server.start({
+    httpStream: {
+        port: 8080,
+        stateless: true,
+    },
+    transportType: "httpStream",
+});

package/dist/prompts/GenerateTerraformConfiguration.js

@@ -0,0 +1,29 @@
+/**
+ * A prompt that generates a Terraform configuration following PagoPA DX best practices.
+ * It guides the user to query the knowledge base for information on folder structure,
+ * modules, and conventions before generating the code.
+ */
+export const GenerateTerraformConfigurationPrompt = {
+    // The arguments for the prompt.
+    arguments: [
+        {
+            description: "Requirements for the Terraform configuration to generate.",
+            name: "requirements",
+            required: false,
+        },
+    ],
+    // The description of the prompt.
+    description: "Generates a Terraform configuration following PagoPA DX best practices.",
+    // The function that loads the prompt.
+    load: async (args) => `To generate a Terraform configuration for ${args.requirements || "any requirement"}, you must follow the PagoPA DX best practices.
+
+You can find information about the "infrastructure folder structure", "Using DX terraform modules", "Using DX terraform provider" and other conventions by using the \`QueryPagoPADXDocumentation\` tool. For example, you can ask "what is the infrastructure folder structure?", but you must ask for the other information as well.
+It's suggested to call the \`QueryPagoPADXDocumentation\` tool multiple times to gather all the necessary information using simple and scoped questions.
+
+When generating the configuration, remember to:
+1.  Use existing Terraform modules from the \`pagopa-dx\` namespace whenever possible. You can search for them using the \`searchModules\` tool.
+2.  Strictly follow the correct folder structure for infrastructure resources.
+3.  Generate HCL code that is clean, readable, and well-documented.`,
+    // The name of the prompt.
+    name: "generate-terraform-configuration",
+};

package/dist/services/__tests__/bedrock.test.js

@@ -0,0 +1,44 @@
+import { describe, expect, it, vi } from "vitest";
+vi.mock("../../utils/logger", () => ({
+    logger: {
+        error: vi.fn(),
+        info: vi.fn(),
+        warn: vi.fn(),
+    },
+}));
+import { queryKnowledgeBase } from "../bedrock.js";
+describe("queryKnowledgeBase", () => {
+    it("should skip images in results", async () => {
+        const mockClient = {
+            config: {
+                apiVersion: "2023-11-20",
+                region: async () => "eu-central-1",
+                requestHandler: { handle: vi.fn() },
+            },
+            destroy: vi.fn(),
+            middlewareStack: {},
+            send: vi.fn().mockResolvedValue({
+                retrievalResults: [
+                    { content: { text: "doc1", type: "TEXT" } },
+                    { content: { type: "IMAGE" } },
+                ],
+            }),
+        };
+        const result = await queryKnowledgeBase("kbId", "query", mockClient, 2, false);
+        expect(result).toContain("doc1");
+    });
+    it("should warn if reranking is not supported in region", async () => {
+        const mockClient = {
+            config: {
+                apiVersion: "2023-11-20",
+                region: async () => "unsupported-region",
+                requestHandler: { handle: vi.fn() },
+            },
+            destroy: vi.fn(),
+            middlewareStack: {},
+            send: vi.fn().mockResolvedValue({ retrievalResults: [] }),
+        };
+        const result = await queryKnowledgeBase("kbId", "query", mockClient, 2, true);
+        expect(typeof result).toBe("string");
+    });
+});

package/dist/services/__tests__/resolveToWebsiteUrl.test.js

@@ -0,0 +1,67 @@
+it("returns dx.pagopa.it/llms-full.txt for llms-full.txt", () => {
+    const location = {
+        s3Location: {
+            uri: "s3://bucket/llms-full.txt",
+        },
+        type: "S3",
+    };
+    const result = resolveToWebsiteUrl(location);
+    expect(result?.webLocation?.url).toBe("https://dx.pagopa.it/llms-full.txt");
+});
+it("returns dx.pagopa.it/llms.txt for llms.txt", () => {
+    const location = {
+        s3Location: {
+            uri: "s3://bucket/llms.txt",
+        },
+        type: "S3",
+    };
+    const result = resolveToWebsiteUrl(location);
+    expect(result?.webLocation?.url).toBe("https://dx.pagopa.it/llms.txt");
+});
+it("returns dx.pagopa.it/blog/ for keys starting with /blog/", () => {
+    const location = {
+        s3Location: {
+            uri: "s3://bucket/blog/some-post.md",
+        },
+        type: "S3",
+    };
+    const result = resolveToWebsiteUrl(location);
+    expect(result?.webLocation?.url).toBe("https://dx.pagopa.it/blog/");
+});
+import { describe, expect, it } from "vitest";
+import { resolveToWebsiteUrl } from "../bedrock.js";
+describe("resolveToWebsiteUrl", () => {
+    it("converte una chiave S3 .md in url dx.pagopa.it/docs", () => {
+        const location = {
+            s3Location: {
+                uri: "s3://bucket/azure/iam.md",
+            },
+            type: "S3",
+        };
+        const result = resolveToWebsiteUrl(location);
+        expect(result?.webLocation?.url).toBe("https://dx.pagopa.it/docs/azure/iam");
+    });
+    it("converte una chiave S3 index.md in url dx.pagopa.it/docs con slash finale", () => {
+        const location = {
+            s3Location: {
+                uri: "s3://bucket/pipelines/index.md",
+            },
+            type: "S3",
+        };
+        const result = resolveToWebsiteUrl(location);
+        expect(result?.webLocation?.url).toBe("https://dx.pagopa.it/docs/pipelines/");
+    });
+    it("ignora location non S3", () => {
+        const location = {
+            type: "WEB",
+            webLocation: {
+                url: "https://example.com",
+            },
+        };
+        const result = resolveToWebsiteUrl(location);
+        expect(result?.webLocation?.url).toBe("https://example.com");
+    });
+    it("restituisce undefined se location è undefined", () => {
+        expect(resolveToWebsiteUrl(undefined)).toBeUndefined();
+    });
+});

package/dist/services/bedrock.js

@@ -0,0 +1,160 @@
+import { RetrieveCommand, } from "@aws-sdk/client-bedrock-agent-runtime";
+import { rerankingSupportedRegions } from "../config/aws.js";
+import { logger } from "../utils/logger.js";
+/**
+ * Queries a Bedrock knowledge base with a given query, handling reranking and result serialization.
+ * This method interacts with the AWS Bedrock service to retrieve knowledge base results.
+ * It supports reranking of results in specific AWS regions using predefined models.
+ *
+ * @param knowledgeBaseId The ID of the knowledge base to query.
+ * @param query The natural language query.
+ * @param kbAgentClient The Bedrock Agent Runtime client.
+ * @param numberOfResults The maximum number of results to return (default: 5).
+ * @param reranking Whether to enable reranking of the results (default: false).
+ * @param rerankingModelName The reranking model to use (default: AMAZON).
+ * @returns A serialized string of the query results.
+ */
+export async function queryKnowledgeBase(knowledgeBaseId, query, kbAgentClient, numberOfResults = 5, reranking = false, rerankingModelName = "AMAZON") {
+    const clientRegion = await kbAgentClient.config.region();
+    let rerankingEnabled = reranking;
+    // Reranking is only supported in specific AWS regions.
+    if (reranking && !rerankingSupportedRegions.includes(clientRegion)) {
+        logger.warn(`Reranking is not supported in region ${clientRegion}`);
+        rerankingEnabled = false;
+    }
+    const retrieveRequest = {
+        vectorSearchConfiguration: {
+            numberOfResults,
+        },
+    };
+    if (rerankingEnabled && retrieveRequest.vectorSearchConfiguration) {
+        const modelNameMapping = {
+            AMAZON: "amazon.rerank-v1:0",
+            COHERE: "cohere.rerank-v3-5:0",
+        };
+        retrieveRequest.vectorSearchConfiguration.rerankingConfiguration = {
+            bedrockRerankingConfiguration: {
+                modelConfiguration: {
+                    modelArn: `arn:aws:bedrock:${clientRegion}::foundation-model/${modelNameMapping[rerankingModelName]}`,
+                },
+            },
+            type: "BEDROCK_RERANKING_MODEL",
+        };
+    }
+    const command = new RetrieveCommand({
+        knowledgeBaseId,
+        retrievalConfiguration: retrieveRequest,
+        retrievalQuery: { text: query },
+    });
+    const response = await kbAgentClient.send(command);
+    const results = response.retrievalResults || [];
+    const documents = [];
+    for (const result of results) {
+        if (result.content?.type === "IMAGE") {
+            logger.warn("Images are not supported at this time. Skipping...");
+            continue;
+        }
+        else if (result.content?.text) {
+            documents.push({
+                content: result.content.text,
+                location: resolveToWebsiteUrl(result.location),
+                score: result.score || -1.0,
+            });
+        }
+    }
+    return serializeResults(documents);
+}
+/**
+ * Resolves an S3 location from a knowledge base result to a public website URL.
+ * This method converts S3 URIs to publicly accessible URLs based on specific rules.
+ * If the location is not an S3 URI, it returns the original location.
+ *
+ * @param location The original location object from the retrieval result.
+ * @returns A new location object with a `WEB` type and a URL, or the original location if no conversion is needed.
+ */
+export function resolveToWebsiteUrl(location) {
+    if (!location) {
+        return undefined;
+    }
+    // If the location is an S3 URI, convert it to a dx.pagopa.it URL.
+    if (typeof location === "object" &&
+        location.type === "S3" &&
+        location.s3Location?.uri) {
+        // The uri format is: s3://bucket/key
+        const match = location.s3Location.uri.match(/^s3:\/\/(?:[^/]+)\/(.+)$/);
+        if (match) {
+            const key = match[1];
+            let url = "";
+            // Special case: llms-full.txt or llms.txt should be returned as https://dx.pagopa.it/<file>
+            if (key === "llms-full.txt" || key === "llms.txt") {
+                url = `https://dx.pagopa.it/${key}`;
+            }
+            // Special case: if key starts with blog/, return https://dx.pagopa.it/blog/
+            else if (key.startsWith("blog/")) {
+                url = "https://dx.pagopa.it/blog/";
+            }
+            // If the key ends with /index.md, return the directory with trailing slash
+            else if (key.endsWith("/index.md")) {
+                url = `https://dx.pagopa.it/docs/${key.replace(/\/index\.md$/, "")}/`;
+            }
+            // Otherwise, remove .md and return the documentation path
+            else {
+                url = `https://dx.pagopa.it/docs/${key.replace(/\.md$/, "")}`;
+            }
+            // Return a RetrievalResultLocation object of type WEB with the computed URL
+            return {
+                type: "WEB",
+                webLocation: {
+                    url,
+                },
+            };
+        }
+    }
+    else {
+        // If not S3, return the original location (e.g. WEB, SHAREPOINT, etc.)
+        return location;
+    }
+    // If unable to determine the URL, return undefined
+    return undefined;
+}
+/**
+ * Serializes an array of knowledge base query results into a formatted string.
+ * This method formats the results for better readability, including content, location, and score.
+ *
+ * Example:
+ * Input:
+ * ```json
+ * [
+ *   { "content": "Result 1 content", "location": { "webLocation": { "url": "https://example.com" } }, "score": 0.95 },
+ *   { "content": "Result 2 content", "location": null, "score": 0.85 }
+ * ]
+ * ```
+ *
+ * Output:
+ * ```
+ * Result 1 (Score: 0.9500):
+ * Result 1 content
+ * Location: https://example.com
+ *
+ * Result 2 (Score: 0.8500):
+ * Result 2 content
+ * Location: undefined
+ * ```
+ */
+function serializeResults(results) {
+    return results
+        .map((result, index) => {
+        let locationStr = "";
+        if (result.location &&
+            typeof result.location === "object" &&
+            "webLocation" in result.location &&
+            result.location.webLocation?.url) {
+            locationStr = result.location.webLocation.url;
+        }
+        else if (result.location) {
+            locationStr = JSON.stringify(result.location);
+        }
+        return `Result ${index + 1} (Score: ${result.score.toFixed(4)}):\n${result.content}\nLocation: ${locationStr}\n`;
+    })
+        .join("\n\n");
+}

package/dist/tools/QueryPagoPADXDocumentation.js

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import { kbRerankingEnabled, kbRuntimeClient, knowledgeBaseId, } from "../config/aws.js";
+import { queryKnowledgeBase } from "../services/bedrock.js";
+/**
+ * A tool that provides access to the complete Terraform documentation for PagoPA Dx.
+ * It uses a Bedrock knowledge base to answer queries about Terraform modules and best practices.
+ */
+export const QueryPagoPADXDocumentationTool = {
+    annotations: {
+        title: "Query PagoPA DX Terraform documentation",
+    },
+    description: `This tool provides access to the complete Terraform documentation for PagoPA Dx.
+Use this knowledge base to generate or review Terraform configurations aligned with the official PagoPA Dx module conventions.
+All prompts and questions should be written in English, so that the tool responds using English resource and variable names.
+The tool should be used to explain, guide, or suggest Terraform usage based on verified module documentation and internal best practices.
+Use only modules from the pagopa-dx namespace. To get terraform modules descriptions, input/output variables and examples, use the \`searchModules\` tool.
+`,
+    execute: async (args) => {
+        const result = await queryKnowledgeBase(knowledgeBaseId, args.query, kbRuntimeClient, undefined, kbRerankingEnabled);
+        return result;
+    },
+    name: "QueryPagoPADXTerraformDocumentation",
+    parameters: z.object({
+        query: z
+            .string()
+            .describe("A natural language query in English used to search the DX documentation for relevant information."),
+    }),
+};

package/dist/tools/SearchGitHubCode.js

@@ -0,0 +1,83 @@
+import { Octokit } from "@octokit/rest";
+import { z } from "zod";
+import { logger } from "../utils/logger.js";
+const defaultOrg = process.env.GITHUB_SEARCH_ORG || "pagopa";
+/**
+ * A tool that searches for code in a GitHub organization.
+ * Useful for finding examples of Terraform module usage or specific code patterns.
+ */
+export const SearchGitHubCodeTool = {
+    annotations: {
+        title: "Search GitHub organization code",
+    },
+    description: `Search for code in a GitHub organization (defaults to pagopa).
+Use this to find examples of specific code patterns, such as Terraform module usage.
+For example, search for "pagopa-dx/azure-function-app/azurerm" to find examples of the azure-function-app module usage.
+Returns file contents matching the search query.`,
+    execute: async (args, context) => {
+        const org = defaultOrg;
+        const token = context.session?.token;
+        if (!token) {
+            throw new Error("GitHub token not available in session");
+        }
+        const octokit = new Octokit({ auth: token });
+        try {
+            const extensionFilter = args.extension
+                ? ` extension:${args.extension}`
+                : "";
+            const searchQuery = `${args.query} org:${org}${extensionFilter}`;
+            logger.info(`Searching GitHub: ${searchQuery}`);
+            const { data } = await octokit.rest.search.code({
+                per_page: 10,
+                q: searchQuery,
+            });
+            if (data.items.length === 0) {
+                return JSON.stringify({ message: "No results found", results: [] });
+            }
+            const results = await Promise.all(data.items.map(async (item) => {
+                try {
+                    const { data: fileContent } = await octokit.rest.repos.getContent({
+                        owner: org,
+                        path: item.path,
+                        repo: item.repository.name,
+                    });
+                    if ("content" in fileContent) {
+                        return {
+                            content: Buffer.from(fileContent.content, "base64").toString("utf-8"),
+                            path: item.path,
+                            repository: item.repository.full_name,
+                            url: item.html_url,
+                        };
+                    }
+                    return null;
+                }
+                catch (error) {
+                    logger.error(error, `Error fetching file ${item.path}`);
+                    return null;
+                }
+            }));
+            const validResults = results.filter((r) => r !== null);
+            return JSON.stringify({
+                organization: org,
+                query: args.query,
+                results: validResults,
+                returned_results: validResults.length,
+                total_results: data.total_count,
+            });
+        }
+        catch (error) {
+            logger.error(error, "Error searching GitHub code");
+            throw error;
+        }
+    },
+    name: "SearchGitHubCode",
+    parameters: z.object({
+        extension: z
+            .string()
+            .optional()
+            .describe('File extension to filter results (e.g., "tf" for Terraform files, "py" for Python files). For example, you can use "tf" to find Terraform module usage examples.'),
+        query: z
+            .string()
+            .describe('Code search query (e.g., "pagopa-dx/azure-function-app/azurerm" to find Terraform module usage examples)'),
+    }),
+};

package/dist/tools/__tests__/QueryPagoPADXDocumentation.test.js

@@ -0,0 +1,22 @@
+import { describe, expect, it, vi } from "vitest";
+vi.mock("../../services/bedrock", () => ({
+    queryKnowledgeBase: vi.fn().mockResolvedValue("mocked result"),
+}));
+vi.mock("../../config/aws", () => ({
+    kbRerankingEnabled: false,
+    kbRuntimeClient: "mockClient",
+    knowledgeBaseId: "mockKbId",
+}));
+import { QueryPagoPADXDocumentationTool } from "../QueryPagoPADXDocumentation.js";
+describe("QueryPagoPADXDocumentationTool", () => {
+    it("should return results from the knowledge base", async () => {
+        const args = { number_of_results: 3, query: "test query" };
+        const result = await QueryPagoPADXDocumentationTool.execute(args);
+        expect(result).toBe("mocked result");
+    });
+    it("should use default number_of_results if not provided", async () => {
+        const args = { query: "test query" };
+        const result = await QueryPagoPADXDocumentationTool.execute(args);
+        expect(result).toBe("mocked result");
+    });
+});

package/dist/utils/__tests__/logger.test.js

@@ -0,0 +1,21 @@
+import { describe, expect, it, vi } from "vitest";
+vi.mock("../logger", () => ({
+    logger: {
+        error: vi.fn(),
+        info: vi.fn(),
+        warn: vi.fn(),
+    },
+}));
+import { logger } from "../logger.js";
+describe("logger", () => {
+    it("should have info, warn, error methods", () => {
+        expect(typeof logger.info).toBe("function");
+        expect(typeof logger.warn).toBe("function");
+        expect(typeof logger.error).toBe("function");
+    });
+    it("should not throw when calling info, warn, error", () => {
+        expect(() => logger.info("test info")).not.toThrow();
+        expect(() => logger.warn("test warn")).not.toThrow();
+        expect(() => logger.error("test error")).not.toThrow();
+    });
+});

package/dist/utils/logger.js

@@ -0,0 +1,9 @@
+import pino from "pino";
+import { pinoLambdaDestination } from "pino-lambda";
+// Creates a Pino logger instance configured for Lambda environments.
+const destination = pinoLambdaDestination();
+export const logger = pino({
+    transport: {
+        target: "pino-pretty",
+    },
+}, destination);

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@pagopa/dx-mcpserver",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "An MCP server that support developers using DX tools.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pagopa/dx.git",
+    "directory": "apps/mcpserver"
+  },
+  "keywords": [
+    "DX",
+    "MCP"
+  ],
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "dx": "./dist/index.js"
+  },
+  "dependencies": {
+    "@aws-sdk/client-bedrock-agent-runtime": "^3.583.0",
+    "@octokit/rest": "^22.0.0",
+    "axios": "^1.12.2",
+    "fastmcp": "^3.19.1",
+    "pino": "^9.1.0",
+    "pino-lambda": "^4.4.1",
+    "pino-pretty": "^13.1.1",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^22.16.2",
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^9.30.0",
+    "typescript": "~5.8.3",
+    "vitest": "^3.2.4",
+    "@pagopa/eslint-config": "^5.1.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint --fix src",
+    "lint:check": "eslint src",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  }
+}