mcp typescript chatgpt claude cloudrun apps

Aplicación WeatherSG MCP: Herramientas adicionales y mapa interactivo en ChatGPT y Claude

WeatherSG, una aplicación MCP en TypeScript: contrato de datos, Streamable HTTP, despliegue en Cloud Run y registro de host para que ChatGPT y Claude muestren un mapa meteorológico en tiempo real.

Editor: REACTAPP.TOPAñadido a este sitio 26 sept 202616 min de lectura3664 palabras

Fuentes: How to Build and Deploy an MCP App

Las aplicaciones MCP amplían el Model Context Protocol más allá de las herramientas que devuelven texto: pueden entregar un recurso de interfaz de usuario interactiva que hosts como ChatGPT o Claude pueden mostrar. Esta guía muestra cómo crear WeatherSG en TypeScript: contrato de datos, obtención de información meteorológica, herramienta estándar, interfaz de mapa empaquetada como un único recurso HTML, transporte HTTP Streamable, despliegue en Cloud Run mediante contenedores y registro en ambos hosts.

Qué es una aplicación MCP

Un servidor sigue exponiendo herramientas y recursos; una aplicación, además, proporciona una interfaz front-end que el host integra después de que una llamada a herramienta la seleccione. El ciclo es: prompt → herramienta → recurso de UI → interacción del usuario → nuevas llamadas a herramientas según sea necesario.

Por qué TypeScript aquí

Un solo lenguaje para el servidor y el empaquetado de la UI mantiene pequeña la unidad de despliegue. Los tipos estrictos ayudan a que el contrato de datos sea preciso entre los normalizadores y la interfaz de mapa.

mkdir weathersg
cd weathersg
npm init -y

npm install \
  @modelcontextprotocol/sdk \
  @modelcontextprotocol/ext-apps \
  express leaflet react react-dom zod

npm install --save-dev \
  @types/express @types/leaflet @types/node \
  @types/react @types/react-dom \
  esbuild supertest tsx typescript vitest

Mantenga los secretos en el entorno de la plataforma; nunca incluya claves API en el HTML empaquetado.

{
  "scripts": {
    "build": "npm run build:web && tsc -p tsconfig.json",
    "build:web": "node scripts/build-web.mjs",
    "dev": "npm run build:web && tsx watch src/index.ts",
    "start": "node dist/src/index.js",
    "test": "vitest run",
    "typecheck": "tsc -p tsconfig.json --noEmit"
  },
  "engines": {
    "node": ">=20"
  }
}

Preferir HTTP transmisible para los hosts que esperan una URL de sesión MCP duradera.

weathersg/
  src/
    weather/
      schema.ts
      client.ts
    http-app.ts
    index.ts
    server.ts
  web/
    src/
      main.tsx
      styles.css
  scripts/
    build-web.mjs
  tests/
  Dockerfile
  package.json
  tsconfig.json

Las verificaciones de estado del contenedor deben dirigirse al endpoint MCP, y no solo a una página estática.

import { z } from "zod";

export const weatherLayerSchema = z.enum([
  "all",
  "forecast",
  "rainfall",
]);

const forecastAreaSchema = z.object({
  id: z.string(),
  name: z.string(),
  latitude: z.number(),
  longitude: z.number(),
  condition: z.string(),
  category: z.enum([
    "clear",
    "cloudy",
    "showers",
    "thunderstorms",
    "windy",
    "hazy",
    "unknown",
  ]),
});

const rainfallStationSchema = z.object({
  id: z.string(),
  name: z.string(),
  latitude: z.number(),
  longitude: z.number(),
  rainfallMm: z.number().nonnegative(),
});

export const weatherSnapshotSchema = z.object({
  layer: weatherLayerSchema,
  generatedAt: z.string(),
  forecast: z.object({
    updatedAt: z.string(),
    validFrom: z.string(),
    validTo: z.string(),
    validPeriodText: z.string(),
    areas: z.array(forecastAreaSchema),
  }).nullable(),
  rainfall: z.object({
    observedAt: z.string(),
    readingType: z.string(),
    unit: z.string(),
    stations: z.array(rainfallStationSchema),
  }).nullable(),
  summary: z.object({
    headline: z.string(),
    areasWithRain: z.number().int().nonnegative(),
    reportingRainStations: z.number().int().nonnegative(),
  }),
  warnings: z.array(z.string()),
  sources: z.array(z.object({
    label: z.string(),
    url: z.string().url(),
  })),
});

