# Social Search

Personal Codex plugin for Reddit and X search and post retrieval. It packages a
short Skill and four MCP tools around one tested provider implementation. The CLI
and legacy HTTP adapters reuse that implementation.

## Installed Architecture

```text
Codex plugin -> existing SSH connection -> VPS stdio MCP
                                         |- Reddit -> loopback Redlib -> Reddit
                                         `- X -> TwitterAPI.io

Existing n8n -> Docker bridge -> legacy HTTP adapters -> same providers
Browser -> Cloudflare -> nginx -> Redlib (static/media cache; dynamic no-store)
```

Current repair and rollback evidence: [2026-09-07 verification](docs/repair-verification-20260907.md).

The MCP transport has no public listening port. Configure `scripts/connect-vps`
with `SOCIAL_SEARCH_VPS_HOST`, `SOCIAL_SEARCH_VPS_PORT`, `SOCIAL_SEARCH_VPS_KEY`,
and (when needed) `SOCIAL_SEARCH_VPS_USER`; no host address, key or credential is
included in this repository. X credentials are read inside the VPS process from
the protected runtime configuration.

## Tools

| Tool | Behavior |
| --- | --- |
| `reddit_search` | Native ordering, canonical source URLs, bounded session pagination |
| `reddit_post` | Original post and comments, parent IDs, hard count/depth limits, coverage |
| `x_search` | One complete provider page, original order, IDs and next cursor |
| `x_post` | Read requested IDs and available quote/reply context; report missing IDs |

Errors remain errors, including authentication, quota, rate limits and malformed
upstream pages. Results retain source links and distinguish returned content from
loaded or source-reported totals. Comment permalink pages disclose unknown parents.

Reddit search cursors expire after 15 minutes and belong to one server process.
A new Codex task or restarted MCP server requires a new search. Separate CLI
invocations cannot continue those in-memory cursors. X calls use an existing paid
third-party account and are not automatically retried. A page is usually 20 posts;
requesting fewer locally does not reduce the upstream page charge.

## Development

Node.js 22 or newer is required for the provider package on the VPS. The installed
local bridge requires only SSH. Dependencies are pinned in `package-lock.json`.

```sh
npm ci --ignore-scripts
npm test
node src/cli.mjs doctor
node scripts/verify-live.mjs ./scripts/connect-vps
```

The final command performs live Reddit requests and a small paid X search/read.
Use it deliberately, not as a periodic free health probe. The ordinary X health
endpoint checks configuration only and explicitly says `upstream_verified:false`.

## Compatibility and Caching

Existing Reddit `GET /api/search`, `GET /api/post`, and X `POST /api/search` routes
remain available on loopback and Docker bridge addresses. Legacy Reddit modes are
accepted as labels, with native ordering; old popularity filters are removed.
The legacy X `limit` is an explicitly reported preview and may omit rows from the
provider page. Use MCP for full-page pagination.

All `/api/` responses bypass nginx cache and declare `private, no-store` for CDN
caches. Normal Redlib webpage and media caching remains enabled. MCP reads Redlib
on loopback directly, bypassing both nginx and Cloudflare page caches.

See [deployment verification](docs/verification.md) for observed results, current
release locations, rollback steps, and remaining boundaries.

## Provenance

The archived reference repository was reviewed at commit
`3e9dea1951ce359f9232378efb6edb81126d1526`; its source remains untouched. The new
package lives separately. Real HTML fixtures were captured from the existing
Redlib deployment. The comment-template fixture comes from Redlib commit
`a4d36e954cf1bd64f209cd8868c5a29edc81b374`. Upstream fixtures retain their respective
project provenance. This package is private and no publication license is granted.

- [Original audit target](https://github.com/vialan-art/search-salvage/tree/3e9dea1951ce359f9232378efb6edb81126d1526)
- [Redlib](https://github.com/redlib-org/redlib)
- [X search contract](https://docs.twitterapi.io/api-reference/endpoint/tweet_advanced_search)
- [X details contract](https://docs.twitterapi.io/api-reference/endpoint/get_tweet_by_ids)
- [Codex plugins](https://developers.openai.com/codex/plugins)
- [Codex MCP](https://developers.openai.com/codex/mcp)
- [Codex Skills](https://developers.openai.com/codex/skills)