Yirifi MCP Server (TypeScript)

A Model Context Protocol (MCP) server that provides Claude and other AI assistants with access to Yirifi's GRC platform external APIs. This enables AI-powered exploration of regulations, GRC knowledge base, vendor marketplace, and more.

Overview

The Yirifi MCP server exposes 45+ tools organized across three main services:

• RegDB Service: Regulations, articles, organizations, and regulatory bodies
• Web3GRC Service: Knowledge base (categories, components, FAQs, glossary), marketplace (vendors, people), news, and templates
• Risk Assessment Service: Risk items, red flags, and incidents

Features

• Comprehensive access to all Yirifi external APIs
• Tool filtering - Expose only the tools you need via YIRIFI_TOOLS env var
• Type-safe input validation with Zod schemas
• Auto-generated JSON schemas for MCP tool definitions from Zod
• Async/await architecture for optimal performance
• Modular code organization with clean separation of concerns
• Single base URL configuration for all services
• Detailed error messages for easy debugging
• Environment-based configuration
• Production-ready code quality with TypeScript strict mode
• Development watch mode with tsx
• Biome for fast linting and formatting

Prerequisites

Before setting up the MCP server, ensure you have:

1. Node.js 18 or higher - Check with node --version
2. Yarn package manager - Install with npm install -g yarn
3. Running Yirifi backend - Services must be accessible (or use production URL)
4. Yirifi API Key - Generated from the Yirifi dashboard

Installation

1. Install Dependencies

yarn install

This installs all required packages:

• @modelcontextprotocol/sdk - MCP protocol implementation
• axios - HTTP client for API requests
• dotenv - Environment variable management
• zod - TypeScript-first schema validation
• zod-to-json-schema - Convert Zod schemas to JSON Schema
• TypeScript and development tools

2. Create Environment Configuration

Create a .env file in the mcp_server directory:

cp .env.example .env

Edit .env and add your configuration:

YIRIFI_API_KEY=your_api_key_here
YIRIFI_BASE_URL=https://dev-api.yirifi.ai

Environment Variables:

• YIRIFI_API_KEY - Your Yirifi API key (required)
• YIRIFI_BASE_URL - Base URL for Yirifi services (default: https://dev-api.yirifi.ai)
• YIRIFI_TOOLS - Tool filtering whitelist (optional, see Tool Filtering)

Tool Filtering

By default, all 37 tools are exposed. To reduce context window usage, you can filter which tools are available using the YIRIFI_TOOLS environment variable.

Pattern Syntax

# Service-level wildcard (all tools from a service)
YIRIFI_TOOLS="regdb:*"

# Category-level wildcard
YIRIFI_TOOLS="web3grc:knowledge:*"

# Multiple patterns
YIRIFI_TOOLS="regdb:*,web3grc:knowledge:*"

Available Patterns

| Pattern | Description | Tools | |---------|-------------|-------| | regdb:* | All RegDB tools | 10 | | regdb:countries:* | Country regulatory tools | 3 | | regdb:articles:* | Article/regulation tools | 3 | | regdb:organizations:* | Organization tools | 4 | | web3grc:* | All Web3GRC tools | 27 | | web3grc:knowledge:* | Knowledge base tools | 14 | | web3grc:marketplace:* | Vendor/people marketplace | 9 | | web3grc:common:* | News and templates | 4 | | risk-assessment:* | All Risk Assessment tools | 8 | | risk-assessment:risk-items:* | Risk item/category tools | 4 | | risk-assessment:red-flags:* | Red flag tools | 2 | | risk-assessment:incidents:* | Incident tools | 2 |

Example Configurations

# Only regulations research
YIRIFI_TOOLS="regdb:*"

# Only vendor comparison features
YIRIFI_TOOLS="web3grc_list_vendors,web3grc_get_vendor,web3grc_compare_vendors"

# Knowledge base + regulations
YIRIFI_TOOLS="regdb:articles:*,web3grc:knowledge:*"

Development

Run in Development Mode

Watch mode with automatic rebuilds:

yarn dev

Build for Production

yarn build

This compiles TypeScript to JavaScript in the dist/ directory.

Run Production Build

yarn start

Type Checking

yarn typecheck

Linting and Formatting

yarn lint        # Check code quality
yarn format      # Format code

Transport Modes

The server supports two transport modes:

| Mode | Use Case | API Key | |------|----------|---------| | STDIO | Claude Desktop integration | From YIRIFI_API_KEY env var | | HTTP | Remote/Docker deployments | From api-key request header |

Using with Claude Desktop (STDIO)

You can run the MCP server in three ways:

• Method 1: Local Build - Run the compiled server directly
• Method 2: npm link - Create a global symlink for local development
• Method 3: GitHub via npx - Run directly from GitHub repository

Method 1: Run Locally (Recommended for Development)

1. Build the Server

yarn build

2. Configure Claude Desktop

Edit your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the server configuration:

{
  "mcpServers": {
    "yirifi": {
      "command": "node",
      "args": [
        "/absolute/path/to/yirifi-external-api-mcp/dist/server-stdio.js"
      ],
      "env": {
        "YIRIFI_API_KEY": "your_api_key_here",
        "YIRIFI_BASE_URL": "https://dev-api.yirifi.ai",
        "YIRIFI_TOOLS": "regdb:*,web3grc:knowledge:*"
      }
    }
  }
}

Tip: Use YIRIFI_TOOLS to limit exposed tools and reduce context window usage. Omit it to expose all 37 tools.

Important:

• Use absolute paths
• Replace /absolute/path/to/yirifi-external-api-mcp with your actual path
• Set your actual API key

3. Restart Claude Desktop

Quit and relaunch Claude Desktop for changes to take effect.

4. Verify Installation

In Claude Desktop, you should see the Yirifi MCP server listed in the available tools. Try asking:

"Can you list all available countries in the Yirifi regulations database?"

Method 2: Using npm link (For Local Development)

npm link creates a global symlink to your local package, allowing you to run the MCP server as if it were installed globally. This is ideal for development and testing.

1. Build and Link the Package

cd /path/to/yirifi-backend/mcp_server

# Install dependencies and build
yarn install
yarn build

# Create global symlink
npm link

This creates a global symlink named yirifi-mcp (from the bin field in package.json).

2. Verify the Link

# Check the symlink was created
npm list -g --depth=0

# Test the command
yirifi-mcp --help

3. Configure Claude Desktop

Edit your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "yirifi": {
      "command": "yirifi-mcp",
      "args": [],
      "env": {
        "YIRIFI_API_KEY": "your_api_key_here",
        "YIRIFI_BASE_URL": "https://dev-api.yirifi.ai",
        "YIRIFI_TOOLS": "regdb:*,web3grc:knowledge:*"
      }
    }
  }
}

Benefits of npm link:

• ✅ Simple command name (no paths needed)
• ✅ Changes to source reflect after rebuild
• ✅ Works like a globally installed package
• ✅ Easy to share config with team members

Development Workflow:

# Make changes to source code
# Rebuild to update the linked package
yarn build

# Restart Claude Desktop to pick up changes

4. Unlinking

To remove the global symlink:

cd /path/to/yirifi-backend/mcp_server
npm unlink

Method 3: Run from GitHub (Using npx)

This method allows you to run the MCP server directly from a GitHub repository without cloning it locally. Ideal for production or when you want to use a specific version/branch.

How It Works: The prepare Script

The package.json includes a prepare script that automatically builds the TypeScript code when installed from GitHub:

{
  "scripts": {
    "prepare": "npm run build"
  },
  "bin": {
    "yirifi-mcp": "dist/index.js"
  }
}

When npx installs the package from GitHub:

1. It clones/downloads the repository
2. Runs npm install to install dependencies
3. Automatically runs the prepare script which executes npm run build
4. The TypeScript is compiled to JavaScript in dist/
5. The bin entry makes yirifi-mcp executable

This means the package works directly from source without requiring pre-compiled files in the repository.

Prerequisites

