gramps-mcp 0.1.0__tar.gz

gramps_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Audel Rouhi
+
+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.

gramps_mcp-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE
+include README.md
+include requirements.txt
+recursive-include gramps_mcp *.py *.json *.md *.yaml *.yml

gramps_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,271 @@
+Metadata-Version: 2.4
+Name: gramps-mcp
+Version: 0.1.0
+Summary: Gramps API + MCP Server + A2A Agent — genealogy (people/families/events/places/sources/media)
+Author-email: Audel Rouhi <knucklessg1@gmail.com>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: <3.15,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: agent-utilities>=0.51.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: mcp
+Requires-Dist: agent-utilities[mcp]>=0.51.0; extra == "mcp"
+Provides-Extra: agent
+Requires-Dist: agent-utilities[agent,logfire]>=0.51.0; extra == "agent"
+Provides-Extra: all
+Requires-Dist: gramps-mcp[agent,logfire,mcp]>=0.1.0; extra == "all"
+Provides-Extra: test
+Requires-Dist: pytest-xdist>=3.6.0; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Dynamic: license-file
+
+# Gramps MCP
+## CLI or API | MCP | Agent
+
+![PyPI - Version](https://img.shields.io/pypi/v/gramps-mcp)
+![MCP Server](https://badge.mcpx.dev?type=server 'MCP Server')
+![PyPI - Downloads](https://img.shields.io/pypi/dd/gramps-mcp)
+![GitHub Repo stars](https://img.shields.io/github/stars/Knuckles-Team/gramps-mcp)
+![PyPI - License](https://img.shields.io/pypi/l/gramps-mcp)
+![GitHub last commit (by committer)](https://img.shields.io/github/last-commit/Knuckles-Team/gramps-mcp)
+
+*Version: 0.1.0*
+
+> **Documentation** — Installation, deployment, usage across the API, CLI, and MCP
+> interfaces, the integrated A2A agent server, and guidance for provisioning the
+> backing platform are maintained in the
+> [official documentation](https://knuckles-team.github.io/gramps-mcp/).
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Key Features](#key-features)
+- [Available MCP Tools](#available-mcp-tools)
+- [Installation](#installation)
+- [Usage](#usage)
+- [MCP](#mcp)
+- [Documentation](#documentation)
+
+---
+
+## Overview
+
+**Gramps MCP MCP Server + A2A Agent**
+
+Gramps API + MCP Server + A2A Agent — genealogy (people/families/events/places/sources/media)
+
+This repository is actively maintained - Contributions are welcome!
+
+## Key Features
+
+- **Action-routed MCP tools** — each domain is exposed as a single MCP tool that routes
+  to many underlying operations via an `action` argument, keeping the tool surface small.
+- **Three interfaces, one package** — use it as a Python **API client**, an **MCP server**
+  (`stdio` / `streamable-http` / `sse`), or a Pydantic-AI **A2A agent**.
+- **`agent-utilities` native** — built on the shared framework (auth, action router,
+  telemetry, governance) for fleet consistency.
+- **Per-tool toggles** — enable or disable each tool domain with environment switches.
+- **Enterprise-ready** — OTEL/Langfuse telemetry and optional Eunomia access governance.
+
+## Available MCP Tools
+
+Each tool is **action-routed**: pass an `action` and a JSON `params_json` payload. Tool
+domains can be toggled on or off with the listed environment variable. The table below is
+**auto-generated from the live server** by the `mcp-readme-table` pre-commit hook
+(`python -m agent_utilities.mcp.readme_tools`) — do not edit it by hand.
+
+<!-- MCP-TOOLS-TABLE:START -->
+
+| MCP Tool | Toggle Env Var | Description |
+|----------|----------------|-------------|
+| `gramps_bookmarks` | `BOOKMARKSTOOL` | Manage Gramps bookmarks operations. CONCEPT:GRMP-001. |
+| `gramps_chat` | `CHATTOOL` | Manage Gramps chat operations. CONCEPT:GRMP-001. |
+| `gramps_citations` | `CITATIONSTOOL` | Manage Gramps citations operations. CONCEPT:GRMP-001. |
+| `gramps_config` | `CONFIGTOOL` | Manage Gramps config operations. CONCEPT:GRMP-001. |
+| `gramps_dna` | `DNATOOL` | Manage Gramps dna operations. CONCEPT:GRMP-001. |
+| `gramps_events` | `EVENTSTOOL` | Manage Gramps events operations. CONCEPT:GRMP-001. |
+| `gramps_exporters` | `EXPORTERSTOOL` | Manage Gramps exporters operations. CONCEPT:GRMP-001. |
+| `gramps_facts` | `FACTSTOOL` | Manage Gramps facts operations. CONCEPT:GRMP-001. |
+| `gramps_families` | `FAMILIESTOOL` | Manage Gramps families operations. CONCEPT:GRMP-001. |
+| `gramps_filters` | `FILTERSTOOL` | Manage Gramps filters operations. CONCEPT:GRMP-001. |
+| `gramps_holidays` | `HOLIDAYSTOOL` | Manage Gramps holidays operations. CONCEPT:GRMP-001. |
+| `gramps_importers` | `IMPORTERSTOOL` | Manage Gramps importers operations. CONCEPT:GRMP-001. |
+| `gramps_living` | `LIVINGTOOL` | Manage Gramps living operations. CONCEPT:GRMP-001. |
+| `gramps_media` | `MEDIATOOL` | Manage Gramps media operations. CONCEPT:GRMP-001. |
+| `gramps_metadata` | `METADATATOOL` | Manage Gramps metadata operations. CONCEPT:GRMP-001. |
+| `gramps_name_formats` | `NAME_FORMATSTOOL` | Manage Gramps name formats operations. CONCEPT:GRMP-001. |
+| `gramps_name_groups` | `NAME_GROUPSTOOL` | Manage Gramps name groups operations. CONCEPT:GRMP-001. |
+| `gramps_notes` | `NOTESTOOL` | Manage Gramps notes operations. CONCEPT:GRMP-001. |
+| `gramps_oidc` | `OIDCTOOL` | Manage Gramps oidc operations. CONCEPT:GRMP-001. |
+| `gramps_people` | `PEOPLETOOL` | Manage Gramps people operations. CONCEPT:GRMP-001. |
+| `gramps_places` | `PLACESTOOL` | Manage Gramps places operations. CONCEPT:GRMP-001. |
+| `gramps_relations` | `RELATIONSTOOL` | Manage Gramps relations operations. CONCEPT:GRMP-001. |
+| `gramps_reports` | `REPORTSTOOL` | Manage Gramps reports operations. CONCEPT:GRMP-001. |
+| `gramps_repositories` | `REPOSITORIESTOOL` | Manage Gramps repositories operations. CONCEPT:GRMP-001. |
+| `gramps_search` | `SEARCHTOOL` | Manage Gramps search operations. CONCEPT:GRMP-001. |
+| `gramps_sources` | `SOURCESTOOL` | Manage Gramps sources operations. CONCEPT:GRMP-001. |
+| `gramps_tags` | `TAGSTOOL` | Manage Gramps tags operations. CONCEPT:GRMP-001. |
+| `gramps_tasks` | `TASKSTOOL` | Manage Gramps tasks operations. CONCEPT:GRMP-001. |
+| `gramps_timeline` | `TIMELINETOOL` | Manage Gramps timeline operations. CONCEPT:GRMP-001. |
+| `gramps_token` | `TOKENTOOL` | Manage Gramps token operations. CONCEPT:GRMP-001. |
+| `gramps_transactions` | `TRANSACTIONSTOOL` | Manage Gramps transactions operations. CONCEPT:GRMP-001. |
+| `gramps_translations` | `TRANSLATIONSTOOL` | Manage Gramps translations operations. CONCEPT:GRMP-001. |
+| `gramps_trees` | `TREESTOOL` | Manage Gramps trees operations. CONCEPT:GRMP-001. |
+| `gramps_types` | `TYPESTOOL` | Manage Gramps types operations. CONCEPT:GRMP-001. |
+| `gramps_users` | `USERSTOOL` | Manage Gramps users operations. CONCEPT:GRMP-001. |
+
+_35 action-routed tools (default `MCP_TOOL_MODE=condensed`). Each is enabled unless its toggle is set false; set `MCP_TOOL_MODE=verbose` (or `both`) for the 1:1 per-operation surface. Auto-generated — do not edit._
+<!-- MCP-TOOLS-TABLE:END -->
+
+## Installation
+
+### Install with `uvx` (no install — run on demand)
+
+```bash
+uvx --from gramps-mcp gramps-mcp      # MCP server
+uvx --from gramps-mcp gramps-agent    # A2A agent server
+```
+
+### Install with `pip`
+
+```bash
+python -m pip install gramps-mcp            # core (API client)
+python -m pip install "gramps-mcp[all]"     # + MCP server + A2A agent + telemetry
+```
+
+### Console scripts
+
+After installation the following entry points are available on your `PATH`:
+
+| Command | Description |
+|---------|-------------|
+| `gramps-mcp` | Launch the MCP server |
+| `gramps-agent` | Launch the A2A agent server |
+
+## Usage
+
+### As a Python API client
+
+```python
+from gramps_mcp.auth import get_client
+
+client = get_client()
+status = client.get_system_status()
+print(status)
+```
+
+### As an MCP server (CLI)
+
+```bash
+# Local stdio (for IDEs)
+gramps-mcp
+
+# Networked streamable-http
+gramps-mcp --transport streamable-http --host 0.0.0.0 --port 8000
+```
+
+### Calling an MCP tool
+
+Tools are action-routed — pass an `action` plus a JSON `params_json` string:
+
+```json
+{
+  "tool": "system_operations",
+  "arguments": {
+    "action": "status",
+    "params_json": "{}"
+  }
+}
+```
+
+## MCP
+
+### Using as an MCP Server
+
+The MCP Server can be run in `stdio` (local), `streamable-http` (networked), or
+`sse` mode.
+
+#### Environment Variables
+
+*   `GRAMPS_URL`: The URL of the target service.
+*   `GRAMPS_TOKEN`: The API token or access token.
+
+#### stdio Transport (local IDEs — Cursor, Claude Desktop, VS Code)
+
+```json
+{
+  "mcpServers": {
+    "gramps-mcp": {
+      "command": "uvx",
+      "args": ["--from", "gramps-mcp", "gramps-mcp"],
+      "env": {
+        "GRAMPS_URL": "https://service.example.com",
+        "GRAMPS_TOKEN": "your_token"
+      }
+    }
+  }
+}
+```
+
+#### Streamable-HTTP Transport (networked / production)
+
+```json
+{
+  "mcpServers": {
+    "gramps-mcp": {
+      "command": "uvx",
+      "args": ["--from", "gramps-mcp", "gramps-mcp", "--transport", "streamable-http", "--port", "8000"],
+      "env": {
+        "TRANSPORT": "streamable-http",
+        "HOST": "0.0.0.0",
+        "PORT": "8000",
+        "GRAMPS_URL": "https://service.example.com",
+        "GRAMPS_TOKEN": "your_token"
+      }
+    }
+  }
+}
+```
+
+<!-- BEGIN GENERATED: additional-deployment-options -->
+### Additional Deployment Options
+
+`gramps-mcp` can also run as a **local container** (Docker / Podman / `uv`) or be
+consumed from a **remote deployment**. The
+[Deployment guide](https://knuckles-team.github.io/gramps-mcp/deployment/) has full,
+copy-paste `mcp_config.json` for all four transports — **stdio**, **streamable-http**,
+**local container / uv**, and **remote URL**:
+
+- **Local container / uv** — launch the server from `mcp_config.json` via `uvx`,
+  `docker run`, or `podman run`, or point at a local streamable-http container by `url`.
+- **Remote URL** — connect to a server deployed behind Caddy at
+  `http://gramps-mcp.arpa/mcp` using the `"url"` key.
+<!-- END GENERATED: additional-deployment-options -->
+
+## Install Python Package
+
+```bash
+python -m pip install gramps-mcp
+```
+
+## Documentation
+
+Full documentation is published to the GitHub Pages site and mirrored under `docs/`:
+
+- [Documentation site](https://knuckles-team.github.io/gramps-mcp/)
+- [Overview](docs/overview.md)
+- [Installation](docs/installation.md)
+- [Usage](docs/usage.md)
+- [Deployment](docs/deployment.md)
+- [Platform](docs/platform.md)
+- [Concept Registry](docs/concepts.md)

gramps_mcp-0.1.0/README.md

@@ -0,0 +1,242 @@
+# Gramps MCP
+## CLI or API | MCP | Agent
+
+![PyPI - Version](https://img.shields.io/pypi/v/gramps-mcp)
+![MCP Server](https://badge.mcpx.dev?type=server 'MCP Server')
+![PyPI - Downloads](https://img.shields.io/pypi/dd/gramps-mcp)
+![GitHub Repo stars](https://img.shields.io/github/stars/Knuckles-Team/gramps-mcp)
+![PyPI - License](https://img.shields.io/pypi/l/gramps-mcp)
+![GitHub last commit (by committer)](https://img.shields.io/github/last-commit/Knuckles-Team/gramps-mcp)
+
+*Version: 0.1.0*
+
+> **Documentation** — Installation, deployment, usage across the API, CLI, and MCP
+> interfaces, the integrated A2A agent server, and guidance for provisioning the
+> backing platform are maintained in the
+> [official documentation](https://knuckles-team.github.io/gramps-mcp/).
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Key Features](#key-features)
+- [Available MCP Tools](#available-mcp-tools)
+- [Installation](#installation)
+- [Usage](#usage)
+- [MCP](#mcp)
+- [Documentation](#documentation)
+
+---
+
+## Overview
+
+**Gramps MCP MCP Server + A2A Agent**
+
+Gramps API + MCP Server + A2A Agent — genealogy (people/families/events/places/sources/media)
+
+This repository is actively maintained - Contributions are welcome!
+
+## Key Features
+
+- **Action-routed MCP tools** — each domain is exposed as a single MCP tool that routes
+  to many underlying operations via an `action` argument, keeping the tool surface small.
+- **Three interfaces, one package** — use it as a Python **API client**, an **MCP server**
+  (`stdio` / `streamable-http` / `sse`), or a Pydantic-AI **A2A agent**.
+- **`agent-utilities` native** — built on the shared framework (auth, action router,
+  telemetry, governance) for fleet consistency.
+- **Per-tool toggles** — enable or disable each tool domain with environment switches.
+- **Enterprise-ready** — OTEL/Langfuse telemetry and optional Eunomia access governance.
+
+## Available MCP Tools
+
+Each tool is **action-routed**: pass an `action` and a JSON `params_json` payload. Tool
+domains can be toggled on or off with the listed environment variable. The table below is
+**auto-generated from the live server** by the `mcp-readme-table` pre-commit hook
+(`python -m agent_utilities.mcp.readme_tools`) — do not edit it by hand.
+
+<!-- MCP-TOOLS-TABLE:START -->
+
+| MCP Tool | Toggle Env Var | Description |
+|----------|----------------|-------------|
+| `gramps_bookmarks` | `BOOKMARKSTOOL` | Manage Gramps bookmarks operations. CONCEPT:GRMP-001. |
+| `gramps_chat` | `CHATTOOL` | Manage Gramps chat operations. CONCEPT:GRMP-001. |
+| `gramps_citations` | `CITATIONSTOOL` | Manage Gramps citations operations. CONCEPT:GRMP-001. |
+| `gramps_config` | `CONFIGTOOL` | Manage Gramps config operations. CONCEPT:GRMP-001. |
+| `gramps_dna` | `DNATOOL` | Manage Gramps dna operations. CONCEPT:GRMP-001. |
+| `gramps_events` | `EVENTSTOOL` | Manage Gramps events operations. CONCEPT:GRMP-001. |
+| `gramps_exporters` | `EXPORTERSTOOL` | Manage Gramps exporters operations. CONCEPT:GRMP-001. |
+| `gramps_facts` | `FACTSTOOL` | Manage Gramps facts operations. CONCEPT:GRMP-001. |
+| `gramps_families` | `FAMILIESTOOL` | Manage Gramps families operations. CONCEPT:GRMP-001. |
+| `gramps_filters` | `FILTERSTOOL` | Manage Gramps filters operations. CONCEPT:GRMP-001. |
+| `gramps_holidays` | `HOLIDAYSTOOL` | Manage Gramps holidays operations. CONCEPT:GRMP-001. |
+| `gramps_importers` | `IMPORTERSTOOL` | Manage Gramps importers operations. CONCEPT:GRMP-001. |
+| `gramps_living` | `LIVINGTOOL` | Manage Gramps living operations. CONCEPT:GRMP-001. |
+| `gramps_media` | `MEDIATOOL` | Manage Gramps media operations. CONCEPT:GRMP-001. |
+| `gramps_metadata` | `METADATATOOL` | Manage Gramps metadata operations. CONCEPT:GRMP-001. |
+| `gramps_name_formats` | `NAME_FORMATSTOOL` | Manage Gramps name formats operations. CONCEPT:GRMP-001. |
+| `gramps_name_groups` | `NAME_GROUPSTOOL` | Manage Gramps name groups operations. CONCEPT:GRMP-001. |
+| `gramps_notes` | `NOTESTOOL` | Manage Gramps notes operations. CONCEPT:GRMP-001. |
+| `gramps_oidc` | `OIDCTOOL` | Manage Gramps oidc operations. CONCEPT:GRMP-001. |
+| `gramps_people` | `PEOPLETOOL` | Manage Gramps people operations. CONCEPT:GRMP-001. |
+| `gramps_places` | `PLACESTOOL` | Manage Gramps places operations. CONCEPT:GRMP-001. |
+| `gramps_relations` | `RELATIONSTOOL` | Manage Gramps relations operations. CONCEPT:GRMP-001. |
+| `gramps_reports` | `REPORTSTOOL` | Manage Gramps reports operations. CONCEPT:GRMP-001. |
+| `gramps_repositories` | `REPOSITORIESTOOL` | Manage Gramps repositories operations. CONCEPT:GRMP-001. |
+| `gramps_search` | `SEARCHTOOL` | Manage Gramps search operations. CONCEPT:GRMP-001. |
+| `gramps_sources` | `SOURCESTOOL` | Manage Gramps sources operations. CONCEPT:GRMP-001. |
+| `gramps_tags` | `TAGSTOOL` | Manage Gramps tags operations. CONCEPT:GRMP-001. |
+| `gramps_tasks` | `TASKSTOOL` | Manage Gramps tasks operations. CONCEPT:GRMP-001. |
+| `gramps_timeline` | `TIMELINETOOL` | Manage Gramps timeline operations. CONCEPT:GRMP-001. |
+| `gramps_token` | `TOKENTOOL` | Manage Gramps token operations. CONCEPT:GRMP-001. |
+| `gramps_transactions` | `TRANSACTIONSTOOL` | Manage Gramps transactions operations. CONCEPT:GRMP-001. |
+| `gramps_translations` | `TRANSLATIONSTOOL` | Manage Gramps translations operations. CONCEPT:GRMP-001. |
+| `gramps_trees` | `TREESTOOL` | Manage Gramps trees operations. CONCEPT:GRMP-001. |
+| `gramps_types` | `TYPESTOOL` | Manage Gramps types operations. CONCEPT:GRMP-001. |
+| `gramps_users` | `USERSTOOL` | Manage Gramps users operations. CONCEPT:GRMP-001. |
+
+_35 action-routed tools (default `MCP_TOOL_MODE=condensed`). Each is enabled unless its toggle is set false; set `MCP_TOOL_MODE=verbose` (or `both`) for the 1:1 per-operation surface. Auto-generated — do not edit._
+<!-- MCP-TOOLS-TABLE:END -->
+
+## Installation
+
+### Install with `uvx` (no install — run on demand)
+
+```bash
+uvx --from gramps-mcp gramps-mcp      # MCP server
+uvx --from gramps-mcp gramps-agent    # A2A agent server
+```
+
+### Install with `pip`
+
+```bash
+python -m pip install gramps-mcp            # core (API client)
+python -m pip install "gramps-mcp[all]"     # + MCP server + A2A agent + telemetry
+```
+
+### Console scripts
+
+After installation the following entry points are available on your `PATH`:
+
+| Command | Description |
+|---------|-------------|
+| `gramps-mcp` | Launch the MCP server |
+| `gramps-agent` | Launch the A2A agent server |
+
+## Usage
+
+### As a Python API client
+
+```python
+from gramps_mcp.auth import get_client
+
+client = get_client()
+status = client.get_system_status()
+print(status)
+```
+
+### As an MCP server (CLI)
+
+```bash
+# Local stdio (for IDEs)
+gramps-mcp
+
+# Networked streamable-http
+gramps-mcp --transport streamable-http --host 0.0.0.0 --port 8000
+```
+
+### Calling an MCP tool
+
+Tools are action-routed — pass an `action` plus a JSON `params_json` string:
+
+```json
+{
+  "tool": "system_operations",
+  "arguments": {
+    "action": "status",
+    "params_json": "{}"
+  }
+}
+```
+
+## MCP
+
+### Using as an MCP Server
+
+The MCP Server can be run in `stdio` (local), `streamable-http` (networked), or
+`sse` mode.
+
+#### Environment Variables
+
+*   `GRAMPS_URL`: The URL of the target service.
+*   `GRAMPS_TOKEN`: The API token or access token.
+
+#### stdio Transport (local IDEs — Cursor, Claude Desktop, VS Code)
+
+```json
+{
+  "mcpServers": {
+    "gramps-mcp": {
+      "command": "uvx",
+      "args": ["--from", "gramps-mcp", "gramps-mcp"],
+      "env": {
+        "GRAMPS_URL": "https://service.example.com",
+        "GRAMPS_TOKEN": "your_token"
+      }
+    }
+  }
+}
+```
+
+#### Streamable-HTTP Transport (networked / production)
+
+```json
+{
+  "mcpServers": {
+    "gramps-mcp": {
+      "command": "uvx",
+      "args": ["--from", "gramps-mcp", "gramps-mcp", "--transport", "streamable-http", "--port", "8000"],
+      "env": {
+        "TRANSPORT": "streamable-http",
+        "HOST": "0.0.0.0",
+        "PORT": "8000",
+        "GRAMPS_URL": "https://service.example.com",
+        "GRAMPS_TOKEN": "your_token"
+      }
+    }
+  }
+}
+```
+
+<!-- BEGIN GENERATED: additional-deployment-options -->
+### Additional Deployment Options
+
+`gramps-mcp` can also run as a **local container** (Docker / Podman / `uv`) or be
+consumed from a **remote deployment**. The
+[Deployment guide](https://knuckles-team.github.io/gramps-mcp/deployment/) has full,
+copy-paste `mcp_config.json` for all four transports — **stdio**, **streamable-http**,
+**local container / uv**, and **remote URL**:
+
+- **Local container / uv** — launch the server from `mcp_config.json` via `uvx`,
+  `docker run`, or `podman run`, or point at a local streamable-http container by `url`.
+- **Remote URL** — connect to a server deployed behind Caddy at
+  `http://gramps-mcp.arpa/mcp` using the `"url"` key.
+<!-- END GENERATED: additional-deployment-options -->
+
+## Install Python Package
+
+```bash
+python -m pip install gramps-mcp
+```
+
+## Documentation
+
+Full documentation is published to the GitHub Pages site and mirrored under `docs/`:
+
+- [Documentation site](https://knuckles-team.github.io/gramps-mcp/)
+- [Overview](docs/overview.md)
+- [Installation](docs/installation.md)
+- [Usage](docs/usage.md)
+- [Deployment](docs/deployment.md)
+- [Platform](docs/platform.md)
+- [Concept Registry](docs/concepts.md)

gramps_mcp-0.1.0/gramps_mcp/__init__.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python
+
+import importlib
+import inspect
+import warnings
+
+warnings.filterwarnings("ignore", message=".*urllib3.*or chardet.*")
+
+__all__: list[str] = []
+
+CORE_MODULES = [
+    "gramps_mcp.api",
+]
+
+OPTIONAL_MODULES = {
+    "gramps_mcp.agent_server": "agent",
+    "gramps_mcp.mcp_server": "mcp",
+}
+
+
+def _import_module_safely(module_name: str):
+    """Try to import a module and return it, or None if not available."""
+    try:
+        return importlib.import_module(module_name)
+    except ImportError:
+        return None
+
+
+def _expose_members(module):
+    """Expose public classes and functions from a module into globals and __all__."""
+    for name, obj in inspect.getmembers(module):
+        if (inspect.isclass(obj) or inspect.isfunction(obj)) and not name.startswith(
+            "_"
+        ):
+            globals()[name] = obj
+            __all__.append(name)
+
+
+for module_name in CORE_MODULES:
+    try:
+        module = importlib.import_module(module_name)
+        _expose_members(module)
+    except ImportError:
+        pass
+
+for module_name, extra_name in OPTIONAL_MODULES.items():
+    module = _import_module_safely(module_name)
+    if module is not None:
+        _expose_members(module)
+        globals()[f"_{extra_name.upper()}_AVAILABLE"] = True
+    else:
+        globals()[f"_{extra_name.upper()}_AVAILABLE"] = False
+
+__all__.extend(["_MCP_AVAILABLE", "_AGENT_AVAILABLE"])

gramps_mcp-0.1.0/gramps_mcp/__main__.py

@@ -0,0 +1,5 @@
+#!/usr/bin/python
+from gramps_mcp.agent_server import agent_server
+
+if __name__ == "__main__":
+    agent_server()

gramps_mcp-0.1.0/gramps_mcp/agent_data/IDENTITY.md

@@ -0,0 +1,15 @@
+# IDENTITY.md - Gramps MCP Agent Identity
+
+## [default]
+ * **Name:** Gramps MCP Agent
+ * **Role:** Gramps API + MCP Server + A2A Agent — genealogy (people/families/events/places/sources/media)
+ * **Emoji:** 🤖
+
+ ### System Prompt
+ You are the Gramps MCP Agent.
+ Use the `mcp-client` universal skill and check the reference documentation for
+ `gramps-mcp.md` to discover the exact tags and tools available for your capabilities.
+
+ ### Capabilities
+ - **MCP Operations**: Leverage the `mcp-client` skill to interact with the target MCP server.
+ - **Custom Agent**: Handle custom tasks or general tasks.

gramps_mcp-0.1.0/gramps_mcp/agent_server.py

@@ -0,0 +1,76 @@
+#!/usr/bin/python
+import logging
+import os
+import sys
+import warnings
+
+__version__ = "0.1.0"
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    handlers=[logging.StreamHandler()],
+)
+logger = logging.getLogger(__name__)
+
+
+def agent_server():
+    from agent_utilities import (
+        build_system_prompt_from_workspace,
+        create_agent_parser,
+        create_agent_server,
+        initialize_workspace,
+        load_identity,
+    )
+
+    warnings.filterwarnings("ignore", message=".*urllib3.*or chardet.*")
+    warnings.filterwarnings("ignore", category=DeprecationWarning, module="fastmcp")
+
+    initialize_workspace()
+    meta = load_identity()
+    agent_name = os.getenv("DEFAULT_AGENT_NAME", meta.get("name", "Gramps MCP"))
+
+    print(f"{agent_name} v{__version__}", file=sys.stderr)
+    parser = create_agent_parser()
+    args = parser.parse_args()
+
+    if args.debug:
+        logging.getLogger().setLevel(logging.DEBUG)
+        logger.debug("Debug mode enabled")
+
+    create_agent_server(
+        mcp_url=args.mcp_url,
+        mcp_config=args.mcp_config or "mcp_config.json",
+        host=args.host,
+        port=args.port,
+        provider=args.provider,
+        model_id=args.model_id,
+        router_model=args.model_id,
+        agent_model=args.model_id,
+        base_url=args.base_url,
+        api_key=args.api_key,
+        agent_description=os.getenv(
+            "AGENT_DESCRIPTION",
+            meta.get(
+                "description",
+                "Gramps API + MCP Server + A2A Agent — genealogy (people/families/events/places/sources/media)",
+            ),
+        ),
+        system_prompt=os.getenv(
+            "AGENT_SYSTEM_PROMPT",
+            meta.get("content") or build_system_prompt_from_workspace(),
+        ),
+        custom_skills_directory=args.custom_skills_directory,
+        enable_web_ui=args.web,
+        enable_otel=args.otel,
+        otel_endpoint=args.otel_endpoint,
+        otel_headers=args.otel_headers,
+        otel_public_key=args.otel_public_key,
+        otel_secret_key=args.otel_secret_key,
+        otel_protocol=args.otel_protocol,
+        debug=args.debug,
+    )
+
+
+if __name__ == "__main__":
+    agent_server()