yubnub-mcp-server

richyBaxter/yubnub-mcp-server

3.2

If you are the rightful owner of yubnub-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Yubnub Admin API is a Model Context Protocol server that integrates with Claude Desktop to manage job feeds, sources, and publishing across multiple platforms.

Tools
5
Resources
0
Prompts
0

Yubnub Admin API - Model Context Protocol Server

Version: 1.0.0
Status: Production Ready
MCP Protocol: 2024-11-05

Overview

This MCP (Model Context Protocol) server provides Claude Desktop with complete access to the Yubnub job feed platform. It enables conversational management of job feeds, sources, enrichment pipelines, and multi-platform publishing.

What is Yubnub?

Yubnub is a job feed aggregation and enrichment platform that:

  • Discovers jobs from career sites
  • Scrapes and enriches job data
  • Distributes to multiple platforms (JBoard, XML feeds, webhooks)
  • Provides real-time pipeline monitoring

Key Features

  • 21 Tools for complete feed management
  • Session State - remembers your current feed/source
  • Auto-Polling - monitors pipeline progress automatically
  • Brand Consistent - all tools prefixed with yubnub_
  • Type Safe - full TypeScript implementation

Quick Start

Installation

  1. Install the MCP server:
cd C:\MCP\yubnub
npm install
npm run build
  1. Configure Claude Desktop:

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "yubnub_admin_api": {
      "command": "node",
      "args": ["C:\\MCP\\yubnub\\dist\\index.js"]
    }
  }
}

  1. Restart Claude Desktop

  2. Verify installation:

In Claude Desktop, type:

Can you check if the Yubnub API is running?

Claude should use the yubnub_health_check tool.

Tool Reference

Health & Information (1 tool)

yubnub_health_check

Check if the Yubnub Admin API is responsive.

Example:

Is the Yubnub API working?

Feed Management (9 tools)

yubnub_list_feeds

List all job feeds for the current user.

Example:

Show me all my feeds
yubnub_get_feed

Get details for a specific feed. If no feedId provided, uses session feed.

Parameters:

  • feedId (optional) - Feed ID

Example:

Show me details for my current feed
yubnub_create_feed

Create a new job feed.

Parameters:

  • name (required) - Feed name (e.g., "Software Engineering Jobs")
  • url (required) - URL slug (e.g., "software-jobs")
  • enabled (optional) - Whether feed is active (default: true)

Example:

Create a new feed called "Remote Tech Jobs" with URL "remote-tech"
yubnub_update_feed

Update an existing feed's name, URL, or status.

Parameters:

  • feedId (optional) - Feed ID (uses session if not provided)
  • name (optional) - New name
  • url (optional) - New URL slug
  • enabled (optional) - New status

Example:

Rename my current feed to "AI & Machine Learning Jobs"
yubnub_delete_feed

Delete a feed and all its data permanently.

Parameters:

  • feedId (optional) - Feed ID

Example:

Delete this feed
yubnub_run_feed

Trigger discovery process for all sources in a feed. Automatically monitors progress with real-time updates.

Parameters:

  • feedId (optional) - Feed ID
  • pollInterval (optional) - Check status every N seconds (default: 10)
  • maxDuration (optional) - Stop monitoring after N seconds (default: 300)

Example:

Run discovery for this feed

What happens:

  1. Starts discovery process
  2. Shows real-time progress updates every 10 seconds
  3. Displays:
    • Current pipeline stage
    • Jobs discovered
    • Enrichment progress
    • Error count
  4. Completes when pipeline finishes or times out
yubnub_get_feed_stats

Get statistics for a feed (job counts, sources).

Parameters:

  • feedId (optional) - Feed ID

Example:

Show me stats for this feed
yubnub_get_xml_url

Get the persistent XML feed URL for external systems.

Parameters:

  • feedId (optional) - Feed ID

Example:

What's the XML URL for this feed?
yubnub_get_pipeline_status

Get detailed pipeline status snapshot (no auto-monitoring).

Parameters:

  • feedId (optional) - Feed ID

Example:

Check pipeline status

Source Management (4 tools)

yubnub_list_sources

List all job sources configured for a feed.

Parameters:

  • feedId (optional) - Feed ID

Example:

Show me all sources for this feed
yubnub_create_source

Add a careers site as a source to a feed.