export type WeatherSnapshot = z.infer<typeof weatherSnapshotSchema>;

El registro del host es una configuración: vuelva a probar después de cada cambio en la URL o la autenticación.

async function fetchValidated<T>(
  url: string,
  schema: z.ZodType<T>,
  sourceLabel: string,
): Promise<{ value: T; warning?: string }> {
  const cached = cache.get(url);

  try {
    const response = await fetch(url, {
      headers: { Accept: "application/json" },
      signal: AbortSignal.timeout(8_000),
    });

    if (!response.ok) {
      throw new Error(`Weather service returned HTTP ${response.status}`);
    }
    const value = schema.parse(await response.json());
    cache.set(url, {
      value,
      expiresAt: Date.now() + 60_000,
    });
    return { value };
  } catch (error) {
    if (cached) {
      return {
        value: cached.value as T,
        warning: `${sourceLabel} could not be refreshed`,
      };
    }
    throw error;
  }
}

Considérelo como un punto de control: las pruebas de protocolo deben superarse antes de conectar cualquier host de chat.

const [forecastResult, rainfallResult] = await Promise.allSettled([
  fetchValidated(TWO_HOUR_FORECAST_URL, forecastSchema, "Forecast"),
  fetchValidated(RAINFALL_URL, rainfallSchema, "Rainfall"),
]);

Mantenga los secretos en el entorno de la plataforma; nunca incluya claves API en el HTML empaquetado.

return weatherSnapshotSchema.parse(snapshot);

Preferir HTTP transmisible para los hosts que esperan una URL de sesión MCP duradera.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { getSingaporeWeather } from "./weather/client.js";
import {
  weatherLayerSchema,
  weatherSnapshotSchema,
} from "./weather/schema.js";

const server = new McpServer(
  { name: "weathersg", version: "0.1.0" },
  {
    instructions:
      "Use get_singapore_weather for factual weather questions. " +
      "Use show_singapore_weather_map when the user asks to see, " +
      "map, compare, or explore weather across Singapore.",
  },
);

Las verificaciones de estado del contenedor deben dirigirse al endpoint MCP, y no solo a una página estática.

server.registerTool(
  "get_singapore_weather",
  {
    title: "Get Singapore weather",
    description:
      "Get current official two-hour forecasts and five-minute " +
      "rainfall observations across Singapore.",
    inputSchema: {
      layer: weatherLayerSchema.default("all"),
    },
    outputSchema: weatherSnapshotSchema,
    annotations: {
      readOnlyHint: true,
      destructiveHint: false,
      openWorldHint: false,
    },
  },
  async ({ layer }) => {
    const snapshot = await getSingaporeWeather(layer);
    return {
      structuredContent: snapshot,
      content: [{
        type: "text",
        text: `${snapshot.summary.headline} Snapshot generated at ${snapshot.generatedAt}.`,
      }],
    };
  },
);

El registro del host es una configuración: vuelva a probar después de cada cambio en la URL o la autenticación.

import {
  registerAppResource,
  registerAppTool,
  RESOURCE_MIME_TYPE,
} from "@modelcontextprotocol/ext-apps/server";

export const WEATHER_APP_URI =
  "ui://weathersg/singapore-weather-map/v1.html";

Considérelo como un punto de control: las pruebas de protocolo deben superarse antes de realizar cualquier conexión con el host de chat.

registerAppTool(
  server,
  "show_singapore_weather_map",
  {
    title: "Show Singapore weather map",
    description:
      "Show an interactive map of official forecasts and rainfall " +
      "observations across Singapore.",
    inputSchema: {
      layer: weatherLayerSchema.default("all"),
    },
    outputSchema: weatherSnapshotSchema,
    annotations: {
      readOnlyHint: true,
      destructiveHint: false,
      openWorldHint: false,
    },
    _meta: {
      ui: { resourceUri: WEATHER_APP_URI },
      "openai/toolInvocation/invoking": "Reading Singapore weather…",
      "openai/toolInvocation/invoked": "Singapore weather map ready",
    },
  },
  async ({ layer }) => {
    const snapshot = await getSingaporeWeather(layer);
    return {
      structuredContent: snapshot,
      content: [{
        type: "text",
        text: snapshot.summary.headline,
      }],
    };
  },
);

