Skip to main content
Glama
Libs MCP Service

Libs MCP Service

by AdminRHS

Libs MCP Service

A Model Context Protocol (MCP) service for integration with external platforms. This service provides CRUD operations for various entities through a standardized MCP interface using the official MCP SDK.

Quick Setup

Configuration

Add the following to your MCP configuration:

{
  "mcpServers": {
    "libs-mcp-service": {
      "command": "npx",
      "args": ["github:AdminRHS/libs-mcp-service"],
      "env": {
        "API_TOKEN": "your_actual_token_here",
        "API_BASE_URL": "https://libs.anyemp.com",
        "MODE": "light"
      }
    }
  }
}

Important: Replace your_actual_token_here with your real API token from the external platform.

Environment Variables

Variable

Required

Description

Default

API_TOKEN

Yes

Authentication token for the external platform

-

API_BASE_URL

Yes

Base URL for the external API

-

MODE

No

UI mode: light (minimal) or standard (full). Affects tool list and response shape

standard

API Environments

  • Production: https://libs.anyemp.com - Main microservice for libraries

  • Development: https://libdev.anyemp.com - Recommended for development and testing

Recommendation: Use the development environment for testing to avoid affecting production data.

Related MCP server: Azure AHDS FHIR MCP Server

โœจ Features

  • ๐Ÿข Official MCP SDK: Full MCP compliance using @modelcontextprotocol/sdk

  • ๐Ÿ”ง Universal Tools: list, get, create, update for all 20+ entity types

  • โšก Performance: Response caching with TTL and smart invalidation

  • ๐Ÿ›ก๏ธ Security: Rate limiting, request size caps, and bearer token authentication

  • ๐Ÿ”„ Smart Updates: Automatic term preservation in update operations

  • ๐Ÿค– AI Metadata: Comprehensive tracking for AI-generated content

  • ๐Ÿ“ฑ Dual Modes: Light mode for minimal UIs, standard mode for full functionality

  • ๐Ÿš€ Easy Deployment: Executable via npx without local installation

๐ŸŽ›๏ธ Modes

Configure behavior with the MODE environment variable:

Light Mode (MODE=light)

  • Same tool list: All tools available (no filtering)

  • Auto-optimization: List operations automatically add all=true and isShort=true parameters

  • Reduced responses: Single get operations return { id, name } format

  • Perfect for: Claude, ChatGPT, and other token-conscious clients

Standard Mode (MODE=standard)

  • Full tool list: All available tools shown

  • Complete responses: Full entity payloads in all operations

  • Manual control: Explicit parameters required for optimization

  • Perfect for: Development and full-featured applications

๐Ÿ› ๏ธ Available Tools

Universal Tools (All Entities)

  • list โ€” List entities with pagination and search

  • get โ€” Fetch single entity by ID

  • create โ€” Create new entity with AI metadata support

  • update โ€” Update entity with automatic term preservation

Essential Specialized Tools

  • get_term_types โ€” Retrieve available term types

  • get_priorities โ€” Retrieve all priorities

  • find_existing_responsibility_terms โ€” Check existing action-object term combinations

  • create_term โ€” Create individual terms with AI metadata

  • update_term โ€” Update individual terms with AI metadata

AI metadata behavior:

  • Create: include aiMetadata only for the term(s) you want marked/recorded as AI-generated; others remain unchanged.

  • Update: include aiMetadata only for term(s) you intend to change; omitting it leaves existing AI fields as-is.

Supported Entities (23 Types)

  • Core: Departments, Professions, Languages, Countries, Cities

  • Content: Actions, Objects, Responsibilities, Formats

  • Organization: Industries, Sub-Industries, Tools, Tool Types

  • System: Statuses, Term Types, Individual Terms

  • Management: Shifts, Currencies, Rates, Levels, Positions, Skills, Priorities

๐Ÿ“š Common Usage Patterns

// List departments with search
{
  "resource": "departments",
  "search": "engineering", 
  "limit": 5
}

Create Entity with AI Metadata

