Maker Circulars MCP Server (Node.js TypeScript)

A Model Context Protocol (MCP) server for managing and searching technical circulars from equipment manufacturers, built with Node.js and TypeScript. This is a TypeScript conversion of the original Python-based MCP server.

Overview

This MCP server provides tools for searching, filtering, and managing circular documents from various equipment manufacturers. It integrates with multiple services including Typesense for search, MongoDB for data storage, and AI services for enhanced search capabilities.

Features

• Smart Circular Search: Universal search tool with semantic search capabilities
• Manufacturer-Specific Queries: Get all circulars from specific equipment makers
• Document Lookup: Find circulars by document name or reference number
• Date Range Filtering: Search circulars within specific time periods
• Vector Search: Advanced search using AI embeddings
• Maker Listings: Get complete list of available manufacturers
• Live Downloads: Fetch latest circulars from manufacturer websites
• Vessel Information: Query machinery details by IMO number
• Web Search: Integrated web search functionality
• Command-Line Configuration: Full support for command-line arguments
• Flexible Configuration: Environment variables, command-line args, or programmatic setup

Prerequisites

• Node.js (v18 or higher)
• MongoDB running locally or accessible instance
• Typesense server (optional, for enhanced search capabilities)
• API keys for AI services (optional):
  • Cohere API key (for reranking)
  • OpenAI API key (for LLM functionality)
  • Perplexity API key (for additional AI features)
  • LlamaParse API key (for document parsing)

Installation

Global Installation (Recommended)

npm install -g maker-circulars-mcp-server

Local Development

1. Clone the repository:

git clone <repository-url>
cd maker-circulars-mcp-server

2. Install dependencies:

npm install

3. Build the project:

npm run build

Configuration

The server supports multiple configuration methods with the following priority:

1. Command-line arguments (highest priority)
2. Environment variables
3. Default values (lowest priority)

Command-Line Arguments

maker-circulars-mcp-server \
  --mongo-uri "mongodb://localhost:27017" \
  --db-name "maker_circulars" \
  --typesense-host "localhost" \
  --typesense-port "8108" \
  --typesense-protocol "http" \
  --typesense-api-key "your_api_key" \
  --cohere-api-key "your_cohere_key" \
  --openai-api-key "your_openai_key" \
  --perplexity-api-key "your_perplexity_key" \
  --llama-api-key "your_llama_key" \
  --vendor-model "your_vendor_model"

Environment Variables

Create a .env file with the following variables:

# MongoDB Configuration
MONGODB_URI=mongodb://localhost:27017
MONGODB_DB_NAME=maker_circulars

# Typesense Configuration (Optional)
TYPESENSE_HOST=localhost
TYPESENSE_PORT=8108
TYPESENSE_PROTOCOL=http
TYPESENSE_API_KEY=your_typesense_api_key_here

# AI Service API Keys (Optional)
COHERE_API_KEY=your_cohere_api_key_here
OPENAI_API_KEY=your_openai_api_key_here
PERPLEXITY_API_KEY=your_perplexity_api_key_here
LLAMA_API_KEY=your_llama_api_key_here
VENDOR_MODEL=your_vendor_model_here

Production Example

# Production deployment with all services
maker-circulars-mcp-server \
  --mongo-uri "mongodb://user:pass@host:27017/database" \
  --db-name "production_db" \
  --typesense-host "search.example.com" \
  --typesense-port "443" \
  --typesense-protocol "https" \
  --typesense-api-key "prod_search_key" \
  --cohere-api-key "prod_cohere_key"

Note: The server will run with reduced functionality if optional services are not configured.

Usage

Global Usage

maker-circulars-mcp-server --help

Development Mode

npm run dev

Production Build and Run

npm run build
npm start

Testing with MCP Inspector

npm run test

This will start the MCP Inspector interface at http://127.0.0.1:6274

Available Tools

The server provides the following MCP tools:

Search Tools

• smart_circular_search - Universal search with semantic capabilities
• get_circular_by_doc_name_or_num - Find by document name or number
• fetch_circular_details_by_vector_search - Vector-based search
• list_maker_specific_circulars - Get all circulars from specific maker
• get_circular_by_maker_and_date_range - Search by maker and date range
• list_all_circular_makers - List all available manufacturers

Data Tools

• get_maker_model_for_particular_imo - Get vessel machinery details by IMO
• latest_circulars_manbw_downloads - Download latest MAN B&W circulars

Utility Tools

• google_search - Web search functionality
• debug_typesense_connection - Debug Typesense connectivity (development)

Project Structure

src/
├── index.ts          # Entry point
├── server.ts         # MCP server setup
├── tools.ts          # Tool implementations
├── tool-schema.ts    # Tool definitions
├── databases.ts      # Database clients
├── constants.ts      # Configuration management
├── resources.ts      # Resource handlers
├── prompts.ts        # Prompt templates
├── utils.ts          # Utility functions
└── logger.ts         # Logging setup

bin/
└── cli.js           # Command-line interface

dist/                # Compiled JavaScript output

Service Dependencies

Required

• MongoDB: Primary database for storing circular and vessel information
  • Handles complex queries and data relationships
  • Stores metadata and search indices

Optional

• Typesense: Enhanced search functionality

  • Full-text and semantic search
  • Faceted navigation
  • Vector search capabilities

• AI Services:

  • Cohere: Document reranking and semantic analysis
  • OpenAI: LLM-based search enhancements
  • Perplexity: Additional AI capabilities
  • LlamaParse: Document parsing and text extraction

Development Status

The project is production-ready with the following status:

• ✅ Core MCP server functionality
• ✅ MongoDB integration
• ✅ Typesense integration with robust error handling
• ✅ TypeScript conversion complete
• ✅ Command-line argument support
• ✅ Flexible configuration management
• ✅ Environment configuration
• ✅ Comprehensive logging system
• ✅ Error handling and graceful degradation
• ✅ AI service integrations
• 🟡 Test coverage (in progress)

Error Handling

The server implements comprehensive error handling:

• Graceful degradation when optional services are unavailable
• Detailed logging for debugging and monitoring
• Proper error responses through MCP protocol
• Connection retry logic for external services
• Validation warnings for missing configuration

Troubleshooting

Common Issues

1. Typesense Connection Issues

   • Verify API key is correct
   • Check host, port, and protocol settings
   • Ensure Typesense server is accessible

2. MongoDB Connection Issues

   • Verify connection string format
   • Check network connectivity
   • Ensure database permissions

3. Missing Collections

   • Verify collection names in Typesense
   • Check data import status

Debug Mode

Enable debug logging with:

maker-circulars-mcp-server --debug

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

MIT License

Support

For support and questions, please open an issue in the repository or contact the development team.

Version History

• v1.0.3 - Production-ready release

  • ✅ Fixed Typesense configuration and collection access
  • ✅ Added comprehensive command-line argument support
  • ✅ Improved error handling and logging
  • ✅ Added LlamaParse integration
  • ✅ Enhanced configuration management

• v0.1.30 - Initial Node.js TypeScript conversion from Python version

  • Includes all features from the original Python implementation
  • Enhanced with TypeScript type safety and modern Node.js patterns