Skip to main content
Glama
Sign In
Scormave

Gramps Web MCP

by Scormave
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Hybrid

List Objects

list_objects
Read-only

Browse Gramps Web records by type one page at a time, filter by fields or relationship rules, and sort results to retrieve Gramps IDs, summaries, handles, and total counts.

Instructions

List the records of one type a page at a time, optionally filtered and sorted: one line per record (Gramps ID, summary, handle) with the page and total count. Use it to browse a type, fetch one Gramps ID, list a source's citations (sourceHandle), filter by field values (gql) or select by relationships with Gramps filter rules (rules), such as a person's ancestors or people with no family links. To find records by text use search; to read one record in full use get_object. rules run first and gql must then also match; grampsId cannot be combined with rules. Filtering runs on the Gramps Web server: invalid gql returns its error, invalid rules are explained, and an ID, tag or saved filter the tree lacks matches nothing instead of failing.

Input Schema

NameRequiredDescriptionDefault
gqlNoFilter in Gramps Query Language, run on the server: field = value with a single = (not ==), also !=, <, <=, >, >=, ~ (contains), !~, and, or and parentheses; text goes in double quotes. Types are numbers, not names, e.g. event type.value = 12 Birth, 13 Death, 1 Marriage, 15 Baptism, 19 Burial. Examples: gender = 1 (male), primary_name.first_name = "Anna", media_list.length >= 1 (optional).
pageNoPage number, from 1 (default 1).
sortNoField to sort by, e.g. gramps_id; a leading - sorts descending, e.g. -change for latest edits first (optional).
rulesNoGramps filter rules, run on the server before gql (a record must match both): {"function": "and" (default), "or" or "one", "invert": true to keep the records that do not match, "rules": [{"name": rule, "values": [one per label of the rule, in order]}]}, or just the array of rules. Values are Gramps IDs (I0001), text, numbers or true/false. An item of rules can be a nested filter of the same form; with "namespace" (Event, Family, Person, Place, Source or Repository) it matches the records each listed one links to, e.g. people by their events. Examples: people with no family links {"rules": [{"name": "Disconnected"}]}; people not related to I0001 {"invert": true, "rules": [{"name": "IsRelatedWith", "values": ["I0001"]}]}; a saved filter {"name": "MatchesFilter", "values": ["its name"]}. Rules of each type and their values: get_reference(topic: "filter-rules", section: type). Not for tags (optional).
grampsIdNoOnly the record with this Gramps ID, e.g. I0001 (not a handle; optional).
pagesizeNoRecords per page, 1–100 (default 20).
objectTypeYesWhich records to list: people, families, events, places, sources, citations, repositories, notes, media or tags.
sourceHandleNoWith objectType citations only: list just the citations of this source; combined with gql by and (optional). Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv2.8.0
    • changedInput schema / properties / gql / description
      Previous value: -"Filter in Gramps Query Language, run on the server, e.g. gender == 1 or media_list.length >= 1 (optional)."New value: +"Filter in Gramps Query Language, run on the server: field = value with a single = (not ==), also !=, <, <=, >, >=, ~ (contains), !~, and, or and parentheses; text goes in double quotes. Types are numbers, not names, e.g. event type.value = 12 Birth, 13 Death, 1 Marriage, 15 Baptism, 19 Burial. Examples: gender = 1 (male), primary_name.first_name = \"Anna\", media_list.length >= 1 (optional)."
  2. Changed1 schema field changedv2.6.0
    • addedInput schema / properties / rules
      Added value: +{
+  "default": null,
+  "description": "Gramps filter rules, run on the server before gql (a record must match both): {\"function\": \"and\" (default), \"or\" or \"one\", \"invert\": true to keep the records that do not match, \"rules\": [{\"name\": rule, \"values\": [one per label of the rule, in order]}]}, or just the array of rules. Values are Gramps IDs (I0001), text, numbers or true/false. An item of rules can be a nested filter of the same form; with \"namespace\" (Event, Family, Person, Place, Source or Repository) it matches the records each listed one links to, e.g. people by their events. Examples: people with no family links {\"rules\": [{\"name\": \"Disconnected\"}]}; people not related to I0001 {\"invert\": true, \"rules\": [{\"name\": \"IsRelatedWith\", \"values\": [\"I0001\"]}]}; a saved filter {\"name\": \"MatchesFilter\", \"values\": [\"its name\"]}. Rules of each type and their values: get_reference(topic: \"filter-rules\", section: type). Not for tags (optional)."
+}
  3. Changed7 schema fields changedv2.3.0
    • changedInput schema / properties / gql / description
      Previous value: -"Optional. Gramps QL expression executed server-side for filtering."New value: +"Filter in Gramps Query Language, run on the server, e.g. gender == 1 or media_list.length >= 1 (optional)."
    • changedInput schema / properties / grampsId / description
      Previous value: -"Optional. Filter by numeric/string Gramps ID (I0001-style), NOT the opaque handle."New value: +"Only the record with this Gramps ID, e.g. I0001 (not a handle; optional)."
    • changedInput schema / properties / objectType / description
      Previous value: -"Object collection: people | families | events | places | sources | citations | repositories | notes | media | tags (exact spelling, case-insensitive)."New value: +"Which records to list: people, families, events, places, sources, citations, repositories, notes, media or tags."
    • changedInput schema / properties / page / description
      Previous value: -"1-based page. Default 1."New value: +"Page number, from 1 (default 1)."
    • changedInput schema / properties / pagesize / description
      Previous value: -"Page size. Default 20, max 100."New value: +"Records per page, 1–100 (default 20)."
    • changedInput schema / properties / sort / description
      Previous value: -"Optional. Sort field; leading - means descending."New value: +"Field to sort by, e.g. gramps_id; a leading - sorts descending, e.g. -change for latest edits first (optional)."
    • changedInput schema / properties / sourceHandle / description
      Previous value: -"Optional. When objectType is citations, limit to citations of this source handle. Handle or Gramps ID (e.g. I0001). Handles are opaque strings from the API. Gramps IDs (like I0001, F0023) are auto-resolved to handles. Find handles with search() or list_objects()."New value: +"With objectType citations only: list just the citations of this source; combined with gql by and (optional). Handle or Gramps ID (e.g. I0001), resolved automatically; find it with search or list_objects."
  4. First observedv2.2.0

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds substantial behavioral context beyond annotations: server-side filtering behavior, that invalid gql returns its error, invalid rules are explained, and missing IDs/tags/saved filters match nothing rather than failing, plus the interaction order 'rules run first and gql must then also match.'

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core action and output format, then proceeds to use cases, alternatives, and caveats. It is dense but every sentence carries actionable information for an 8-parameter tool; minor length is justified by the behavioral constraints it discloses.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description supplies the return format ('one line per record ... with the page and total count'). It covers filtering mechanics, error handling, parameter interactions, and use-case routing, leaving no critical gaps for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents each parameter thoroughly, giving a baseline of 3. The description adds value by explaining cross-parameter interactions not present in the schema, such as 'rules run first and gql must then also match' and 'grampsId cannot be combined with rules.'

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'List the records of one type a page at a time, optionally filtered and sorted,' and immediately gives the output shape (Gramps ID, summary, handle, page, total count). It distinguishes itself from siblings by naming search for text lookup and get_object for full-record reads.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It enumerates concrete use cases (browse a type, fetch one Gramps ID, list a source's citations, filter with gql, select by relationships with rules) and explicitly routes agents to alternatives: 'To find records by text use search; to read one record in full use get_object.' It also states a key exclusion: 'grampsId cannot be combined with rules.'

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools