agentgraph-server 0.5.0__tar.gz

agentgraph_server-0.5.0/.agents/skills/graph/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: graph
+description: Use the AgentGraph CLI to query the local knowledge graph, inspect connectors, fetch entities, traverse relationships, and configure MCP access.
+---
+
+# /graph — AgentGraph CLI skill
+
+Use the `agentgraph` CLI to query the local knowledge graph. Always prefer the CLI over direct Python/DB access.
+
+## Commands
+
+```bash
+# Semantic search across entities
+agentgraph search "<query>" [--type <type>] [--platform <platform>] [--limit N] [--json]
+
+# Fetch full existing entity details by ID, UUID prefix, platform ref, or URL
+agentgraph get <entity-id|platform/ref|url> --resolve [--json]
+
+# List edges for an entity
+agentgraph edges <entity-id|platform/ref> [--type <edge-type>] [--direction in|out|both] [--json]
+
+# Traverse the graph from a starting entity
+agentgraph traverse <entity-id|platform/ref> --resolve [--depth N] [--json]
+
+# Filter entities by type and metadata
+agentgraph query --type <entity-type> [--filter key=value] [--since 12h|30m|2d] [--mine] [--has-attachments] [--limit N] [--order-by created_at|updated_at|last_accessed] [--json]
+
+# Trigger a connector fetch for a platform entity (by platform + platform-specific ID)
+agentgraph fetch <platform> <resource-id> [--json]
+
+# Trigger a connector re-fetch for an entity by its internal UUID
+agentgraph fetch-entity <entity-id> [--json]
+
+# Download an entity's source file using connector auth, including Gmail attachment Document stubs
+agentgraph download <entity-id|platform/ref> [--output <file-or-dir>] [--json]
+
+# Bookmark an entity or retrieve and bookmark an HTTP(S) URL; use --remove to clear bookmark protection
+agentgraph bookmark <entity-id|platform/ref|url> [--remove] [--json]
+
+# Delete an entity from the graph
+agentgraph delete <entity-id|platform/ref|url> [--json]
+
+# Merge duplicate Person entities that refer to the same human
+agentgraph unify-persons <primary-person-id> <duplicate-person-id>... [--json]
+
+# Queue a background poll for one or all connectors
+agentgraph poll [<source>] [--json]   # source: slack, gmail, discord, drive, rss — omit for all; reports already_running and skipped auth failures
+
+# Run a one-shot bulk ingest for a connector (all data within the retention window, beyond what poll covers)
+agentgraph ingest <source> [--json]   # e.g. gmail, rss
+
+# List installed connectors and their sync status; credential fields are null for connectors like RSS/web
+agentgraph connectors [--verify] [--json] # auth_provider, auth_status/auth_detail when applicable, auth_verified, url_patterns, polls, poll_delegates, polled_by, sync, last_synced_at
+
+# Run a connector-owned command
+agentgraph connector <source> <command> [args...] [--json] # e.g. agentgraph connector rss add https://simonwillison.net/atom/everything/
+agentgraph connector <source> --help
+agentgraph connector rss add <feed-url> [feed-url...] [--json] # validates feeds, rejects non-feeds without saving, and queues an RSS poll
+agentgraph connector rss remove <feed-url> [feed-url...] [--json] # removes exact configured feed URLs
+agentgraph connector rss import-opml <file.opml> [--all | --select 1,3-5] [--json] # omit flags for checkbox selection
+
+# Show credential-backed auth provider state (dedupes shared providers like Google); add --verify for live provider API checks
+agentgraph auth [--verify] [--json] status # provider, connectors[], auth_status/auth_detail, auth_verified, accounts[] including auth_method
+
+# Authenticate connectors/providers
+agentgraph auth google [--add] [--account <account-id>]   # uses AgentGraph's packaged OAuth client
+agentgraph auth slack [--method oauth|browser] [--client-id <client-id>] [--add] [--account <account-id>] # --client-id implies OAuth; without one, OAuth shows admin/app setup guidance
+agentgraph auth slack --method browser [--xoxc-token <token>] [--d-cookie <cookie>] # explicit browser-session fallback; credential flags imply browser
+agentgraph auth discord [--add] [--account <account-id>]  # Discord bot token
+agentgraph auth remove <provider> [--account <account-id>] [--json] # remove stored credentials; does not delete graph data
+agentgraph connector rss add <feed-url>                   # RSS/Atom feed URLs are connector configuration, not auth
+
+# Server
+agentgraph serve [--reload]
+agentgraph mcp-serve
+agentgraph mcp-config   # stdio config for Claude Desktop/Claude Code; ChatGPT uses a tunneled HTTPS /mcp endpoint
+
+# Install the bundled AgentGraph skill into ~/.agents/skills or ./.agents/skills
+agentgraph install-skill [graph] [--target user|project] [--force] [--json]
+```
+
+`--depth 0` returns only the requested entity; depths 1 through 4 include that many relationship hops.
+
+## MCP tool equivalents
+
+When using AgentGraph through MCP instead of the CLI, use these equivalent tools:
+
+```text
+agentgraph connectors              -> list_connectors_tool(verify)
+agentgraph auth [--json] status    -> list_auth_providers_tool(verify) # credential-backed providers only
+agentgraph auth <provider> ...     -> authenticate_provider_tool(provider, args, account_id, add)
+agentgraph auth remove ...         -> remove_auth_provider_tool(provider, account_id)
+agentgraph connector <source> ...  -> run_connector_command_tool(source, args)
+agentgraph search ...              -> search_entities_tool(...)
+agentgraph get ...                 -> get_entity_tool(entity_id)
+agentgraph edges ...               -> get_edges_tool(entity_id, edge_type, direction)
+agentgraph traverse ...            -> traverse_graph_tool(entity_id, max_depth)
+agentgraph query ...               -> query_by_filter_tool(...)
+agentgraph fetch ...               -> fetch_entity_tool(platform, resource_id)
+agentgraph fetch-entity ...        -> fetch_entity_by_id_tool(entity_id)
+agentgraph download ...            -> download_entity_tool(entity_id, output_path)
+agentgraph poll [source]           -> poll_connectors_tool(source) # returns polled, already_running, and skipped lists
+agentgraph ingest <source>         -> ingest_connector_tool(source)
+agentgraph bookmark ...            -> bookmark_entity_tool(entity_id, bookmarked)
+agentgraph delete ...              -> delete_entity_tool(entity_id)
+agentgraph unify-persons ...       -> unify_persons_tool(primary_entity_id, duplicate_entity_ids)
+agentgraph install-skill ...       -> install_skill_tool(skill, target, force)
+```
+
+## Entity types
+
+| Type | Contains |
+|---|---|
+| `Message` | Chat messages (Discord, Slack). **Chat images and file uploads are attachments on Message entities** — stored in `metadata.attachments` (JSON array with `url`, `filename`, `content_type`, `width`, `height`). Use `--has-attachments` to filter to messages with files. |
+| `Document` | Text documents (Google Docs, etc.) and Gmail attachment stubs. Gmail attachment stubs are referenced by their owning `Thread` and can be downloaded with `agentgraph download`. |
+| `Channel` | Chat channels and DM threads. |
+| `Task` | Tasks or to-do items. |
+| `Project` | Project/repository containers. |
+
+To find chat images uploaded this week: `agentgraph query --type Message --has-attachments --since 7d --json`
+
+To download a Gmail attachment: re-fetch the Gmail thread, traverse one hop to
+find referenced Gmail `Document` stubs, then download the attachment document:
+
+```bash
+agentgraph fetch-entity <gmail-thread-entity-id>
+agentgraph traverse <gmail-thread-entity-id> --depth 1 --json
+agentgraph download <attachment-document-entity-id> --output <file-or-dir>
+```
+
+## Notes
+
+- Graph data commands require the AgentGraph server. If a command reports the server is unavailable, run `agentgraph serve`.
+- Use `--json` when you need to parse results programmatically
+- List-style commands (`search`, `query`, and graph viewer/browse results) return bounded content snippets with `content_truncated` when applicable. Use `agentgraph get <entity-id> --json` for full entity content.
+- MCP `search_entities_tool` and `query_by_filter_tool` default to `refresh=false` so connector-owned network enrichment does not slow normal reads. Set `refresh=true` only when fresh connector-owned presentation metadata is needed.
+- Bookmark targets accept: full UUID, UUID prefix, platform ref (`slack/T123/C123`, `gdocs/doc-id`, `discord/dm/456`), or HTTP(S) URL
+- `agentgraph bookmark --remove <entity-id|platform/ref|url>` clears bookmark protection for existing graph entities
+- Delete targets accept: full UUID, UUID prefix, platform ref, or HTTP(S) URL. Connected edges are removed with the entity.
+- Use `agentgraph download` for source files stored behind connector auth, such as Drive PDFs, exported Google Docs/Sheets, or Gmail attachment `Document` stubs
+- `agentgraph fetch` and `agentgraph fetch-entity` persist the connector's complete returned batch before reporting counts; content-rich resources such as RSS feeds may take several minutes
+- Use `agentgraph bookmark` for entities or HTTP(S) URLs that should survive retention-window garbage collection
+- Use `agentgraph unify-persons` only after confirming two or more `Person` entities are the same human; the first argument is the canonical person to keep. Without `--json`, the command displays the updated canonical Person, including merged identity metadata and duplicate identities.
+- `polls: false` does not always mean stale: check `polled_by` / `sync` for connectors refreshed by another connector, e.g. `gdocs` and `gsheets` are refreshed via the `gdrive` Drive Changes poll
+- Server logs go to stdout unless the process manager redirects them elsewhere
+
+## Stub Entities
+
+An entity is a **stub** when it has no title and no content — it was referenced in an edge but never fetched from its source. Using `--resolve` (default for `get` and `traverse`) automatically fetches stubs from their source before returning. If you omitted `--resolve` and get empty results, re-run with it or use `agentgraph fetch-entity <entity-id>` then re-fetch.
+
+## Workflow
+
+When the user asks about graph data:
+1. Run `agentgraph connectors --json` to verify the relevant connector is installed and to inspect its last sync state
+2. Run `agentgraph auth --json status` to inspect local provider-level authentication state, especially for shared auth like Google
+3. If credential validity is uncertain, run `agentgraph auth --verify --json status` or `agentgraph connectors --verify --json` to live-check provider APIs for credential-backed connectors
+4. If Google has `auth_status: "invalid"` or `"missing"`, tell the user to run `agentgraph auth google`
+5. Run the appropriate `agentgraph` command with `--json` to get structured output
+6. Use `edges` or `traverse` to follow relationships when needed

