Content
# mcp-context-wporg
MCP context server for WordPress.org — provides AI agents with access to WordPress.org project data via the load-provider / execute-tool meta-tool pattern.
Designed for use with any MCP client.
## Providers
| Provider | Data Source | Status |
| ---------- | --------------------------------------------------------------------- | ------------------------------------------------ |
| **make** | Make WordPress blogs (core, meta, design, etc.) | Working |
| **github** | WordPress + wp-cli GitHub orgs (every repo, queryable via search API) | Working |
| **trac** | WordPress.org Trac instances: Core, bbPress, BuddyPress | Requires WordPress.org auth for bot-like traffic |
## Usage
### With an MCP client
Configure your MCP client to launch the built server:
```json
{
"command": "node",
"args": ["/path/to/mcp-context-wporg/dist/index.js"]
}
```
### With Claude Code
```json
{
"mcpServers": {
"wporg": {
"command": "node",
"args": ["/path/to/mcp-context-wporg/dist/index.js"]
}
}
}
```
### Direct execution
```bash
node dist/index.js
```
## Tools
Two meta-tools following the load-provider / execute-tool pattern:
- **`wporg-load-provider`** — Load a provider and return its available tools
- **`wporg-execute-tool`** — Execute a tool within a loaded provider
### Make provider tools
- `search-posts` — Search across Make WordPress blogs
- `get-post` — Get a specific blog post
- `get-timeline` — Recent posts across blogs
- `list-blogs` — List all Make blogs (for discovery)
### GitHub provider tools
Covers the `WordPress` and `wp-cli` GitHub orgs. By default every tool queries
both orgs across their full repo set; narrow with the `org` or `repo`
parameters when you want a focused view.
- `search-issues` — Search issues/PRs across covered orgs (defaults to all). Supports `org` (`WordPress` or `wp-cli`) and `repo` (e.g. `WordPress/gutenberg`, `wp-cli/wp-cli`).
- `get-issue` — Get issue/PR details for any repo in the covered orgs.
- `get-timeline` — Recent activity across covered orgs in a single search-API call (drops the per-repo loop).
- `list-repos` — List active repos in covered orgs (live from `/orgs/{org}/repos`, cached 1h). Excludes archived by default.
> **Tip:** Set `GITHUB_TOKEN` to lift the unauthenticated 60-req/h core API limit to 5000-req/h. The search API has its own 30-req/min authenticated limit, which all four tools share.
### Trac provider tools
Trac can return `403` for unauthenticated bot-like traffic. Set
`WPORG_TRAC_COOKIE` when using the Trac provider persistently; a dedicated
WordPress.org user or service account is preferred over a personal browser
session.
Trac tools default to Core Trac. Pass `trac` or `trac_instance` as `core`,
`bbpress`, or `buddypress` to query another Trac instance.
- `search-tickets` — Search Trac tickets
- `get-ticket` — Ticket details + comments
- `get-timeline` — Recent development activity
- `list-components` — Trac components (for discovery)
## Environment Variables
| Variable | Description |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GITHUB_TOKEN` | GitHub personal access token (optional — increases rate limits for GitHub provider) |
| `WPORG_TRAC_COOKIE` | WordPress.org authentication cookie header value for Trac requests (optional, required for blocked Trac) |
| `WPORG_TRAC_USER_AGENT` | Custom Trac request user agent (optional, defaults to `mcp-context-wporg`) |
| `WPORG_TRAC_HEADERS_B64_JSON` | Base64-encoded JSON object of additional browser-compatible Trac headers. `Cookie`, `User-Agent`, `Host`, `Authorization`, and `Content-Length` are ignored here and should use dedicated auth fields where supported. |
## Development
```bash
npm install
npm run dev # Run with tsx
npm run build # Build with tsup
npm run check # TypeScript type check
```
## License
GPL v2 or later
