mcp-identification

MCP Identification

A TypeScript library to identify and parse MCP (Model Context Protocol) server configurations from various sources including npm packages, Docker images, Python packages, and SSE endpoints.

Installation

npm install mcp-identification

Usage

Basic Usage

import { determineMcpSource, parseMcpJson } from 'mcp-identification';
import type { McpServerSource, ParsedMcpConfig } from 'mcp-identification';

// Example 1: Using determineMcpSource with a complete server config
const serverConfig: McpServerSource = {
  sourceId: 'my-server',
  name: 'example-server',
  type: 'npx',
  isRemote: true,
  analysisStatus: 'PENDING',
  category: 'development',
  rawConfig: JSON.stringify({
    command: 'npx',
    args: ['-y', 'mcp-server@1.2.3']
  })
};

const result = determineMcpSource(serverConfig);
console.log(result);
// Output: Server object with parsed sourceId, version info, etc.

// Example 2: Using parseMcpJson directly
const mcpConfig: ParsedMcpConfig = {
  command: 'docker',
  args: ['run', 'ghcr.io/some-org/mcp-server:latest']
};

const parsedInfo = parseMcpJson(mcpConfig);
console.log(parsedInfo);
// Output: { id: 'ghcr.io/some-org/mcp-server', version: 'latest', type: 'docker' }

Supported MCP Sources

The library can parse and identify MCP servers from:

NPX Packages

const npxConfig = {
  command: 'npx',
  args: ['-y', 'mcp-server@1.2.3']
};
// Identifies: { id: 'mcp-server', version: '1.2.3' }

Docker Images

const dockerConfig = {
  command: 'docker',
  args: ['run', 'ghcr.io/org/mcp-server:v2.0']
};
// Identifies: { id: 'ghcr.io/org/mcp-server', version: 'v2.0' }

UVX (Python) Packages

const uvxConfig = {
  command: 'uvx',
  args: ['run', 'my-python-mcp@1.0.0']
};
// Identifies: { id: 'my-python-mcp', version: '1.0.0' }

SSE Endpoints

const sseConfig = {
  url: 'https://api.example.com/mcp?token=abc123'
};
// Identifies: { id: 'https://api.example.com/mcp', config: 'full-url-with-token' }

API Reference

determineMcpSource(server: McpServerSource)

Main function to determine the source of an MCP server configuration.

Parameters:

• server: Complete MCP server configuration object

Returns: Enhanced server object with parsed source information

parseMcpJson(configJson: ParsedMcpConfig, gitUrl?: string)

Parse a raw MCP configuration to extract source information.

Parameters:

• configJson: Raw MCP configuration object
• gitUrl: Optional Git URL for repository-based MCPs

Returns: McpSourceInfo object with parsed details

Types

export type ParsedMcpConfig = {
  command?: string;
  args?: string[];
  url?: string;
};

export type McpSourceInfo = {
  id?: string;
  version?: string;
  type?: McpServerType;
  config?: string;
};

export enum McpServerType {
  COMMAND = 'command',
  SSE = 'sse',
  DOCKER = 'docker',
  UVX = 'uvx',
  UNKNOWN = 'unknown',
  NPX = 'npx',
  NODE = 'node',
  PIP = 'pip',
  PYTHON = 'python',
  GENERIC = 'generic',
}

Development

# Install dependencies
npm install

# Run tests
npm test

# Build the package
npm run build

# Watch mode for tests
npm run test:watch

# Run the example
npm run example

# Test what files will be included in the package
npm run pack-test

Publishing

To publish this package to npm:

• Make sure you're logged in to npm: npm login
• Update the version in package.json
• Run npm publish

The prepublishOnly script will automatically build the package before publishing.

Package Contents

When published, the package will include:

• dist/ - Compiled JavaScript and TypeScript definitions
• README.md - Documentation
• package.json - Package metadata

Source files, tests, and development configurations are excluded via .npmignore.

License

ISC