MCPサーバー構築ガイド：TypeScript+PostgreSQLで経験を検索できるAIアシスタントを構築

sql
-- この例のようなSQLが実行できないとベクトル検索は実現できない
-- match_experiences.sql（実際に使用しているSQL）
CREATE OR REPLACE FUNCTION match_experiences(
  query_embedding vector,
  match_threshold float DEFAULT 0.7,
  match_count int DEFAULT 15
)
RETURNS TABLE (
  id uuid,
  title text,
  experience_json jsonb,
  unique_value text,
  applications text,
  original_quote text,
  related_articles jsonb,
  similarity float
)
LANGUAGE plpgsql
AS $$
BEGIN
  RETURN QUERY
  SELECT
    exp.id,
    exp.title,
    exp."experienceJson",
    exp."uniqueValue",
    exp.applications,
    exp."originalQuote",
    (
      SELECT jsonb_agg(jsonb_build_object(
        'title', art.title,
        'slug', art.slug
      ))
      FROM "ArticleExperience" ae
      JOIN "Article" art ON ae."articleId" = art.id
      WHERE ae."experienceId" = exp.id
    ) AS related_articles,
    1 - (exp.embedding <=> query_embedding) AS similarity
  FROM "Experience" exp
  WHERE exp.embedding IS NOT NULL
  AND 1 - (exp.embedding <=> query_embedding) > match_threshold
  ORDER BY similarity DESC
  LIMIT match_count;
END;
$$;

bash
mkdir my-mcp-server
cd my-mcp-server
npm init -y
npm install typescript @types/node --save-dev
npx tsc --init

bash
npm install @modelcontextprotocol/sdk dotenv zod
npm install @supabase/supabase-js # ベクトル検索用

typescript
#!/usr/bin/env node

// 本質部分: MCPサーバーの作成と起動
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { createMcpServer } from "./server.js";

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

main();

typescript
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
import { z } from "zod";
import { findExperiencesByText } from "./services/experience.js";

// 入力スキーマの定義
const FindRelevantExperiencesInputSchema = z.object({
  inputText: z.string().min(1, { message: "inputText は必須です" }),
  threshold: z.number().min(0).max(1).optional().default(0.7),
  count: z.number().int().positive().optional().default(15),
});

// MCPサーバーの定義
export function createMcpServer(): Server {
  const server = new Server(
    {
      name: "experience-extraction-mcp",
      version: "0.1.0",
    },
    {
      capabilities: {
        tools: {}, // ツールハンドラを設定
      },
    }
  );

  setupToolHandlers(server);
  return server;
}

// ツールハンドラの設定
function setupToolHandlers(server: Server): void {
  // 利用可能なツールをリストするハンドラ
  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [getFindRelevantExperiencesToolDefinition()],
  }));

  // `find_relevant_experiences` ツールを呼び出すハンドラ
  server.setRequestHandler(CallToolRequestSchema, async (request) => {
    // 本質部分: 引数を取得して経験検索を実行し結果を返す
    const { inputText, threshold, count } = request.params.arguments;
    const experiences = await findExperiencesByText(
      inputText,
      threshold,
      count
    );

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({ experiences }, null, 2),
        },
      ],
    };
  });
}

// ツール定義
function getFindRelevantExperiencesToolDefinition() {
  return {
    name: "find_relevant_experiences",
    description: "入力テキストに基づいて関連性の高い経験を検索する",
    inputSchema: {
      type: "object",
      properties: {
        inputText: {
          type: "string",
          description: "検索クエリテキスト",
          minLength: 1,
        },
        threshold: {
          type: "number",
          description: "類似度閾値（0.0-1.0）",
          minimum: 0,
          maximum: 1,
          default: 0.7,
        },
        count: {
          type: "integer",
          description: "返却する最大件数",
          minimum: 1,
          default: 15,
        },
      },
      required: ["inputText"],
    },
  };
}

typescript
// src/database/supabase.ts
import { createClient, SupabaseClient } from "@supabase/supabase-js";
import * as dotenv from "dotenv";

// 環境変数をロード
dotenv.config();

// Supabaseクライアントのシングルトンインスタンス
let supabaseInstance: SupabaseClient;

/**
 * Supabaseクライアントのシングルトンインスタンスを取得
 */
export function getSupabaseClient(): SupabaseClient {
  if (!supabaseInstance) {
    // 環境変数を取得
    const supabaseUrl = process.env.SUPABASE_URL || "";
    const supabaseAnonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY || "";

    // 環境変数のチェック
    if (!supabaseUrl) {
      console.error("環境変数 SUPABASE_URL が設定されていません。");
      throw new Error("環境変数 SUPABASE_URL が設定されていません。");
    }
    if (!supabaseAnonKey) {
      throw new Error(
        "環境変数 NEXT_PUBLIC_SUPABASE_ANON_KEY が設定されていません。"
      );
    }

    supabaseInstance = createClient(supabaseUrl, supabaseAnonKey);
    console.error("Supabase client initialized with URL:", supabaseUrl);
  }
  return supabaseInstance;
}

typescript
// src/database/rpc.ts
import { PostgrestError } from "@supabase/supabase-js";
import { getSupabaseClient } from "./supabase.js";
import { FoundExperience } from "../types/experience.js";

/**
 * 指定されたベクトルに類似する Experience を検索する Supabase RPC 関数を呼び出す
 */
