novaposhta

@shopanaio/novaposhta

Hosted

0 Stars 2 次浏览 shopanaio 更新于 2026-08-23

MCP Server for Nova Poshta API integration with AI assistants

开发者工具

MCP 服务配置

复制以下 JSON 到 OPClaw 或其他 MCP 客户端的配置文件中即可使用

{
  "mcpServers": {
    "@shopana/novaposhta-mcp-server": {
      "args": [
        "@shopana/novaposhta-mcp-server@0.0.1-alpha.7"
      ],
      "command": "npx"
    }
  }
}

可用工具（5 个）

该服务在 MCP 协议中暴露的工具，AI 可按需调用

tavily_search 14 个参数需填 1 项 Search the web for current information on any topic. Use for news, facts, or data beyond your knowledge cutoff. Returns snippets and source URLs.

Search the web for current information on any topic. Use for news, facts, or data beyond your knowledge cutoff. Returns snippets and source URLs.

必填参数：query

tavily_extract 6 个参数需填 1 项 Extract content from URLs. Returns raw page content in markdown or text format.

Extract content from URLs. Returns raw page content in markdown or text format.

必填参数：urls

tavily_crawl 11 个参数需填 1 项 Crawl a website starting from a URL. Extracts content from pages with configurable depth and breadth.

Crawl a website starting from a URL. Extracts content from pages with configurable depth and breadth.

必填参数：url

tavily_map 8 个参数需填 1 项 Map a website's structure. Returns a list of URLs found starting from the base URL.

Map a website's structure. Returns a list of URLs found starting from the base URL.

必填参数：url

tavily_research 2 个参数需填 1 项 Perform comprehensive research on a given topic or question. Use this tool when you need to gather information from multiple sources to answer a question or complete a task. Returns a detailed response based on the research findings.

Perform comprehensive research on a given topic or question. Use this tool when you need to gather information from multiple sources to answer a question or complete a task. Returns a detailed response based on the research findings.

必填参数：input

服务介绍

@shopana/carrier-api

Modern type-safe API clients for shipping carriers

Features 鈥� Packages 鈥� Quick Start 鈥� Documentation 鈥� Contributing

馃殌 Overview

A production-ready monorepo containing enterprise-grade TypeScript API clients for shipping carriers. Built with modern architecture patterns, each client features plugin-based design, full type safety, and transport-agnostic implementation.

馃幆 Why Carrier API?

鉁� Type-Safe: Complete TypeScript coverage with strict typing
馃攲 Plugin Architecture: Use only what you need, tree-shake the rest
馃寪 Universal: Works in Node.js, browsers, and edge runtimes
馃帹 Transport-Agnostic: Bring your own HTTP client
馃 AI-Ready: MCP server for Claude and other AI assistants
馃摝 Zero Config: Sensible defaults, works out of the box

馃摝 Packages

Carrier API Clients

@shopana/novaposhta-api-client

Nova Poshta API client with plugin architecture and complete type safety.

Features:

馃敡 Plugin-based services (Address, Reference, Tracking, Waybill, Counterparty, ContactPerson)
馃摏 Namespaced API: client.address.*, client.reference.*, client.tracking.*, client.waybill.*
馃幆 Full TypeScript support with strict typing
馃攧 Transport-agnostic design
馃尦 Tree-shakeable - only bundle what you use
馃摉 Comprehensive documentation with examples

npm i @shopana/novaposhta-api-client @shopana/novaposhta-transport-fetch

馃摎 Documentation

AI Integration

@shopana/novaposhta-mcp-server

Model Context Protocol (MCP) server for integrating Nova Poshta with AI assistants like Claude.

Features:

馃 Full MCP 1.22+ support
馃搷 Comprehensive tracking and address search
馃摑 Waybill creation and management
馃摎 Reference data access
馃攧 Dual transport (stdio + HTTP)
馃彚 Production-ready with enterprise-grade error handling

npx @shopana/novaposhta-mcp-server

馃摎 Documentation

Transport Implementations

@shopana/novaposhta-transport-fetch

Fetch-based HTTP transport for Nova Poshta API client.

Features:

馃寪 Cross-platform (Node.js, browsers, edge runtimes)
鈿欙笍 Configurable headers and fetch implementation
馃毇 AbortSignal support for request cancellation
馃摝 Minimal dependencies
鈿� Lightweight and fast

npm i @shopana/novaposhta-transport-fetch

馃摎 Documentation

馃殌 Quick Start

Nova Poshta API Client

import { createClient, AddressService, ReferenceService, TrackingService } from '@shopana/novaposhta-api-client';
import { createFetchHttpTransport } from '@shopana/novaposhta-transport-fetch';

// Create client with plugins
const client = createClient({
  transport: createFetchHttpTransport(),
  baseUrl: 'https://api.novaposhta.ua/v2.0/json/',
  apiKey: process.env.NOVA_POSHTA_API_KEY,
})
  .use(new AddressService())
  .use(new ReferenceService())
  .use(new TrackingService());

// Use the namespaced API
const cities = await client.address.searchCities({ FindByString: '袣懈褩胁', Limit: 10 });
const cargoTypes = await client.reference.getCargoTypes();
const tracking = await client.tracking.trackDocument({ Documents: ['20450123456789'] });

console.log('Found cities:', cities.data.length);
console.log('Package status:', tracking.data[0].Status);

MCP Server for AI Assistants

Add to your .mcp.json or Claude Desktop config:

{
  "mcpServers": {
    "novaposhta": {
      "command": "npx",
      "args": ["-y", "-p", "@shopana/novaposhta-mcp-server", "novaposhta-mcp"],
      "env": {
        "NOVA_POSHTA_API_KEY": "your_api_key_here"
      }
    }
  }
}

Then ask Claude:

"Track Nova Poshta package 20450123456789"
"Find warehouses in Kyiv with POS terminals"
"Calculate shipping cost from Kyiv to Lviv for 5kg parcel"

馃彈锔� Architecture

All carrier clients in this monorepo follow a consistent, battle-tested design pattern:

鈹屸攢鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�
鈹�           Your Application              鈹�
鈹斺攢鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹攢鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�
               鈹�
               鈻�
鈹屸攢鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�
鈹�      Plugin-based API Client            鈹�
鈹�  鈹屸攢鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹� 鈹屸攢鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹� 鈹屸攢鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹� 鈹�
鈹�  鈹� Address  鈹� 鈹俁eference 鈹� 鈹俆racking 鈹� 鈹�
鈹�  鈹� Service  鈹� 鈹� Service  鈹� 鈹� Service 鈹� 鈹�
鈹�  鈹斺攢鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹� 鈹斺攢鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹� 鈹斺攢鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹� 鈹�
鈹斺攢鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹攢鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�
               鈹�
               鈻�
鈹屸攢鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�
鈹�      Transport Layer (Injectable)       鈹�
鈹�         fetch / axios / custom          鈹�
鈹斺攢鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�鈹�

Key Principles

馃攲 Plugin-based: Connect only the services you need
馃幆 Type-safe: Complete TypeScript coverage with inference
馃帹 Transport-agnostic: Use fetch, axios, or custom HTTP client
馃尦 Tree-shakeable: Optimal bundle size - only what you use
馃摏 Namespaced API: Clean, organized method calls
馃И Testable: Mock transport layer for unit tests

馃摎 Documentation

Package Documentation

Additional Resources

馃洜锔� Development

Prerequisites

Node.js 18+ or 20+
Yarn 3+ (Yarn Workspaces)

Setup

# Clone the repository
git clone https://github.com/shopanaio/carrier-api.git
cd carrier-api

# Install dependencies
yarn install

# Build all packages
yarn build

Available Scripts

# Development
yarn dev                  # Watch mode for API client
yarn dev:mcp:stdio        # Run MCP server in stdio mode
yarn dev:mcp:http         # Run MCP server in HTTP mode

# Building
yarn build                # Build API client
yarn build:mcp            # Build MCP server

# Testing
yarn test                 # Run all tests
yarn test:watch           # Run tests in watch mode
yarn test:coverage        # Generate coverage report
yarn test:mcp             # Run MCP server tests

# Code Quality
yarn lint                 # Lint TypeScript files
yarn lint:fix             # Fix linting issues
yarn format               # Format code with Prettier
yarn format:check         # Check code formatting
yarn type-check           # Run TypeScript type checking

Project Structure

carrier-api/
鈹溾攢鈹� packages/
鈹�   鈹溾攢鈹� novaposhta-api-client/       # Core API client
鈹�   鈹�   鈹溾攢鈹� src/
鈹�   鈹�   鈹�   鈹溾攢鈹� core/                # Client core logic
鈹�   鈹�   鈹�   鈹溾攢鈹� services/            # Service plugins
鈹�   鈹�   鈹�   鈹溾攢鈹� types/               # TypeScript types
鈹�   鈹�   鈹�   鈹斺攢鈹� index.ts
鈹�   鈹�   鈹斺攢鈹� package.json
鈹�   鈹�
鈹�   鈹溾攢鈹� novaposhta-mcp-server/       # MCP server for AI
鈹�   鈹�   鈹溾攢鈹� src/
鈹�   鈹�   鈹�   鈹溾攢鈹� cli/                 # CLI entry points
鈹�   鈹�   鈹�   鈹溾攢鈹� tools/               # MCP tools
鈹�   鈹�   鈹�   鈹溾攢鈹� server.ts            # Server implementation
鈹�   鈹�   鈹�   鈹斺攢鈹� config.ts
鈹�   鈹�   鈹斺攢鈹� package.json
鈹�   鈹�
鈹�   鈹斺攢鈹� novaposhta-transport-fetch/  # Fetch transport
鈹�       鈹溾攢鈹� src/
鈹�       鈹斺攢鈹� package.json
鈹�
鈹溾攢鈹� e2e/                             # End-to-end tests
鈹溾攢鈹� postman/                         # Postman collections
鈹溾攢鈹� .mcp.json                        # MCP server config
鈹斺攢鈹� package.json                     # Root package.json

馃 Contributing

We welcome contributions from the community! Whether it's bug fixes, new features, documentation improvements, or examples - all contributions are appreciated.