MCPサーバーの作り方2026年完全ガイド：TypeScript・Python両対応チュートリアル

#!/usr/bin/env node
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import * as fs from "fs/promises";
import * as path from "path";

// サーバーインスタンス作成
const server = new McpServer({
  name: "file-explorer",
  version: "1.0.0",
});

// ルートディレクトリ（環境変数 or デフォルト）
const ROOT_DIR = process.env.MCP_ROOT_DIR || process.cwd();

// ツール1: ファイル一覧取得
server.tool(
  "list_files",
  "指定パターンにマッチするファイルの一覧を返す",
  {
    directory: z.string().describe("検索するディレクトリの相対パス"),
    extension: z.string().optional().describe("フィルタする拡張子（例: .md, .ts）"),
  },
  async ({ directory, extension }) => {
    const targetDir = path.resolve(ROOT_DIR, directory);
    
    // ディレクトリトラバーサル防止
    if (!targetDir.startsWith(ROOT_DIR)) {
      return { content: [{ type: "text", text: "エラー: ルートディレクトリ外へのアクセスは禁止" }] };
    }
    
    const entries = await fs.readdir(targetDir, { withFileTypes: true, recursive: true });
    let files = entries
      .filter(e => e.isFile())
      .map(e => path.relative(ROOT_DIR, path.join(e.parentPath || targetDir, e.name)));
    
    if (extension) {
      files = files.filter(f => f.endsWith(extension));
    }
    
    return {
      content: [{ type: "text", text: files.join("\n") || "ファイルが見つかりません" }],
    };
  }
);

// ツール2: ファイル読み取り
server.tool(
  "read_file",
  "指定パスのファイル内容を返す",
  {
    file_path: z.string().describe("読み取るファイルの相対パス"),
    max_lines: z.number().optional().default(200).describe("最大行数（デフォルト200）"),
  },
  async ({ file_path, max_lines }) => {
    const fullPath = path.resolve(ROOT_DIR, file_path);
    
    if (!fullPath.startsWith(ROOT_DIR)) {
      return { content: [{ type: "text", text: "エラー: ルートディレクトリ外へのアクセスは禁止" }] };
    }
    
    const content = await fs.readFile(fullPath, "utf-8");
    const lines = content.split("\n").slice(0, max_lines);
    const truncated = content.split("\n").length > max_lines
      ? `\n\n--- (${content.split("\n").length - max_lines}行省略) ---`
      : "";
    
    return {
      content: [{ type: "text", text: lines.join("\n") + truncated }],
    };
  }
);

// ツール3: ファイル内テキスト検索
server.tool(
  "search_files",
  "ファイル内容をキーワード検索し、マッチした行を返す",
  {
    query: z.string().describe("検索キーワード"),
    directory: z.string().optional().default(".").describe("検索ディレクトリ"),
    extension: z.string().optional().describe("対象拡張子"),
  },
  async ({ query, directory, extension }) => {
    const targetDir = path.resolve(ROOT_DIR, directory);
    if (!targetDir.startsWith(ROOT_DIR)) {
      return { content: [{ type: "text", text: "エラー: アクセス禁止" }] };
    }
    
    const entries = await fs.readdir(targetDir, { withFileTypes: true, recursive: true });
    const results: string[] = [];
    
    for (const entry of entries) {
      if (!entry.isFile()) continue;
      const filePath = path.join(entry.parentPath || targetDir, entry.name);
      if (extension && !filePath.endsWith(extension)) continue;
      
      try {
        const content = await fs.readFile(filePath, "utf-8");
        const lines = content.split("\n");
        lines.forEach((line, i) => {
          if (line.toLowerCase().includes(query.toLowerCase())) {
            const relPath = path.relative(ROOT_DIR, filePath);
            results.push(`${relPath}:${i + 1}: ${line.trim()}`);
          }
        });
      } catch { /* バイナリファイル等はスキップ */ }
    }
    
    return {
      content: [{ type: "text", text: results.slice(0, 50).join("\n") || "マッチなし" }],
    };
  }
);

// リソース: プロジェクト情報
server.resource(
  "project-info",
  "project://info",
  async (uri) => ({
    contents: [{
      uri: uri.href,
      mimeType: "text/plain",
      text: `ルートディレクトリ: ${ROOT_DIR}\nサーバー: file-explorer v1.0.0`,
    }],
  })
);

