Skip to content

Commit 2ba80b8

Browse files
tmelliottjrtmelliottjr
committed
move query rules
1 parent e6f77c0 commit 2ba80b8

File tree

4 files changed

+54
-95
lines changed

4 files changed

+54
-95
lines changed

‎README.md‎

Lines changed: 10 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -830,70 +830,29 @@ Options are:
830830
- `project_number`: The project's number. (number, required)
831831

832832
- **list_project_fields** - List project fields
833-
- `after`: Forward pagination cursor. Use when the previous response's pageInfo.hasNextPage=true. Supply pageInfo.nextCursor as 'after' and immediately request the next page. LOOP UNTIL pageInfo.hasNextPage=false (don't stop early). Keep per_page identical for every page. (string, optional)
834-
- `before`: Backward pagination cursor (rare): supply to move to the preceding page using pageInfo.prevCursor. Not needed for normal forward iteration. (string, optional)
833+
- `after`: Forward pagination cursor from previous pageInfo.nextCursor. (string, optional)
834+
- `before`: Backward pagination cursor from previous pageInfo.prevCursor (rare). (string, optional)
835835
- `owner`: If owner_type == user it is the handle for the GitHub user account. If owner_type == org it is the name of the organization. The name is not case sensitive. (string, required)
836836
- `owner_type`: Owner type (string, required)
837-
- `per_page`: Results per page (max 50). Keep constant across paginated requests; changing mid-sequence can complicate page traversal. (number, optional)
837+
- `per_page`: Results per page (max 50) (number, optional)
838838
- `project_number`: The project's number. (number, required)
839839

840840
- **list_project_items** - List project items
841-
- `after`: Forward pagination cursor. Use when the previous response's pageInfo.hasNextPage=true. Supply pageInfo.nextCursor as 'after' and immediately request the next page. LOOP UNTIL pageInfo.hasNextPage=false (don't stop early). Keep query, fields, and per_page identical for every page. (string, optional)
842-
- `before`: Backward pagination cursor (rare): supply to move to the preceding page using pageInfo.prevCursor. Not needed for normal forward iteration. (string, optional)
841+
- `after`: Forward pagination cursor from previous pageInfo.nextCursor. (string, optional)
842+
- `before`: Backward pagination cursor from previous pageInfo.prevCursor (rare). (string, optional)
843843
- `fields`: Field IDs to include (e.g. ["102589", "985201"]). CRITICAL: Always provide to get field values. Without this, only titles returned. Get IDs from list_project_fields first. (string[], optional)
844844
- `owner`: If owner_type == user it is the handle for the GitHub user account. If owner_type == org it is the name of the organization. The name is not case sensitive. (string, required)
845845
- `owner_type`: Owner type (string, required)
846-
- `per_page`: Results per page (max 50). Keep constant across paginated requests; changing mid-sequence can complicate page traversal. (number, optional)
846+
- `per_page`: Results per page (max 50) (number, optional)
847847
- `project_number`: The project's number. (number, required)
848-
- `query`: Query string - For advanced filtering of project items using GitHub's search syntax:
849-
850-
MUST reflect user intent; strongly prefer explicit content type if narrowed:
851-
- "open issues" → state:open is:issue
852-
- "merged PRs" → state:merged is:pr
853-
- "items updated this week" → updated:>@today-7d (omit type only if mixed desired)
854-
- "list all P1 priority items" → priority:p1 (omit state if user wants all, omit type if user specifies "items")
855-
- "list all open P2 issues" → is:issue state:open priority:p2 (include state if user wants open or closed, include type if user specifies "issues" or "PRs")
856-
- "all open issues I'm working on" → is:issue state:open assignee:@me
857-
858-
Query Construction Heuristics:
859-
a. Extract type nouns: issues → is:issue | PRs, Pulls, or Pull Requests → is:pr | tasks/tickets → is:issue (ask if ambiguity)
860-
b. Map temporal phrases: "this week" → updated:>@today-7d
861-
c. Map negations: "excluding wontfix" → -label:wontfix
862-
d. Map priority adjectives: "high/sev1/p1" → priority:high OR priority:p1 (choose based on field presence)
863-
e. When filtering by label, always use wildcard matching to account for cross-repository differences or emojis: (e.g. "bug 🐛" → label:*bug*)
864-
f. When filtering by milestone, always use wildcard matching to account for cross-repository differences: (e.g. "v1.0" → milestone:*v1.0*)
865-
866-
Syntax Essentials (items):
867-
AND: space-separated. (label:bug priority:high).
868-
OR: comma inside one qualifier (label:bug,critical).
869-
NOT: leading '-' (-label:wontfix).
870-
Hyphenate multi-word field names. (team-name:"Backend Team", story-points:>5).
871-
Quote multi-word values. (status:"In Review" team-name:"Backend Team").
872-
Ranges: points:1..3, updated:<@today-30d.
873-
Wildcards: title:*crash*, label:bug*.
874-
Assigned to User: assignee:@me | assignee:username | no:assignee
875-
876-
Common Qualifier Glossary (items):
877-
is:issue | is:pr | state:open|closed|merged | assignee:@me|username | label:NAME | status:VALUE |
878-
priority:p1|high | sprint-name:@current | team-name:"Backend Team" | parent-issue:"org/repo#123" |
879-
updated:>@today-7d | title:*text* | -label:wontfix | label:bug,critical | no:assignee | has:label
880-
881-
Pagination Mandate:
882-
Do not analyze until ALL pages fetched (loop while pageInfo.hasNextPage=true). Always reuse identical query, fields, per_page.
883-
884-
Recovery Guidance:
885-
If user provides ambiguous request ("show project activity") → ask clarification OR return mixed set (omit is:issue/is:pr). If user mixes project + item qualifiers in one phrase → split: run list_projects for discovery, then list_project_items for detail.
886-
887-
Never:
888-
- Infer field IDs; fetch via list_project_fields.
889-
- Drop 'fields' param on subsequent pages if field values are needed. (string, optional)
848+
- `query`: Query string for advanced filtering of project items. See Projects server instructions (list_project_items query rules) for full construction heuristics, syntax essentials, qualifier glossary, pagination mandate, recovery guidance, and prohibited behaviors. (string, optional)
890849

