بناء أول خادم MCP باستخدام TypeScript: الأدوات والموارد والقوالب

mkdir my-mcp-server && cd my-mcp-server
npm init -y

npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node

npx tsc --init

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"]
}

{
  "name": "my-mcp-server",
  "version": "1.0.0",
  "type": "module",
  "bin": {
    "my-mcp-server": "./build/index.js"
  },
  "scripts": {
    "build": "tsc",
    "start": "node build/index.js",
    "dev": "tsc --watch"
  }
}

mkdir src

#!/usr/bin/env node
 
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
// Create the MCP server
const server = new McpServer({
  name: "my-mcp-server",
  version: "1.0.0",
});
 
// Connect using stdio transport
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("MCP server running on stdio");
}
 
main().catch(console.error);

npm run build

import { z } from "zod";
 
server.tool(
  "count_words",
  "Count the number of words in a given text",
  {
    text: z.string().describe("The text to count words in"),
  },
  async ({ text }) => {
    const wordCount = text
      .trim()
      .split(/\s+/)
      .filter((w) => w.length > 0).length;
 
    return {
      content: [
        {
          type: "text",
          text: `The text contains ${wordCount} words.`,
        },
      ],
    };
  }
);

server.tool(
  "check_url",
  "Check if a URL is reachable and return its HTTP status code",
  {
    url: z.string().url().describe("The URL to check"),
    timeout: z
      .number()
      .optional()
      .default(5000)
      .describe("Timeout in milliseconds"),
  },
  async ({ url, timeout }) => {
    try {
      const controller = new AbortController();
      const timeoutId = setTimeout(() => controller.abort(), timeout);
 
      const response = await fetch(url, {
        method: "HEAD",
        signal: controller.signal,
      });
 
      clearTimeout(timeoutId);
 
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                url,
                status: response.status,
                statusText: response.statusText,
                reachable: true,
              },
              null,
              2
            ),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                url,
                reachable: false,
                error:
                  error instanceof Error ? error.message : "Unknown error",
              },
              null,
              2
            ),
          },
        ],
        isError: true,
      };
    }
  }
);

server.tool(
  "calculate_bmi",
  "Calculate Body Mass Index from weight and height",
  {
    weightKg: z.number().positive().describe("Weight in kilograms"),
    heightM: z.number().positive().describe("Height in meters"),
  },
  async ({ weightKg, heightM }) => {
    const bmi = weightKg / (heightM * heightM);
    const category =
      bmi < 18.5
        ? "Underweight"
        : bmi < 25
        ? "Normal"
        : bmi < 30
        ? "Overweight"
        : "Obese";
 
    return {
      content: [
        {
          type: "text",
          text: `BMI: ${bmi.toFixed(1)} (${category})`,
        },
      ],
    };
  }
);

server.resource(
  "server-info",
  "info://server",
  async (uri) => {
    return {
      contents: [
        {
          uri: uri.href,
          mimeType: "application/json",
          text: JSON.stringify(
            {
              name: "my-mcp-server",
              version: "1.0.0",
              capabilities: ["word counting", "URL checking", "BMI calculation"],
              uptime: process.uptime(),
            },
            null,
            2
          ),
        },
      ],
    };
  }
);

// Simulated data store
const projects = new Map([
  [
    "web-app",
    {
      name: "Web Application",
      status: "active",
      tech: ["Next.js", "TypeScript", "PostgreSQL"],
    },
  ],
  [
    "api",
    {
      name: "REST API",
      status: "active",
      tech: ["Hono", "Bun", "SQLite"],
    },
  ],
  [
    "mobile",
    {
      name: "Mobile App",
      status: "planning",
      tech: ["React Native", "Expo"],
    },
  ],
]);
 