Parameters:

  • feedId (optional) - Feed ID
  • careersPageUrl (required) - URL of careers/jobs page
  • exampleJobUrl (optional) - Example job URL for pattern detection
  • enabled (optional) - Whether source is active (default: true)

Example:

Add https://www.mercedesamgf1.com/careers/vacancies/ as a source
yubnub_update_source

Update an existing source.

Parameters:

  • feedId (optional) - Feed ID
  • sourceId (optional) - Source ID (uses session if not provided)
  • careersPageUrl (optional) - New URL
  • exampleJobUrl (optional) - New example URL
  • enabled (optional) - New status

Example:

Disable the current source
yubnub_delete_source

Remove a source from a feed.

Parameters:

  • feedId (optional) - Feed ID
  • sourceId (optional) - Source ID

Example:

Delete this source

Job Management (2 tools)

yubnub_list_jobs

List all discovered jobs for a feed.

Parameters:

  • feedId (optional) - Feed ID

Example:

Show me the jobs we found
yubnub_get_job

Get detailed information for a specific job.

Parameters:

  • feedId (optional) - Feed ID
  • jobId (required) - Job ID

Example:

Show me details for job_abc123

Push Target Management (4 tools)

yubnub_list_push_targets

List all configured push targets for a feed.

Parameters:

  • feedId (optional) - Feed ID

Example:

What push targets are configured?
yubnub_create_push_target

Create a new push target (JBoard, XML, webhook).

Parameters:

  • feedId (optional) - Feed ID
  • type (required) - "jboard", "xml", or "webhook"
  • enabled (optional) - Whether active (default: true)
  • config (optional) - Target-specific configuration
  • credentials (optional) - Authentication credentials

Example:

Create a JBoard push target with employer ID 12345

For JBoard:

{
  "type": "jboard",
  "config": {
    "employerId": "12345",
    "boardId": "67890"
  },
  "credentials": {
    "apiKey": "your-jboard-api-key"
  }
}
yubnub_update_push_target

Update an existing push target.

Parameters:

  • feedId (optional) - Feed ID
  • targetId (required) - Push target ID
  • enabled (optional) - New status
  • config (optional) - New configuration
  • credentials (optional) - New credentials

Example:

Enable push target target_xyz
yubnub_delete_push_target

Remove a push target.

Parameters:

  • feedId (optional) - Feed ID
  • targetId (required) - Push target ID

Example:

Delete push target target_xyz

Publishing (1 tool)

yubnub_push_feed

Push all jobs to a specific target.

Parameters:

  • feedId (optional) - Feed ID
  • targetId (required) - Push target ID

Example:

Push jobs to target_xyz

Common Workflows

Workflow 1: Create Feed & Discover Jobs

User: "Create a new feed for F1 teams called 'F1 Jobs'"
Claude: [Creates feed, sets session]

User: "Add Mercedes F1 careers as a source: https://www.mercedesamgf1.com/careers/vacancies/"
Claude: [Creates source]

User: "Run discovery"
Claude: [Starts discovery, shows real-time progress:]
  [12:00:10] Stage: discovery_started
    Jobs: 0 | Enriched: 0 (0%) | Errors: 0

  [12:01:25] Stage: scraping_queued
    Jobs: 12 | Enriched: 0 (0%) | Errors: 0

  [12:03:40] Stage: enrichment_started
    Jobs: 12 | Enriched: 5 (42%) | Errors: 0

  [12:05:15] Stage: enrichment_completed
    Jobs: 12 | Enriched: 12 (100%) | Errors: 0

  Pipeline completed!
  Total duration: 5m 15s

User: "Show me the jobs"
Claude: [Lists 12 discovered jobs]

Workflow 2: Configure JBoard Push

User: "Create a JBoard push target"
Claude: "I'll need some information for the JBoard configuration."

User: "Use employer ID 12345 and this API key: [key]"
Claude: [Creates JBoard push target]

User: "Push the jobs"
Claude: [Pushes jobs to JBoard, shows results]

Workflow 3: Export as XML Feed

User: "What's the XML feed URL for this?"
Claude: [Returns persistent XML URL]

User: "Great, I'll add that to our job board"

Session State Management

The MCP server maintains session state to reduce repetitive inputs:

What's Remembered

  • Current Feed ID - Auto-selected when creating/viewing feeds
  • Current Source ID - Auto-selected when creating/viewing sources
  • Last Operation - Tracks recent actions

