Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Add Employed by Guaq AI (hosted job-search MCP) to the integrations catalog

Open Beginner friendly
  • Is something wrong?
#769 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

@buddywhitman is already working on this.

Since Oct 13, 2026.

  • #768 by @buddywhitman — open

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
62/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
json, python
Domain
tooling

Research direction

Start from the shape of integrations/catalog/atlassian-rovo.json and check it against integrations/catalog.schema.json, then add integrations/catalog/employed.json with the oauth2 none client-auth option and no hardcoded OAuth URLs. Run npm run build:integrations to regenerate integrations/catalog-index.js. Done when the pytest files named in the issue pass and the entry is returned by listIntegrationCatalog() and get_integration_catalog_entry_model("employed"). The implementation is also tracked in #768, so check that before starting.

Written by the indexing model from the issue text.

Description

priority:low ready-for-dev

Request

Add Employed by Guaq AI to the integrations catalog (integrations/catalog/) so it appears on the OpenHands MCP page next to the other hosted MCP servers.

None of the current catalog entries covers job search or hiring data. An agent can research companies on the web, but it has no structured source of live job postings: roles it can filter by seniority, location, work mode, technology or visa signal, with each one linking to the employer's own apply page. It also has no way to read an employer's current hiring mix. This entry fills that gap for job-hunting and hiring-research tasks.

What Employed's MCP server provides

  • Server: a hosted Streamable HTTP MCP server at https://jobs.guaqai.me/mcp. It indexes live postings read directly from about 5,000 employers' own applicant-tracking systems (Greenhouse, Lever, Workday, Ashby, SmartRecruiters and others).
  • Read-only tools:
    • search_jobs, count_jobs and get_job;
    • list_companies and company_profile (seniority mix, functions, cities, technologies, longest-open roles);
    • market_signal, plus api_meta for the filter vocabulary.
  • Account tools for the signed-in user's own profile, application tracker and alerts. They change only that user's data, and never apply to jobs or contact employers.
  • Auth: OAuth 2.1.
    • An unauthenticated request returns 401 with WWW-Authenticate: Bearer resource_metadata="https://jobs.guaqai.me/.well-known/oauth-protected-resource/mcp".
    • That metadata names https://jobs.guaqai.me as the authorization server.
    • The authorization server's metadata advertises a registration_endpoint, code_challenge_methods_supported: ["S256"] and token_endpoint_auth_methods_supported including none, so a public client registers itself with no pre-shared credentials.

Proposed catalog entry

One new file, integrations/catalog/employed.json, with a single oauth connection option: strategy: oauth2, clientAuthentication: none, and no hardcoded authorization, token or registration URLs, on an shttp transport. It matches the shape used by atlassian-rovo and granola. integrations/catalog-index.js is regenerated with npm run build:integrations, and no other files change. The implementation is in #768.

integrations/catalog/employed.json 
{
  "id": "employed",
  "name": "Employed by Guaq AI",
  "description": "Search live job postings read from about 5,000 employers' own applicant-tracking systems, research an employer's hiring, and brief a hiring market.",
  "categories": [
    "Jobs",
    "Research"
  ],
  "appUrl": "https://jobs.guaqai.me",
  "docsUrl": "https://jobs.guaqai.me/connectors",
  "notes": "OAuth 2.1 with dynamic client registration is handled by the hosted Employed MCP server; no client credentials are needed. Search tools are read-only; account tools change only the signed-in user's own profile, application tracker and alerts, and never apply to jobs or contact employers.",
  "installHint": "Sign in with an Employed account when the authentication flow starts; a free account is enough to start.",
  "iconBg": "#CCFF33",
  "iconColor": "#14110F",
  "logoUrl": "https://jobs.guaqai.me/assets/brand/icon-512.png",
  "keywords": [
    "jobs",
    "job-search",
    "hiring",
    "careers",
    "internships",
    "ats",
    "recruiting",
    "mcp"
  ],
  "connectionOptions": [
    {
      "id": "oauth",
      "provider": "mcp",
      "transport": {
        "kind": "shttp",
        "url": "https://jobs.guaqai.me/mcp"
      },
      "auth": {
        "strategy": "oauth2",
        "oauth": {
          "clientAuthentication": "none"
        }
      }
    }
  ]
}

Verification

  • pytest tests/test_catalog_schema.py tests/test_integration_catalog_in_sync.py tests/test_catalogs.py: 117 passed.
  • The discovery chain above was checked live against the server.

Docs: https://jobs.guaqai.me/connectors. Privacy policy: https://jobs.guaqai.me/privacy-policy.

OpenHands AI triage

The following comments and acceptance criteria were added by the OpenHands AI agent.

Scope

Add one hosted-OAuth MCP entry, integrations/catalog/employed.json, for Employed by Guaq AI: MCP over Streamable HTTP at https://jobs.guaqai.me/mcp, auth.strategy oauth2 with oauth.clientAuthentication none, and no hardcoded authorization, token, or registration URLs. Regenerate integrations/catalog-index.js with npm run build:integrations. The single hand-authored JSON file is the source of truth; the regenerated JS index is the only derived artifact.

Non-goals

No changes to OpenHands apps, Agent Canvas, the SDK, or any runtime/connection code; no second connection option, API-key fallback, or scope list; no edits to the catalog schema, integrations/README.md, or unrelated entries. Implementation is tracked in PR #768 and is out of scope for this triage.

Acceptance Criteria
  • integrations/catalog/employed.json exists with "id": "employed" matching its filename and carries name, description, and docsUrl.
  • The entry validates against integrations/catalog.schema.json under Draft202012Validator, including the cross-field rule that an mcp option requires a transport and must not carry http.
  • Its single connection option is id: "oauth", provider: "mcp", transport.kind: "shttp", transport.url: "https://jobs.guaqai.me/mcp", auth.strategy: "oauth2", and auth.oauth.clientAuthentication: "none", with no hardcoded authorizationUrl, tokenUrl, or registrationUrl.
  • integrations/catalog-index.js is regenerated (npm run build:integrations) to statically import ./catalog/employed.json, and no aggregate integration-catalog.json is introduced.
  • The entry is returned by both JS (listIntegrationCatalog(), getIntegrationCatalogEntry("employed")) and Python (list_integration_catalog_models(), get_integration_catalog_entry_model("employed")), appears under the mcp=true and oauth=true filters, and carries no derived fields such as supportsMcp or supportsOauth.
  • docsUrl and logoUrl are https:// URLs that resolve (both currently return HTTP 200).
  • uv run --with-editable . --with pytest --with jsonschema pytest tests/test_catalog_schema.py tests/test_integration_catalog_in_sync.py tests/test_catalogs.py passes with the new entry present.
Dominant language
Python
Stars
172
Forks
117
Avg merge
1d 20h
Merged PRs (30d)
65

Getting set up

  • No Dockerfile or Docker Compose file
  • Has a pull request template
  • No contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from OpenHands/extensions

All issues in OpenHands/extensions

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.