// Resource template — the {id} is a URI parameter
server.resource(
  "project",
  "projects://{id}",
  async (uri) => {
    const id = uri.pathname.replace("//", "");
    const project = projects.get(id);
 
    if (!project) {
      throw new Error(`Project "${id}" not found`);
    }
 
    return {
      contents: [
        {
          uri: uri.href,
          mimeType: "application/json",
          text: JSON.stringify(project, null, 2),
        },
      ],
    };
  }
);

server.prompt(
  "code-review",
  "Review code for bugs, security issues, and best practices",
  {
    code: z.string().describe("The code to review"),
    language: z
      .string()
      .optional()
      .default("typescript")
      .describe("Programming language"),
    focus: z
      .enum(["bugs", "security", "performance", "all"])
      .optional()
      .default("all")
      .describe("What to focus on in the review"),
  },
  async ({ code, language, focus }) => {
    const focusInstructions = {
      bugs: "Focus on finding logical errors, edge cases, and potential runtime exceptions.",
      security:
        "Focus on security vulnerabilities: injection, XSS, authentication flaws, data exposure.",
      performance:
        "Focus on performance: unnecessary allocations, O(n²) algorithms, missing caching.",
      all: "Review for bugs, security vulnerabilities, performance issues, and adherence to best practices.",
    };
 
    return {
      messages: [
        {
          role: "user",
          content: {
            type: "text",
            text: `Review the following ${language} code. ${focusInstructions[focus]}
 
\`\`\`${language}
${code}
\`\`\`
 
Provide your review as:
1. **Critical Issues** — Must fix before merging
2. **Warnings** — Should fix, but not blocking
3. **Suggestions** — Nice-to-have improvements
4. **Summary** — Overall code quality assessment`,
          },
        },
      ],
    };
  }
);

server.prompt(
  "generate-sql",
  "Generate SQL queries from natural language descriptions",
  {
    description: z
      .string()
      .describe("Natural language description of the query"),
    dialect: z
      .enum(["postgresql", "mysql", "sqlite"])
      .optional()
      .default("postgresql")
      .describe("SQL dialect to target"),
    schema: z
      .string()
      .optional()
      .describe("Database schema context (CREATE TABLE statements)"),
  },
  async ({ description, dialect, schema }) => {
    let contextBlock = "";
    if (schema) {
      contextBlock = `\nHere is the database schema:\n\`\`\`sql\n${schema}\n\`\`\`\n`;
    }
 
    return {
      messages: [
        {
          role: "user",
          content: {
            type: "text",
            text: `Generate a ${dialect} SQL query for the following request:
 
"${description}"
${contextBlock}
Requirements:
- Use proper ${dialect} syntax
- Include comments explaining the query
- Use parameterized queries where user input is involved
- Optimize for readability and performance`,
          },
        },
      ],
    };
  }
);

#!/usr/bin/env node
 
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
 
// ── Server ──────────────────────────────────────────────
 
const server = new McpServer({
  name: "my-mcp-server",
  version: "1.0.0",
});
 
// ── Tools ───────────────────────────────────────────────
 
server.tool(
  "count_words",
  "Count the number of words in a given text",
  { text: z.string().describe("The text to count words in") },
  async ({ text }) => {
    const wordCount = text
      .trim()
      .split(/\s+/)
      .filter((w) => w.length > 0).length;
 
    return {
      content: [{ type: "text", text: `The text contains ${wordCount} words.` }],
    };
  }
);
 
server.tool(
  "check_url",
  "Check if a URL is reachable and return its HTTP status code",
  {
    url: z.string().url().describe("The URL to check"),
    timeout: z.number().optional().default(5000).describe("Timeout in ms"),
  },
  async ({ url, timeout }) => {
    try {
      const controller = new AbortController();
      const timeoutId = setTimeout(() => controller.abort(), timeout);
      const response = await fetch(url, {
        method: "HEAD",
        signal: controller.signal,
      });
      clearTimeout(timeoutId);
 
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                url,
                status: response.status,
                statusText: response.statusText,
                reachable: true,
              },
              null,
              2
            ),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                url,
                reachable: false,
                error: error instanceof Error ? error.message : "Unknown error",
              },
              null,
              2
            ),
          },
        ],
        isError: true,
      };
    }
  }
);
 
