@esaio/esa-mcp-server 0.1.0

package/src/i18n/__tests__/index.test.ts

@@ -0,0 +1,53 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { initI18n, setLanguage, t } from "../index.js";
+
+describe("i18n", () => {
+  // Helper to set language environment variable and initialize i18n
+  const initI18nWithLang = async (envVar: string, value: string) => {
+    vi.stubEnv(envVar, value);
+    return await initI18n();
+  };
+
+  beforeEach(() => {
+    vi.resetModules();
+    vi.stubEnv("LC_ALL", undefined);
+    vi.stubEnv("LC_MESSAGES", undefined);
+    vi.stubEnv("LANG", undefined);
+    vi.stubEnv("LANGUAGE", undefined);
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("should detect language from LC_ALL env var", async () => {
+    const i18n = await initI18nWithLang("LC_ALL", "ja_JP.UTF-8");
+    expect(i18n.language).toBe("ja");
+  });
+
+  it("should detect language from LC_MESSAGES env var", async () => {
+    const i18n = await initI18nWithLang("LC_MESSAGES", "ja_JP.UTF-8");
+    expect(i18n.language).toBe("ja");
+  });
+
+  it("should detect language from LANG env var", async () => {
+    const i18n = await initI18nWithLang("LANG", "ja_JP.UTF-8");
+    expect(i18n.language).toBe("ja");
+  });
+
+  it("should detect language from LANGUAGE env var", async () => {
+    const i18n = await initI18nWithLang("LANGUAGE", "ja_JP.UTF-8");
+    expect(i18n.language).toBe("ja");
+  });
+
+  it("should fallback to en when no env vars are set", async () => {
+    const i18n = await initI18n();
+    expect(i18n.language).toBe("en");
+  });
+
+  it("should change language dynamically with setLanguage", async () => {
+    await initI18n();
+    await setLanguage("ja");
+    expect(t("prompts.summarize_post.title")).toContain("要約");
+  });
+});

package/src/i18n/index.ts

@@ -0,0 +1,39 @@
+import i18next from "i18next";
+import enTranslations from "../locales/en.json" with { type: "json" };
+import jaTranslations from "../locales/ja.json" with { type: "json" };
+
+export async function initI18n() {
+  // https://github.com/neet/i18next-cli-language-detector/blob/main/src/i18next-cli-language-detector.ts
+  // を参考に簡易版の環境変数からの自動検出
+  const lng =
+    process.env.LC_ALL?.split(/[-_.]/)[0] ||
+    process.env.LC_MESSAGES?.split(/[-_.]/)[0] ||
+    process.env.LANG?.split(/[-_.]/)[0] ||
+    process.env.LANGUAGE?.split(/[-_.]/)[0] ||
+    "en";
+  await i18next.init({
+    lng,
+    fallbackLng: "en",
+    resources: {
+      ja: {
+        translation: jaTranslations,
+      },
+      en: {
+        translation: enTranslations,
+      },
+    },
+    interpolation: {
+      escapeValue: false,
+    },
+  });
+
+  return i18next;
+}
+
+export function setLanguage(lng: string) {
+  return i18next.changeLanguage(lng);
+}
+
+export function t(key: string, options?: Record<string, unknown>) {
+  return i18next.t(key, options);
+}

package/src/index.ts

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { config, validateConfig } from "./config/index.js";
+import { initI18n } from "./i18n/index.js";
+import { setupPrompts } from "./prompts/index.js";
+import { setupResources } from "./resources/index.js";
+import { setupTools } from "./tools/index.js";
+
+try {
+  validateConfig();
+} catch (error) {
+  console.error("Configuration error:", error);
+  process.exit(1);
+}
+
+async function main() {
+  await initI18n();
+
+  const server = new McpServer({
+    name: config.server.name,
+    version: config.server.version,
+  });
+
+  setupTools(server, config.esa);
+  setupResources(server, config.esa);
+  setupPrompts(server, config.esa);
+
+  const transport = new StdioServerTransport();
+
+  // Handle transport errors gracefully
+  transport.onclose = () => {
+    console.error("Transport closed");
+  };
+
+  transport.onerror = (error) => {
+    console.error("Transport error:", error);
+  };
+
+  await server.connect(transport);
+  console.error(`${config.server.name} v${config.server.version} started`);
+}
+
+await main().catch((error) => {
+  console.error("Server startup error:", error);
+  process.exit(1);
+});

package/src/locales/en.json

@@ -0,0 +1,13 @@
+{
+  "prompts": {
+    "summarize_post": {
+      "title": "Summarize esa post",
+      "description": "Summarize an esa post in various formats (bullet points, paragraph, or keywords)",
+      "args": {
+        "team_name": "The name of the esa team",
+        "post_number": "The post number to summarize",
+        "format": "Summary format (bullet/paragraph/keywords)"
+      }
+    }
+  }
+}

package/src/locales/ja.json

@@ -0,0 +1,13 @@
+{
+  "prompts": {
+    "summarize_post": {
+      "title": "esaの記事の要約",
+      "description": "esa記事を指定した形式で要約します(bullet: 箇条書き, paragraph: 文章, keywords: キーワード)",
+      "args": {
+        "team_name": "esaチーム名",
+        "post_number": "要約する記事番号",
+        "format": "要約形式 (bullet/paragraph/keywords)"
+      }
+    }
+  }
+}

package/src/prompts/__tests__/index.test.ts

@@ -0,0 +1,47 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { MCPContext } from "../../context/mcp-context.js";
+import { setupPrompts } from "../index.js";
+
+describe("setupPrompts", () => {
+  let server: McpServer;
+  let context: MCPContext;
+  let consoleErrorSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    server = new McpServer({
+      name: "test-server",
+      version: "1.0.0",
+    });
+    context = {} as unknown as MCPContext;
+
+    consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    consoleErrorSpy.mockRestore();
+  });
+
+  it("should register all prompts with correct handlers", () => {
+    const registerPromptSpy = vi.spyOn(server, "registerPrompt");
+
+    setupPrompts(server, context);
+
+    expect(registerPromptSpy).toHaveBeenCalledTimes(1);
+
+    for (let i = 0; i < 1; i++) {
+      const [promptName, schema, handler] = registerPromptSpy.mock.calls[i];
+      expect(typeof promptName).toBe("string");
+      expect(promptName).toMatch(/^esa_/); // All prompts should start with 'esa_'
+      expect(schema).toBeTypeOf("object"); // Schema verification handled by individual prompt tests
+      expect(handler).toBeTypeOf("function"); // Handler functionality tested in specific prompt tests
+    }
+  });
+
+  it("should log setup completion message", () => {
+    setupPrompts(server, context);
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith("Setting up MCP prompts...");
+  });
+});