// Create department with AI tracking
{
  "resource": "departments",
  "payload": {
    "mainTerm": {
      "value": "Data Science",
      "language_id": 1,
      "term_type_id": 1,
      "aiMetadata": {
        "ai_generated": true,
        "ai_model": "gpt-4o",
        "ai_confidence_score": 9.5
      }
    }
  }
}

Update with Term Preservation

// Update preserves existing terms automatically
{
  "resource": "departments", 
  "id": "123",
  "payload": {
    "mainTerm": {
      "value": "Updated Name",
      "language_id": 1,
      "term_type_id": 1
    }
    // Existing terms automatically preserved
  }
}

๐Ÿ—๏ธ Architecture

Core Components

  • index.js - Main MCP server with official SDK integration

  • config.js - Environment validation and configuration

  • api.js - HTTP client with caching, timeouts, and error handling

  • entities.js - CRUD operations for all 23 entity types

  • tools.js - MCP tool definitions with JSON Schema validation

  • handlers.js - Tool handler mappings and routing

Advanced Features

  • src/errors.js - Structured error handling with MCP formatting

  • src/cache.js - Response caching with TTL and smart invalidation

  • src/rateLimit.js - Fixed-window rate limiting per client

Build System

  • libs-mcp-service.js - Bundled executable (530KB) for npx deployment

๐Ÿงช Testing Status

โœ… Comprehensive Testing Complete (23/23 Entities)

Entity Category

Entities

Status

Features Tested

Core

Departments, Professions, Languages

โœ… Complete

CRUD, AI metadata, term preservation

Geography

Countries, Cities

โœ… Complete

Complex terms, ISO codes, coordinates

Content

Actions, Objects, Responsibilities

โœ… Complete

Term relationships, format linking

Organization

Industries, Sub-Industries

โœ… Complete

Parent-child relationships

System

Tools, Tool Types, Formats

โœ… Complete

Many-to-many relationships

Meta

Statuses, Term Types, Terms

โœ… Complete

Individual term management

Management

Shifts, Currencies, Rates, Levels, Positions, Skills, Priorities

โœ… Complete

Time, financial, position, role, skill, and priority management

Key Testing Results

  • โœ… Schema Validation: All entity schemas validated against actual API

  • โœ… Permission Testing: Proper 403 handling for restricted operations

  • โœ… AI Metadata: Comprehensive testing of AI tracking fields

  • โœ… Term Preservation: Smart update logic maintains existing terms

  • โœ… Relationship Handling: Complex entity relationships working correctly

  • โœ… Error Handling: Structured errors with proper MCP formatting

๐Ÿ”’ Security Features

  • ๐Ÿ›ก๏ธ Bearer Authentication: Secure API token handling

  • โฑ๏ธ Rate Limiting: 60 requests/minute per client (configurable)

  • ๐Ÿ“ Request Size Limits: 100KB body size cap

  • ๐Ÿ” Secret Masking: Authorization headers masked in cache keys

  • โฐ Timeout Protection: 30-second request timeouts with AbortController

๐Ÿ“ˆ Performance Optimizations

  • ๐Ÿ’พ Response Caching: 5-minute TTL with smart invalidation

  • ๐Ÿ—‚๏ธ Cache Management: Automatic prefix-based invalidation on writes

  • ๐Ÿ“ฆ Bundle Optimization: Minified 530KB bundle with tree-shaking

  • โšก Efficient Updates: Term preservation reduces API calls

๐Ÿš€ Installation & Deployment

npx github:AdminRHS/libs-mcp-service

Option 2: Global Installation

npm install -g github:AdminRHS/libs-mcp-service
libs-mcp-service

Option 3: Development Mode

git clone https://github.com/AdminRHS/libs-mcp-service.git
cd libs-mcp-service
npm install
npm run dev

๐Ÿ”ง API Integration

The service expects RESTful endpoints following this pattern:

GET    /api/token/{entity}           # List with pagination
GET    /api/token/{entity}/:id       # Get by ID  
POST   /api/token/{entity}           # Create new
PUT    /api/token/{entity}/:id       # Update existing
DELETE /api/token/{entity}/:id       # Delete (where permitted)