Mantenga los secretos en el entorno de la plataforma; nunca incluya claves API en el HTML empaquetado.

registerAppResource(
  server,
  "Singapore weather map",
  WEATHER_APP_URI,
  { description: "Interactive map of Singapore weather" },
  async () => ({
    contents: [{
      uri: WEATHER_APP_URI,
      mimeType: RESOURCE_MIME_TYPE,
      text: loadWeatherAppHtml(),
      _meta: {
        ui: {
          prefersBorder: true,
          csp: {
            connectDomains: [],
            resourceDomains: ["https://www.onemap.gov.sg"],
          },
        },
      },
    }],
  }),
);

Preferir HTTP transmisible para aquellos hosts que esperan una URL de sesión MCP duradera.

import { App } from "@modelcontextprotocol/ext-apps";
import { createRoot } from "react-dom/client";

const app = new App(
  { name: "WeatherSG map", version: "0.1.0" },
  {},
  { autoResize: true },
);

function parseSnapshot(value: unknown): WeatherSnapshot | null {
  if (!value || typeof value !== "object") return null;
  const candidate = value as Partial<WeatherSnapshot>;
  if (!candidate.summary || !Array.isArray(candidate.sources)) return null;
  if (!candidate.forecast && !candidate.rainfall) return null;
  return candidate as WeatherSnapshot;
}

app.ontoolresult = (result) => {
  const snapshot = parseSnapshot(result.structuredContent);
  if (snapshot) deliverSnapshot(snapshot);
};

createRoot(document.getElementById("root")!).render(<WeatherApp />);

void app.connect().catch((error) => {
  console.error("Unable to connect to the host", error);
});

Las verificaciones de estado del contenedor deben dirigirse al endpoint MCP, y no solo a una página estática.

await build({
  entryPoints: ["web/src/main.tsx"],
  bundle: true,
  minify: true,
  format: "esm",
  platform: "browser",
  write: false,
  outdir: "dist/web-bundle",
});

El registro del host es parte de la configuración: vuelva a probarlo después de cualquier cambio en la URL o en los métodos de autenticación.

npm run build

Considérelo como un punto de control: las pruebas de protocolo deben superarse antes de realizar cualquier conexión con el host de chat.

import { createMcpExpressApp } from
  "@modelcontextprotocol/sdk/server/express.js";
import { StreamableHTTPServerTransport } from
  "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { createWeatherMcpServer } from "./server.js";

const app = createMcpExpressApp();

app.post("/mcp", async (request, response) => {
  response.setHeader("Cache-Control", "no-store");

  const server = createWeatherMcpServer();
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined,
  });

  await server.connect(transport);

  response.on("close", () => {
    void transport.close();
    void server.close();
  });

  await transport.handleRequest(request, response, request.body);
});

Mantenga los secretos en el entorno de la plataforma; nunca incluya claves API en el HTML empaquetado.

app.get("/health", (_request, response) => {
  response.json({ status: "ok", service: "weathersg" });
});

app.get("/ready", (_request, response) => {
  const ready = existsSync("dist/web/weather-app.html");
  response.status(ready ? 200 : 503).json({
    status: ready ? "ready" : "not_ready",
  });
});

Preferir HTTP transmisible para aquellos hosts que esperan una URL de sesión MCP duradera.

const port = Number(process.env.PORT ?? 3000);
const app = createWeatherHttpApp();

app.listen(port, "0.0.0.0", () => {
  console.log(`WeatherSG listening on ${port}`);
});

Las verificaciones de estado del contenedor deben dirigirse al endpoint MCP, y no solo a una página estática.

npm run dev

El registro del host es una configuración: vuelva a probar después de cada cambio en la URL o en los métodos de autenticación.

npx @modelcontextprotocol/inspector@latest

Considérelo como un punto de control: las pruebas de protocolo deben superarse antes de conectar cualquier host de chat.

git clone https://github.com/modelcontextprotocol/ext-apps.git
cd ext-apps/examples/basic-host
npm install
SERVERS='["http://localhost:3000/mcp"]' npm start

Mantenga los datos confidenciales en el entorno de la plataforma; nunca incluya claves API en el HTML empaquetado.

npm run typecheck
npm test
npm run build

Prefiera HTTP con transmisión en flujo para los hosts que requieren una URL de sesión MCP estable.