package/src/prompts/__tests__/summarize-post.test.ts

@@ -0,0 +1,291 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { createEsaClient } from "../../api_client/index.js";
+import { createSummarizePostSchema, summarizePost } from "../summarize-post.js";
+
+describe("createSummarizePostSchema", () => {
+  it("should create schema with proper fields", () => {
+    const schema = createSummarizePostSchema();
+    const shape = schema.shape;
+
+    expect(shape.teamName).toBeDefined();
+    expect(shape.postNumber).toBeDefined();
+    expect(shape.format).toBeDefined();
+  });
+
+  it("should validate correct input", () => {
+    const schema = createSummarizePostSchema();
+    const result = schema.safeParse({
+      teamName: "test-team",
+      postNumber: "123",
+      format: "bullet",
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  it("should allow optional format", () => {
+    const schema = createSummarizePostSchema();
+    const result = schema.safeParse({
+      teamName: "test-team",
+      postNumber: "123",
+    });
+
+    expect(result.success).toBe(true);
+  });
+});
+
+describe("summarizePost", () => {
+  const mockClient = {
+    GET: vi.fn(),
+  } as unknown as ReturnType<typeof createEsaClient> & {
+    GET: ReturnType<typeof vi.fn>;
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  const mockPost = {
+    number: 123,
+    name: "test-post.md",
+    full_name: "dev/test-post.md #tag1 #tag2",
+    wip: false,
+    body_md: "# Test Post\n\nThis is a test post content.",
+    body_html: "<h1>Test Post</h1><p>This is a test post content.</p>",
+    created_at: "2024-01-01T00:00:00+09:00",
+    updated_at: "2024-01-02T00:00:00+09:00",
+    message: "Update test post",
+    url: "https://test-team.esa.example.com/posts/123",
+    category: "dev",
+    tags: ["tag1", "tag2"],
+    revision_number: 3,
+    created_by: {
+      name: "user1",
+      screen_name: "user1",
+      icon: "https://example.com/icon1.png",
+    },
+    updated_by: {
+      name: "user2",
+      screen_name: "user2",
+      icon: "https://example.com/icon2.png",
+    },
+    kind: "stock",
+    comments_count: 5,
+    tasks_count: 3,
+    done_tasks_count: 2,
+    stargazers_count: 10,
+    watchers_count: 8,
+    star: true,
+    watch: false,
+  };
+
+  it("should generate a bullet format summary prompt", async () => {
+    mockClient.GET.mockResolvedValue({
+      data: mockPost,
+      error: undefined,
+      response: {
+        ok: true,
+        status: 200,
+      } as Response,
+    });
+
+    const result = await summarizePost(mockClient, {
+      teamName: "test-team",
+      postNumber: "123",
+    });
+
+    expect(mockClient.GET).toHaveBeenCalledWith(
+      "/v1/teams/{team_name}/posts/{post_number}",
+      {
+        params: {
+          path: { team_name: "test-team", post_number: 123 },
+        },
+      },
+    );
+
+    expect(result.messages).toHaveLength(1);
+    expect(result.messages[0].role).toBe("user");
+    expect(result.messages[0].content.type).toBe("text");
+
+    const promptText = result.messages[0].content.text;
+    expect(promptText).toContain("Please summarize the following post:");
+    expect(promptText).toContain("Title: test-post.md");
+    expect(promptText).toContain(
+      "URL: https://test-team.esa.example.com/posts/123",
+    );
+    expect(promptText).toContain("Author: user1");
+    expect(promptText).toContain("Category: dev");
+    expect(promptText).toContain("Tags: tag1, tag2");
+    expect(promptText).toContain("# Test Post");
+    expect(promptText).toContain("Please provide a summary in bullet points");
+  });
+
+  it("should generate a paragraph format summary prompt", async () => {
+    mockClient.GET.mockResolvedValue({
+      data: mockPost,
+      error: undefined,
+      response: {
+        ok: true,
+        status: 200,
+      } as Response,
+    });
+
+    const result = await summarizePost(mockClient, {
+      teamName: "test-team",
+      postNumber: "123",
+      format: "paragraph",
+    });
+
+    const promptText = result.messages[0].content.text;
+    expect(promptText).toContain("Please provide a summary in 2-3 paragraphs");
+  });
+
+  it("should generate a keywords format summary prompt", async () => {
+    mockClient.GET.mockResolvedValue({
+      data: mockPost,
+      error: undefined,
+      response: {
+        ok: true,
+        status: 200,
+      } as Response,
+    });
+
+    const result = await summarizePost(mockClient, {
+      teamName: "test-team",
+      postNumber: "123",
+      format: "keywords",
+    });
+
+    const promptText = result.messages[0].content.text;
+    expect(promptText).toContain(
+      "Please extract and list 10-15 important keywords",
+    );
+  });
+
+  it("should handle post without category and tags", async () => {
+    const postWithoutCategoryAndTags = {
+      ...mockPost,
+      category: null,
+      tags: [],
+    };
+
+    mockClient.GET.mockResolvedValue({
+      data: postWithoutCategoryAndTags,
+      error: undefined,
+    });
+
+    const result = await summarizePost(mockClient, {
+      teamName: "test-team",
+      postNumber: "456",
+    });
+
+    const promptText = result.messages[0].content.text;
+    expect(promptText).not.toContain("Category:");
+    expect(promptText).not.toContain("Tags:");
+  });
+
+  it("should handle post with null body_md", async () => {
+    const postWithNullBody = {
+      ...mockPost,
+      body_md: null,
+    };
+
+    mockClient.GET.mockResolvedValue({
+      data: postWithNullBody,
+      error: undefined,
+      response: {
+        ok: true,
+        status: 200,
+      } as Response,
+    });
+
+    const result = await summarizePost(mockClient, {
+      teamName: "test-team",
+      postNumber: "789",
+    });
+
+    const promptText = result.messages[0].content.text;
+    expect(promptText).not.toContain("Content:");
+    expect(promptText).toContain("Please provide a summary in bullet points");
+  });
+
+  it("should handle API errors", async () => {
+    const mockError = { error: "not_found", message: "Post not found" };
+
+    mockClient.GET.mockResolvedValue({
+      data: undefined,
+      error: mockError,
+      response: {
+        ok: false,
+        status: 404,
+      } as Response,
+    });
+
+    const result = await summarizePost(mockClient, {
+      teamName: "test-team",
+      postNumber: "999",
+    });
+
+    expect(result.messages).toHaveLength(1);
+    expect(result.messages[0].role).toBe("user");
+    expect(result.messages[0].content.text).toContain(
+      JSON.stringify(mockError, null, 2),
+    );
+  });
+
+  it("should handle network errors", async () => {
+    const networkError = new Error("Network connection failed");
+
+    mockClient.GET.mockRejectedValue(networkError);
+
+    const result = await summarizePost(mockClient, {
+      teamName: "test-team",
+      postNumber: "123",
+    });
+
+    expect(result.messages).toHaveLength(1);
+    expect(result.messages[0].role).toBe("user");
+    expect(result.messages[0].content.text).toContain(
+      "Network connection failed",
+    );
+  });
+
+  it("should handle non-Error exceptions", async () => {
+    mockClient.GET.mockRejectedValue("Unexpected error");
+
+    const result = await summarizePost(mockClient, {
+      teamName: "test-team",
+      postNumber: "123",
+    });
+
+    expect(result.messages).toHaveLength(1);
+    expect(result.messages[0].role).toBe("user");
+    expect(result.messages[0].content.text).toContain("Unexpected error");
+  });
+
+  it("should handle invalid post number", async () => {
+    const result = await summarizePost(mockClient, {
+      teamName: "test-team",
+      postNumber: "invalid",
+    });
+
+    expect(result.messages).toHaveLength(1);
+    expect(result.messages[0].role).toBe("user");
+    expect(result.messages[0].content.text).toContain(
+      "Post number must be a positive integer",
+    );
+  });
+
+  it("should throw MissingTeamNameError when teamName is empty", async () => {
+    await expect(
+      summarizePost(mockClient, {
+        teamName: "",
+        postNumber: "123",
+      }),
+    ).rejects.toThrow(
+      "Missing required parameter 'teamName'. Use esa_get_teams to list available teams, then retry with teamName specified.",
+    );
+
+    expect(mockClient.GET).not.toHaveBeenCalled();
+  });
+});

package/src/prompts/index.ts

@@ -0,0 +1,21 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { z } from "zod";
+import { withContext } from "../api_client/with-context.js";
+import type { MCPContext } from "../context/mcp-context.js";
+import { t } from "../i18n/index.js";
+import { createSummarizePostSchema, summarizePost } from "./summarize-post.js";
+
+export function setupPrompts(server: McpServer, context: MCPContext): void {
+  console.error("Setting up MCP prompts...");
+  // NOTE: Stremable HTTP Stransport では ユーザーの LANG 設定に応じて i18next の lang 設定を変える
+  server.registerPrompt(
+    "esa_summarize_post",
+    {
+      title: t("prompts.summarize_post.title"),
+      description: t("prompts.summarize_post.description"),
+      argsSchema: createSummarizePostSchema().shape,
+    },
+    async (params: z.infer<ReturnType<typeof createSummarizePostSchema>>) =>
+      withContext(context, summarizePost, params),
+  );
+}

package/src/prompts/summarize-post.ts

@@ -0,0 +1,94 @@
+import { z } from "zod";
+import type { createEsaClient } from "../api_client/index.js";
+import { MissingTeamNameError } from "../errors/missing-team-name-error.js";
+import {
+  formatPromptError,
+  formatPromptResponse,
+} from "../formatters/mcp-response.js";
+import type { components } from "../generated/api-types.js";
+import { t } from "../i18n/index.js";
+
+// 多言語化対応のために 関数化してスキーマを遅延定義している
+export const createSummarizePostSchema = () =>
+  z.object({
+    teamName: z.string().describe(t("prompts.summarize_post.args.team_name")),
+    postNumber: z
+      .string()
+      .describe(t("prompts.summarize_post.args.post_number")),
+    format: z
+      .enum(["bullet", "paragraph", "keywords"])
+      .optional()
+      .describe(t("prompts.summarize_post.args.format")),
+  });
+
+export async function summarizePost(
+  client: ReturnType<typeof createEsaClient>,
+  args: z.infer<ReturnType<typeof createSummarizePostSchema>>,
+) {
+  const { teamName, postNumber: postNumberStr, format = "bullet" } = args;
+
+  if (!teamName) {
+    throw new MissingTeamNameError();
+  }
+  const postNumber = Number.parseInt(postNumberStr, 10);
+
+  if (Number.isNaN(postNumber) || postNumber <= 0) {
+    return formatPromptError("Post number must be a positive integer");
+  }
+
+  try {
+    const { data, error, response } = await client.GET(
+      "/v1/teams/{team_name}/posts/{post_number}",
+      {
+        params: {
+          path: { team_name: teamName, post_number: postNumber },
+        },
+      },
+    );
+
+    if (error || !response.ok) {
+      return formatPromptError(error || response.status);
+    }
+
+    const post: components["schemas"]["Post"] = data;
+
+    let prompt = `Please summarize the following post:\n\n`;
+    prompt += `Title: ${post.name}\n`;
+    prompt += `URL: ${post.url}\n`;
+    prompt += `Author: ${post.created_by.name}\n`;
+    prompt += `Created: ${post.created_at}\n`;
+    prompt += `Updated: ${post.updated_at}\n`;
+
+    if (post.category) {
+      prompt += `Category: ${post.category}\n`;
+    }
+
+    if (post.tags && post.tags.length > 0) {
+      prompt += `Tags: ${post.tags.join(", ")}\n`;
+    }
+
+    prompt += "\n---\n\n";
+
+    if (post.body_md) {
+      prompt += `Content:\n${post.body_md}\n\n---\n\n`;
+    }
+
+    switch (format) {
+      case "bullet":
+        prompt +=
+          "Please provide a summary in bullet points (3-5 main points).";
+        break;
+      case "paragraph":
+        prompt += "Please provide a summary in 2-3 paragraphs.";
+        break;
+      case "keywords":
+        prompt +=
+          "Please extract and list 10-15 important keywords from this post.";
+        break;
+    }
+
+    return formatPromptResponse(prompt);
+  } catch (error) {
+    return formatPromptError(error);
+  }
+}

package/src/resources/__tests__/index.test.ts

@@ -0,0 +1,49 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { MCPContext } from "../../context/mcp-context.js";
+import { setupResources } from "../index.js";
+
+describe("setupResources", () => {
+  let server: McpServer;
+  let context: MCPContext;
+  let consoleErrorSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    server = new McpServer({
+      name: "test-server",
+      version: "1.0.0",
+    });
+    context = {} as unknown as MCPContext;
+
+    consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    consoleErrorSpy.mockRestore();
+  });
+
+  it("should register all resources with correct handlers", () => {
+    const registerResourceSpy = vi.spyOn(server, "registerResource");
+
+    setupResources(server, context);
+
+    expect(registerResourceSpy).toHaveBeenCalledTimes(1);
+
+    for (let i = 0; i < 1; i++) {
+      const [resourceName, template, metadata, handler] =
+        registerResourceSpy.mock.calls[i];
+      expect(typeof resourceName).toBe("string");
+      expect(resourceName).toMatch(/^esa_/); // All resources should start with 'esa_'
+      expect(template).toBeTypeOf("object"); // Template verification handled by specific resource tests
+      expect(metadata).toBeTypeOf("object"); // Metadata verification handled by specific resource tests
+      expect(handler).toBeTypeOf("function"); // Handler functionality tested in specific resource tests
+    }
+  });
+
+  it("should log setup completion message", () => {
+    setupResources(server, context);
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith("Setting up MCP resources...");
+  });
+});