All requests include Authorization: Bearer <API_TOKEN> header.

Supported Endpoints

  • /api/token/departments - Department management

  • /api/token/professions - Profession management

  • /api/token/languages - Language and term management

  • /api/token/countries - Country data with ISO codes

  • /api/token/cities - City data with coordinates

  • /api/token/actions - Action definitions with terms

  • /api/token/objects - Object definitions with formats

  • /api/token/responsibilities - Responsibility linking

  • /api/token/industries - Industry classifications

  • /api/token/sub-industries - Sub-industry definitions

  • /api/token/tools - Tool management with types

  • /api/token/tool-types - Tool type definitions

  • /api/token/formats - Format specifications

  • /api/token/statuses - Status management

  • /api/token/priorities - Priority management

  • /api/token/term-types - Term type definitions

  • /api/token/terms - Individual term management

  • /api/token/shifts - Working time management

  • /api/token/currencies - Currency management

  • /api/token/rates - Rate management

  • /api/token/levels - Position level management

  • /api/token/positions - Position and role management

  • /api/token/skills - Skill management (responsibility-tool relationships)

๐Ÿ› Troubleshooting

Common Issues

โŒ "API_TOKEN environment variable is required"

  • Verify API_TOKEN is set in your MCP client configuration

  • Check for typos in environment variable names

โŒ "HTTP error! status: 401"

  • Verify your API token is valid and not expired

  • Ensure proper Bearer token format

โŒ "HTTP error! status: 403"

  • Normal behavior for write operations on most entities

  • Only certain entities allow POST/PUT operations

โŒ "Rate limit exceeded"

  • Check if multiple clients are using same configuration

โŒ Service not starting

  • Ensure Node.js 18+ is installed

  • Check network connectivity to API_BASE_URL

Debug Mode

Enable detailed logging:

DEBUG=* npx github:AdminRHS/libs-mcp-service

Health Check

Test connectivity:

// Use 'list' tool with minimal parameters
{
  "resource": "term_types",
  "limit": 1
}

๐Ÿ“Š Metrics & Monitoring

The service includes built-in metrics tracking:

  • Request counts by tool and entity type

  • Error rates with status code breakdown

  • Cache hit/miss ratios for performance monitoring

  • Rate limit statistics per client

  • Response times for performance analysis

๐Ÿค– AI Metadata Support

Comprehensive AI tracking for all terms and entities:

Supported Fields

  • ai_generated - Whether content was AI-generated

  • ai_model - AI model used (e.g., "gpt-4o", "claude-3.5")

  • ai_confidence_score - Confidence rating (0.00-9.99)

  • ai_quality_score - Quality assessment (0.00-9.99)

  • ai_validation_status - Review status ("pending", "approved", "rejected")

  • ai_human_reviewed - Human review flag

  • ai_source_data - Original source information

  • ai_metadata - Additional AI-specific data

Usage Examples

See docs-models/AI_METADATA_GUIDE.md for comprehensive examples and best practices.

๐Ÿ“„ License

MIT License - see LICENSE file for details.

๐Ÿค Contributing

  1. Fork the repository

  2. Create a feature branch (git checkout -b feature/amazing-feature)

  3. Make your changes

  4. Run npm run build to update the bundled file

  5. Commit both source and bundled files

  6. Submit a pull request

๐Ÿ“ž Support

  • Issues: Create an issue on GitHub

  • Documentation: Check the docs-models/ directory

  • API Questions: Verify API_BASE_URL and token configuration

  • Performance: Monitor cache hit rates and adjust TTL settings


Status: โœ… Production Ready - All 23 entities tested and validated

Built with โค๏ธ using the official Model Context Protocol SDK

Available Tools

11 tools
createA

