Merge branch 'main' into add-remote-mcp-to-registry

Author: almaleksia

.github/workflows/docker-publish.yml

@@ -70,7 +70,7 @@ jobs:
       # https://github.com/docker/metadata-action
       - name: Extract Docker metadata
         id: meta
-        uses: docker/metadata-action@c1e51972afc2121e065aed6d45c65596fe445f3f # v5.8.0
+        uses: docker/metadata-action@318604b99e75e41977312d83839a89be02ca4893 # v5.9.0
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           tags: |

README.md

@@ -844,24 +844,30 @@ Options are:
   - `project_number`: The project's number. (number, required)
 
 - **list_project_fields** - List project fields
+  - `after`: Forward pagination cursor from previous pageInfo.nextCursor. (string, optional)
+  - `before`: Backward pagination cursor from previous pageInfo.prevCursor (rare). (string, optional)
   - `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)
   - `owner_type`: Owner type (string, required)
-  - `per_page`: Number of results per page (max 100, default: 30) (number, optional)
+  - `per_page`: Results per page (max 50) (number, optional)
   - `project_number`: The project's number. (number, required)
 
 - **list_project_items** - List project items
-  - `fields`: Specific list of field IDs to include in the response (e.g. ["102589", "985201", "169875"]). If not provided, only the title field is included. (string[], optional)
+  - `after`: Forward pagination cursor from previous pageInfo.nextCursor. (string, optional)
+  - `before`: Backward pagination cursor from previous pageInfo.prevCursor (rare). (string, optional)
+  - `fields`: Field IDs to include (e.g. ["102589", "985201"]). CRITICAL: Always provide to get field values. Without this, only titles returned. (string[], optional)
   - `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)
   - `owner_type`: Owner type (string, required)
-  - `per_page`: Number of results per page (max 100, default: 30) (number, optional)
+  - `per_page`: Results per page (max 50) (number, optional)
   - `project_number`: The project's number. (number, required)
-  - `query`: Search query to filter items (string, optional)
+  - `query`: Query string for advanced filtering of project items using GitHub's project filtering syntax. (string, optional)
 
 - **list_projects** - List projects