export async function callMatchExperiencesRpc(
  embedding: number[],
  threshold: number = 0.7,
  count: number = 15
): Promise<{ data: FoundExperience[] | null; error: PostgrestError | null }> {
  const supabase = getSupabaseClient();

  // SQL で定義した RPC 関数を呼び出す
  const { data, error } = await supabase.rpc("match_experiences", {
    query_embedding: embedding,
    match_threshold: threshold,
    match_count: count,
  });

  if (error) {
    console.error("Error calling match_experiences RPC:", error);
    return { data: null, error };
  }

  // データベースから返された結果を適切な型に整形
  const formattedResults = data.map((item: any) => {
    // 関連記事の情報を整形
    let relatedArticle = null;

    if (item.related_articles && item.related_articles.length > 0) {
      const article = item.related_articles[0];
      relatedArticle = {
        title: article.title,
        path: `/ja/insight/${article.slug}`,
      };
    }

    return {
      id: item.id,
      title: item.title,
      experienceJson: item.experience_json,
      uniqueValue: item.unique_value,
      applications: item.applications,
      originalQuote: item.original_quote,
      similarity: item.similarity,
      relatedArticle: relatedArticle,
    };
  });

  console.error(
    `Found ${formattedResults.length} matching experiences via RPC.`
  );
  return { data: formattedResults, error: null };
}

typescript
// src/services/embedding.ts
import * as dotenv from "dotenv";

// 環境変数をロード
dotenv.config();

/**
 * 指定されたテキストを Azure OpenAI Embeddings API を使用してベクトル化
 */
export async function vectorizeText(text: string): Promise<number[]> {
  // 本質部分: テキストをベクトル化するAPI呼び出し
  const azureOpenaiEmbeddingUrl = process.env.AZURE_OPENAI_EMBEDDING_URL || "";
  const azureOpenaiKey = process.env.AZURE_OPENAI_KEY || "";

  const response = await fetch(azureOpenaiEmbeddingUrl, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "api-key": azureOpenaiKey,
    },
    body: JSON.stringify({ input: text }),
  });

  const data = await response.json();
  return data.data[0].embedding;
}

typescript
// src/services/experience.ts
import { PostgrestError } from "@supabase/supabase-js";
import { callMatchExperiencesRpc } from "../database/rpc.js";
import { FoundExperience } from "../types/experience.js";
import { vectorizeText } from "./embedding.js";

/**
 * 入力テキストに基づいて関連性の高い Experience を検索
 */
export async function findExperiencesByText(
  inputText: string,
  threshold: number = 0.7,
  count: number = 10
): Promise<FoundExperience[]> {
  // 本質部分: テキストをベクトル化して類似した経験を検索
  const queryVector = await vectorizeText(inputText);
  const { data } = await callMatchExperiencesRpc(queryVector, threshold, count);
  return data || [];
}

typescript
// src/types/experience.ts
/**
 * 関連記事の型定義
 */
export type ArticleReference = {
  title: string; // 記事タイトル
  path: string; // 記事パス (形式: /[lang]/[category]/[slug])
};

/**
 * 経験データの型定義
 */
export type ExperienceData = {
  context: string; // 経験の文脈
  insight: string; // 得られた洞察
  details: string; // その他の詳細
};

/**
 * MCPツール`find_relevant_experiences`の返却値の型定義
 */
export type FoundExperience = {
  id: string; // 経験ID
  title: string; // 経験タイトル
  experienceJson: any; // 経験の詳細情報
  uniqueValue: string; // 独自の価値
  applications: string; // 応用可能性
  originalQuote: string; // 原文引用
  similarity: number; // 類似度スコア（0.0-1.0）
  relatedArticle: ArticleReference | null; // 関連記事 (1対1の紐付け)
};

/**
 * MCPツール`find_relevant_experiences`の返却値全体の型定義
 */
export type FindRelevantExperiencesOutput = {
  experiences: FoundExperience[];
};

sql
-- pgvector拡張機能が利用可能か確認
SELECT * FROM pg_extension WHERE extname = 'vector';

-- まだ入っていなければ拡張機能を追加
CREATE EXTENSION IF NOT EXISTS vector;

-- ベクトル検索用のRPC関数
CREATE OR REPLACE FUNCTION match_experiences(
  query_embedding vector,
  match_threshold float DEFAULT 0.7,
  match_count int DEFAULT 15
)
RETURNS TABLE (
  id uuid,
  title text,
  experience_json jsonb,
  unique_value text,
  applications text,
  original_quote text,
  related_articles jsonb,
  similarity float
)
LANGUAGE plpgsql
AS $$
BEGIN
  RETURN QUERY
  SELECT
    exp.id,
    exp.title,
    exp."experienceJson",
    exp."uniqueValue",
    exp.applications,
    exp."originalQuote",
    (
      SELECT jsonb_agg(jsonb_build_object(
        'title', art.title,
        'slug', art.slug
      ))
      FROM "ArticleExperience" ae
      JOIN "Article" art ON ae."articleId" = art.id
      WHERE ae."experienceId" = exp.id
    ) AS related_articles,
    1 - (exp.embedding <=> query_embedding) AS similarity
  FROM "Experience" exp
  WHERE exp.embedding IS NOT NULL
  AND 1 - (exp.embedding <=> query_embedding) > match_threshold
  ORDER BY similarity DESC
  LIMIT match_count;
END;
$$;

json
{
  "scripts": {
    "inspector": "npx @modelcontextprotocol/inspector build/index.js"
  }
}

bash
npm run inspector

bash
npm run build
node build/index.js

json
# ~/Library/Application Support/Claude/claude_desktop_config.json (Mac の場合)
{
  "mcpServers": {
    ...
    "experience-mcp-server": {
      "command": "node",
      "args": [
        "${path}/build/index.js"
      ],
      "env": {
        "ENV_VARIABLE": "**********",
      }
    }
    ...
  }
}