Local Social Research MCP

An Apache-2.0 local MCP server for bounded social research. A host LLM discovers Facebook Page candidates from the user's request, chooses an observed source, and calls tools to collect evidence. The wrapper contains no internal LLM and requires no developer-hosted backend.

Status: experimental, not a live-Facebook-verified release. The local workflow and stdio protocol have automated coverage. The pinned Playwright MCP runs against Chrome in controlled browser tests. Facebook extraction is tested on synthetic intercepted HTML; authenticated Facebook compatibility and host LLM source selection still need acceptance testing. Unsupported UI must produce an explicit error, never a successful empty result.

Requirements

• Node.js 24.19.0 or a tested later 24.x patch; npm.

• An MCP host that supports launching local stdio servers. HTTP-only hosts cannot directly launch this server; Streamable HTTP is not implemented in this release.

• Installed Google Chrome (default) or Microsoft Edge (WRAPPER_BROWSER=msedge) for browser jobs.

• Tested environment: Windows, Node 24.19.0. Other operating systems are not yet release-verified.

Related MCP server: Facebook MCP Server

Install and build

From a downloaded source checkout:

npm ci
npm run typecheck
npm run build

The executable is node dist/index.js. It waits for an MCP client on stdin; it is not an interactive command prompt or website. Protocol output uses stdout and diagnostics use stderr.

Runtime dependencies are pinned in package-lock.json, including MCP server/client SDK 2.4.0 and Playwright MCP 0.0.85. That Playwright MCP version embeds a Playwright alpha build; the exact browser combination must be tested before distribution. Startup does not download a replacement package or launch a browser until a browser job needs it.

Try synthetic mode first

Configure your host with the pattern in examples/host-config.example.json. Replace the executable, repository and data-directory paths. The example uses mock mode, with clearly synthetic data and no social network access.

The host workflow is:

1. Call discover_sources with a topic, e.g. DCA กองทุน.

2. Poll that job_id with get_job; choose only an observed candidate matching the user's intent.

3. Call register_source with its candidate_id and source_type: page.

4. Call start_search with the returned source_id, keywords and limits.

5. Poll get_job. Call read_comments only for selected stored posts if requested.

6. Export a terminal search/comments job with export_results.

7. Use delete_job to remove a terminal job and its owned export files.

One search job uses one source. Multiple sources require separate jobs and share one serialized browser queue. A known valid source URL can skip discovery. A local export path is not automatically an uploaded chat download link; delivery depends on the host.

Configure real browser mode

Set these environment variables in the host configuration:

.env files are not automatically loaded. Restart the server after configuration changes. Data directories require local filesystem SQLite locking; network shares are unsupported. Configuration is not accepted through untrusted tool arguments.

The example config denies external access initially. authorization.facebook.discovery_allowed permits Page discovery. collection_scope is none, listed_sources (canonical source_urls), or platform. A user with authorization covering dynamically selected Pages can configure the platform scope once; a fixed Page list and repeated confirmations are not required. These settings describe the user's authorized scope; they do not create permission from a website. Public visibility or group membership alone is not proof of permission to automate collection.

On needs_login, log in directly in the dedicated browser. Never pass passwords, OTPs, cookies or storage state to MCP tools or chat. After login, submit a new explicit job (optionally resume an eligible search). Old jobs do not restart when polled, and queued attempts are stopped without disturbing login. The profile persists in the data directory; do not use a personal default browser profile.

What the adapter currently does

• Page discovery uses Facebook Pages search UI, returning observed names/URLs for the host LLM to choose.

• Search samples visible feed posts and filters text/dates locally. It does not promise an exhaustive Page search or enforce Facebook's own keyword/date filters.

• Post permalinks must establish ownership by the selected Page, or match the exact selected post. Comment articles must establish their containing post. Unverifiable aliases, shared/recommended foreign posts and unsupported permalink variants stop with source_mismatch; the document URL alone is insufficient evidence.

• Comments are opt-in. Direct evidence URLs, reply parents and sort are reported only when observed. Requested comment sorting is currently not enforced, and output reports unknown plus limitations.

• Missing/ambiguous dates remain unknown. With an active date range, unknown dates are excluded and counted.

• Facebook Groups, X and Instagram are unsupported; Page/post support remains experimental until live acceptance is recorded.

• No posting, liking, replying, group joining, arbitrary browser/code passthrough, access-control bypass or internal LLM.

Limits and lifecycle

Defaults / hard maximums: posts 30/100, comments per post 20/100, total comments 300/1000, search/comment duration 180/600 seconds, discovery candidates 5/10, discovery duration 30/120 seconds, result page size 20/100. Local config can lower the ceilings. Queue capacity defaults to 20; stored text is limited to 20,000 Unicode code points per item; paginated item payloads are limited to 256 KiB.

Post/comment limits count distinct examined items, not only matches. Invalid limits are rejected, not silently clamped. Durations start at running; queue wait is separate. Polling never creates jobs. Each submission creates a new job.

Cancellation preserves committed results and rejects late writes. A job deadline returns partial evidence with time_limit. Browser request timeouts report browser_action_timeout and terminate the owned browser process tree before another queued job runs; dependency failures also reset the browser. Tool discovery is bounded and cancellable. A new runtime marks interrupted queued/running jobs as partial/failed without automatic replay. completed means the bounded workflow finished, not complete coverage of a platform. See tool contracts.

Local data, export and deletion

SQLite jobs/evidence, the profile, browser diagnostics and exports live below the configured data directory. Text sent back to the host may be forwarded to its model provider; local execution does not guarantee that model-visible evidence stays on the machine. No developer telemetry service is enabled.

JSON preserves original text/provenance. CSV uses UTF-8 BOM, quotes/newlines correctly, and escapes spreadsheet formula prefixes; the database text is unchanged. Export accepts a safe filename basename ending in .json/.csv and never overwrites an existing file. Export is per terminal search/comments job; discovery export and automatic merged multi-job exports are unsupported.

delete_job removes a terminal job, its observations and owned export files while preserving identities referenced by other jobs. Incomplete file cleanup remains retryable. Retention defaults to 30 days after completion, checked at startup/hourly; retention_days: 0 disables expiry. Active jobs are never expired. Registered sources and browser sessions are separate from job deletion.

To erase the whole local dataset/profile, stop the MCP host/server and browser first, confirm the configured data directory, then delete that directory using the operating system. Never commit or publish runtime data.

Development and verification

npm run typecheck
npm run build
npm test
npm run test:browser
npm run check:package

npm test runs offline unit/integration tests, including real stdio child processes and temporary SQLite databases. test:browser uses the real pinned Playwright MCP and headless Chrome, with local/intercepted synthetic pages and no Facebook requests. It is not live verification.

npm run test:live is explicit opt-in and refuses to start without WRAPPER_LIVE_QUERY, WRAPPER_CONFIG_FILE and a dedicated WRAPPER_DATA_DIR. It uses real data and your configured authorization/login. See testing instructions for limitations and cleanup. A separate host walkthrough must verify semantic source choice by the host LLM.

License and contributions

Original wrapper source is licensed under Apache-2.0; see LICENSE. Dependencies retain their respective licenses. Third-party attribution and copied license/notice texts are included; the npm package does not bundle dependency source code or browser binaries. Do not imply endorsement by Microsoft, Meta or a model provider.

Local conversation/specification documents are intentionally git-ignored; public installation, architecture, tool, data-model and test documentation are tracked. See CONTRIBUTING.md and SECURITY.md.