@immicore/noc 1.0.0

package/Dockerfile

@@ -0,0 +1,21 @@
+FROM node:20-alpine AS builder
+
+WORKDIR /app
+COPY package*.json ./
+RUN npm install
+
+COPY tsconfig.json ./
+COPY src ./src
+RUN npm run build
+
+FROM node:20-alpine
+
+WORKDIR /app
+COPY package*.json ./
+RUN npm install --production
+
+COPY --from=builder /app/dist ./dist
+
+EXPOSE 3108
+
+CMD ["node", "dist/index.js", "--http", "--port", "3108"]

package/dist/common/prompt-schema.js

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+/**
+ * Zod schema for a single prompt template, with arguments.
+ */
+export const promptSchema = z.object({
+    name: z.string().describe('Prompt unique name.'),
+    description: z.string().optional().describe('Prompt description.'),
+    arguments: z.array(z.object({
+        name: z.string().describe('Argument name.'),
+        description: z.string().optional().describe('Argument description.'),
+        required: z.boolean().optional().describe('Is this argument required?'),
+        type: z.string().describe('Argument type (e.g., string, number, boolean, enum, etc.)'),
+    })).optional().describe('Prompt arguments.'),
+});

package/dist/common/resource-schema.js

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+/**
+ * Zod schema for a single resource.
+ */
+export const resourceSchema = z.object({
+    id: z.string(),
+    type: z.string().optional(),
+    label: z.string().optional(),
+    name: z.string().optional(),
+    description: z.string().optional(),
+    uri: z.string().optional(), // 允许 formbro://xxx 等自定义 scheme
+    mimeType: z.string().optional(),
+    meta: z.record(z.any()).optional(),
+});

package/dist/common/tool-schema.js

@@ -0,0 +1,33 @@
+/**
+ * Helper to create tool registration config from Tool interface
+ */
+export function createToolConfig(tool) {
+    return {
+        title: tool.annotations?.title || tool.name,
+        description: tool.description,
+        inputSchema: tool.inputShape,
+        outputSchema: tool.outputSchema,
+        annotations: {
+            readOnlyHint: tool.annotations?.readOnlyHint ?? true,
+            destructiveHint: tool.annotations?.destructiveHint ?? false,
+            idempotentHint: tool.annotations?.idempotentHint ?? true,
+            openWorldHint: tool.annotations?.openWorldHint ?? true,
+        },
+    };
+}
+/**
+ * Get required environment variable or throw
+ */
+export function requireEnv(name) {
+    const value = process.env[name];
+    if (!value) {
+        throw new Error(`Required environment variable ${name} is not set`);
+    }
+    return value;
+}
+/**
+ * Get optional environment variable with default
+ */
+export function getEnv(name, defaultValue) {
+    return process.env[name] || defaultValue;
+}

package/dist/index.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import express from 'express';
+import { createToolConfig } from './common/tool-schema.js';
+import { KeywordSearchMcpTool, SemanticSearchMcpTool } from './noc/index.js';
+const allTools = [
+    KeywordSearchMcpTool,
+    SemanticSearchMcpTool,
+];
+const SERVER_NAME = 'immicore-noc';
+const SERVER_VERSION = '1.0.0';
+const DEFAULT_HTTP_PORT = 3008;
+function createServer() {
+    const server = new McpServer({
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+    });
+    for (const tool of allTools) {
+        const config = createToolConfig(tool);
+        server.registerTool(tool.name, {
+            title: config.title,
+            description: config.description,
+            inputSchema: config.inputSchema,
+            annotations: config.annotations,
+        }, async (args) => {
+            const result = await tool.call(args);
+            return {
+                content: result.content,
+                structuredContent: result.structuredContent,
+                isError: result.isError,
+            };
+        });
+    }
+    return server;
+}
+async function runStdioMode() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`${SERVER_NAME} running in stdio mode`);
+}
+async function runHttpMode(port) {
+    const app = express();
+    app.use(express.json());
+    app.post('/mcp', async (req, res) => {
+        const server = createServer();
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+            enableJsonResponse: true
+        });
+        res.on('close', () => transport.close());
+        await server.connect(transport);
+        await transport.handleRequest(req, res, req.body);
+    });
+    app.get('/health', (_req, res) => {
+        res.json({ status: 'ok', server: SERVER_NAME, version: SERVER_VERSION });
+    });
+    app.listen(port, () => {
+        console.log(`${SERVER_NAME} running in HTTP mode on http://localhost:${port}/mcp`);
+    });
+}
+async function runSseMode(port) {
+    const app = express();
+    app.use(express.json());
+    const sessions = new Map();
+    app.get('/sse', (req, res) => {
+        const server = createServer();
+        const transport = new SSEServerTransport('/messages', res);
+        const sessionId = transport.sessionId;
+        sessions.set(sessionId, { server, transport });
+        res.on('close', () => {
+            sessions.delete(sessionId);
+        });
+        server.connect(transport);
+    });
+    app.post('/messages', (req, res) => {
+        const sessionId = req.query.sessionId;
+        const session = sessions.get(sessionId);
+        if (!session) {
+            res.status(404).json({ error: 'Session not found' });
+            return;
+        }
+        session.transport.handlePostMessage(req, res, req.body);
+    });
+    app.get('/health', (_req, res) => {
+        res.json({ status: 'ok', server: SERVER_NAME, version: SERVER_VERSION, mode: 'sse' });
+    });
+    app.listen(port, () => {
+        console.log(`${SERVER_NAME} running in SSE mode on http://localhost:${port}/sse`);
+    });
+}
+function parseArgs() {
+    const args = process.argv.slice(2);
+    let mode = 'stdio';
+    let port = DEFAULT_HTTP_PORT;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--http') {
+            mode = 'http';
+        }
+        else if (args[i] === '--sse') {
+            mode = 'sse';
+        }
+        else if (args[i] === '--stdio') {
+            mode = 'stdio';
+        }
+        else if (args[i] === '--port' && args[i + 1]) {
+            port = parseInt(args[i + 1], 10);
+            i++;
+        }
+    }
+    return { mode, port };
+}
+async function main() {
+    const { mode, port } = parseArgs();
+    if (mode === 'http') {
+        await runHttpMode(port);
+    }
+    else if (mode === 'sse') {
+        await runSseMode(port);
+    }
+    else {
+        await runStdioMode();
+    }
+}
+main().catch(console.error);