Create an entity for the given resource. Payload shape depends on resource (e.g., departments, professions, languages, etc.). For entities with terms, provide mainTerm and optional terms with correct IDs/types. IMPORTANT: When creating AI-generated content, ALWAYS include aiMetadata fields with ai_generated=true, ai_model (e.g., "gpt-4o-mini"), and ai_generation_date. Only attach aiMetadata to the specific term(s) you are creating; terms without aiMetadata will not be touched.

Inputs: payload (required), resource (required).

create_termA

Create a new individual term using API token authentication. Terms can exist independently and be linked to term groups. IMPORTANT: When creating AI-generated terms, ALWAYS include aiMetadata with ai_generated=true, ai_model (e.g., "gpt-4o-mini"), and ai_generation_date for proper tracking. Only the created termโ€™s AI metadata is affected.

Inputs: value (required), language_id (required), term_type_id (required), term_group_id (required), +3 more.

find_existing_responsibility_termsA

Find existing Actions and Objects by language to check what terms already exist. Use this BEFORE adding new terms to responsibilities. This tool helps you find existing responsibility combinations or check if a specific action-object pair already has terms.

Inputs: action_id (required), object_id (required), language_id (required), term_type_id (required), +1 more.

find_existing_skill_termsA

Find existing Skills by responsibility and tool to check what terms already exist. Use this BEFORE adding new terms to skills. This tool helps you find existing skill combinations or check if a specific responsibility-tool pair already has terms.

Inputs: tool_id (required), language_id (required), term_type_id (required), responsibility_id (required), +1 more.

getC

Get single entity by ID (short form in light mode)

Inputs: id (required), resource (required), isShort.

get_prioritiesC

Get all priorities

Inputs: page, limit, search.

get_priorityA

Get single priority by ID

Inputs: id (required), isShort.

get_term_typesC

Get all term types

Inputs: page, limit, search.

listC

List entities (supports UA/RU/EN resource names)

Inputs: resource (required), all, page, limit, +2 more.

updateA

Update an entity by ID for the given resource. Payload shape depends on resource. For term-managed entities, send the FULL terms array on update to avoid deletions (include unchanged terms with their IDs). IMPORTANT: Include aiMetadata ONLY for the term(s) you want to update; other terms without aiMetadata in the payload will keep their existing AI metadata. Recommended fields when updating AI-generated content: ai_generated=true, ai_model (e.g., "gpt-4o-mini"), ai_generation_date.

Inputs: id (required), payload (required), resource (required).

update_termA

Update an existing individual term using API token authentication. IMPORTANT: Send aiMetadata only when you intend to change AI fields for this term; omitting aiMetadata leaves existing AI fields unchanged. Recommended: include ai_generated=true, ai_model, ai_generation_date. Supports version tracking and term group relation management.

Inputs: termId (required), term_group_id (required), value, status_id, +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    TDQS

    B3.2/5.0

    Scored across 11 tools

    Disambiguation3/5

    Generic tools like list/get/create/update overlap with specialized tools like get_priority, create_term, and update_term, making it unclear whether to use the generic path or the specialized one for term and priority operations. Descriptions help clarify intent, but the boundaries are not crisp.

    Naming Consistency3/5

    The generic operations use bare verbs (list, get, create, update) while the specialized operations use verb_noun patterns (get_priority, create_term, find_existing_skill_terms), so the naming convention is mixed. All names are readable and consistently snake_case, but the pattern is not uniform.

    Tool Count5/5

    Eleven tools is a reasonable count for an entity/term management server, covering generic resource operations plus dedicated priority, term type, and lookup helpers. Each tool appears purposeful and the set is not bloated.

    Completeness3/5

    The tool surface covers list, get, create, and update operations, but there is no delete operation for entities or terms, which leaves the lifecycle incomplete. The find_existing_* helpers partially cover term discovery, but dedicated term listing/retrieval is still somewhat implicit.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that provides AI models with structured access to external data and services, acting as a bridge between AI assistants and applications, databases, and APIs in a standardized, secure way.
      2
      -
    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      A Model Context Protocol service registry and connector framework that enables seamless integration with multiple services and models through a standardized API interface. Provides an extensible architecture for custom service adapters, API integrations, and model registries.
      -