@feedmob/github-issues 0.0.7 → 0.0.9

package/README.md

@@ -1,86 +1,147 @@
 # FeedMob GitHub Issues MCP Server
 
-A GitHub Issues MCP server customized for the FeedMob team
+A GitHub Issues MCP server customized for the FeedMob team.
+
+## Prerequisites
+- Node.js 18+
+- npm 9+
+
+## Installation
+Run inside `src/github-issues/`:
+
+```bash
+npm install
+npm run build
+```
+
+## MCP Server Configuration Guide
+
+### Environment Variables
+
+- `GITHUB_PERSONAL_ACCESS_TOKEN`:
+  - Recommended for all GitHub operations.
+  - Required for private repositories and write actions (`create_issue`, `update_issue`, `add_issue_comment`).
+- `GITHUB_DEFAULT_OWNER`:
+  - Optional default owner for issue create/update flows.
+  - Can be omitted if you always pass `owner` explicitly in tool input.
+- `AI_API_URL`:
+  - Required by FeedMob API-backed features:
+    - `search_issues`
+    - `get_issues`
+    - `sync_latest_issues`
+    - resource `issues/search_schema`
+- `AI_API_TOKEN`:
+  - Bearer token for the FeedMob API above.
+
+### Example MCP Client Config (stdio)
+
+Use the built artifact (`dist/index.js`) after `npm run build`:
+
+```json
+{
+  "mcpServers": {
+    "feedmob-github-issues": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@feedmob/github-issues"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx",
+        "GITHUB_DEFAULT_OWNER": "feedmob",
+        "AI_API_URL": "https://your-feedmob-api.example.com",
+        "AI_API_TOKEN": "your-feedmob-api-token"
+      }
+    }
+  }
+}
+```
+
+### Local Development Run (without build)
+
+From repo root:
+
+```bash
+npx tsx src/github-issues/index.ts
+```
+
+Or from `src/github-issues`:
+
+```bash
+npx tsx index.ts
+```
 
 ## Tools
 
 ### `search_issues`
-- Search GitHub Issues through FeedMob API
+- Search GitHub issues through FeedMob API.
 - Input parameters:
-  - `scheam` (string, required): Get from system resource `issues/search_schema`
-  - `start_date` (string): Issue creation start date, defaults to 6 days ago
-  - `end_date` (string): Issue creation end date, defaults to today
-  - `status` (optional string): Issue status, e.g., 'open', 'closed'
+  - `scheam` (string, required): Get from resource `issues/search_schema`.
+  - `start_date` (string): Issue creation start date.
+  - `end_date` (string): Issue creation end date.
+  - `status` (optional string): For example `open`, `closed`.
   - `repo` (optional string)
-  - `users` (optional string[]): List of users
-  - `team` (optional string): Team name, e.g., 'Star', 'Mighty'
-- Returns: Search results
+  - `users` (optional string[]): User list.
+  - `team` (optional string): For example `Star`, `Mighty`.
+  - `title` (optional string): Fuzzy title match.
+  - `labels` (optional string[]): Labels filter.
+  - `score_status` (optional string)
+  - `fields` (string[], required): Response fields to return.
 
 ### `create_issue`
-- Create a new Issue in a GitHub repository
+- Create a new issue in a GitHub repository.
 - Input parameters:
-  - `owner` (optional string): Repository owner, can use environment variable default
-  - `repo` (string, required): Repository name
-  - `title` (string, required): Issue title
-  - `body` (optional string): Issue description
-  - `assignees` (optional string[]): Usernames to assign to
-  - `labels` (optional string[]): Labels to add
-  - `milestone` (optional number): Milestone number
-- Returns: Created Issue details
+  - `owner` (optional string): Repository owner. Falls back to `GITHUB_DEFAULT_OWNER`.
+  - `repo` (string, required): Repository name.
+  - `title` (string, required): Issue title.
+  - `body` (optional string): Issue description.
+  - `assignees` (optional string[]): Usernames to assign.
+  - `labels` (optional string[]): Labels to add.
+  - `milestone` (optional number): Milestone number.
 
 ### `update_issue`
-- Update an existing Issue
+- Update an existing issue in a GitHub repository.
 - Input parameters:
