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

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 Entities with Search

// 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)

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

Option 1: Direct Execution (Recommended)

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