agentgraph_server-0.5.0/.agents/skills/slack-auth/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: slack-auth
+description: Authenticate AgentGraph to Slack with user OAuth PKCE by default, or explicitly use browser-session credentials as a fallback.
+---
+
+# /slack-auth - Slack Authentication
+
+Use Slack user OAuth with PKCE unless the user explicitly requests the browser-session fallback.
+
+## OAuth (default)
+
+1. Check status without exposing credentials:
+
+```bash
+agentgraph auth status --json | jq '.[] | select(.provider == "slack")'
+```
+
+2. Start the interactive chooser and select Slack user OAuth with PKCE:
+
+```bash
+agentgraph auth slack
+```
+
+AgentGraph reuses a Client ID stored with the selected account or reads
+`AGENTGRAPH_SLACK_CLIENT_ID`. Otherwise it asks whether the user has admin
+permission in the target workspace.
+
+Admins create AgentGraph at `https://api.slack.com/apps` with **Create New App →
+From an app manifest**, select the target workspace, paste the manifest printed by
+AgentGraph into Slack's **JSON** tab, approve it, and enter its Client ID. The
+manifest includes the only
+supported callback, `http://localhost:8766/slack/oauth/callback`.
+
+Non-admins choose either **Enter a Client ID provided by a Slack admin** or **Set up
+the AgentGraph Slack App**. The setup path checks whether the target workspace
+appears under **Pick a workspace**. If it does, create the app from the printed
+manifest and enter its Client ID. If it does not, send the printed example request
+and manifest to a Workspace Owner or app manager, then rerun with the supplied Client
+ID:
+
+```bash
+agentgraph auth slack --add --client-id '<client-id>'
+```
+
+During authorization, click **Allow** when available. If Slack shows **Request
+approval**, use AgentGraph's copyable **Message for your Slack Admin**, submit it,
+and rerun with the same Client ID after Slackbot confirms approval. If installation
+is blocked without a request action, contact a Workspace Owner or app manager.
+
+For explicit OAuth selection, use `agentgraph auth slack --method oauth`.
+
+Use `--add` for another identity or `--account slack:<team>:<user>` to replace that identity's current method. Verify `auth_method` afterward:
+
+```bash
+agentgraph auth status --verify --json | jq '.[] | select(.provider == "slack") | .accounts'
+```
+
+If the user declines optional `users:read.email`, authentication still succeeds without email enrichment.
+
+## Browser fallback
+
+Only use this flow when OAuth cannot be approved or the user explicitly selects it. Load the `agent-browser` skill, connect to a logged-in `app.slack.com` session, and derive the team-specific token:
+
+```bash
+TEAM_ID=$(agent-browser get url | sed -n 's#.*app\.slack\.com/client/\(T[A-Z0-9]*\).*#\1#p')
+TOKEN=$(agent-browser eval "(() => { const cfg = JSON.parse(localStorage.getItem('localConfig_v2')); return cfg.teams['$TEAM_ID'].token; })()" | jq -r .)
+COOKIE=$(agent-browser --json cookies get | jq -r '.data.cookies[] | select(.name == "d" and (.domain | contains("slack"))) | .value' | head -n 1)
+```
+
+Validate without printing either secret, then save them through the explicit method:
+
+```bash
+if [ -z "$TOKEN" ] || [ "$TOKEN" = "null" ]; then echo "missing token" >&2; exit 1; fi
+if [ -z "$COOKIE" ] || [ "$COOKIE" = "null" ]; then echo "missing d cookie" >&2; exit 1; fi
+case "$TOKEN" in xoxc-*) ;; *) echo "token did not use xoxc prefix" >&2; exit 1;; esac
+agentgraph auth slack --method browser --xoxc-token "$TOKEN" --d-cookie "$COOKIE"
+```
+
+Supplying `--client-id` without `--method` infers OAuth. Supplying `--xoxc-token` or
+`--d-cookie` without `--method` infers browser mode for compatibility. Never combine
+OAuth and browser credential options.
+
+## Revocation
+
+Remove one identity or all Slack credentials locally:
+
+```bash
+agentgraph auth remove slack --account 'slack:<team>:<user>'
+agentgraph auth remove slack
+```
+
+Local removal does not revoke Slack's grant. For OAuth, also revoke the app from Slack's connected-app settings or ask the workspace admin to remove the internal app.

