# xmcp-core

`xmcp-core` is a generic X/bookmark intelligence MCP core. It lets an operator
bring their own X account, ingest their own bookmark corpus, classify and enrich
that corpus, embed it, retrieve across it, generate briefs, scan academic paper
feeds, and expose the result through MCP tools.

What this is:

- Corpus-agnostic bookmark intelligence pipeline plumbing.
- MCP tools for local intel search, semantic retrieval, ingestion, enrichment,
  briefs, paper radar, and model registry checks.
- Optional generated X API MCP tools from X's OpenAPI surface when credentials
  and network access are available.
- Public starter configuration with environment hooks for paths, topics,
  watchlists, and credentials.

What this is not:

- It is not a private intel corpus.
- It does not ship runtime `db/`, `intel/`, `logs/`, `drop/`, or `state/`.
- It does not ship OAuth tokens, cached X data, `.env`, secrets, private wiki
  promotion code, or private audit documents.
- It does not include the deferred wiki promoter module. The wiki-coupled tools
  `intel_domains`, `intel_stale_domains`, and `intel_promote` are intentionally
  absent from this MVP.

## Setup

```bash
python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt -r requirements-dev.txt
cp env.example .env
```

Fill `.env` or `~/.config/xmcp/secrets.env` with your own credentials. Keep all
secret values out of git. The tracked `env.example` contains empty placeholders
only.

For bookmark ingest, create an X app with OAuth 2.0 user auth and run:

```bash
.venv/bin/python scripts/x-oauth-setup.py
```

For the optional hosted X MCP bridge, install/configure `xurl`, preferably with
a separate X app/client ID from the bookmark pipeline. See [CONNECT.md](CONNECT.md).

## Configuration

Useful environment hooks:

- `XMCP_DB_PATH`: SQLite database path. Defaults to `db/bookmarks.db`.
- `XMCP_INTEL_DIR`: generated JSONL corpus path. Defaults to `intel/`.
- `XMCP_LOG_DIR`: logs path. Defaults to `logs/`.
- `XMCP_TOPICS_FILE`: JSON list or `{ "topics": [...] }` file.
- `XMCP_WATCHLIST_PATH`: watchdog keyword file. Defaults to
  `state/watchlist.json`.
- `XMCP_OAUTH_TOKEN_PATH`: explicit OAuth2 token file path.
- `XMCP_INCLUDE_X_API=0`: build the MCP server with only local intel/model tools.

Examples live in `examples/`. To customize topics:

```bash
export XMCP_TOPICS_FILE="$PWD/examples/topics.default.json"
```

To enable watchlist alerts, create an untracked runtime file:

```bash
mkdir -p state
cp examples/watchlist.example.json state/watchlist.json
```

## Run

Run the local MCP server:

```bash
.venv/bin/python server.py
```

Run the pipeline manually:

```bash
.venv/bin/python -m pipeline.run --dry-run
.venv/bin/python -m pipeline.run
```

Run tests:

```bash
pytest
```

Live corpus tests are opt-in with `XMCP_RUN_LIVE_TESTS=1`.

## IRIN satellite

`xmcp-core` is an IRIN satellite: generic MCP plumbing that an operator can run
next to IRIN, not a private corpus and not a required IRIN dependency. When
IRIN's Sheldon validator is enabled and a local xmcp server is reachable and
exposes the generated X tool `searchPostsRecent`, IRIN uses only that tool for
live or recent X posts. Sheldon does not use this repo's bookmark corpus or
hybrid intel tools for validation, and IRIN does not claim Gateway transport supplies
search. If no local xmcp server is reachable, IRIN just proceeds without that
evidence path — this server is optional, not a hard dependency. It also runs
fully standalone for operators who never use IRIN. See [CONNECT.md](CONNECT.md)
for local vs hosted X MCP routing.

## License

Apache-2.0 — same as the IRIN triad repos. See [LICENSE](LICENSE).