# opportunities-circle-mcp

An [MCP](https://modelcontextprotocol.io) server that gives AI agents the full
capabilities and catalog of **[Opportunities Circle](https://www.opportunitiescircle.com)** —
scholarships, fellowships, internships, grants, jobs, competitions, online
courses, training, conferences and exchange programs — as searchable,
well-typed tools.

It talks to Opportunities Circle's public WordPress REST API (no key, no
scraping, no login), resolves human-friendly filters (opportunity type,
country, funding, tags) into the right queries, and returns clean,
reader-friendly text — including each opportunity's full description,
eligibility, benefits, deadlines and official apply links.

## Features

| Tool | What it does |
| --- | --- |
| `oppcircle_search` | Search the catalog by keywords + filters (type, country, funding, tags, date range, sort). Newest-first, excludes expired by default. The main discovery tool. |
| `oppcircle_get` | Full details of one opportunity by `id`, `slug`, or `url` — complete description, type, tags, country/funding, deadline urgency and image. |
| `oppcircle_latest` | The most recently posted active opportunities, optionally by type. |
| `oppcircle_list_categories` | List opportunity **types** with counts + slugs (scholarships, phd-scholarships, fellowships, internships, jobs, grants, …). |
| `oppcircle_list_tags` | Search the 13k+ tag taxonomy to find valid **country / funding / level / org** slugs for filtering. |
| `oppcircle_overview` | High-level snapshot: site info, active total, and type breakdown. Good first call. |

## Quick start

```bash
git clone <your-repo-url> opportunities-circle-mcp
cd opportunities-circle-mcp
npm install
npm run build
```

### Add to Claude Code

```bash
claude mcp add opportunities-circle -- node "/absolute/path/to/opportunities-circle-mcp/dist/index.js"
```

Or, once published to npm:

```bash
claude mcp add opportunities-circle -- npx -y opportunities-circle-mcp
```

### Add to Claude Desktop

Edit `claude_desktop_config.json`:

```jsonc
{
  "mcpServers": {
    "opportunities-circle": {
      "command": "node",
      "args": ["/absolute/path/to/opportunities-circle-mcp/dist/index.js"]
    }
  }
}
```

## Configuration

All env vars are optional — the server runs with zero configuration.

| Variable | Default | Description |
| --- | --- | --- |
| `OPPCIRCLE_BASE_URL` | `https://www.opportunitiescircle.com` | Site to query. |
| `OPPCIRCLE_MAX_CONTENT_CHARS` | `8000` | Max body text returned by `oppcircle_get`. |
| `OPPCIRCLE_TIMEOUT_MS` | `20000` | Per-request network timeout. |
| `OPPCIRCLE_USER_AGENT` | (built-in) | Custom User-Agent header. |

## Tool reference & example prompts

**Discover what's available**
> "Give me an overview of Opportunities Circle."  → `oppcircle_overview`

**Search with filters**
> "Find fully funded PhD scholarships in Germany."
> → `oppcircle_search { query: "fully funded", type: "phd-scholarships", country: "germany" }`

> "What internships are open in the USA right now?"
> → `oppcircle_search { type: "internships", country: "usa" }`

**Find the right filter slugs**
> "What tags exist for the UK?" → `oppcircle_list_tags { search: "uk" }`
> "List the opportunity types." → `oppcircle_list_categories`

**Read the full posting**
> "Open the FAO Volunteer Program listing."
> → `oppcircle_get { url: "https://www.opportunitiescircle.com/fao-volunteer-program-in-italy/" }`

**Stay current**
> "What are the 10 newest fellowships?"
> → `oppcircle_latest { type: "fellowships", limit: 10 }`

### Filtering model

- **Type** (`type`) maps to the site's WordPress *category* — the opportunity
  kind. Common slugs: `scholarships`, `masters-scholarships`, `phd-scholarships`,
  `undergraduate-scholarship`, `fellowships`, `phd-fellowships`, `internships`,
  `international-internships`, `research-internship`, `jobs`, `grants`,
  `competitions`, `conferences`, `online-courses`, `training`,
  `exchange-programs`, `awards`.
- **country / funding / tags** map to the *tag* taxonomy. Because there are
  13k+ tags, use `oppcircle_list_tags` to find the exact slug (e.g. `usa`,
  `europe`, `fully-funded`, `paid`, `un-program`). Slugs and names are both
  accepted and fuzzy-matched.
- Multiple `tags` are combined with AND.
- Expired opportunities are excluded unless `include_expired: true`.

## How it works

```
Claude / MCP client
        │  stdio (JSON-RPC)
        ▼
opportunities-circle-mcp
   ├── src/index.ts   MCP server + 6 tool definitions
   ├── src/api.ts     WordPress REST client, term (slug→id) resolution + cache
   └── src/format.ts  HTML → clean markdown/text, list & detail formatting
        │  HTTPS (GET only, public API)
        ▼
https://www.opportunitiescircle.com/wp-json/wp/v2/*
```

Opportunities are stored as WordPress `post`s organized by `category`
(type), `tags` (country/funding/level/org/deadline), plus `di_urgency`
(deadline urgency) and `subject` (field of study) taxonomies. The server reads
only public, published content via `GET` — it never writes.

## FAQ

**Do I need an API key or account?** No. The catalog is served over a public,
read-only REST API.

**Does it modify anything on the site?** No — `GET` requests only.

**Why are some results marked ⚠️ EXPIRED?** They're archived opportunities. They
are hidden by default; pass `include_expired: true` to include them.

**Can I point it at another WordPress site?** Yes — set `OPPCIRCLE_BASE_URL`.
The type slugs and tags will differ per site.

## Development

```bash
npm run dev        # tsc --watch
npm run typecheck  # no-emit type check
npm run build      # compile to dist/
```

## License

MIT