Metadata-Version: 2.4
Name: eight-mcp-community
Version: 0.1.6
Summary: Unofficial Python client and stdio MCP server for Eight person search workflows.
Project-URL: Homepage, https://github.com/new-village/eight-mcp-community
Project-URL: Repository, https://github.com/new-village/eight-mcp-community
Project-URL: Issues, https://github.com/new-village/eight-mcp-community/issues
Author: new-village
License-Expression: MIT
License-File: LICENSE
Keywords: business-cards,community,eight,mcp,model-context-protocol,stdio
Requires-Python: >=3.11
Requires-Dist: mcp>=1.23.0
Requires-Dist: requests>=2.32.0
Provides-Extra: browser
Requires-Dist: playwright>=1.56.0; extra == 'browser'
Provides-Extra: cloudflare
Requires-Dist: curl-cffi>=0.13.0; extra == 'cloudflare'
Description-Content-Type: text/markdown

# eight-mcp-community

Unofficial Python client and stdio MCP server for Eight person-search workflows.

> [!WARNING]
> This project is unofficial and not affiliated with Eight or Sansan. It uses private/internal web endpoints that can change without notice. Keep cookies, passwords, and raw contact data out of GitHub, logs, issues, prompts, and public reports.

## Design

This package follows the same idea as `note-mcp-community`, but the core is Python:

- PyPI/project name: `eight-mcp-community`
- Python import package: `eight`
- CLI commands: `eight-mcp-community` and `eight-mcp`
- MCP server: stdio, suitable for local/private agent use

The core client is reusable without an LLM:

```python
from eight import EightClient

client = EightClient.from_default_config()
result = client.search_person("鈴木太郎 東京商事")
print(result.to_safe_dict())
```

The MCP server is a thin wrapper over the same `EightClient`.

## Install / run

Local development:

```bash
uv sync --dev
uv run eight-mcp-community --help
uv run eight-mcp-community serve
```

Run directly without installing permanently:

```bash
uvx eight-mcp-community serve
```

If Eight returns Cloudflare-style `403` responses with valid cookies, use the optional `curl_cffi` transport. It impersonates Chrome for the normal CLI/MCP path and does not require Playwright:

```bash
uvx --from 'eight-mcp-community[cloudflare]' eight-mcp-community serve
```

If you install with `python -m pip install --user eight-mcp-community`, the command may be placed under `~/.local/bin`, which is not always on `PATH`. Either add that directory to `PATH`, use the absolute path, or run the module form:

```bash
python -m eight serve
~/.local/bin/eight-mcp-community serve
```

MCP client configuration:

```json
{
  "mcpServers": {
    "eight": {
      "command": "uvx",
      "args": ["eight-mcp-community", "serve"]
    }
  }
}
```

Codex MCP examples:

```bash
# PATH-based
codex mcp add eight -- eight-mcp-community serve

# pip --user / absolute-path style
codex mcp add eight -- /Users/you/.local/bin/eight-mcp-community serve

# Cloudflare-resistant transport via uvx
codex mcp add eight -- uvx --from 'eight-mcp-community[cloudflare]' eight-mcp-community serve
```

After package upgrades, optional dependency changes, authentication changes, or MCP configuration edits, restart Codex / your MCP client or otherwise restart the MCP server process. Already-running MCP servers keep using the old Python process.

Recommended post-install message for agents:

```text
Eight MCP registration is installed, but Eight authentication is not configured yet.
First run setup guidance: /Users/you/.local/bin/eight-mcp-community auth-setup
To configure auth, choose one setup path:
1. Cookie header: /Users/you/.local/bin/eight-mcp-community set-cookie '<COOKIE_HEADER>'
2. Password login: /Users/you/.local/bin/eight-mcp-community set-cookie --email '<EIGHT_LOGIN_EMAIL>' --password '<EIGHT_LOGIN_PASSWORD>'
auth-check は設定後の確認用です: /Users/you/.local/bin/eight-mcp-community auth-check
If auth-check returns 403 even with a valid cookie, use/install eight-mcp-community[cloudflare]. Restart Codex or the MCP client after changes.
```

Do not list `auth-check` as a way to configure cookies; it only verifies an already configured cookie/session.

Local development MCP config:

```json
{
  "mcpServers": {
    "eight": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/eight-mcp-community",
        "run",
        "eight-mcp-community",
        "serve"
      ]
    }
  }
}
```

## Authentication

Start with the setup helper, especially after `pip install --user` or Codex MCP registration:

```bash
~/.local/bin/eight-mcp-community auth-setup
```

The base package intentionally does **not** install Playwright. Do not make `auth-login` the first instruction after a base install. Configure a Cookie header first, or install the optional browser extra before using browser login.