// ── Resources ───────────────────────────────────────────
 
const projects = new Map([
  ["web-app", { name: "Web Application", status: "active", tech: ["Next.js", "TypeScript", "PostgreSQL"] }],
  ["api", { name: "REST API", status: "active", tech: ["Hono", "Bun", "SQLite"] }],
  ["mobile", { name: "Mobile App", status: "planning", tech: ["React Native", "Expo"] }],
]);
 
server.resource("server-info", "info://server", async (uri) => ({
  contents: [
    {
      uri: uri.href,
      mimeType: "application/json",
      text: JSON.stringify(
        {
          name: "my-mcp-server",
          version: "1.0.0",
          capabilities: ["word counting", "URL checking"],
          uptime: process.uptime(),
        },
        null,
        2
      ),
    },
  ],
}));
 
server.resource("project", "projects://{id}", async (uri) => {
  const id = uri.pathname.replace("//", "");
  const project = projects.get(id);
  if (!project) throw new Error(`Project "${id}" not found`);
  return {
    contents: [
      { uri: uri.href, mimeType: "application/json", text: JSON.stringify(project, null, 2) },
    ],
  };
});
 
// ── Prompts ─────────────────────────────────────────────
 
server.prompt(
  "code-review",
  "Review code for bugs, security issues, and best practices",
  {
    code: z.string().describe("The code to review"),
    language: z.string().optional().default("typescript").describe("Programming language"),
    focus: z
      .enum(["bugs", "security", "performance", "all"])
      .optional()
      .default("all")
      .describe("Review focus area"),
  },
  async ({ code, language, focus }) => {
    const focusMap = {
      bugs: "Focus on logical errors and edge cases.",
      security: "Focus on security vulnerabilities.",
      performance: "Focus on performance bottlenecks.",
      all: "Review bugs, security, performance, and best practices.",
    };
 
    return {
      messages: [
        {
          role: "user" as const,
          content: {
            type: "text" as const,
            text: `Review this ${language} code. ${focusMap[focus]}\n\n\`\`\`${language}\n${code}\n\`\`\``,
          },
        },
      ],
    };
  }
);
 
// ── Start ───────────────────────────────────────────────
 
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("MCP server running on stdio");
}
 
main().catch(console.error);

npm run build

npx @modelcontextprotocol/inspector node build/index.js

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/my-mcp-server/build/index.js"]
    }
  }
}

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/my-mcp-server/build/index.js"]
    }
  }
}

server.tool(
  "read_json_file",
  "Read and parse a JSON file",
  {
    path: z.string().describe("Path to the JSON file"),
  },
  async ({ path }) => {
    try {
      const { readFile } = await import("node:fs/promises");
      const content = await readFile(path, "utf-8");
      const parsed = JSON.parse(content);
 
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(parsed, null, 2),
          },
        ],
      };
    } catch (error) {
      if (error instanceof SyntaxError) {
        return {
          content: [{ type: "text", text: `Invalid JSON in file: ${path}` }],
          isError: true,
        };
      }
 
      const nodeError = error as NodeJS.ErrnoException;
      if (nodeError.code === "ENOENT") {
        return {
          content: [{ type: "text", text: `File not found: ${path}` }],
          isError: true,
        };
      }
 
      return {
        content: [
          {
            type: "text",
            text: `Error reading file: ${nodeError.message}`,
          },
        ],
        isError: true,
      };
    }
  }
);

const DEBUG = process.env.MCP_DEBUG === "true";
 
function debug(...args: unknown[]) {
  if (DEBUG) console.error("[DEBUG]", ...args);
}
 
// Use in tool handlers:
debug("check_url called with:", url);

MCP_DEBUG=true node build/index.js