// サーバー起動
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("file-explorer MCPサーバーが起動しました");
}

main().catch(console.error);

#!/usr/bin/env node
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "github-explorer",
  version: "1.0.0",
});

const GITHUB_TOKEN = process.env.GITHUB_TOKEN || "";

async function githubFetch(endpoint: string) {
  const headers: Record<string, string> = {
    "Accept": "application/vnd.github.v3+json",
    "User-Agent": "mcp-github-explorer",
  };
  if (GITHUB_TOKEN) {
    headers["Authorization"] = `Bearer ${GITHUB_TOKEN}`;
  }
  
  const res = await fetch(`https://api.github.com${endpoint}`, { headers });
  if (!res.ok) throw new Error(`GitHub API error: ${res.status}`);
  return res.json();
}

// ツール: リポジトリ情報取得
server.tool(
  "get_repo",
  "GitHubリポジトリの詳細情報を取得する",
  {
    owner: z.string().describe("リポジトリオーナー"),
    repo: z.string().describe("リポジトリ名"),
  },
  async ({ owner, repo }) => {
    const data = await githubFetch(`/repos/${owner}/${repo}`);
    const info = [
      `📦 ${data.full_name}`,
      `⭐ ${data.stargazers_count.toLocaleString()} stars`,
      `🍴 ${data.forks_count.toLocaleString()} forks`,
      `📝 ${data.description || "説明なし"}`,
      `🔧 言語: ${data.language || "不明"}`,
      `📅 最終更新: ${new Date(data.updated_at).toLocaleDateString("ja-JP")}`,
      `📄 ライセンス: ${data.license?.spdx_id || "不明"}`,
    ].join("\n");
    
    return { content: [{ type: "text", text: info }] };
  }
);

// ツール: リポジトリ検索
server.tool(
  "search_repos",
  "キーワードでGitHubリポジトリを検索する",
  {
    query: z.string().describe("検索キーワード"),
    sort: z.enum(["stars", "forks", "updated"]).optional().default("stars"),
    limit: z.number().optional().default(10),
  },
  async ({ query, sort, limit }) => {
    const data = await githubFetch(
      `/search/repositories?q=${encodeURIComponent(query)}&sort=${sort}&per_page=${limit}`
    );
    
    const results = data.items.map((item: any, i: number) =>
      `${i + 1}. ${item.full_name} (⭐${item.stargazers_count}) - ${item.description || ""}`
    );
    
    return {
      content: [{ type: "text", text: `検索結果 (${data.total_count}件中${limit}件):\n\n${results.join("\n")}` }],
    };
  }
);

// ツール: Issue一覧取得
server.tool(
  "list_issues",
  "リポジトリのオープンIssue一覧を取得する",
  {
    owner: z.string(),
    repo: z.string(),
    limit: z.number().optional().default(10),
  },
  async ({ owner, repo, limit }) => {
    const data = await githubFetch(`/repos/${owner}/${repo}/issues?state=open&per_page=${limit}`);
    
    const issues = data.map((issue: any) =>
      `#${issue.number} ${issue.title} (${issue.labels.map((l: any) => l.name).join(", ") || "ラベルなし"})`
    );
    
    return {
      content: [{ type: "text", text: issues.join("\n") || "オープンIssueなし" }],
    };
  }
);

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main().catch(console.error);

// ❌ 悪い例：パストラバーサル脆弱性
server.tool("read", { path: z.string() }, async ({ path }) => {
  const content = await fs.readFile(path, "utf-8"); // ../../etc/passwd が読める
  return { content: [{ type: "text", text: content }] };
});

// ✅ 良い例：ルートディレクトリ制限
server.tool("read", { path: z.string() }, async ({ path }) => {
  const fullPath = path.resolve(ROOT_DIR, path);
  if (!fullPath.startsWith(ROOT_DIR)) {
    throw new Error("Access denied");
  }
  const content = await fs.readFile(fullPath, "utf-8");
  return { content: [{ type: "text", text: content }] };
});

// ❌ stdoutに出力 → JSON-RPCが壊れる
console.log("デバッグ情報");

// ✅ stderrに出力 → 安全
console.error("デバッグ情報");