Candidate MCP Server Library

候補者向け MCP サーバーライブラリ

LLM が候補者の情報にアクセスできるようにする、Model Context Protocol（MCP）サーバーです。

概要

重要：このサーバーは、単独のサービスとしてではなく、他のアプリケーションに統合するライブラリとして使用することを想定しています。提供されている起動方法は、デモおよびテストのみを目的としています。

リソース

この MCP サーバーは、以下のリソースを提供します。

• candidate-info://resume-text：履歴書の内容をテキストとして返します
• candidate-info://resume-url：履歴書の URL
• candidate-info://linkedin-url：LinkedIn プロフィールの URL
• candidate-info://github-url：GitHub プロフィールの URL
• candidate-info://website-url：個人ウェブサイトの URL
• candidate-info://website-text：個人ウェブサイトの内容

ツール

この MCP サーバーは、同じ候補者情報を返すツールも提供します。

• get_resume_text：候補者の履歴書の内容をテキストとして返します
• get_resume_url：候補者の履歴書の URL を返します
• get_linkedin_url：候補者の LinkedIn プロフィールの URL を返します
• get_github_url：候補者の GitHub プロフィールの URL を返します
• get_website_url：候補者の個人ウェブサイトの URL を返します
• get_website_text：候補者の個人ウェブサイトの内容を返します
• contact_candidate：候補者にメールを送信します（Mailgun の設定が必要です）

使用方法

npm install @jhgaylor/candidate-mcp-server

ライブラリの使用方法

このパッケージは、独自のアプリケーションにインポートして使用するように設計されています。

Stdio

stdio を使えば、プロセスを簡単に起動できます。重要なのは、候補者の設定を渡すことです。

候補者の設定をどこから取得するかは、完全に自由です。ハードコードしても、プロセスの起動時に JSONResume の URL を受け取ってもかまいません。お好みで選べます。

import { createServer } from '@jhgaylor/candidate-mcp-server';
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

// Configure your server
const serverConfig = { 
  name: "MyCandidateServer", 
  version: "1.0.0",
  mailgunApiKey: process.env.MAILGUN_API_KEY,
  mailgunDomain: process.env.MAILGUN_DOMAIN
};
const candidateConfig = { 
  name: "John Doe",
  email: "[email protected]", // Required for the contact_candidate tool
  resumeUrl: "https://example.com/resume.pdf",
  // other candidate properties
};

// Create server instance
const server = createServer(serverConfig, candidateConfig);

// Connect with your preferred transport
await server.connect(new StdioServerTransport());
// or integrate with your existing HTTP server

StreamableHttp

typescript sdk が提供するサンプルコードを使用して、この MCP サーバーを express サーバーにバインドできます。

import express from 'express';
import { Request, Response } from 'express';
import { createServer } from '@jhgaylor/candidate-mcp-server';
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamablehttp.js";

// Configure your server
const serverConfig = { 
  name: "MyCandidateServer", 
  version: "1.0.0",
  mailgunApiKey: process.env.MAILGUN_API_KEY,
  mailgunDomain: process.env.MAILGUN_DOMAIN,
  contactEmail: "[email protected]",
};
const candidateConfig = { 
  name: "John Doe",
  resumeUrl: "https://example.com/resume.pdf",
  // other candidate properties
};

// Factory function to create a new server instance for each request
const getServer = () => createServer(serverConfig, candidateConfig);

const app = express();
app.use(express.json());

app.post('/mcp', async (req: Request, res: Response) => {
  // In stateless mode, create a new instance of transport and server for each request
  // to ensure complete isolation. A single instance would cause request ID collisions
  // when multiple clients connect concurrently.
  
  try {
    const server = getServer(); 
    const transport = new StreamableHTTPServerTransport({
      sessionIdGenerator: undefined,
    });
    res.on('close', () => {
      console.log('Request closed');
      transport.close();
      server.close();
    });
    await server.connect(transport);
    await transport.handleRequest(req, res, req.body);
  } catch (error) {
    console.error('Error handling MCP request:', error);
    if (!res.headersSent) {
      res.status(500).json({
        jsonrpc: '2.0',
        error: {
          code: -32603,
          message: 'Internal server error',
        },
        id: null,
      });
    }
  }
});

app.get('/mcp', async (req: Request, res: Response) => {
  console.log('Received GET MCP request');
  res.writeHead(405).end(JSON.stringify({
    jsonrpc: "2.0",
    error: {
      code: -32000,
      message: "Method not allowed."
    },
    id: null
  }));
});

app.delete('/mcp', async (req: Request, res: Response) => {
  console.log('Received DELETE MCP request');
  res.writeHead(405).end(JSON.stringify({
    jsonrpc: "2.0",
    error: {
      code: -32000,
      message: "Method not allowed."
    },
    id: null
  }));
});

// Start the server
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`MCP Stateless Streamable HTTP Server listening on port ${PORT}`);
});

Express

express と MCP トランスポートのバインドを自分で記述する代わりに、express-mcp-handler を使って処理できます。

npm install express-mcp-handler

import express from 'express';
import { statelessHandler } from 'express-mcp-handler';
import { createServer } from './server';

// You can configure the server factory to include Mailgun settings
const createServerWithConfig = () => {
  const serverConfig = { 
    name: "MyCandidateServer", 
    version: "1.0.0",
    mailgunApiKey: process.env.MAILGUN_API_KEY,
    mailgunDomain: process.env.MAILGUN_DOMAIN,
    contactEmail: "[email protected]",
  };
  const candidateConfig = { 
    name: "John Doe",
    resumeUrl: "https://example.com/resume.pdf",
    // other candidate properties
  };
  
  return createServer(serverConfig, candidateConfig);
};