agentgraph_server-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Simon Wade
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentgraph_server-0.5.0/PKG-INFO

@@ -0,0 +1,286 @@
+Metadata-Version: 2.4
+Name: agentgraph-server
+Version: 0.5.0
+Summary: AgentGraph builds a local, queryable graph of your digital world across tools like Slack, Discord, Gmail, Google Docs, Sheets, Drive, and RSS feeds, so your AI agents can search, fetch, and reason over the same connected context you work from.
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: agentgraph-connector-web<0.6,>=0.5.0
+Requires-Dist: apscheduler>=3.11.2
+Requires-Dist: click<8.4
+Requires-Dist: fastapi>=0.135.2
+Requires-Dist: fastembed>=0.8.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: mcp>=1.26.0
+Requires-Dist: numpy>=2.4.6
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pydantic-settings>=2.13.1
+Requires-Dist: rich>=14.3.3
+Requires-Dist: sqlite-vec>=0.1.9
+Requires-Dist: typer>=0.24.1
+Requires-Dist: uvicorn>=0.42.0
+Provides-Extra: google
+Requires-Dist: agentgraph-connector-google<0.6,>=0.5.0; extra == "google"
+Provides-Extra: slack
+Requires-Dist: agentgraph-connector-slack<0.6,>=0.5.0; extra == "slack"
+Provides-Extra: discord
+Requires-Dist: agentgraph-connector-discord<0.6,>=0.5.0; extra == "discord"
+Provides-Extra: rss
+Requires-Dist: agentgraph-connector-rss<0.6,>=0.5.0; extra == "rss"
+Provides-Extra: web
+Requires-Dist: agentgraph-connector-web<0.6,>=0.5.0; extra == "web"
+Provides-Extra: all
+Requires-Dist: agentgraph-connector-web<0.6,>=0.5.0; extra == "all"
+Requires-Dist: agentgraph-connector-google<0.6,>=0.5.0; extra == "all"
+Requires-Dist: agentgraph-connector-slack<0.6,>=0.5.0; extra == "all"
+Requires-Dist: agentgraph-connector-discord<0.6,>=0.5.0; extra == "all"
+Requires-Dist: agentgraph-connector-rss<0.6,>=0.5.0; extra == "all"
+Dynamic: license-file
+
+# AgentGraph
+
+AgentGraph is a local knowledge graph for AI agents. It indexes content from Slack, Discord, Gmail, Google Docs, Google Sheets, Google Drive, and RSS/Atom feeds into a queryable graph of entities, people, and relationships that you can use from the CLI, web viewer, browser extension, or MCP.
+
+## Docs
+
+- [Install](docs-src/install.md)
+- [Quickstart](docs-src/quickstart.md)
+- [Configuration](docs-src/configuration.md)
+- [Performance testing](docs-src/performance.md)
+- [Extending](docs-src/extending.md)
+- [Commands](docs-src/commands/index.md)
+- [MCP tools](docs-src/mcp/index.md)
+- [Privacy](docs-src/privacy.md)
+
+## Installation
+
+### Prerequisites
+
+- Python 3.12+
+- [uv](https://docs.astral.sh/uv/)
+- Chrome for the browser extension
+
+Install `uv` if needed:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### Clone and sync
+
+```bash
+git clone https://github.com/simonexmachina/agent-graph
+cd agent-graph
+uv sync --extra all
+```
+
+Or install only the connectors you need:
+
+```bash
+uv sync --extra google
+uv sync --extra slack
+uv sync --extra discord
+uv sync --extra rss
+```
+
+Credentials and local state live in `~/.agentgraph/` by default, or under `AGENTGRAPH_CONFIG_DIR` if you set a custom config directory.
+
+## Quick Start
+
+### 1. Authenticate connectors
+
+Run the guided onboarding flow:
+
+```bash
+agentgraph onboard
+```
+
+Or authenticate a single source directly:
+
+```bash
+agentgraph auth <source>
+```
+
+### 2. Start AgentGraph
+
+```bash
+agentgraph serve
+```
+
+The default server URL is `http://127.0.0.1:8765`.
+
+### 3. Install the browser extension
+
+Install the [AgentGraph Chrome Extension](https://chromewebstore.google.com/detail/agentgraph-extension/iilkfclglabllelhjacijldknapbhidi?authuser=0&hl=en-AU) from the Chrome Web Store.
+
+To build it locally instead:
+
+```bash
+cd extension
+npm install
+npm run build
+```
+
+Then open `chrome://extensions`, enable Developer Mode, click **Load unpacked**, and select `extension/dist/`.
+
+### 4. Browse something supported
+
+Open a Slack channel, Discord thread, Google Doc, Google Sheet, Gmail thread, or Drive folder and keep the tab focused long enough for the dwell threshold to trigger a fetch.
+
+### 5. Verify entities landed
+
+```bash
+agentgraph connectors --json
+agentgraph search "slack" --limit 5
+agentgraph query --type Document --limit 5
+```
+
+### 6. Connect an assistant
+
+```bash
+agentgraph mcp-config
+```
+
+Use the printed stdio config with Claude Desktop or Claude Code. For ChatGPT developer mode, run AgentGraph with streamable HTTP and expose the local `/mcp` endpoint through HTTPS before creating the app/connector.
+
+## How It Works
+
+The browser extension watches supported URLs and sends dwell events to your local AgentGraph server. When you stay on a page long enough, the matching connector fetches the resource and turns it into graph entities, people, and edges. After that first fetch, supported connectors keep known resources fresh with background polling.
+
+```text
+Browser extension -> local server -> connector -> local graph
+                                         |
+                                         +-> CLI / viewer / MCP
+```
+
+AgentGraph is local-first. Indexed content is stored in a local SQLite database. The project does not run a hosted service for your graph data.
+
+## Surfaces
+
+| Surface | Use it for | Entry point |
+| --- | --- | --- |
+| CLI | Search, fetch, ingest, debugging, and operations | `agentgraph search`, `agentgraph fetch`, `agentgraph serve` |
+| MCP | Claude Desktop, Claude Code, ChatGPT developer mode, and other MCP clients | `agentgraph mcp-config`, `agentgraph mcp-serve` |
+| Browser extension | Passive indexing from supported browser tabs | [Chrome Web Store](https://chromewebstore.google.com/detail/agentgraph-extension/iilkfclglabllelhjacijldknapbhidi?authuser=0&hl=en-AU) |
+| Viewer | Visual graph inspection and manual exploration | `http://127.0.0.1:8765/viewer` |
+
+## Commands
+
+### Query
+
+```bash
+agentgraph search "project kickoff notes"
+agentgraph query --type Message --filter platform=slack --since 12h
+agentgraph get <entity-id>
+agentgraph edges <entity-id>
+agentgraph traverse <entity-id> --depth 2
+```
+
+### Fetch and files
+
+```bash
+agentgraph fetch gdocs <document-id>
+agentgraph fetch-entity <entity-id>
+agentgraph download <entity-id>
+agentgraph bookmark <entity-id> --remove
+agentgraph delete <entity-id>
+```
+
+Gmail attachments are indexed as `Document` stub entities referenced by the
+owning `Thread`. Re-fetch the thread, traverse one hop to find the attachment
+document, then pass that document ID to `agentgraph download`.
+
+### Sync and connectors
+
+```bash
+agentgraph connectors
+agentgraph poll
+agentgraph ingest gmail
+agentgraph connector rss add https://example.com/feed.xml
+```
+
+### MCP
+
+```bash
+agentgraph mcp-serve
+agentgraph mcp-serve --transport sse --port 8808
+agentgraph mcp-serve --transport streamable-http --host 0.0.0.0 --port 8808
+```
+
+ChatGPT uses the streamable HTTP endpoint, such as `https://your-tunnel.example/mcp`, not the stdio JSON config.
+
+See the full [command reference](docs-src/commands/index.md) and [MCP tool reference](docs-src/mcp/index.md).
+
+## Connectors
+
+Included connectors:
+
+| Source | Entities | Auth | Refresh model |
+| --- | --- | --- | --- |
+| Slack | Channel, Message | User OAuth PKCE; browser-session fallback | Browser dwell plus 5 minute polling |
+| Discord | Channel, Message | Bot token | Browser dwell plus 5 minute polling |
+| Google Docs | Document | Google OAuth | Browser dwell plus Drive-backed refresh |
+| Google Sheets | Spreadsheet | Google OAuth | Browser dwell plus Drive-backed refresh |
+| Google Drive | Folder, Document | Google OAuth | Browser dwell for folders and files, plus Drive changes polling |
+| Gmail | Thread, Document stubs for attachments | Google OAuth | Browser dwell plus background poll and ingest |
+| RSS | Folder, Document | Feed URLs | Background poll and ingest; `add` validates feeds and queues a poll |
+
+AgentGraph is designed to be extended. Custom connectors live in separate packages, register through the connector entry point, and implement the shared `BaseConnector` interface. See [Extending](docs-src/extending.md).
+
+## Configuration
+
+Settings are read from environment variables and from a `.env` file in the config directory.
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `AGENTGRAPH_CONFIG_DIR` | `~/.agentgraph` | Directory for config, credentials, and the default SQLite database |
+| `AGENTGRAPH_BACKEND` | `sqlite` | Persistence backend. The built-in backend is `sqlite` |
+| `AGENTGRAPH_BACKEND_SQLITE_PATH` | `$AGENTGRAPH_CONFIG_DIR/agentgraph.db` | SQLite database path |
+| `AGENTGRAPH_SERVER_HOST` | `127.0.0.1` | Server bind address |
+| `AGENTGRAPH_SERVER_PORT` | `8765` | Server port |
+| `AGENTGRAPH_DWELL_THRESHOLD_SECONDS` | `3` | Seconds of focus before a fetch is triggered |
+| `AGENTGRAPH_RETENTION_DAYS` | `90` | Days before an unvisited entity is garbage collected |
+| `AGENTGRAPH_EMBEDDING_MODEL` | `BAAI/bge-small-en-v1.5` | FastEmbed model used for embeddings |
+| `AGENTGRAPH_SLACK_CLIENT_ID` | prompt/stored account | Optional Client ID override for the admin-created internal Slack OAuth app |
+| `AGENTGRAPH_SLACK_REDIRECT_URI` | `http://localhost:8766/slack/oauth/callback` | Exact Slack OAuth callback registered on the app |
+
+See [Configuration](docs-src/configuration.md) for the full setup.
+
+## MCP Tools
+
+`agentgraph mcp-serve` exposes these tool families to MCP clients:
+
+- `list_connectors_tool`
+- `list_auth_providers_tool`
+- `authenticate_provider_tool`
+- `run_connector_command_tool`
+- `search_entities_tool`
+- `get_entity_tool`
+- `get_edges_tool`
+- `traverse_graph_tool`
+- `query_by_filter_tool`
+- `fetch_entity_tool`
+- `fetch_entity_by_id_tool`
+- `download_entity_tool`
+- `poll_connectors_tool`
+- `ingest_connector_tool`
+- `bookmark_entity_tool`
+- `delete_entity_tool`
+- `unify_persons_tool`
+
+## Contributing
+
+See [AGENTS.md](AGENTS.md) for repo-specific development rules.
+
+Before opening a change, run:
+
+```bash
+uv run pytest tests/ -m "not integration" -q
+uv run pyright
+uv run ruff check agentgraph/
+```
+
+## License
+
+See [LICENSE](LICENSE).