Cómo crear un servidor MCP en TypeScript: conecta tus propias herramientas con agentes de IA

mkdir unsplashx
cd unsplashx
npm init -y

npm install @modelcontextprotocol/sdk

{
  "name": "unsplashx",
  "version": "1.1.0",
  "description": "Unsplash MCP Server",
  "main": "index.js",
  "type": "module",
  "bin": {
    "unsplashx": "./index.js"
  },
  "scripts": {
    "start": "node index.js"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.4"
  }
}

#!/usr/bin/env node
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
import fs from "fs/promises";
import path from "path";
 
const UNSPLASH_ACCESS_KEY = process.env.UNSPLASH_ACCESS_KEY || process.argv[2];
const API_BASE = "https://api.unsplash.com";
 
if (!UNSPLASH_ACCESS_KEY) {
  console.error("Error: UNSPLASH_ACCESS_KEY is required.");
  process.exit(1);
}
 
const server = new Server(
  { name: "unsplash-mcp", version: "1.1.0" },
  { capabilities: { tools: {} } }
);

async function fetchUnsplash(endpoint, params = {}) {
  const url = new URL(`${API_BASE}${endpoint}`);
  Object.entries(params).forEach(([key, value]) => {
    if (value !== undefined) url.searchParams.append(key, value);
  });
 
  const response = await fetch(url, {
    headers: {
      Authorization: `Client-ID ${UNSPLASH_ACCESS_KEY}`,
      "Accept-Version": "v1",
    },
  });
 
  if (!response.ok) {
    throw new Error(`Unsplash API error: ${response.statusText}`);
  }
 
  return response.json();
}

const searchPhotosTool = {
  name: "search_photos",
  description: "Search for high-quality photos on Unsplash.",
  inputSchema: {
    type: "object",
    properties: {
      query: { type: "string", description: "Search keyword (e.g. 'abstract dark network')" },
      count: { type: "number", description: "Number of results (max 30)", default: 5 },
      orientation: {
        type: "string",
        enum: ["landscape", "portrait", "squarish"],
        description: "Filter by orientation",
      },
    },
    required: ["query"],
  },
};

const downloadToProjectTool = {
  name: "download_to_project",
  description: "Download a photo locally to your project directory. Automatically tracks the download.",
  inputSchema: {
    type: "object",
    properties: {
      photo_id: { type: "string", description: "The Unsplash photo ID" },
      destination_dir: { type: "string", description: "Absolute path to destination directory" },
      file_name: { type: "string", description: "Desired file name (e.g., 'cover.jpeg')" },
      width: { type: "number", description: "Optional width in pixels" },
      height: { type: "number", description: "Optional height in pixels" },
      quality: { type: "number", description: "Optional quality (1-100)", default: 80 },
    },
    required: ["photo_id", "destination_dir", "file_name"],
  },
};

server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [searchPhotosTool, downloadToProjectTool],
  };
});

async function handleSearchPhotos(args) {
  const results = await fetchUnsplash("/search/photos", {
    query: args.query,
    per_page: args.count || 5,
    orientation: args.orientation,
  });
 
  const photos = results.results.map((p) => ({
    id: p.id,
    description: p.description || p.alt_description,
    preview_url: p.urls.small,
    photographer: p.user.name,
    attribution: `Photo by [${p.user.name}](${p.user.links.html}?utm_source=unsplashx&utm_medium=referral) on [Unsplash](https://unsplash.com/?utm_source=unsplashx&utm_medium=referral)`,
  }));
 
  return {
    content: [{ type: "text", text: JSON.stringify(photos, null, 2) }],
  };
}

async function handleDownloadToProject(args) {
  const photo = await fetchUnsplash(`/photos/${args.photo_id}`);
 
  // Requerido por Unsplash: registrar la descarga de la foto
  await fetchUnsplash(`/photos/${args.photo_id}/download`);
 
  const url = new URL(photo.urls.regular);
  if (args.width) url.searchParams.set("w", args.width);
  if (args.height) url.searchParams.set("h", args.height);
  if (args.quality) url.searchParams.set("q", args.quality);
 
  const response = await fetch(url.toString());
  const buffer = Buffer.from(await response.arrayBuffer());
 
  const fullPath = path.join(args.destination_dir, args.file_name);
  await fs.mkdir(args.destination_dir, { recursive: true });
  await fs.writeFile(fullPath, buffer);
 
  const attribution = `Photo by [${photo.user.name}](${photo.user.links.html}?utm_source=unsplashx&utm_medium=referral) on [Unsplash](https://unsplash.com/?utm_source=unsplashx&utm_medium=referral)`;
 
  return {
    content: [
      {
        type: "text",
        text: `Successfully downloaded photo to ${fullPath}.\n\nREQUIRED ATTRIBUTION:\n${attribution}`,
      },
    ],
  };
}

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
 
  try {
    if (name === "search_photos") return await handleSearchPhotos(args);
    if (name === "download_to_project") return await handleDownloadToProject(args);
    throw new Error(`Unknown tool: ${name}`);
  } catch (error) {
    return {
      content: [{ type: "text", text: `Error: ${error.message}` }],
      isError: true,
    };
  }
});

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Unsplash MCP Server running on stdio");
}
 
main().catch((error) => {
  console.error("Fatal error:", error);
  process.exit(1);
});

{
  "mcpServers": {
    "unsplashx": {
      "command": "npx",
      "args": ["-y", "unsplashx"],
      "env": {
        "UNSPLASH_ACCESS_KEY": "YOUR_UNSPLASH_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "unsplashx": {
      "command": "npx",
      "args": ["-y", "unsplashx"],
      "env": {
        "UNSPLASH_ACCESS_KEY": "YOUR_UNSPLASH_KEY"
      }
    }
  }
}