package/dist/noc/index.js

@@ -0,0 +1,3 @@
+export { KeywordSearchMcpTool, KeywordSearchInputSchema, KeywordSearchOutputSchema } from './keyword_search.tool.js';
+export { SemanticSearchMcpTool, SemanticSearchInputSchema, SemanticSearchOutputSchema } from './semantic_search.tool.js';
+export { keywordSearchPrompts, semanticSearchPrompts } from './prompts.js';

package/dist/noc/keyword_search.handler.js

@@ -0,0 +1,32 @@
+import axios from 'axios';
+import { requireEnv } from '../common/tool-schema.js';
+function getNocRetrieveApiUrl() {
+    const HOST_URL = requireEnv('HOST_URL');
+    return `${HOST_URL}/noc/keyword-noc-retrieve`;
+}
+function getSystemToken() {
+    return requireEnv('SEARCH_SERVICE_TOKEN');
+}
+export async function keywordSearchHandler(input) {
+    try {
+        const response = await axios.post(getNocRetrieveApiUrl(), input, {
+            timeout: 30000,
+            headers: { Authorization: `Bearer ${getSystemToken()}` },
+        });
+        return response.data;
+    }
+    catch (error) {
+        if (axios.isAxiosError(error)) {
+            console.error('Error calling keyword-noc-retrieve API:', error.message);
+            if (error.response) {
+                console.error('Response data:', error.response.data);
+                console.error('Response status:', error.response.status);
+            }
+            throw new Error(`Failed to retrieve NOC entries: ${error.response?.data?.detail || error.message}`);
+        }
+        else {
+            console.error('Unexpected error:', error);
+            throw new Error('An unexpected error occurred while retrieving NOC entries.');
+        }
+    }
+}