Benefits

Before (No Session):

User: "Create feed 'Tech Jobs'"
Claude: [Creates feed_abc123]

User: "Add source https://example.com/careers"
Claude: "I need the feed ID"
User: "feed_abc123"
Claude: [Creates source]

User: "Run discovery"
Claude: "I need the feed ID"
User: "feed_abc123"

After (With Session):

User: "Create feed 'Tech Jobs'"
Claude: [Creates feed_abc123, saves to session]

User: "Add source https://example.com/careers"
Claude: [Uses session feed, creates source]

User: "Run discovery"
Claude: [Uses session feed, starts discovery]

Clearing Session

Session is cleared when:

  • Deleting the current feed
  • Deleting the current source
  • Creating/selecting a different feed

Auto-Polling Feature

When you run yubnub_run_feed, the server automatically monitors progress:

How It Works

  1. Starts Discovery - Triggers pipeline
  2. Polls Every 10s - Checks status automatically
  3. Shows Updates - Displays progress in real-time
  4. Detects Completion - Stops when done or after 5 minutes

Customization

Run discovery with faster polling:
  pollInterval: 5 seconds
  maxDuration: 600 seconds (10 minutes)

Manual Monitoring

If you prefer manual checks:

Use yubnub_get_pipeline_status to check progress yourself

Architecture

Components

┌─────────────────┐
│ Claude Desktop  │
│  (User Input)   │
└────────┬────────┘
         │ MCP Protocol
         ↓
┌─────────────────┐
│  MCP Server     │
│  (This Code)    │
└────────┬────────┘
         │ REST API
         ↓
┌─────────────────┐
│  Admin API      │
│  (Cloudflare)   │
└────────┬────────┘
         │
         ↓
┌─────────────────────────┐
│  Pipeline Workers       │
│  - Discovery            │
│  - Scraper             │
│  - Enrichment          │
│  - Pusher              │
└─────────────────────────┘

API Endpoints

Admin API Base:
https://yubnub-admin-api-staging.fluidjobs.workers.dev

Pipeline Logger Base:
https://yubnub-pipeline-logger-staging.fluidjobs.workers.dev

Development

Project Structure

yubnub/
├── src/
│   ├── index.ts          # MCP server implementation
│   ├── api-client.ts     # API client wrapper
│   └── types.ts          # TypeScript interfaces
├── dist/                 # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md            # This file

Building

npm run build

Compiles TypeScript to dist/ directory.

Testing Locally

# Run the server
node dist/index.js

# Test with MCP Inspector
npx @modelcontextprotocol/inspector dist/index.js

Adding New Tools

  1. Add tool definition to getTools()
  2. Add case to handleToolCall() switch
  3. Update this README
  4. Rebuild: npm run build

Troubleshooting

Tool Not Showing in Claude

Problem: Claude doesn't see your tools

Solutions:

  1. Restart Claude Desktop
  2. Check claude_desktop_config.json path is correct
  3. Verify node dist/index.js runs without errors

"No feed ID provided" Error

Problem: Tool requires feedId but none in session

Solutions:

  1. Create a feed first: yubnub_create_feed
  2. Select a feed: yubnub_get_feed with feedId
  3. Provide feedId explicitly in tool call

Pipeline Not Starting

Problem: yubnub_run_feed doesn't start discovery

Solutions:

  1. Check feed has sources: yubnub_list_sources
  2. Verify API health: yubnub_health_check
  3. Check staging environment is running

Auto-Polling Times Out

Problem: Pipeline monitoring stops after 5 minutes

Solutions:

  1. Increase maxDuration parameter
  2. Check pipeline manually: yubnub_get_pipeline_status
  3. View pipeline logger directly

API Documentation

For detailed API schemas and endpoints:

  • Admin API OpenAPI: openapi-formatted.json
  • Pipeline Logger API: See project documentation

Version History

v1.0.0 (Current)

  • All 21 tools implemented
  • Session state management
  • Auto-polling for run_feed
  • Brand-consistent yubnub_ prefix
  • Production ready

Support

Issues: Report via project issue tracker
Questions: Contact team at rb@richardbaxter.co
API Status: https://yubnub-admin-api-staging.fluidjobs.workers.dev/api/health

License

Proprietary - Yubnub Platform

Contributing

Internal project - contact maintainers for contribution guidelines.