-  - `owner` (string, required): Repository owner
-  - `repo` (string, required): Repository name
-  - `issue_number` (number, required): Issue number to update
-  - `title` (optional string): New title
-  - `body` (optional string): New description
-  - `state` (optional string): New state ('open' or 'closed')
-  - `labels` (optional string[]): New labels
-  - `assignees` (optional string[]): New assignees
-  - `milestone` (optional number): New milestone number
-- Returns: Updated Issue details
-
-### `get_issue`
-- Get details of a specific Issue in a repository
+  - `owner` (string, required): Repository owner.
+  - `repo` (string, required): Repository name.
+  - `issue_number` (number, required): Issue number to update.
+  - `title` (optional string): New title.
+  - `body` (optional string): New description.
+  - `state` (optional string): `open` or `closed`.
+  - `labels` (optional string[]): New labels.
+  - `assignees` (optional string[]): New assignees.
+  - `milestone` (optional number): New milestone number.
+
+### `get_issues`
+- Fetch comments for multiple issues in bulk through FeedMob API.
 - Input parameters:
-  - `owner` (string, required): Repository owner
-  - `repo` (string, required):
-  - `issue_number` (number, required): Issue number to retrieve
-- Returns: GitHub Issue object and details
+  - `repo_issues` (array, required): Each item includes `repo` and `issue_number`.
+  - `comment_count` (string, optional): `all` or a specific count.
 
 ### `add_issue_comment`
-- Add a comment to an existing Issue
+- Add a comment to an existing issue.
 - Input parameters:
-  - `owner` (string, required): Repository owner
-  - `repo` (string, required):
-  - `issue_number` (number, required): Issue number
-  - `body` (string, required): Comment content
-- Returns: Created comment details
+  - `owner` (string, required): Repository owner.
+  - `repo` (string, required): Repository name.
+  - `issue_number` (number, required): Issue number.
+  - `body` (string, required): Comment content.
 
 ### `sync_latest_issues`
-- Sync GitHub Issues Latest Data By FeedMob API
+- Sync latest issues data from FeedMob API.
 
 ## Resources
 
 ### `issues/search_schema`
-- Provides schema definition for Issues search
+- Provides the schema definition for `search_issues`.
 
-### Local Development
-For local development, you can run the server using the following commands:
+## Troubleshooting
 
-```bash
-# Install dependencies
-npm install
+### `Server does not support completions (required for completion/complete)`
 
-# Build project
-npm run build
+Cursor (and other MCP clients using protocol 2025-11-25) may request the `completion/complete` capability. FastMCP 2.1 uses `@modelcontextprotocol/sdk`; SDK **1.22.0+** requires the server to advertise the completions capability when registering a completion handler, but FastMCP does not set it, so the server crashes on start.
 
-# Run server
-npx tsx src/github-issues/index.ts
-```
+**Fix:** This package pins the SDK to **1.21.2** via `overrides` in `package.json`. After pulling, run `npm install` in `src/github-issues/` so the override is applied. If you use `npx -y @feedmob/github-issues`, reinstall or use the local build: `node /path/to/fm-mcp-servers/src/github-issues/dist/index.js`.
 
-## License
+### `SyntaxError: Unexpected token ':'` with JSON on stdin
 
-This MCP server is licensed under the MIT License. This means you can freely use, modify, and distribute this software, but must comply with the terms and conditions of the MIT License. For more details, please refer to the LICENSE file in the project repository.
+If you see Node parsing the MCP `initialize` JSON as JavaScript (e.g. `Expected ';', '}' or <eof>`), the process is likely being run with **stdin as script** (e.g. `node -`). The server must be started with **stdio** so that stdin is the MCP channel, not script input. In Cursor MCP config, use a plain command such as `node /absolute/path/to/dist/index.js` or `npx -y @feedmob/github-issues` with no `-` or stdin-eval.

package/dist/common/version.js

@@ -1,3 +1,3 @@
 // If the format of this file changes, so it doesn't simply export a VERSION constant,
 // this will break .github/workflows/version-check.yml.
-export const VERSION = "0.0.7";
+export const VERSION = "0.0.9";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feedmob/github-issues",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "MCP server for using the GitHub API",
   "license": "MIT",
   "author": "FeedMob",
@@ -19,11 +19,10 @@
     "watch": "tsc --watch"
   },
   "dependencies": {
-    "date-fns": "^4.1.0",
-    "fastmcp": "2.1.0",
-    "@modelcontextprotocol/sdk": "1.0.1",
     "@types/node": "^22",
     "@types/node-fetch": "^2.6.12",
+    "date-fns": "^4.1.0",
+    "fastmcp": "2.1.0",
     "node-fetch": "^3.3.2",
     "universal-user-agent": "^7.0.2",
     "zod": "^3.22.4",
@@ -36,5 +35,8 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/feed-mob/fm-mcp-servers"
+  },
+  "overrides": {
+    "@modelcontextprotocol/sdk": "1.21.2"
   }
 }