package/dist/noc/keyword_search.tool.js

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+import { keywordSearchHandler } from './keyword_search.handler.js';
+export const KeywordSearchInputSchema = z.object({
+    main_duties: z.string().regex(/^[\x00-\x7F]*$/, { message: 'Main duties must be in English and contain only ASCII characters.' }).optional().describe('Main duties for the NOC entry. This should be a concise description of the primary responsibilities, in English. Example: "manage software development projects"'),
+    top_k: z.number().int().optional().default(5).describe('The number of top results to retrieve. Defaults to 5.'),
+    title: z.string().regex(/^[\x00-\x7F]*$/, { message: 'Title must be in English and contain only ASCII characters.' }).optional().describe('The title for the NOC entry. This should be a job title, in English. Example: "Software Project Manager"')
+}).describe('Input schema for the keyword_search tool. All text inputs (main_duties, title) must be in English. If both title and main_duties are omitted, the top_k NOC entries from the entire dataset will be returned.');
+export const KeywordSearchOutputSchema = z.array(z.object({
+    noc_code: z.string().describe('The NOC code.'),
+    title: z.string().describe('The title of the NOC entry.'),
+    title_examples: z.array(z.string()).describe('Examples of titles for the NOC entry.'),
+    main_duties: z.array(z.string()).describe('Main duties associated with the NOC entry.'),
+    employment_requirement: z.string().describe('Employment requirement for the NOC entry.'),
+    additional_information: z.array(z.string()).describe('Additional information for the NOC entry.'),
+    exclusion: z.array(z.string()).describe('Exclusions for the NOC entry.'),
+})).describe('Output schema for the keyword_search tool.');
+export const NOC_KEYWORD_SEARCH_DESCRIPTION = `Performs a keyword search for National Occupational Classification (NOC) entries using Elasticsearch.
+This tool helps find NOC codes based on job titles and main duties.
+All text inputs (title, main_duties) must be in English.
+If both 'title' and 'main_duties' are omitted, the tool will return the top_k entries from the entire NOC dataset.
+
+Input Parameters:
+  - title (string, optional): The job title to search for (must be in English). Example: "Software Engineer".
+  - main_duties (string, optional): A description of the main duties or responsibilities for the role (must be in English). Example: "design, develop, and test software applications".
+  - top_k (number, optional): The number of top results to retrieve. Defaults to 5.
+
+Example Usage:
+{
+  "title": "Marketing Manager",
+  "main_duties": "develop and implement marketing strategies, manage campaigns, analyze market trends",
+  "top_k": 3
+}
+
+The tool returns a list of matching NOC entries, including the NOC code, title, example titles, main duties, employment requirements, additional information, and exclusions.`;
+export const KeywordSearchMcpTool = {
+    name: 'noc_keyword_search',
+    description: NOC_KEYWORD_SEARCH_DESCRIPTION,
+    inputShape: KeywordSearchInputSchema,
+    outputSchema: KeywordSearchOutputSchema,
+    annotations: {
+        title: 'NOC Keyword Search',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+    call: async (rawInput) => {
+        try {
+            const processedInput = {
+                ...rawInput,
+                title: rawInput.title ?? "",
+                main_duties: rawInput.main_duties ?? ""
+            };
+            const nocEntriesArray = await keywordSearchHandler(processedInput);
+            if (!nocEntriesArray || nocEntriesArray.length === 0) {
+                return {
+                    content: [{ type: 'text', text: 'No NOC entries found for the given criteria.' }],
+                    structuredContent: { results: [], total: 0 },
+                    _meta: { total: 0 }
+                };
+            }
+            return {
+                content: nocEntriesArray.map(entry => ({
+                    type: 'text',
+                    text: [
+                        entry.noc_code ? `NOC Code: ${entry.noc_code}` : 'NOC Code: Not specified',
+                        entry.title ? `Title: ${entry.title}` : 'Title: Not specified',
+                        entry.title_examples?.length ? `Title Examples: \n - ${entry.title_examples.join('\n - ')}` : '',
+                        entry.main_duties?.length ? `Main Duties: \n - ${entry.main_duties.join('\n - ')}` : '',
+                        entry.employment_requirement ? `Employment Requirement: ${entry.employment_requirement}` : ''
+                    ].filter(Boolean).join('\n\n')
+                })),
+                structuredContent: { results: nocEntriesArray, total: nocEntriesArray.length },
+                _meta: { total: nocEntriesArray.length }
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Failed to retrieve NOC entries.';
+            console.error('Error in noc_keyword_search tool call:', error);
+            return {
+                content: [{ type: 'text', text: `Error: ${errorMessage}` }],
+                isError: true,
+                _meta: { error: true }
+            };
+        }
+    },
+};

package/dist/noc/prompts.js

@@ -0,0 +1,27 @@
+export const keywordSearchPrompts = [
+    {
+        name: 'noc_keyword_search', // Corresponds to NocKeywordSearchMcpTool.name
+        description: 'Search NOC information using keywords. User can specify query text, NOC code, and top_k results.',
+        arguments: [
+            { name: 'query_text', type: 'string', description: 'The search query text for NOC keywords.', required: true },
+            { name: 'noc_code', type: 'string', description: 'Optional NOC code to filter by (e.g., "2173").', required: false },
+            { name: 'top_k', type: 'number', description: 'Optional number of results to return.', required: false },
+        ],
+    },
+];
+export const semanticSearchPrompts = [
+    {
+        name: 'noc_semantic_search', // Corresponds to NocSemanticSearchMcpTool.name
+        description: 'Perform a semantic search for NOC information. User can specify query text, NOC code, title keywords, and top_k results.',
+        arguments: [
+            { name: 'query_text', type: 'string', description: 'The natural language query for semantic NOC search.', required: true },
+            { name: 'noc_code', type: 'string', description: 'Optional NOC code to filter by (e.g., "2173").', required: false },
+            { name: 'title', type: 'string', description: 'Optional keywords to filter by NOC title.', required: false },
+            { name: 'top_k', type: 'number', description: 'Optional number of results to return.', required: false },
+        ],
+    },
+];
+export const nocToolPrompts = {
+    keyword_search: keywordSearchPrompts, // Tool name from NocKeywordSearchMcpTool
+    semantic_search: semanticSearchPrompts, // Tool name from NocSemanticSearchMcpTool
+};

package/dist/noc/semantic_search.handler.js

@@ -0,0 +1,32 @@
+import axios from 'axios';
+import { requireEnv } from '../common/tool-schema.js';
+function getNocSearchApiUrl() {
+    const HOST_URL = requireEnv('HOST_URL');
+    return `${HOST_URL}/noc/semantic-noc-search`;
+}
+function getSystemToken() {
+    return requireEnv('SEARCH_SERVICE_TOKEN');
+}
+export async function semanticSearchHandler(input) {
+    try {
+        const response = await axios.post(getNocSearchApiUrl(), input, {
+            timeout: 30000,
+            headers: { Authorization: `Bearer ${getSystemToken()}` },
+        });
+        return response.data;
+    }
+    catch (error) {
+        if (axios.isAxiosError(error)) {
+            console.error('Error calling semantic-noc-search API:', error.message);
+            if (error.response) {
+                console.error('Response data:', error.response.data);
+                console.error('Response status:', error.response.status);
+            }
+            throw new Error(`Failed to search NOC entries: ${error.response?.data?.detail || error.message}`);
+        }
+        else {
+            console.error('Unexpected error:', error);
+            throw new Error('An unexpected error occurred while searching NOC entries.');
+        }
+    }
+}

package/dist/noc/semantic_search.tool.js

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+import { semanticSearchHandler } from './semantic_search.handler.js';
+export const SemanticSearchInputSchema = z.object({
+    query_text: z.string().regex(/^[\x00-\x7F]+$/, { message: 'Query text must be in English.' }).describe('The semantic query text for NOC entries. This should be a natural language description of a job, its duties, or skills, in English. Example: "seeking a professional who can lead marketing initiatives and manage a team"'),
+    top_k: z.number().int().optional().default(5).describe('The number of top results to retrieve. Defaults to 5.')
+}).describe('Input schema for the semantic_search tool. The query_text must be in English.');
+export const SemanticSearchOutputSchema = z.object({
+    results: z.array(z.object({
+        noc_code: z.string().describe('The NOC code.'),
+        title: z.string().describe('The title of the NOC entry.'),
+        title_examples: z.array(z.string()).describe('Examples of titles for the NOC entry.'),
+        main_duties: z.array(z.string()).describe('Main duties associated with the NOC entry.'),
+        employment_requirement: z.string().describe('Employment requirement for the NOC entry.'),
+        additional_information: z.array(z.string()).describe('Additional information for the NOC entry.'),
+        exclusion: z.array(z.string()).describe('Exclusions for the NOC entry.'),
+    })).describe('List of NOC entries matching the semantic search.'),
+    total: z.number().int().describe('The total number of results found.'),
+}).describe('Output schema for the semantic_search tool.');
+export const NOC_SEMANTIC_SEARCH_DESCRIPTION = `Performs a semantic search for National Occupational Classification (NOC) entries using Supabase.
+This tool is useful for finding NOC codes when you can describe a role or its duties in natural language, rather than specific keywords.
+The input query_text must be in English.
+
+Input Parameters:
+  - query_text (string, required): A natural language description of the job, its duties, or required skills (must be in English). Example: "Looking for a job that involves creating visual concepts, by hand or using computer software, to communicate ideas that inspire, inform, or captivate consumers."
+  - top_k (number, optional): The number of top results to retrieve. Defaults to 5.
+
+Example Usage:
+{
+  "query_text": "Manages company's financial planning, reporting, and ensures compliance with financial regulations.",
+  "top_k": 3
+}
+
+The tool returns a list of NOC entries that are semantically similar to the query_text.`;
+export const SemanticSearchMcpTool = {
+    name: 'noc_semantic_search',
+    description: NOC_SEMANTIC_SEARCH_DESCRIPTION,
+    inputShape: SemanticSearchInputSchema,
+    outputSchema: SemanticSearchOutputSchema,
+    annotations: {
+        title: 'NOC Semantic Search',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+    call: async (input) => {
+        try {
+            const result = await semanticSearchHandler(input);
+            if (!result.results || result.results.length === 0) {
+                return {
+                    content: [{ type: 'text', text: `No NOC entries found for query "${input.query_text}".` }],
+                    structuredContent: { results: [], total: 0 },
+                    _meta: { total: 0 }
+                };
+            }
+            return {
+                content: result.results.map(entry => ({
+                    type: 'text',
+                    text: [
+                        entry.noc_code ? `NOC Code: ${entry.noc_code}` : '',
+                        entry.title ? `Title: ${entry.title}` : '',
+                        entry.title_examples?.length ? `Title Examples: ${entry.title_examples.slice(0, 3).join(', ')}` : '',
+                        entry.main_duties?.length ? `Main Duties: ${entry.main_duties.slice(0, 3).join('; ')}` : ''
+                    ].filter(Boolean).join('\n')
+                })),
+                structuredContent: result,
+                _meta: { total: result.total }
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Failed to search NOC entries.';
+            console.error('Error in noc_semantic_search tool call:', error);
+            return {
+                content: [{ type: 'text', text: `Error: ${errorMessage}` }],
+                isError: true,
+                _meta: { error: true }
+            };
+        }
+    },
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@immicore/noc",
+  "version": "1.0.0",
+  "description": "MCP server for National Occupational Classification (NOC) search",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "immicore-noc": "dist/index.js"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts --stdio",
+    "dev:http": "tsx src/index.ts --http --port 3008",
+    "dev:sse": "tsx src/index.ts --sse --port 3008",
+    "build": "tsc",
+    "start": "node dist/index.js --stdio",
+    "start:http": "node dist/index.js --http --port 3008",
+    "start:sse": "node dist/index.js --sse --port 3008"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.1",
+    "axios": "^1.8.4",
+    "dotenv": "^17.2.3",
+    "express": "^4.21.2",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.15.2",
+    "tsx": "^4.16.2",
+    "typescript": "^5.4.5"
+  }
+}

package/src/common/prompt-schema.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+
+/**
+ * Zod schema for a single prompt template, with arguments.
+ */
+export const promptSchema = z.object({
+  name: z.string().describe('Prompt unique name.'),
+  description: z.string().optional().describe('Prompt description.'),
+  arguments: z.array(
+    z.object({
+      name: z.string().describe('Argument name.'),
+      description: z.string().optional().describe('Argument description.'),
+      required: z.boolean().optional().describe('Is this argument required?'),
+      type: z.string().describe('Argument type (e.g., string, number, boolean, enum, etc.)'),
+    })
+  ).optional().describe('Prompt arguments.'),
+});
+
+export type Prompt = z.infer<typeof promptSchema>;
+export type PromptArgument = Prompt['arguments'] extends Array<infer T> ? T : never; 

package/src/common/resource-schema.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+
+/**
+ * Zod schema for a single resource.
+ */
+export const resourceSchema = z.object({
+  id: z.string(),
+  type: z.string().optional(),
+  label: z.string().optional(),
+  name: z.string().optional(),
+  description: z.string().optional(),
+  uri: z.string().optional(), // 允许 formbro://xxx 等自定义 scheme
+  mimeType: z.string().optional(),
+  meta: z.record(z.any()).optional(),
+});
+
+export type Resource = z.infer<typeof resourceSchema>; 

package/src/common/tool-schema.ts

@@ -0,0 +1,92 @@
+import { z } from 'zod';
+
+/**
+ * Tool annotations for MCP registerTool API
+ */
+export interface ToolAnnotations {
+  title?: string;
+  readOnlyHint?: boolean;
+  destructiveHint?: boolean;
+  idempotentHint?: boolean;
+  openWorldHint?: boolean;
+}
+
+/**
+ * MCP Tool response content item - matches SDK types
+ */
+export type ToolContentItem = {
+  type: 'text';
+  text: string;
+};
+
+/**
+ * MCP Tool response structure - matches SDK CallToolResult
+ */
+export interface ToolResponse<T = unknown> {
+  content: ToolContentItem[];
+  structuredContent?: T;
+  isError?: boolean;
+  _meta?: Record<string, unknown>;
+}
+
+/**
+ * Tool definition interface for MCP servers
+ */
+export interface Tool<
+  TInput extends z.ZodTypeAny = z.ZodTypeAny,
+  TOutput = unknown
+> {
+  name: string;
+  description: string;
+  inputShape: TInput;
+  outputSchema?: z.ZodTypeAny;
+  annotations?: ToolAnnotations;
+  call: (args: z.infer<TInput>) => Promise<ToolResponse<TOutput>>;
+}
+
+/**
+ * Configuration for registering tools with McpServer
+ */
+export interface ToolRegistrationConfig {
+  title: string;
+  description: string;
+  inputSchema: z.ZodTypeAny;
+  outputSchema?: z.ZodTypeAny;
+  annotations: ToolAnnotations;
+}
+
+/**
+ * Helper to create tool registration config from Tool interface
+ */
+export function createToolConfig(tool: Tool): ToolRegistrationConfig {
+  return {
+    title: tool.annotations?.title || tool.name,
+    description: tool.description,
+    inputSchema: tool.inputShape,
+    outputSchema: tool.outputSchema,
+    annotations: {
+      readOnlyHint: tool.annotations?.readOnlyHint ?? true,
+      destructiveHint: tool.annotations?.destructiveHint ?? false,
+      idempotentHint: tool.annotations?.idempotentHint ?? true,
+      openWorldHint: tool.annotations?.openWorldHint ?? true,
+    },
+  };
+}
+
+/**
+ * Get required environment variable or throw
+ */
+export function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(`Required environment variable ${name} is not set`);
+  }
+  return value;
+}
+
+/**
+ * Get optional environment variable with default
+ */
+export function getEnv(name: string, defaultValue: string): string {
+  return process.env[name] || defaultValue;
+}

package/src/index.ts

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import express, { Request, Response } from 'express';
+
+import { Tool, createToolConfig } from './common/tool-schema.js';
+
+import {
+  KeywordSearchMcpTool,
+  SemanticSearchMcpTool
+} from './noc/index.js';
+
+const allTools: Tool[] = [
+  KeywordSearchMcpTool,
+  SemanticSearchMcpTool,
+];
+
+const SERVER_NAME = 'immicore-noc';
+const SERVER_VERSION = '1.0.0';
+const DEFAULT_HTTP_PORT = 3008;
+
+function createServer(): McpServer {
+  const server = new McpServer({
+    name: SERVER_NAME,
+    version: SERVER_VERSION,
+  });
+
+  for (const tool of allTools) {
+    const config = createToolConfig(tool);
+    server.registerTool(
+      tool.name,
+      {
+        title: config.title,
+        description: config.description,
+        inputSchema: config.inputSchema,
+        annotations: config.annotations,
+      },
+      async (args: Record<string, unknown>) => {
+        const result = await tool.call(args);
+        return {
+          content: result.content as Array<{ type: 'text'; text: string }>,
+          structuredContent: result.structuredContent as Record<string, unknown> | undefined,
+          isError: result.isError,
+        };
+      }
+    );
+  }
+
+  return server;
+}
+
+async function runStdioMode(): Promise<void> {
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(`${SERVER_NAME} running in stdio mode`);
+}
+
+async function runHttpMode(port: number): Promise<void> {
+  const app = express();
+  app.use(express.json());
+
+  app.post('/mcp', async (req, res) => {
+    const server = createServer();
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined,
+      enableJsonResponse: true
+    });
+
+    res.on('close', () => transport.close());
+
+    await server.connect(transport);
+    await transport.handleRequest(req, res, req.body);
+  });
+
+  app.get('/health', (_req, res) => {
+    res.json({ status: 'ok', server: SERVER_NAME, version: SERVER_VERSION });
+  });
+
+  app.listen(port, () => {
+    console.log(`${SERVER_NAME} running in HTTP mode on http://localhost:${port}/mcp`);
+  });
+}
+
+async function runSseMode(port: number): Promise<void> {
+  const app = express();
+  app.use(express.json());
+
+  const sessions: Map<string, { server: McpServer; transport: SSEServerTransport }> = new Map();
+
+  app.get('/sse', (req: Request, res: Response) => {
+    const server = createServer();
+    const transport = new SSEServerTransport('/messages', res);
+    const sessionId = transport.sessionId;
+
+    sessions.set(sessionId, { server, transport });
+
+    res.on('close', () => {
+      sessions.delete(sessionId);
+    });
+
+    server.connect(transport);
+  });
+
+  app.post('/messages', (req: Request, res: Response) => {
+    const sessionId = req.query.sessionId as string;
+    const session = sessions.get(sessionId);
+
+    if (!session) {
+      res.status(404).json({ error: 'Session not found' });
+      return;
+    }
+
+    session.transport.handlePostMessage(req, res, req.body);
+  });
+
+  app.get('/health', (_req, res) => {
+    res.json({ status: 'ok', server: SERVER_NAME, version: SERVER_VERSION, mode: 'sse' });
+  });
+
+  app.listen(port, () => {
+    console.log(`${SERVER_NAME} running in SSE mode on http://localhost:${port}/sse`);
+  });
+}
+
+function parseArgs(): { mode: 'stdio' | 'http' | 'sse'; port: number } {
+  const args = process.argv.slice(2);
+  let mode: 'stdio' | 'http' | 'sse' = 'stdio';
+  let port = DEFAULT_HTTP_PORT;
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--http') {
+      mode = 'http';
+    } else if (args[i] === '--sse') {
+      mode = 'sse';
+    } else if (args[i] === '--stdio') {
+      mode = 'stdio';
+    } else if (args[i] === '--port' && args[i + 1]) {
+      port = parseInt(args[i + 1], 10);
+      i++;
+    }
+  }
+
+  return { mode, port };
+}
+
+async function main(): Promise<void> {
+  const { mode, port } = parseArgs();
+
+  if (mode === 'http') {
+    await runHttpMode(port);
+  } else if (mode === 'sse') {
+    await runSseMode(port);
+  } else {
+    await runStdioMode();
+  }
+}
+
+main().catch(console.error);

