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

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:

.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.

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:

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

To enable watchlist alerts, create an untracked runtime file:

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

Run

Run the local MCP server:

.venv/bin/python server.py

Run the pipeline manually:

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

Run tests:

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 for local vs hosted X MCP routing.

License

Apache-2.0 — same as the IRIN triad repos. See LICENSE.