// Configure the stateless handler
const handler = statelessHandler(createServerWithConfig);

// Create Express app
const app = express();
app.use(express.json());

// Mount the handler (stateless only needs POST)
app.post('/mcp', handler);

// Start the server
const PORT = process.env.PORT || 3002;
app.listen(PORT, () => {
  console.log(`Stateless MCP server running on port ${PORT}`);
});

開発

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode with auto-restart
npm run dev

stdio によるデモ／デバッグ起動

# Start with STDIO (demo only)
npm start

STDIO で実行する場合、1 行の JSON オブジェクトとして MCP メッセージを送信することで、サーバーとやり取りできます。

# Example of sending an initialize message via STDIO
echo '{"jsonrpc": "2.0","id": 1,"method": "initialize","params": {"protocolVersion": "2024-11-05","capabilities": {"roots": {"listChanged": true},"sampling": {}},"clientInfo": {"name": "ExampleClient","version": "1.0.0"}}}' | node dist/index.js --stdio

# List resources
echo '{"jsonrpc": "2.0","id": 2,"method": "resources/list","params": {}}' | node dist/index.js --stdio

# Access a resource
echo '{"jsonrpc": "2.0","id": 3,"method": "resources/read","params": {"uri": "candidate-info://resume-text"}}' | node dist/index.js --stdio

# List Tools
echo '{"jsonrpc": "2.0","id": 2,"method": "tools/list","params": {}}' | node dist/index.js --stdio

# Call a tool
echo '{"jsonrpc": "2.0","id": 4,"method": "tools/call","params": {"name": "get_resume_text", "args": {}}}' | node dist/index.js --stdio

# Send an email to the candidate
echo '{"jsonrpc": "2.0","id": 5,"method": "tools/call","params": {"name": "contact_candidate", "args": {"subject": "Hello from AI!", "message": "This is a test email sent via the MCP server.", "reply_address": "[email protected]"}}}' | node dist/index.js --stdio

各メッセージは 1 行で記述し、JSON オブジェクト内に改行を含めないでください。

機能

• 他のアプリケーションへの統合を重視したライブラリ設計
• カスタム候補者情報を追加できるモジュール式のリソースシステム
• 型安全性と開発者エクスペリエンスの向上を実現する TypeScript
• Model Context Protocol の仕様全体を実装
• 複数のトランスポートタイプに対応（STDIO、HTTP、Streamable HTTP）
• 依存関係を最小限に抑制

サーバーの構成

src/
  ├── index.ts                # Main package entry point
  ├── server.ts               # MCP server factory with configuration
  ├── config.ts               # Configuration type definitions
  └── resources/              # Modular resource definitions
      └── index.ts            # Resource factory and implementation

MCP プロトコル

このライブラリは、LLM が外部のデータや機能を利用するための標準化された方法である Model Context Protocol（MCP）を実装しています。アプリケーションに統合すると、JSON-RPC リクエストに応答するステートレス API を公開します。

API の使用方法

アプリケーションに統合すると、クライアントは JSON-RPC リクエストを送信して MCP サーバーとやり取りできます。以下は、このライブラリを統合した後にアプリケーションが処理するリクエストの例です。

初期化

curl -X POST http://your-application-url/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {
        "roots": {
          "listChanged": true
        },
        "sampling": {}
      },
      "clientInfo": {
        "name": "ExampleClient",
        "version": "1.0.0"
      }
    }
  }'

候補者のリソースへのアクセス

curl -X POST http://your-application-url/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "resources/read",
    "params": {
      "uri": "candidate-info://resume-text"
    },
    "id": 2
  }'

ライブラリの拡張

このライブラリは、カスタムリソース、ツール、プロンプトで拡張できるように設計されています。独自のリソースを追加する方法は次のとおりです。

import { McpServer, Resource } from '@jhgaylor/candidate-mcp-server';

// Create your custom resource class
class CustomCandidateResource extends Resource {
  constructor(candidateConfig) {
    super(
      `${candidateConfig.name} Custom Data`, 
      "candidate-info://custom-data", 
      async () => {
        return {
          contents: [
            { 
              uri: "candidate-info://custom-data", 
              mimeType: "text/plain", 
              text: "Your custom candidate data here"
            }
          ]
        };
      }
    );
  }
}

// Create server with standard configuration
const server = createServer(serverConfig, candidateConfig);

// Add your custom resource
const customResource = new CustomCandidateResource(candidateConfig);
customResource.bind(server);

// Connect with preferred transport
// ...

カスタムツールの追加

カスタムツールを追加してライブラリを拡張することもできます。

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';
import { createServer } from '@jhgaylor/candidate-mcp-server';

// Create server with standard configuration
const server = createServer(serverConfig, candidateConfig);

// Add a custom tool
server.tool(
  'get_candidate_skills',
  'Returns a list of the candidate skills',
  {},
  async (_args, _extra) => {
    return {
      content: [
        { 
          type: "text", 
          text: "JavaScript, TypeScript, React, Node.js, MCP Protocol" 
        }
      ]
    };
  }
);

// Connect with preferred transport
// ...

要件

• Node.js 20+
• npm または yarn

ライセンス

MIT

npm への公開

まだログインしていない場合は、npm にログインします。

npm login

パッケージを npm に公開します（prepublishOnly ビルドが実行されます）。

npm publish

バージョンを更新し、タグを付けてプッシュするには、次のコマンドを実行します。

npm version patch    # or minor, major
git push origin main --tags