package/src/noc/index.ts

@@ -0,0 +1,13 @@
+export {
+  KeywordSearchMcpTool,
+  KeywordSearchInputSchema,
+  KeywordSearchOutputSchema
+} from './keyword_search.tool.js';
+
+export {
+  SemanticSearchMcpTool,
+  SemanticSearchInputSchema,
+  SemanticSearchOutputSchema
+} from './semantic_search.tool.js';
+
+export { keywordSearchPrompts, semanticSearchPrompts } from './prompts.js';

package/src/noc/keyword_search.handler.ts

@@ -0,0 +1,37 @@
+import axios from 'axios';
+import { z } from 'zod';
+import { KeywordSearchInputSchema, KeywordSearchOutputSchema } from './keyword_search.tool.js';
+import { requireEnv } from '../common/tool-schema.js';
+
+function getNocRetrieveApiUrl(): string {
+  const HOST_URL = requireEnv('HOST_URL');
+  return `${HOST_URL}/noc/keyword-noc-retrieve`;
+}
+
+function getSystemToken(): string {
+  return requireEnv('SEARCH_SERVICE_TOKEN');
+}
+
+export async function keywordSearchHandler(
+  input: z.infer<typeof KeywordSearchInputSchema>
+): Promise<z.infer<typeof KeywordSearchOutputSchema>> {
+  try {
+    const response = await axios.post(getNocRetrieveApiUrl(), input, {
+      timeout: 30000,
+      headers: { Authorization: `Bearer ${getSystemToken()}` },
+    });
+    return response.data;
+  } catch (error) {
+    if (axios.isAxiosError(error)) {
+      console.error('Error calling keyword-noc-retrieve API:', error.message);
+      if (error.response) {
+        console.error('Response data:', error.response.data);
+        console.error('Response status:', error.response.status);
+      }
+      throw new Error(`Failed to retrieve NOC entries: ${error.response?.data?.detail || error.message}`);
+    } else {
+      console.error('Unexpected error:', error);
+      throw new Error('An unexpected error occurred while retrieving NOC entries.');
+    }
+  }
+}