If `auth-check` returns HTTP 403, it usually means either auth is still missing/expired or Eight/Cloudflare rejected the plain HTTP transport. Re-run `auth-setup`, configure a valid cookie, and if the cookie is known-good use the `[cloudflare]` extra:

```bash
python -m pip install --user 'eight-mcp-community[cloudflare]'
```

Supported credential lookup order:

1. `EIGHT_COOKIE` — Cookie header
2. `EIGHT_SESSION_COOKIE` — alternate Cookie header
3. `EIGHT_MCP_COMMUNITY_CONFIG` — path to config JSON with a `cookie` field
4. Default config file: `~/.config/eight-mcp-community/config.json`
5. `EIGHT_COOKIE_FILE` — Mozilla/Netscape cookie jar path
6. Optional env login: `EIGHT_EMAIL` + `EIGHT_PASSWORD`

For remote/server use, prefer a cookie config or env secret. The package does not require browser automation.

Create a config file from a trusted Cookie header:

```bash
~/.local/bin/eight-mcp-community set-cookie '<COOKIE_HEADER>'
~/.local/bin/eight-mcp-community auth-check
```

If you do not have a Cookie header, you can ask the CLI to log in and save cookies:

```bash
~/.local/bin/eight-mcp-community set-cookie --email '<EIGHT_LOGIN_EMAIL>' --password '<EIGHT_LOGIN_PASSWORD>'
```

`--email` and `--password` are used only for the login request. The config file stores the resulting Cookie header, not the email or password.

Eight may require MFA or another browser challenge. In that case, install the optional browser extra before using the browser login flow:

```bash
python -m pip install --user 'eight-mcp-community[browser]'
python -m playwright install chromium
~/.local/bin/eight-mcp-community auth-login
```

Browser login is optional and only installed through the `[browser]` extra. The standard CLI/MCP path does not depend on Playwright. If you run `auth-login` from a base install, it prints JSON setup guidance instead of a traceback.

If Playwright's browser binary is missing, install it once on the same machine/user account:

```bash
python -m playwright install chromium
```

Or use env:

```bash
EIGHT_COOKIE='<COOKIE_HEADER>' eight-mcp-community auth-check
```

If `EIGHT_EMAIL` and `EIGHT_PASSWORD` are set, the client can perform the same password-login flow used by the existing Hermes skill and save resulting cookies into the default config as a Cookie header. MFA/challenge responses are reported as structured errors and are not bypassed.

## CLI

```bash
eight-mcp-community auth-setup
eight-mcp-community auth-status
eight-mcp-community auth-check
eight-mcp-community set-cookie 'Cookie header'
eight-mcp-community set-cookie --email '<EIGHT_LOGIN_EMAIL>' --password '<EIGHT_LOGIN_PASSWORD>'
python -m pip install --user 'eight-mcp-community[browser]'
python -m playwright install chromium
eight-mcp-community auth-login
eight-mcp-community clear-cookie
eight-mcp-community search '鈴木'
eight-mcp-community search '鈴木' --always-network
eight-mcp-community serve
```

All command output is JSON except `--help`.

## MCP tools

Authentication/setup tools:

- `eight_auth_status` — report whether auth is configured and from where, without leaking secrets
- `eight_auth_setup` — return recommended setup steps; use this before telling users to run browser login
- `eight_auth_check` — verify access to Eight `/myhome` and CSRF extraction
- `eight_set_cookie` — store a Cookie header in the local config file, or log in with `email`/`password` and save cookies
- `eight_auth_login_browser` — open a Playwright browser login flow and save cookies locally after verifying `/myhome` status and CSRF token presence
- `eight_clear_cookie` — delete the stored config-file cookie
- `eight_login_help` — explain supported setup paths

Search tools:

- `eight_search_person` — search registered/exchanged cards first; search public Eight network only if no registered-card hit, unless `alwaysNetwork` is true
- `eight_search_registered_cards` — search only registered/exchanged business cards
- `eight_search_network_people` — search only public Eight network people, keeping public results separate from private cards

Returned data is intentionally minimal and LLM-safe: source, name, company, department, title, updated date, confidence/source bucket, and when available `matched_fields` / `match_excerpt` so users can understand why a result matched. Raw HTML, raw JSON, cookies, tokens, email addresses, phone numbers, and bulk exports are not returned.

## Privacy and safety

- Do not use this project for bulk contact export or contact-list harvesting.
- Do not commit cookies, config files, raw API dumps, screenshots, or credentials.
- Treat registered business-card results as private context; cite public sources for public-facing reports.
- Eight business-card data can be stale. Corroborate current affiliation/title with public sources when accuracy matters.

## Development

```bash
uv sync --dev
uv run ruff check .
uv run pytest
```

Manual MCP smoke test:

```bash
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke-test","version":"0.0.0"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
| timeout 5s uv run eight-mcp-community serve
```