+  - `after`: Forward pagination cursor from previous pageInfo.nextCursor. (string, optional)
+  - `before`: Backward pagination cursor from previous pageInfo.prevCursor (rare). (string, optional)
   - `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)
   - `owner_type`: Owner type (string, required)
-  - `per_page`: Number of results per page (max 100, default: 30) (number, optional)
-  - `query`: Filter projects by a search query (matches title and description) (string, optional)
+  - `per_page`: Results per page (max 50) (number, optional)
+  - `query`: Filter projects by title text and open/closed state; permitted qualifiers: is:open, is:closed; examples: "roadmap is:open", "is:open feature planning". (string, optional)
 
 - **update_project_item** - Update project item
   - `item_id`: The unique identifier of the project item. This is not the issue or pull request ID. (number, required)
@@ -1218,7 +1224,7 @@ Possible options:
 
 ## Dynamic Tool Discovery
 
-**Note**: This feature is currently in beta and may not be available in all environments. Please test it out and let us know if you encounter any issues.
+**Note**: This feature is currently in beta and is not available in the Remote GitHub MCP Server. Please test it out and let us know if you encounter any issues.
 
 Instead of starting with all tools enabled, you can turn on dynamic toolset discovery. Dynamic toolsets allow the MCP host to list and enable toolsets in response to a user prompt. This should help to avoid situations where the model gets confused by the sheer number of tools available.
 

docs/remote-server.md

@@ -57,7 +57,7 @@ The Remote GitHub MCP server has optional headers equivalent to the Local server
 
 - `X-MCP-Toolsets`: Comma-separated list of toolsets to enable. E.g. "repos,issues".
     - Equivalent to `GITHUB_TOOLSETS` env var for Local server.
-    - If the list is empty, default toolsets will be used. If a bad toolset is provided, the server will fail to start and emit a 400 bad request status. Whitespace is ignored.
+    - If the list is empty, default toolsets will be used. Invalid or unknown toolsets are silently ignored without error and will not prevent the server from starting. Whitespace is ignored.
 - `X-MCP-Readonly`: Enables only "read" tools.
     - Equivalent to `GITHUB_READ_ONLY` env var for Local server.
     - If this header is empty, "false", "f", "no", "n", "0", or "off" (ignoring whitespace and case), it will be interpreted as false. All other values are interpreted as true.

pkg/github/__toolsnaps__/list_project_fields.snap

@@ -6,6 +6,14 @@
   "description": "List Project fields for a user or org",
   "inputSchema": {
     "properties": {
+      "after": {
+        "description": "Forward pagination cursor from previous pageInfo.nextCursor.",
+        "type": "string"
+      },
+      "before": {
+        "description": "Backward pagination cursor from previous pageInfo.prevCursor (rare).",
+        "type": "string"
+      },
       "owner": {
         "description": "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.",
         "type": "string"
@@ -19,7 +27,7 @@
         "type": "string"
       },
       "per_page": {
-        "description": "Number of results per page (max 100, default: 30)",
+        "description": "Results per page (max 50)",
         "type": "number"
       },
       "project_number": {

pkg/github/__toolsnaps__/list_project_items.snap

@@ -3,11 +3,19 @@
     "title": "List project items",
     "readOnlyHint": true
   },
-  "description": "List Project items for a user or org",
+  "description": "Search project items with advanced filtering",
   "inputSchema": {
     "properties": {
+      "after": {
+        "description": "Forward pagination cursor from previous pageInfo.nextCursor.",
+        "type": "string"
+      },
+      "before": {
+        "description": "Backward pagination cursor from previous pageInfo.prevCursor (rare).",
+        "type": "string"
+      },
       "fields": {
-        "description": "Specific list of field IDs to include in the response (e.g. [\"102589\", \"985201\", \"169875\"]). If not provided, only the title field is included.",
+        "description": "Field IDs to include (e.g. [\"102589\", \"985201\"]). CRITICAL: Always provide to get field values. Without this, only titles returned.",
         "items": {
           "type": "string"
         },
@@ -26,15 +34,15 @@
         "type": "string"
       },
       "per_page": {
-        "description": "Number of results per page (max 100, default: 30)",
+        "description": "Results per page (max 50)",
         "type": "number"
       },
       "project_number": {
         "description": "The project's number.",
         "type": "number"
       },
       "query": {
-        "description": "Search query to filter items",
+        "description": "Query string for advanced filtering of project items using GitHub's project filtering syntax.",
         "type": "string"
       }
     },

pkg/github/__toolsnaps__/list_projects.snap

@@ -3,9 +3,17 @@
     "title": "List projects",
     "readOnlyHint": true
   },
-  "description": "List Projects for a user or org",
+  "description": "List Projects for a user or organization",
   "inputSchema": {
     "properties": {
+      "after": {
+        "description": "Forward pagination cursor from previous pageInfo.nextCursor.",
+        "type": "string"
+      },
+      "before": {
+        "description": "Backward pagination cursor from previous pageInfo.prevCursor (rare).",
+        "type": "string"
+      },
       "owner": {
         "description": "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.",
         "type": "string"
@@ -19,11 +27,11 @@
         "type": "string"
       },
       "per_page": {
-        "description": "Number of results per page (max 100, default: 30)",
+        "description": "Results per page (max 50)",
         "type": "number"
       },
       "query": {
-        "description": "Filter projects by a search query (matches title and description)",
+        "description": "Filter projects by title text and open/closed state; permitted qualifiers: is:open, is:closed; examples: \"roadmap is:open\", \"is:open feature planning\".",
         "type": "string"
       }
     },

pkg/github/instructions.go

@@ -62,6 +62,75 @@ Check 'list_issue_types' first for organizations to use proper issue types. Use
 		return `## Discussions
 		
 Use 'list_discussion_categories' to understand available categories before creating discussions. Filter by category for better organization.`
+	case "projects":
+		return `## Projects
+
+Workflow: 1) list_project_fields (get field IDs), 2) list_project_items (with pagination), 3) optional updates.
+
+Field usage:
+	- Call list_project_fields first to understand available fields and get IDs/types before filtering.
+	- Use EXACT returned field names (case-insensitive match). Don't invent names or IDs.
+	- Iteration synonyms (sprint/cycle) only if that field exists; map to the actual name (e.g. sprint:@current).
+	- Only include filters for fields that exist and are relevant.
+
+Pagination (mandatory):
+	- Loop while pageInfo.hasNextPage=true using after=pageInfo.nextCursor.
+	- Keep query, fields, per_page IDENTICAL on every page.
+	- Use before=pageInfo.prevCursor only when explicitly navigating to a previous page.
+
+Counting rules:
+	- Count items array length after full pagination.
+	- Never count field objects, content, or nested arrays as separate items.
+
+Summary vs list:
+	- Summaries ONLY if user uses verbs: analyze | summarize | summary | report | overview | insights.
+	- Listing verbs (list/show/get/fetch/display/enumerate) → enumerate + total.
+
+Self-check before returning:
+	- Paginated fully
+	- Correct IDs used
+	- Field names valid
+	- Summary only if requested.
+
+Return COMPLETE data or state what's missing (e.g. pages skipped).
+
+list_project_items query rules:
+Query string - For advanced filtering of project items using GitHub's project filtering syntax:
+
+MUST reflect user intent; strongly prefer explicit content type if narrowed:
+	- "open issues" → state:open is:issue
+	- "merged PRs" → state:merged is:pr
+	- "items updated this week" → updated:>@today-7d (omit type only if mixed desired)
+	- "list all P1 priority items" → priority:p1 (omit state if user wants all, omit type if user specifies "items")
+	- "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")
+	- "all open issues I'm working on" → is:issue state:open assignee:@me
+
+Query Construction Heuristics:
+	a. Extract type nouns: issues → is:issue | PRs, Pulls, or Pull Requests → is:pr | tasks/tickets → is:issue (ask if ambiguity)
+	b. Map temporal phrases: "this week" → updated:>@today-7d
+	c. Map negations: "excluding wontfix" → -label:wontfix
+	d. Map priority adjectives: "high/sev1/p1" → priority:high OR priority:p1 (choose based on field presence)
+	e. When filtering by label, always use wildcard matching to account for cross-repository differences or emojis: (e.g. "bug 🐛" → label:*bug*)
+	f. When filtering by milestone, always use wildcard matching to account for cross-repository differences: (e.g. "v1.0" → milestone:*v1.0*)
+
+Syntax Essentials (items):
+   AND: space-separated. (label:bug priority:high).
+   OR: comma inside one qualifier (label:bug,critical).
+   NOT: leading '-' (-label:wontfix).
+   Hyphenate multi-word field names. (team-name:"Backend Team", story-points:>5).
+   Quote multi-word values. (status:"In Review" team-name:"Backend Team").
+   Ranges: points:1..3, updated:<@today-30d.
+   Wildcards: title:*crash*, label:bug*.
+   Assigned to User: assignee:@me | assignee:username | no:assignee
+
+Common Qualifier Glossary (items):
+   is:issue | is:pr | state:open|closed|merged | assignee:@me|username | label:NAME | status:VALUE |
+   priority:p1|high | sprint-name:@current | team-name:"Backend Team" | parent-issue:"org/repo#123" |
+   updated:>@today-7d | title:*text* | -label:wontfix | label:bug,critical | no:assignee | has:label
+
+Never:
+   - Infer field IDs; fetch via list_project_fields.
+   - Drop 'fields' param on subsequent pages if field values are needed.`
 	default:
 		return ""
 	}