FROM node:22-alpine AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:22-alpine AS runtime
WORKDIR /app
ENV NODE_ENV=production
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=5s \
  CMD ["node", "-e", "fetch('http://127.0.0.1:'+(process.env.PORT||3000)+'/ready').then(r=>{if(!r.ok)process.exit(1)}).catch(()=>process.exit(1))"]
CMD ["node", "dist/src/index.js"]

Las verificaciones de estado del contenedor deben dirigirse al endpoint MCP, y no solo a una página estática.

docker build -t weathersg .
docker run --rm -p 3000:3000 weathersg

El registro del host es una configuración: vuelva a probar después de cada cambio en la URL o en los métodos de autenticación.

gcloud auth login
gcloud config set project YOUR_PROJECT_ID
gcloud services enable \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  artifactregistry.googleapis.com

Considérelo como un punto de control: las pruebas de protocolo deben superarse antes de conectar cualquier host de chat.

gcloud run deploy weathersg \
  --source . \
  --region asia-southeast1 \
  --allow-unauthenticated \
  --set-env-vars PUBLISHER_NAME=WeatherSG

Mantenga los datos confidenciales en el entorno de la plataforma; nunca incluya claves API en el HTML empaquetado.

https://YOUR_SERVICE_HOST/mcp

Prefiera HTTP con transmisión en flujo para los hosts que requieren una URL de sesión MCP estable.

curl -fsS https://YOUR_SERVICE_HOST/health
curl -fsS https://YOUR_SERVICE_HOST/ready

Las verificaciones de estado del contenedor deben dirigirse al endpoint MCP, y no solo a una página estática.

Is it raining anywhere in Singapore right now?

Show me the Singapore weather map.

Now show only rainfall stations.

El registro del host es parte de la configuración: vuelva a probarlo después de cualquier cambio en la URL o en los métodos de autenticación.

https://YOUR_SERVICE_HOST/mcp

Considérelo como un punto de control: las pruebas de protocolo deben superarse antes de conectar cualquier host de chat.

Pruebas antes de la interfaz de chat

Utilice herramientas y recursos como un inspector MCP o un cliente con scripts. Los hosts de chat amplifican los fallos; tener el protocolo funcionando localmente ahorra horas de trabajo.

Despliegue y registro

Envíe el contenedor a Cloud Run (o un servicio equivalente), luego dirija los conectores de ChatGPT y Claude hacia la URL pública MCP con los encabezados de autenticación necesarios. Verifique nuevamente la interacción del mapa después de la terminación TLS.

Cierre

Una aplicación MCP es una superficie de producto que incluye el contrato, las herramientas, los recursos de interfaz, el transporte, el contenedor y la configuración del host. Si se omite algún componente, la demostración dejará de funcionar en el cliente de otra persona.

Versión de los contratos API junto a los IDs de los incrustadores.

Separar los controladores HTTP de los servicios puros para las pruebas unitarias.

Los temas de interfaz oscuro/claro no deben separar la lógica de recuperación.

Registrar los IDs de las consultas junto con las turnos de chat para su posterior triaje.

Volver a crear los índices a un ritmo acorde al cambio en las fuentes.

Rechazar cuando los segmentos principales parezcan débiles.

Versión de los contratos API junto a los IDs de los incrustadores.

Separar los controladores HTTP de los servicios puros para las pruebas unitarias.

Los temas de interfaz oscuro/claro no deben separar la lógica de recuperación.

Registrar los IDs de las consultas junto con las turnos de chat para su posterior triaje.

Volver a crear los índices a un ritmo acorde al cambio en las fuentes.

Rechazar cuando los segmentos principales parezcan débiles.

Versión de los contratos API junto a los IDs de los incrustadores.

Separar los controladores HTTP de los servicios puros para las pruebas unitarias.

Los temas de interfaz oscuro/claro no deben separar la lógica de recuperación.

Registrar los IDs de las consultas junto con las turnos de chat para su posterior triaje.

Volver a crear índices a un ritmo acorde al cambio en la fuente de datos.

Rechazar las solicitudes cuando los segmentos principales parezcan débiles.

Versionar los contratos de la API junto con los IDs de los incrustadores.

Separar los controladores HTTP de los servicios puros para pruebas unitarias.

Los temas de interfaz oscuro/claro no deben dividir la lógica de recuperación.

Registrar los IDs de las consultas junto con las turnos de chat para su posterior clasificación.