891850
- **list_projects** - List projects
892-
- `after`: Forward pagination cursor. Use when the previous response's pageInfo.hasNextPage=true. Supply pageInfo.nextCursor as 'after' and immediately request the next page. LOOP UNTIL pageInfo.hasNextPage=false (don't stop early). Keep query and per_page identical for every page. (string, optional)
893-
- `before`: Backward pagination cursor (rare): supply to move to the preceding page using pageInfo.prevCursor. Not needed for normal forward iteration. (string, optional)
851+
- `after`: Forward pagination cursor from previous pageInfo.nextCursor. (string, optional)
852+
- `before`: Backward pagination cursor from previous pageInfo.prevCursor (rare). (string, optional)
894853
- `owner`: If owner_type == user it is the handle for the GitHub user account. If owner_type == org it is the name of the organization. The name is not case sensitive. (string, required)
895854
- `owner_type`: Owner type (string, required)
896-
- `per_page`: Results per page (max 50). Keep constant across paginated requests; changing mid-sequence can complicate page traversal. (number, optional)
855+
- `per_page`: Results per page (max 50) (number, optional)
897856
- `query`: Filter projects by a search query
898857

899858
Scope: title text + open/closed state.

‎pkg/github/__toolsnaps__/list_project_items.snap‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@
4242
"type": "number"
4343
},
4444
"query": {
45-
"description": "Query string - For advanced filtering of project items using GitHub's search syntax:\n\nMUST reflect user intent; strongly prefer explicit content type if narrowed:\n\t- \"open issues\" → state:open is:issue\n\t- \"merged PRs\" → state:merged is:pr\n\t- \"items updated this week\" → updated:\u003e@today-7d (omit type only if mixed desired)\n\t- \"list all P1 priority items\" → priority:p1 (omit state if user wants all, omit type if user specifies \"items\")\n\t- \"list all open P2 issues\" → is:issue state:open priority:p2 (include state if user wants open or closed, include type if user specifies \"issues\" or \"PRs\")\n\t- \"all open issues I'm working on\" → is:issue state:open assignee:@me\n\nQuery Construction Heuristics:\n\ta. Extract type nouns: issues → is:issue | PRs, Pulls, or Pull Requests → is:pr | tasks/tickets → is:issue (ask if ambiguity)\n\tb. Map temporal phrases: \"this week\" → updated:\u003e@today-7d\n\tc. Map negations: \"excluding wontfix\" → -label:wontfix\n\td. Map priority adjectives: \"high/sev1/p1\" → priority:high OR priority:p1 (choose based on field presence)\n\te. When filtering by label, always use wildcard matching to account for cross-repository differences or emojis: (e.g. \"bug 🐛\" → label:*bug*)\n\tf. When filtering by milestone, always use wildcard matching to account for cross-repository differences: (e.g. \"v1.0\" → milestone:*v1.0*)\n\nSyntax Essentials (items):\n AND: space-separated. (label:bug priority:high).\n OR: comma inside one qualifier (label:bug,critical).\n NOT: leading '-' (-label:wontfix).\n Hyphenate multi-word field names. (team-name:\"Backend Team\", story-points:\u003e5).\n Quote multi-word values. (status:\"In Review\" team-name:\"Backend Team\").\n Ranges: points:1..3, updated:\u003c@today-30d.\n Wildcards: title:*crash*, label:bug*.\n\t Assigned to User: assignee:@me | assignee:username | no:assignee\n\nCommon Qualifier Glossary (items):\n is:issue | is:pr | state:open|closed|merged | assignee:@me|username | label:NAME | status:VALUE |\n priority:p1|high | sprint-name:@current | team-name:\"Backend Team\" | parent-issue:\"org/repo#123\" |\n updated:\u003e@today-7d | title:*text* | -label:wontfix | label:bug,critical | no:assignee | has:label\n\nPagination Mandate:\n Do not analyze until ALL pages fetched (loop while pageInfo.hasNextPage=true). Always reuse identical query, fields, per_page.\n\nRecovery Guidance:\n If user provides ambiguous request (\"show project activity\") → ask clarification OR return mixed set (omit is:issue/is:pr). If user mixes project + item qualifiers in one phrase → split: run list_projects for discovery, then list_project_items for detail.\n\nNever:\n - Infer field IDs; fetch via list_project_fields.\n - Drop 'fields' param on subsequent pages if field values are needed.",
45+
"description": "Query string for advanced filtering of project items. See Projects server instructions (list_project_items query rules) for full construction heuristics, syntax essentials, qualifier glossary, pagination mandate, recovery guidance, and prohibited behaviors.",
4646
"type": "string"
4747
}
4848
},

