@yirifi-org/mcp-server 1.2.0

package/README.md

@@ -0,0 +1,809 @@
+# 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 40+ tools organized across two main services:
+
+- **RegDB Service**: Regulations, articles, organizations, and regulatory bodies
+- **Web3GRC Service**: Knowledge base (categories, components, FAQs, glossary), marketplace (vendors, people), news, and templates
+
+## 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
+
+```bash
+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:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` and add your configuration:
+
+```env
+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))
+
+## 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
+
+```bash
+# 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 |
+
+### Example Configurations
+
+```bash
+# 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:
+
+```bash
+yarn dev
+```
+
+### Build for Production
+
+```bash
+yarn build
+```
+
+This compiles TypeScript to JavaScript in the `dist/` directory.
+
+### Run Production Build
+
+```bash
+yarn start
+```
+
+### Type Checking
+
+```bash
+yarn typecheck
+```
+
+### Linting and Formatting
+
+```bash
+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
+
+```bash
+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:
+
+```json
+{
+  "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
+
+```bash
+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
+
+```bash
+# 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`
+
+```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:**
+```bash
+# 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:
+
+```bash
+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:
+
+```json
+{
+  "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:
+
+```json
+{
+  "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:
+
+```json
+{
+  "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
+
+```bash
+# 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):**
+```json
+{
+  "mcpServers": {
+    "yirifi": {
+      "url": "https://mcp.yirifi.ai/mcp",
+      "headers": {
+        "api-key": "your_yirifi_api_key_here"
+      }
+    }
+  }
+}
+```
+
+**Using Local Server:**
+```json
+{
+  "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:**
+```json
+{
+  "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:
+
+```json
+{
+  "mcpServers": {
+    "yirifi": {
+      "type": "url",
+      "url": "https://mcp.yirifi.ai/mcp",
+      "headers": {
+        "api-key": "your_yirifi_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### Testing the HTTP Server
+
+**Local Server:**
+```bash
+# 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:**
+```bash
+# 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
+
+```bash
+# 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:
+
+```bash
+# 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 40+ 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`
+
+## 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:
+```bash
+yarn build
+```
+
+### TypeScript errors
+
+Run type checking to see detailed errors:
+```bash
+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
+```typescript
+// Tool: regdb_list_countries
+{
+  "page": 1,
+  "limit": 10,
+  "region": "Europe"
+}
+```
+
+### Search Articles
+```typescript
+// Tool: regdb_filter_articles
+{
+  "query": "GDPR",
+  "country": "european-union",
+  "limit": 20
+}
+```
+
+### Get Vendor Information
+```typescript
+// 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