package/src/noc/keyword_search.tool.ts

@@ -0,0 +1,96 @@
+import { z } from 'zod';
+import { Tool, ToolResponse } from '../common/tool-schema.js';
+import { keywordSearchHandler } from './keyword_search.handler.js';
+
+export const KeywordSearchInputSchema = z.object({
+  main_duties: z.string().regex(/^[\x00-\x7F]*$/, { message: 'Main duties must be in English and contain only ASCII characters.' }).optional().describe('Main duties for the NOC entry. This should be a concise description of the primary responsibilities, in English. Example: "manage software development projects"'),
+  top_k: z.number().int().optional().default(5).describe('The number of top results to retrieve. Defaults to 5.'),
+  title: z.string().regex(/^[\x00-\x7F]*$/, { message: 'Title must be in English and contain only ASCII characters.' }).optional().describe('The title for the NOC entry. This should be a job title, in English. Example: "Software Project Manager"')
+}).describe('Input schema for the keyword_search tool. All text inputs (main_duties, title) must be in English. If both title and main_duties are omitted, the top_k NOC entries from the entire dataset will be returned.');
+
+export const KeywordSearchOutputSchema = z.array(z.object({
+  noc_code: z.string().describe('The NOC code.'),
+  title: z.string().describe('The title of the NOC entry.'),
+  title_examples: z.array(z.string()).describe('Examples of titles for the NOC entry.'),
+  main_duties: z.array(z.string()).describe('Main duties associated with the NOC entry.'),
+  employment_requirement: z.string().describe('Employment requirement for the NOC entry.'),
+  additional_information: z.array(z.string()).describe('Additional information for the NOC entry.'),
+  exclusion: z.array(z.string()).describe('Exclusions for the NOC entry.'),
+})).describe('Output schema for the keyword_search tool.');
+
+export const NOC_KEYWORD_SEARCH_DESCRIPTION = `Performs a keyword search for National Occupational Classification (NOC) entries using Elasticsearch.
+This tool helps find NOC codes based on job titles and main duties.
+All text inputs (title, main_duties) must be in English.
+If both 'title' and 'main_duties' are omitted, the tool will return the top_k entries from the entire NOC dataset.
+
+Input Parameters:
+  - title (string, optional): The job title to search for (must be in English). Example: "Software Engineer".
+  - main_duties (string, optional): A description of the main duties or responsibilities for the role (must be in English). Example: "design, develop, and test software applications".
+  - top_k (number, optional): The number of top results to retrieve. Defaults to 5.
+
+Example Usage:
+{
+  "title": "Marketing Manager",
+  "main_duties": "develop and implement marketing strategies, manage campaigns, analyze market trends",
+  "top_k": 3
+}
+
+The tool returns a list of matching NOC entries, including the NOC code, title, example titles, main duties, employment requirements, additional information, and exclusions.`;
+
+type KeywordSearchOutput = z.infer<typeof KeywordSearchOutputSchema>;
+
+export const KeywordSearchMcpTool: Tool = {
+  name: 'noc_keyword_search',
+  description: NOC_KEYWORD_SEARCH_DESCRIPTION,
+  inputShape: KeywordSearchInputSchema,
+  outputSchema: KeywordSearchOutputSchema,
+  annotations: {
+    title: 'NOC Keyword Search',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+  call: async (rawInput: z.infer<typeof KeywordSearchInputSchema>): Promise<ToolResponse> => {
+    try {
+      const processedInput = {
+        ...rawInput,
+        title: rawInput.title ?? "",
+        main_duties: rawInput.main_duties ?? ""
+      };
+
+      const nocEntriesArray = await keywordSearchHandler(processedInput);
+
+      if (!nocEntriesArray || nocEntriesArray.length === 0) {
+        return {
+          content: [{ type: 'text' as const, text: 'No NOC entries found for the given criteria.' }],
+          structuredContent: { results: [], total: 0 },
+          _meta: { total: 0 }
+        };
+      }
+
+      return {
+        content: nocEntriesArray.map(entry => ({
+          type: 'text' as const,
+          text: [
+            entry.noc_code ? `NOC Code: ${entry.noc_code}` : 'NOC Code: Not specified',
+            entry.title ? `Title: ${entry.title}` : 'Title: Not specified',
+            entry.title_examples?.length ? `Title Examples: \n - ${entry.title_examples.join('\n - ')}` : '',
+            entry.main_duties?.length ? `Main Duties: \n - ${entry.main_duties.join('\n - ')}` : '',
+            entry.employment_requirement ? `Employment Requirement: ${entry.employment_requirement}` : ''
+          ].filter(Boolean).join('\n\n')
+        })),
+        structuredContent: { results: nocEntriesArray, total: nocEntriesArray.length },
+        _meta: { total: nocEntriesArray.length }
+      };
+    } catch (error: unknown) {
+      const errorMessage = error instanceof Error ? error.message : 'Failed to retrieve NOC entries.';
+      console.error('Error in noc_keyword_search tool call:', error);
+      return {
+        content: [{ type: 'text', text: `Error: ${errorMessage}` }],
+        isError: true,
+        _meta: { error: true }
+      };
+    }
+  },
+};

package/src/noc/prompts.ts

@@ -0,0 +1,31 @@
+import { Prompt } from '../common/prompt-schema.js';
+
+export const keywordSearchPrompts: Prompt[] = [
+  {
+    name: 'noc_keyword_search', // Corresponds to NocKeywordSearchMcpTool.name
+    description: 'Search NOC information using keywords. User can specify query text, NOC code, and top_k results.',
+    arguments: [
+      { name: 'query_text', type: 'string', description: 'The search query text for NOC keywords.', required: true },
+      { name: 'noc_code', type: 'string', description: 'Optional NOC code to filter by (e.g., "2173").', required: false },
+      { name: 'top_k', type: 'number', description: 'Optional number of results to return.', required: false },
+    ],
+  },
+];
+
+export const semanticSearchPrompts: Prompt[] = [
+  {
+    name: 'noc_semantic_search', // Corresponds to NocSemanticSearchMcpTool.name
+    description: 'Perform a semantic search for NOC information. User can specify query text, NOC code, title keywords, and top_k results.',
+    arguments: [
+      { name: 'query_text', type: 'string', description: 'The natural language query for semantic NOC search.', required: true },
+      { name: 'noc_code', type: 'string', description: 'Optional NOC code to filter by (e.g., "2173").', required: false },
+      { name: 'title', type: 'string', description: 'Optional keywords to filter by NOC title.', required: false },
+      { name: 'top_k', type: 'number', description: 'Optional number of results to return.', required: false },
+    ],
+  },
+];
+
+export const nocToolPrompts: Record<string, Prompt[]> = {
+  keyword_search: keywordSearchPrompts, // Tool name from NocKeywordSearchMcpTool
+  semantic_search: semanticSearchPrompts, // Tool name from NocSemanticSearchMcpTool
+};

package/src/noc/semantic_search.handler.ts

@@ -0,0 +1,37 @@
+import axios from 'axios';
+import { z } from 'zod';
+import { SemanticSearchInputSchema, SemanticSearchOutputSchema } from './semantic_search.tool.js';
+import { requireEnv } from '../common/tool-schema.js';
+
+function getNocSearchApiUrl(): string {
+  const HOST_URL = requireEnv('HOST_URL');
+  return `${HOST_URL}/noc/semantic-noc-search`;
+}
+
+function getSystemToken(): string {
+  return requireEnv('SEARCH_SERVICE_TOKEN');
+}
+
+export async function semanticSearchHandler(
+  input: z.infer<typeof SemanticSearchInputSchema>
+): Promise<z.infer<typeof SemanticSearchOutputSchema>> {
+  try {
+    const response = await axios.post(getNocSearchApiUrl(), input, {
+      timeout: 30000,
+      headers: { Authorization: `Bearer ${getSystemToken()}` },
+    });
+    return response.data;
+  } catch (error) {
+    if (axios.isAxiosError(error)) {
+      console.error('Error calling semantic-noc-search API:', error.message);
+      if (error.response) {
+        console.error('Response data:', error.response.data);
+        console.error('Response status:', error.response.status);
+      }
+      throw new Error(`Failed to search NOC entries: ${error.response?.data?.detail || error.message}`);
+    } else {
+      console.error('Unexpected error:', error);
+      throw new Error('An unexpected error occurred while searching NOC entries.');
+    }
+  }
+}

package/src/noc/semantic_search.tool.ts

@@ -0,0 +1,88 @@
+import { z } from 'zod';
+import { Tool, ToolResponse } from '../common/tool-schema.js';
+import { semanticSearchHandler } from './semantic_search.handler.js';
+
+export const SemanticSearchInputSchema = z.object({
+  query_text: z.string().regex(/^[\x00-\x7F]+$/, { message: 'Query text must be in English.' }).describe('The semantic query text for NOC entries. This should be a natural language description of a job, its duties, or skills, in English. Example: "seeking a professional who can lead marketing initiatives and manage a team"'),
+  top_k: z.number().int().optional().default(5).describe('The number of top results to retrieve. Defaults to 5.')
+}).describe('Input schema for the semantic_search tool. The query_text must be in English.');
+
+export const SemanticSearchOutputSchema = z.object({
+  results: z.array(z.object({
+    noc_code: z.string().describe('The NOC code.'),
+    title: z.string().describe('The title of the NOC entry.'),
+    title_examples: z.array(z.string()).describe('Examples of titles for the NOC entry.'),
+    main_duties: z.array(z.string()).describe('Main duties associated with the NOC entry.'),
+    employment_requirement: z.string().describe('Employment requirement for the NOC entry.'),
+    additional_information: z.array(z.string()).describe('Additional information for the NOC entry.'),
+    exclusion: z.array(z.string()).describe('Exclusions for the NOC entry.'),
+  })).describe('List of NOC entries matching the semantic search.'),
+  total: z.number().int().describe('The total number of results found.'),
+}).describe('Output schema for the semantic_search tool.');
+
+export const NOC_SEMANTIC_SEARCH_DESCRIPTION = `Performs a semantic search for National Occupational Classification (NOC) entries using Supabase.
+This tool is useful for finding NOC codes when you can describe a role or its duties in natural language, rather than specific keywords.
+The input query_text must be in English.
+
+Input Parameters:
+  - query_text (string, required): A natural language description of the job, its duties, or required skills (must be in English). Example: "Looking for a job that involves creating visual concepts, by hand or using computer software, to communicate ideas that inspire, inform, or captivate consumers."
+  - top_k (number, optional): The number of top results to retrieve. Defaults to 5.
+
+Example Usage:
+{
+  "query_text": "Manages company's financial planning, reporting, and ensures compliance with financial regulations.",
+  "top_k": 3
+}
+
+The tool returns a list of NOC entries that are semantically similar to the query_text.`;
+
+type SemanticSearchOutput = z.infer<typeof SemanticSearchOutputSchema>;
+
+export const SemanticSearchMcpTool: Tool = {
+  name: 'noc_semantic_search',
+  description: NOC_SEMANTIC_SEARCH_DESCRIPTION,
+  inputShape: SemanticSearchInputSchema,
+  outputSchema: SemanticSearchOutputSchema,
+  annotations: {
+    title: 'NOC Semantic Search',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+  call: async (input: z.infer<typeof SemanticSearchInputSchema>): Promise<ToolResponse> => {
+    try {
+      const result = await semanticSearchHandler(input);
+
+      if (!result.results || result.results.length === 0) {
+        return {
+          content: [{ type: 'text' as const, text: `No NOC entries found for query "${input.query_text}".` }],
+          structuredContent: { results: [], total: 0 },
+          _meta: { total: 0 }
+        };
+      }
+
+      return {
+        content: result.results.map(entry => ({
+          type: 'text' as const,
+          text: [
+            entry.noc_code ? `NOC Code: ${entry.noc_code}` : '',
+            entry.title ? `Title: ${entry.title}` : '',
+            entry.title_examples?.length ? `Title Examples: ${entry.title_examples.slice(0, 3).join(', ')}` : '',
+            entry.main_duties?.length ? `Main Duties: ${entry.main_duties.slice(0, 3).join('; ')}` : ''
+          ].filter(Boolean).join('\n')
+        })),
+        structuredContent: result,
+        _meta: { total: result.total }
+      };
+    } catch (error: unknown) {
+      const errorMessage = error instanceof Error ? error.message : 'Failed to search NOC entries.';
+      console.error('Error in noc_semantic_search tool call:', error);
+      return {
+        content: [{ type: 'text' as const, text: `Error: ${errorMessage}` }],
+        isError: true,
+        _meta: { error: true }
+      };
+    }
+  },
+};

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "resolveJsonModule": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}