Purchase MCP Server

A TypeScript-based server for handling purchase-related operations, casefile management, and document processing.

Features

• Document parsing and processing
• Casefile management
• Vendor search and contact information
• Purchase requisition handling
• Expense tracking
• Budget management
• Typesense integration for search
• MongoDB integration for data storage

Prerequisites

• Node.js (v18 or higher)
• MongoDB
• Typesense
• OpenAI API key
• LlamaParse API key
• Perplexity API key

Configuration

You can configure the server in two ways:

1. Environment Variables (.env file)

Create a .env file in the root directory:

1MONGO_URI=mongodb://localhost:27017
2DB_NAME=mcp_purchase
3TYPESENSE_HOST=localhost
4TYPESENSE_PORT=8108
5TYPESENSE_PROTOCOL=http
6TYPESENSE_API_KEY=your_typesense_api_key
7OPENAI_API_KEY=your_openai_api_key
8LLAMA_API_KEY=your_llama_api_key
9VENDOR_MODEL=gpt-4
10S3_API_TOKEN=your_s3_api_token
11S3_GENERATE_HTML_URL=your_s3_generate_html_url
12LLAMA_PARSE_URL=your_llama_parse_url
13PERPLEXITY_API_KEY=your_perplexity_api_key
14GOOGLE_CLIENT_ID=your_google_client_id
15GOOGLE_CLIENT_SECRET=your_google_client_secret
16GOOGLE_REDIRECT_URI=your_google_redirect_uri
17GOOGLE_API_KEY=your_google_api_key
18GOOGLE_SEARCH_ENGINE_ID=your_google_search_engine_id
19COHERE_API_KEY=your_cohere_api_key

2. Command Line Arguments

Command line arguments will override values from the .env file:

1node dist/index.js \
2  --mongo-uri mongodb://localhost:27017 \
3  --db-name mcp_purchase \
4  --typesense-host localhost \
5  --typesense-port 8108 \
6  --typesense-protocol http \
7  --typesense-api-key your_api_key \
8  --openai-api-key your_openai_key \
9  --llama-api-key your_llama_key \
10  --vendor-model gpt-4 \
11  --s3-api-token your_s3_token \
12  --perplexity-api-key your_perplexity_key

Available Command Line Arguments

Argument	Environment Variable	Default	Description
--mongo-uri	MONGO_URI	mongodb://localhost:27017	MongoDB connection URI
--db-name	DB_NAME	mcp_purchase	MongoDB database name
--typesense-host	TYPESENSE_HOST	localhost	Typesense server host
--typesense-port	TYPESENSE_PORT	8108	Typesense server port
--typesense-protocol	TYPESENSE_PROTOCOL	http	Typesense protocol (http/https)
--typesense-api-key	TYPESENSE_API_KEY	(empty)	Typesense API key
--openai-api-key	OPENAI_API_KEY	(empty)	OpenAI API key
--llama-api-key	LLAMA_API_KEY	(empty)	LlamaParse API key
--vendor-model	VENDOR_MODEL	gpt-4	Default LLM model
--s3-api-token	S3_API_TOKEN	(empty)	S3 API token
--s3-generate-html-url	S3_GENERATE_HTML_URL	(empty)	S3 HTML generation URL
--llama-parse-url	LLAMA_PARSE_URL	(empty)	LlamaParse service URL
--perplexity-api-key	PERPLEXITY_API_KEY	(empty)	Perplexity API key
--google-client-id	GOOGLE_CLIENT_ID	(empty)	Google OAuth client ID
--google-client-secret	GOOGLE_CLIENT_SECRET	(empty)	Google OAuth client secret
--google-redirect-uri	GOOGLE_REDIRECT_URI	(empty)	Google OAuth redirect URI
--google-api-key	GOOGLE_API_KEY	(empty)	Google API key
--google-search-engine-id	GOOGLE_SEARCH_ENGINE_ID	(empty)	Google Custom Search Engine ID
--cohere-api-key	COHERE_API_KEY	(empty)	Cohere API key

Installation

1. Clone the repository:

1git clone https://github.com/yourusername/purchase_mcp_server.git
2cd purchase_mcp_server

2. Install dependencies:

1npm install

3. Build the project:

1npm run build

4. Start the server:

1npm start

Development

For development with hot reload:

1npm run dev

Testing

Test the server with MCP Inspector:

1npm test

MCP Tools and Resources

Document Tools

• parse_document_link: Parse documents from URLs or local files
• write_casefile_data: Create and update casefiles
• retrieve_casefile_data: Search and retrieve casefiles
• get_all_vessel_purchase_requisitions: Get vessel purchase requisitions
• get_vessel_expense_data: Retrieve vessel expense information
• get_complete_vessel_budget_data: Get comprehensive vessel budget information

Vendor Tools

• find_relevant_vendors: Search for vendors by name, service, or location
• get_vendor_contact_details: Retrieve vendor contact information

Search Tools

• google_search: Perform Google searches
• smart_purchase_table_search: Advanced purchase search with filters
• smart_budget_search: Advanced budget search with filters
• smart_expense_search: Advanced expense search with filters
• vessel_info_search: Search for vessel information
• mongodb_find: Direct MongoDB queries

Purchase Management Tools

• get_purchase_requisition_details: Get detailed purchase requisition information
• get_purchase_order_details: Get detailed purchase order information
• list_requisitions_by_status: List requisitions filtered by status
• list_purchase_orders_by_status: List purchase orders by status
• list_overdue_open_requisitions: Find overdue requisitions
• list_recent_vessel_purchase_requisitions: Get recent vessel requisitions
• list_top_expenses_by_category: Get top expenses by category

Project Structure

src/
├── tools/
│   ├── documentTools.ts    # Document processing and casefile management
│   ├── purchaseTools.ts    # Purchase requisition and order management
│   ├── searchTools.ts      # Search functionality
│   ├── vendorTools.ts      # Vendor management
│   └── index.ts           # Main tool handler
├── utils/
│   ├── config.ts          # Configuration management with CLI support
│   ├── logger.ts          # Logging utilities
│   ├── mongodb.ts         # MongoDB client
│   ├── typesense.ts       # Typesense client
│   └── llm.ts            # LLM integration
├── types/
│   └── index.ts          # TypeScript type definitions
└── index.ts              # Main application entry point

Key Features

Document Processing

• Parse documents from URLs or local files
• Generate markdown and JSON outputs
• Support for various document formats

Casefile Management

• Create and update casefiles
• Track casefile status and importance
• Manage casefile pages and indexes
• Generate casefile URLs

Vendor Management

• Search for vendors by name, service, and location
• Retrieve vendor contact information
• Store and update vendor data

Vessel Data

• Track purchase requisitions
• Monitor expenses
• Manage budgets
• Link data to vessels by IMO

Search Integration

• Full-text search using Typesense
• Vector search for semantic matching
• Filtering and pagination support

Error Handling

The application implements comprehensive error handling:

• Input validation
• Database operation error handling
• API integration error handling
• Proper error logging
• User-friendly error messages

Logging

Logging is implemented using Winston that:

• Logs to console with timestamps
• Includes different log levels (debug, info, error)
• Provides detailed error information
• Supports structured logging

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.