‎pkg/github/instructions.go‎

Lines changed: 42 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -118,7 +118,48 @@ Self-check before returning:
118118
- Field names valid
119119
- Summary only if requested.
120120
121-
Return COMPLETE data or state what's missing (e.g. pages skipped).`
121+
Return COMPLETE data or state what's missing (e.g. pages skipped).
122+
123+
list_project_items query rules:
124+
Query string - For advanced filtering of project items using GitHub's search syntax:
125+
126+
MUST reflect user intent; strongly prefer explicit content type if narrowed:
127+
- "open issues" → state:open is:issue
128+
- "merged PRs" → state:merged is:pr
129+
- "items updated this week" → updated:>@today-7d (omit type only if mixed desired)
130+
- "list all P1 priority items" → priority:p1 (omit state if user wants all, omit type if user specifies "items")
131+
- "list all open P2 issues" → is:issue state:open priority:p2 (include state if user wants open or closed, include type if user specifies "issues" or "PRs")
132+
- "all open issues I'm working on" → is:issue state:open assignee:@me
133+
134+
Query Construction Heuristics:
135+
a. Extract type nouns: issues → is:issue | PRs, Pulls, or Pull Requests → is:pr | tasks/tickets → is:issue (ask if ambiguity)
136+
b. Map temporal phrases: "this week" → updated:>@today-7d
137+
c. Map negations: "excluding wontfix" → -label:wontfix
138+
d. Map priority adjectives: "high/sev1/p1" → priority:high OR priority:p1 (choose based on field presence)
139+
e. When filtering by label, always use wildcard matching to account for cross-repository differences or emojis: (e.g. "bug 🐛" → label:*bug*)
140+
f. When filtering by milestone, always use wildcard matching to account for cross-repository differences: (e.g. "v1.0" → milestone:*v1.0*)
141+
142+
Syntax Essentials (items):
143+
AND: space-separated. (label:bug priority:high).
144+
OR: comma inside one qualifier (label:bug,critical).
145+
NOT: leading '-' (-label:wontfix).
146+
Hyphenate multi-word field names. (team-name:"Backend Team", story-points:>5).
147+
Quote multi-word values. (status:"In Review" team-name:"Backend Team").
148+
Ranges: points:1..3, updated:<@today-30d.
149+
Wildcards: title:*crash*, label:bug*.
150+
Assigned to User: assignee:@me | assignee:username | no:assignee
151+
152+
Common Qualifier Glossary (items):
153+
is:issue | is:pr | state:open|closed|merged | assignee:@me|username | label:NAME | status:VALUE |
154+
priority:p1|high | sprint-name:@current | team-name:"Backend Team" | parent-issue:"org/repo#123" |
155+
updated:>@today-7d | title:*text* | -label:wontfix | label:bug,critical | no:assignee | has:label
156+
157+
Pagination Mandate:
158+
Do not analyze until ALL pages fetched (loop while pageInfo.hasNextPage=true). Always reuse identical query, fields, per_page.
159+
160+
Never:
161+
- Infer field IDs; fetch via list_project_fields.
162+
- Drop 'fields' param on subsequent pages if field values are needed.`
122163
default:
123164
return ""
124165
}

‎pkg/github/projects.go‎

Lines changed: 1 addition & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -408,48 +408,7 @@ func ListProjectItems(getClient GetClientFn, t translations.TranslationHelperFun
408408
mcp.Description("The project's number."),
409409
),
410410
mcp.WithString("query",
411-
mcp.Description(`Query string - For advanced filtering of project items using GitHub's search syntax:
412-
413-
MUST reflect user intent; strongly prefer explicit content type if narrowed:
414-
- "open issues" → state:open is:issue
415-
- "merged PRs" → state:merged is:pr
416-
- "items updated this week" → updated:>@today-7d (omit type only if mixed desired)
417-
- "list all P1 priority items" → priority:p1 (omit state if user wants all, omit type if user specifies "items")
418-
- "list all open P2 issues" → is:issue state:open priority:p2 (include state if user wants open or closed, include type if user specifies "issues" or "PRs")
419-
- "all open issues I'm working on" → is:issue state:open assignee:@me
420-
421-
Query Construction Heuristics:
422-
a. Extract type nouns: issues → is:issue | PRs, Pulls, or Pull Requests → is:pr | tasks/tickets → is:issue (ask if ambiguity)
423-
b. Map temporal phrases: "this week" → updated:>@today-7d
424-
c. Map negations: "excluding wontfix" → -label:wontfix
425-
d. Map priority adjectives: "high/sev1/p1" → priority:high OR priority:p1 (choose based on field presence)
426-
e. When filtering by label, always use wildcard matching to account for cross-repository differences or emojis: (e.g. "bug 🐛" → label:*bug*)
427-
f. When filtering by milestone, always use wildcard matching to account for cross-repository differences: (e.g. "v1.0" → milestone:*v1.0*)
428-
429-
Syntax Essentials (items):
430-
AND: space-separated. (label:bug priority:high).
431-
OR: comma inside one qualifier (label:bug,critical).
432-
NOT: leading '-' (-label:wontfix).
433-
Hyphenate multi-word field names. (team-name:"Backend Team", story-points:>5).
434-
Quote multi-word values. (status:"In Review" team-name:"Backend Team").
435-
Ranges: points:1..3, updated:<@today-30d.
436-
Wildcards: title:*crash*, label:bug*.
437-
Assigned to User: assignee:@me | assignee:username | no:assignee
438-
439-
Common Qualifier Glossary (items):
440-
is:issue | is:pr | state:open|closed|merged | assignee:@me|username | label:NAME | status:VALUE |
441-
priority:p1|high | sprint-name:@current | team-name:"Backend Team" | parent-issue:"org/repo#123" |
442-
updated:>@today-7d | title:*text* | -label:wontfix | label:bug,critical | no:assignee | has:label
443-
444-
Pagination Mandate:
445-
Do not analyze until ALL pages fetched (loop while pageInfo.hasNextPage=true). Always reuse identical query, fields, per_page.
446-
447-
Recovery Guidance:
448-
If user provides ambiguous request ("show project activity") → ask clarification OR return mixed set (omit is:issue/is:pr). If user mixes project + item qualifiers in one phrase → split: run list_projects for discovery, then list_project_items for detail.
449-
450-
Never:
451-
- Infer field IDs; fetch via list_project_fields.
452-
- Drop 'fields' param on subsequent pages if field values are needed.`),
411+
mcp.Description(`Query string for advanced filtering of project items. See Projects server instructions (list_project_items query rules) for full construction heuristics, syntax essentials, qualifier glossary, pagination mandate, recovery guidance, and prohibited behaviors.`),
453412
),
454413
mcp.WithNumber("per_page",
455414
mcp.Description(fmt.Sprintf("Results per page (max %d)", MaxProjectsPerPage)),

0 commit comments

Comments
 (0)