1. GitHub Repository: Your code must be in a GitHub repository (public or private)
2. GitHub Personal Access Token (PAT): Required for private repositories

Step 1: Create a GitHub Personal Access Token (PAT)

1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)

   • Direct link: https://github.com/settings/tokens

2. Click "Generate new token" → "Generate new token (classic)"

3. Configure the token:

   • Note: Give it a descriptive name (e.g., "Claude Desktop MCP Server")
   • Expiration: Choose your preferred expiration (or "No expiration" for convenience)
   • Scopes: Select these permissions:
     • ✅ repo (Full control of private repositories) - if using private repo
     • ✅ read:org (Read org and team membership) - optional, for org repos

4. Click "Generate token" at the bottom

5. IMPORTANT: Copy the token immediately! You won't be able to see it again.

   • Format: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Step 2: Configure Claude Desktop with GitHub

Edit your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "yirifi-github": {
      "command": "npx",
      "args": [
        "-y",
        "github:your-org/yirifi-backend/mcp_server"
      ],
      "env": {
        "GITHUB_TOKEN": "ghp_your_github_personal_access_token_here",
        "YIRIFI_API_KEY": "your_yirifi_api_key_here",
        "YIRIFI_BASE_URL": "https://dev-api.yirifi.ai",
        "YIRIFI_TOOLS": "regdb:*"
      }
    }
  }
}

Configuration Parameters:

• command: "npx" - Uses npx to run packages from GitHub

• args:

  • -y - Automatically accept installation prompts
  • github:your-org/yirifi-backend/mcp_server - GitHub repository path
    • Format: github:OWNER/REPO/SUBDIRECTORY
    • Example: github:yirifi/yirifi-backend/mcp_server
    • Use subdirectory path if MCP server is not at repo root

• env:

  • GITHUB_TOKEN - Your GitHub PAT (required for private repos)
  • YIRIFI_API_KEY - Your Yirifi API key
  • YIRIFI_BASE_URL - Yirifi API base URL
  • YIRIFI_TOOLS - (Optional) Tool filtering pattern to reduce context usage

Step 3: Using Specific Branches or Commits

You can specify a particular branch, tag, or commit:

{
  "mcpServers": {
    "yirifi-github-main": {
      "command": "npx",
      "args": [
        "-y",
        "github:your-org/yirifi-backend/mcp_server#main"
      ],
      "env": { /* ... */ }
    },
    "yirifi-github-dev": {
      "command": "npx",
      "args": [
        "-y",
        "github:your-org/yirifi-backend/mcp_server#development"
      ],
      "env": { /* ... */ }
    },
    "yirifi-github-tag": {
      "command": "npx",
      "args": [
        "-y",
        "github:your-org/yirifi-backend/mcp_server#v1.0.0"
      ],
      "env": { /* ... */ }
    }
  }
}

Branch/Tag/Commit Syntax:

• #main - Use the main branch
• #development - Use the development branch
• #v1.0.0 - Use a specific tag
• #abc123 - Use a specific commit hash

Step 4: Restart Claude Desktop

Quit and completely restart Claude Desktop for the changes to take effect.

Step 5: Verify GitHub Installation

Check Claude Desktop logs to verify the server is running:

• macOS: ~/Library/Logs/Claude/mcp*.log
• Windows: %APPDATA%\Claude\logs\mcp*.log

The server should download from GitHub and start automatically.

GitHub Method Benefits

✅ Always up-to-date: Pull latest changes by restarting Claude Desktop ✅ No local setup: No need to clone or build locally ✅ Version control: Pin to specific branches or tags ✅ Multi-environment: Run different versions simultaneously (dev/staging/prod) ✅ Easy deployment: Share configuration with team members

GitHub Method Considerations

⚠️ First run is slower: Downloads and builds from GitHub ⚠️ Requires internet: Must be online to download ⚠️ GitHub rate limits: May hit API limits if restarting frequently ⚠️ PAT security: Keep your GitHub token secure and don't commit it

Troubleshooting GitHub Method

Server not starting:

1. Verify your GitHub token is valid and has correct permissions
2. Check the repository path is correct (owner/repo/subdirectory)
3. Ensure the repository contains a valid package.json
4. Check Claude Desktop logs for detailed error messages

Authentication errors:

1. Regenerate your GitHub PAT if it expired
2. Verify repo scope is enabled for private repositories
3. Ensure token is correctly set in the env.GITHUB_TOKEN field

Build errors:

1. Verify the repository has all necessary build files (package.json, tsconfig.json)
2. Check that dependencies are correctly specified in package.json
3. Review Claude Desktop logs for specific build error messages

Using with HTTP Transport (Remote/Docker)

The HTTP transport enables remote MCP server deployments, ideal for:

• Docker/Kubernetes deployments
• Shared team servers
• Multi-tenant scenarios (each client uses their own API key)

Production Server

A production instance is available at:

Base URL: https://mcp.yirifi.ai

| Endpoint | Method | Description | |----------|--------|-------------| | / | GET | Server info and available endpoints | | /health | GET | Health check (returns {"status":"ok","tools":38}) | | /mcp | POST | MCP JSON-RPC endpoint |

Running the HTTP Server Locally

# Development
yarn dev:http

# Production
yarn start:http

# Docker
docker-compose up --build

The server runs on port 8002 by default (configurable via PORT env var).

Configuring Claude Desktop for HTTP

Edit your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Using Production Server (Recommended):

{
  "mcpServers": {
    "yirifi": {
      "url": "https://mcp.yirifi.ai/mcp",
      "headers": {
        "api-key": "your_yirifi_api_key_here"
      }
    }
  }
}

Using Local Server:

{
  "mcpServers": {
    "yirifi-local": {
      "url": "http://localhost:8002/mcp",
      "headers": {
        "api-key": "your_yirifi_api_key_here"
      }
    }
  }
}

Configuring Cursor for HTTP

In Cursor settings (.cursor/mcp.json), add MCP server configuration:

Using Production Server:

{
  "mcpServers": {
    "yirifi": {
      "url": "https://mcp.yirifi.ai/mcp",
      "headers": {
        "api-key": "your_yirifi_api_key_here"
      }
    }
  }
}

Configuring Claude Code CLI for HTTP

Create or edit .mcp.json in your project root or home directory:

{
  "mcpServers": {
    "yirifi": {
      "type": "url",
      "url": "https://mcp.yirifi.ai/mcp",
      "headers": {
        "api-key": "your_yirifi_api_key_here"
      }
    }
  }
}

Testing the HTTP Server

Local Server:

# Server info
curl http://localhost:8002/

# Health check
curl http://localhost:8002/health

# List tools (MCP JSON-RPC)
curl -X POST http://localhost:8002/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "api-key: YOUR_YIRIFI_API_KEY" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# Call a tool
curl -X POST http://localhost:8002/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "api-key: YOUR_YIRIFI_API_KEY" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"regdb_list_countries","arguments":{}},"id":2}'

Production Server:

# Server info
curl https://mcp.yirifi.ai/

# Health check
curl https://mcp.yirifi.ai/health

# List tools (MCP JSON-RPC)
curl -X POST https://mcp.yirifi.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "api-key: YOUR_YIRIFI_API_KEY" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Docker Deployment

# Build and run
docker-compose up --build

# Run in background
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

Environment variables for Docker (set in .env or docker-compose):

• PORT - Server port (default: 8002)
• YIRIFI_BASE_URL - Yirifi API base URL
• YIRIFI_TOOLS - Tool filtering patterns
• YIRIFI_DEFER_TOOLS - Deferred tool patterns

Deploying to Production

Use the included deploy script to deploy to the production server:

# Full deploy
./deploy.sh

# View logs
./deploy.sh --logs

# Check status
./deploy.sh --status

# Quick restart (no rebuild)
./deploy.sh --skip-build

# Fresh build (no cache)
./deploy.sh --no-cache

Available Tools

The server provides 45+ tools across different domains:

RegDB Tools (10 tools)

• Countries: regdb_list_countries, regdb_filter_country_regulatory, regdb_list_regulatory_groups
• Articles: regdb_filter_articles, regdb_get_article, regdb_get_article_tags
• Organizations: regdb_list_organizations, regdb_get_organization, regdb_list_regulatory_bodies, regdb_list_organization_types

Web3GRC Knowledge Base (14 tools)

• Categories: web3grc_list_categories, web3grc_get_category
• Components: web3grc_list_components, web3grc_get_component
• Features: web3grc_list_features, web3grc_list_feature_categories
• Glossary: web3grc_list_glossary, web3grc_get_glossary_term
• Questions: web3grc_list_questions, web3grc_get_question
• FAQs: web3grc_list_faqs, web3grc_get_faq
• Solutions: web3grc_list_solutions, web3grc_get_solution

Web3GRC Marketplace (9 tools)

• People: web3grc_list_people, web3grc_get_person
• Vendors: web3grc_list_vendors, web3grc_get_vendor, web3grc_get_vendors_by_usecase, web3grc_get_vendor_components, web3grc_compare_vendors, web3grc_get_vendor_solutions, web3grc_get_vendor_locations

Web3GRC Common Resources (4 tools)

• News: web3grc_list_news, web3grc_get_news
• Templates: web3grc_list_templates, web3grc_get_template

Risk Assessment Tools (8 tools)

• Risk Items: risk-assessment_listRiskItems, risk-assessment_getRiskItemDetail, risk-assessment_listRiskCategories, risk-assessment_getRiskCategoryDetail
• Red Flags: risk-assessment_listRedFlags, risk-assessment_getRedFlagDetail
• Incidents: risk-assessment_listIncidents, risk-assessment_getIncidentDetail

Project Structure

mcp_server/
├── src/
│   ├── client.ts           # HTTP client for Yirifi APIs
│   ├── config.ts           # Configuration and environment loading
│   ├── index.ts            # CLI entry point (STDIO)
│   ├── server-core.ts      # Shared MCP server logic
│   ├── server-stdio.ts     # STDIO transport entry point
│   ├── server-http.ts      # HTTP transport entry point
│   └── tools/
│       ├── filter.ts       # Tool filtering utility
│       ├── generator.ts    # OpenAPI → MCP tool generator
│       └── executor.ts     # Generic tool executor
├── dist/                   # Compiled JavaScript (generated)
├── Dockerfile              # Docker image for HTTP server
├── docker-compose.yml      # Docker Compose configuration
├── package.json
├── tsconfig.json
├── biome.json
└── .env                    # Your environment config (create this)

Troubleshooting

"Cannot find module" errors

Make sure you've built the project:

yarn build

TypeScript errors

Run type checking to see detailed errors:

yarn typecheck

Environment variable not loaded

1. Verify .env file exists in the mcp_server directory
2. Check that variable names match exactly (case-sensitive)
3. Restart the server after changing .env

Server not appearing in Claude Desktop

1. Check Claude Desktop config syntax is valid JSON
2. Use absolute paths (not relative paths with ~)
3. Verify the dist/server-stdio.js file exists (for STDIO) or server is running (for HTTP)
4. Check logs in Claude Desktop (Help → View Logs)
5. Restart Claude Desktop completely

API Examples

List Countries

// Tool: regdb_list_countries
{
  "page": 1,
  "limit": 10,
  "region": "Europe"
}

Search Articles

// Tool: regdb_filter_articles
{
  "query": "GDPR",
  "country": "european-union",
  "limit": 20
}

Get Vendor Information

// Tool: web3grc_get_vendor
{
  "identifier": "vendor-slug-or-id"
}

Contributing

When contributing to the TypeScript version:

1. Follow existing code style (Biome enforces this)
2. Add Zod schemas for new API inputs
3. Update tool descriptions when adding features
4. Run yarn typecheck before committing
5. Run yarn format to auto-format code

License

UNLICENSED - Private Yirifi project

Support

For issues or questions:

• Check existing documentation files
• Review Claude Desktop logs
• Verify API key and network connectivity
• Ensure Yirifi backend services are running