Release: v2.0.8 - Enhanced README with npm/npx installation options

- Added comprehensive installation section with 3 options:
  - Option A: npx (recommended - always latest, no installation)
  - Option B: Global npm install (for version control)
  - Option C: Manual GitHub download (for developers)
- Added detailed troubleshooting section
- Updated "What's New" to reflect v2.0.7+ improvements
- Improved configuration examples for all platforms
- Enhanced guidance for Windows, macOS, and Linux users
- Single README works for both npm and GitHub
- Better user experience with clear benefits for each method

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: xplusplusai

README.md

@@ -55,29 +55,27 @@ Ensure you have **Node.js** installed:
 - Download from: https://nodejs.org/
 - Minimum version: Node.js 18+
 
-### 2. Download & Setup
-
-1. Download the latest release and extract it anywhere on your system
-2. The package includes pre-compiled server files
-3. Run `npm install` in the extracted folder to install dependencies
-
-### 3. Get API Key
+### 2. Get API Key
 
 Get your API key from: **https://www.xplusplus.ai/**
 
 Visit our website to view available plans and pricing.
 
-### 4. Configure
+### 3. Installation
+
+Choose the installation method that works best for you:
 
-Update your MCP client configuration (replace paths with your actual paths):
+#### Option A: Use with npx (Recommended - Always Latest Version)
+
+No installation needed! Your MCP client will automatically fetch the latest version when started.
 
 **Cursor IDE** (`~/.cursor/mcp.json` or `%USERPROFILE%\.cursor\mcp.json`):
 ```json
 {
   "mcpServers": {
     "fo-semantic-mcp": {
-      "command": "node",
-      "args": ["C:\\path\\to\\fo-semantic-mcp\\dist\\server.js"],
+      "command": "npx",
+      "args": ["-y", "fo-semantic-mcp"],
       "env": {
         "FOINDEX_API_KEY": "your_api_key_here",
         "FO_LOCAL_ASSETS_PATH": "C:\\Users\\YourName\\AppData\\Local\\Microsoft\\Dynamics365\\10.0.xxxx\\PackagesLocalDirectory"
@@ -88,12 +86,90 @@ Update your MCP client configuration (replace paths with your actual paths):
 ```
 
 **Claude Desktop** (`~/AppData/Roaming/Claude/claude_desktop_config.json` on Windows):
+```json
+{
+  "mcpServers": {
+    "fo-semantic-mcp": {
+      "command": "npx",
+      "args": ["-y", "fo-semantic-mcp"],
+      "env": {
+        "FOINDEX_API_KEY": "your_api_key_here",
+        "FO_LOCAL_ASSETS_PATH": "C:\\Users\\YourName\\AppData\\Local\\Microsoft\\Dynamics365\\10.0.xxxx\\PackagesLocalDirectory"
+      }
+    }
+  }
+}
+```
+
+**VS Code** (similar to Cursor IDE configuration above)
+
+**Benefits of npx:**
+- ✅ No installation required
+- ✅ Always uses latest version automatically
+- ✅ No manual updates needed
+- ✅ Works on Windows, macOS, and Linux
+
+**macOS/Linux users:** Use forward slashes in paths:
+```json
+{
+  "env": {
+    "FOINDEX_API_KEY": "your_api_key_here",
+    "FO_LOCAL_ASSETS_PATH": "/Users/yourname/.local/Microsoft/Dynamics365/10.0.xxxx/PackagesLocalDirectory"
+  }
+}
+```
+
+#### Option B: Global Installation
+
+Install the package globally on your system:
+
+```bash
+npm install -g fo-semantic-mcp
+```
+
+Then configure your MCP client:
+
+**Cursor IDE / Claude Desktop / VS Code**:
+```json
+{
+  "mcpServers": {
+    "fo-semantic-mcp": {
+      "command": "fo-semantic-mcp",
+      "env": {
+        "FOINDEX_API_KEY": "your_api_key_here",
+        "FO_LOCAL_ASSETS_PATH": "C:\\Users\\YourName\\AppData\\Local\\Microsoft\\Dynamics365\\10.0.xxxx\\PackagesLocalDirectory"
+      }
+    }
+  }
+}
+```
+
+**When to use global installation:**
+- You want to pin to a specific version
+- You have limited internet connectivity
+- You prefer explicit version control
+
+**To update:**
+```bash
+npm update -g fo-semantic-mcp
+```
+
+#### Option C: Manual Installation from GitHub Release
+
+Download and run from a local directory:
+
+1. Download the [latest release](https://github.com/xplusplusai/fo-semantic-mcp/releases) from GitHub
+2. Extract to your preferred location (e.g., `C:\tools\fo-semantic-mcp`)
+3. Run `npm install` in the extracted folder
+
+Then configure using the full path:
+
 ```json
 {
   "mcpServers": {
     "fo-semantic-mcp": {
       "command": "node",
-      "args": ["C:\\path\\to\\fo-semantic-mcp\\dist\\server.js"],
+      "args": ["C:\\tools\\fo-semantic-mcp\\dist\\server.js"],
       "env": {
         "FOINDEX_API_KEY": "your_api_key_here",
         "FO_LOCAL_ASSETS_PATH": "C:\\Users\\YourName\\AppData\\Local\\Microsoft\\Dynamics365\\10.0.xxxx\\PackagesLocalDirectory"
@@ -103,25 +179,34 @@ Update your MCP client configuration (replace paths with your actual paths):
 }
 ```
 
-**macOS/Linux** paths use forward slashes: `/Users/yourname/path/to/fo-semantic-mcp/dist/server.js`
+**macOS/Linux** paths use forward slashes: `/path/to/fo-semantic-mcp/dist/server.js`
+
+**When to use manual installation:**
+- You want full control over the installation location
+- You're developing or customizing the server
+- Your environment restricts npm package execution
 
-### 5. Restart Your AI Client
+### 4. Restart Your AI Client
 
-Completely restart Cursor IDE or Claude Desktop to load the MCP server.
+Completely restart Cursor IDE, Claude Desktop, or VS Code to load the MCP server.
 
 ## 🔧 Configuration Options
 
+### Environment Variables
+
 | Variable | Description | Default | Required |
 |----------|-------------|---------|----------|
 | `FOINDEX_API_KEY` | Your API key from xplusplus.ai | - | ✅ Yes |
 | `FO_LOCAL_ASSETS_PATH` | Path to F&O PackagesLocalDirectory | - | Recommended |
-| `FO_SEARCH_DEFAULT_THRESHOLD` | Relevance filter (0-1) | `0.5` | No |
+| `FO_SEARCH_DEFAULT_THRESHOLD` | Relevance filter (0-1) | No threshold | No |
 | `FO_SEARCH_TIMEOUT_MS` | Request timeout (milliseconds) | `10000` | No |
 | `FO_SEARCH_DEFAULT_LIMIT` | Default result limit | `10` | No |
 | `FO_SEARCH_MAX_LIMIT` | Maximum result limit | `50` | No |
 
 ### Finding Your PackagesLocalDirectory
 
+The `FO_LOCAL_ASSETS_PATH` enables reading actual F&O XML source files. This is **optional** but highly recommended for full analysis capabilities.
+
 **Windows:**
 ```
 C:\Users\[YourName]\AppData\Local\Microsoft\Dynamics365\[version]\PackagesLocalDirectory
@@ -132,6 +217,15 @@ C:\Users\[YourName]\AppData\Local\Microsoft\Dynamics365\[version]\PackagesLocalD
 Get-ChildItem "$env:LOCALAPPDATA\Microsoft\Dynamics365\" -Recurse -Filter "PackagesLocalDirectory" | Select-Object FullName
 ```
 
+**macOS/Linux:**
+Depends on your F&O development setup. Common locations:
+```
+~/.local/Microsoft/Dynamics365/[version]/PackagesLocalDirectory
+~/Library/Application Support/Microsoft/Dynamics365/[version]/PackagesLocalDirectory
+```
+
+**Note:** If `FO_LOCAL_ASSETS_PATH` is not configured, the server will still work for semantic search but won't be able to read local XML files.
+
 ## 💡 Example Usage
 
 ### Basic Searches
@@ -153,14 +247,23 @@ You can filter by artifact type for more focused results:
 - Views
 - Queries
 
+### Advanced Queries
+```
+"Find all tables related to inventory management"
+"Show me forms that use the CustTable datasource"
+"Search for classes that implement pricing logic"
+"Find data entities for financial reporting"
+```
+
 ### In Claude Desktop
-Use the `fo-development-assistant` prompt for guided F&O development workflows.
+Use the `fo-development-assistant` prompt for guided F&O development workflows. Simply type `/fo-development-assistant` to activate the structured workflow.
 
-### In Cursor IDE
-Ask your AI assistant to search F&O artifacts, then guide it to:
+### In Cursor IDE & VS Code
+Ask your AI assistant to search F&O artifacts, then guide it through a workflow:
 1. Search standard D365 implementations
-2. Search your workspace for custom code
-3. Combine insights for context-aware solutions
+2. Read source files to understand patterns
+3. Search your workspace for existing customizations
+4. Combine insights for context-aware solutions
 
 ## 🎬 Live Demo
 
@@ -177,38 +280,113 @@ Ask your AI assistant to search F&O artifacts, then guide it to:
 
 👉 [**View the Complete Demo**](https://www.xplusplus.ai/mcp-demo.html)
 
-## 📖 What's New in v2.0
+## 🔧 Troubleshooting
 
-### Breaking Changes
-- ✅ **Simplified architecture** - Server instructions now provide concise tool documentation only
-- ✅ **Clean tool responses** - Returns data without workflow checklists
-- ✅ **Single prompt** - One clear `fo-development-assistant` prompt (was 2 confusing prompts)
-- ✅ **Removed obfuscation** - Standard TypeScript build for transparency
-- ✅ **Production-ready package** - Only essential runtime files included
+### Tools Not Loading
+
+**Symptom:** MCP server appears in your client but tools don't show up
+
+**Solutions:**
+1. Verify `FOINDEX_API_KEY` is set correctly (no quotes in JSON, no extra spaces)
+2. Completely restart your AI client (not just reload window)
+3. Check MCP server logs in your client's developer console
+4. Test with `npx fo-semantic-mcp` directly in terminal to verify installation
+
+### Timeout Errors
+
+**Symptom:** "Request timeout" or "Connection refused" errors
 
-### Improvements
-- ✅ **Honest capabilities** - Clear about what works automatically vs manually
+**Solutions:**
+1. Verify internet connectivity to `https://search.xplusplus.ai`
+2. Increase timeout: `"FO_SEARCH_TIMEOUT_MS": "30000"` (30 seconds)
+3. Check if firewall/proxy is blocking the connection
+4. Try with a different network (corporate firewalls may block external APIs)
+
+### Local File Reading Not Working
+
+**Symptom:** Can search artifacts but can't read XML source files
+
+**Solutions:**
+1. Verify `FO_LOCAL_ASSETS_PATH` points to correct directory
+2. Ensure the path exists and is accessible
+3. On Windows, use double backslashes: `"C:\\Users\\..."`
+4. Check file permissions for the PackagesLocalDirectory
+5. Restart your AI client after updating the path
+
+### npx Command Fails
+
+**Symptom:** "npx: command not found" or npm errors
+
+**Solutions:**
+1. Ensure Node.js 18+ is installed: `node --version`
+2. Ensure npm is installed: `npm --version`
+3. Update npm: `npm install -g npm@latest`
+4. Try global installation method instead (Option B above)
+
+### Version-Specific Issues
+
+**To check your installed version:**
+```bash
+# For global installation
+npm list -g fo-semantic-mcp
+
+# For npx (shows latest available)
+npm view fo-semantic-mcp version
+```
+
+**To force specific version with npx:**
+```json
+{
+  "command": "npx",
+  "args": ["-y", "[email protected]"]
+}
+```
+
+## 📖 What's New in v2.0.7
+
+### Latest Fixes
+- ✅ **MCP STDIO protocol compliance** - Fixed initialization timeouts in Claude Desktop
+- ✅ **MCP registry publication** - Now discoverable in official MCP catalog at registry.modelcontextprotocol.io
+- ✅ **npm installation support** - Install via `npm install -g` or use directly with `npx`
+- ✅ **Character encoding fixes** - Clean display of prompts and responses
+- ✅ **Logging improvements** - All logs use STDERR for proper MCP protocol compliance
+
+### Previous v2.0 Improvements
+- ✅ **Simplified architecture** - Concise tool documentation and clean responses
+- ✅ **Single prompt** - One clear `fo-development-assistant` prompt
+- ✅ **Standard TypeScript build** - Removed obfuscation for transparency
+- ✅ **Production-ready package** - Only essential runtime files included
 - ✅ **Better MCP alignment** - Follows proper MCP architecture patterns
-- ✅ **Simpler codebase** - Easier to understand and maintain
-- ✅ **Cleaner release** - No development artifacts or intermediate files
 
-### Migration from v1.x
-No breaking API changes - just update your installation and restart your AI client.
+### Migration from Earlier Versions
+
+**From v1.x:**
+- No breaking API changes
+- Update installation and restart your AI client
+- Configuration format is compatible
+
+**From v2.0.0-2.0.6:**
+- Use npx method for easiest updates
+- Update configuration to use `npx` command (recommended)
+- Restart AI client to load new version
 
 ## 🆘 Support
 
-- **Issues**: Report bugs and feature requests on GitHub
-- **Documentation**: See `docs/GETTING_STARTED.md` for detailed setup
-- **Enterprise**: Contact [email protected] for custom solutions
+- **Issues**: Report bugs and feature requests on [GitHub Issues](https://github.com/xplusplusai/fo-semantic-mcp/issues)
+- **Documentation**: See [Getting Started Guide](https://github.com/xplusplusai/fo-semantic-mcp/blob/main/docs/GETTING_STARTED.md)
+- **Enterprise**: Contact [email protected] for custom solutions and enterprise support
+- **Community**: Join discussions on GitHub
 
 ## 📄 License
 
-This software is licensed for commercial use. See `LICENSE` file for details.
+This software is licensed for commercial use. See [LICENSE](https://github.com/xplusplusai/fo-semantic-mcp/blob/main/LICENSE) file for details.
 
 ## 🚀 About FO-Index
 
 Built by the team behind [FO-Index](https://www.xplusplus.ai) - the comprehensive knowledge base for Microsoft Dynamics 365 Finance & Operations development.
 
+**Our Mission:** Accelerate D365 F&O development by making Microsoft's vast standard artifact library searchable and understandable through AI.
+
 ---
 
 **Ready to enhance your F&O development?** [Get your API key](https://www.xplusplus.ai) and start today! 🎯

dist/utils/config.js

@@ -1,6 +1,6 @@
 {
   "name": "fo-semantic-mcp",
-  "version": "2.0.7",
+  "version": "2.0.8",
   "mcpName": "io.github.xplusplusai/fo-semantic-mcp",
   "description": "Model Context Protocol server providing semantic search over Dynamics 365 F&O artifacts.",
   "type": "module",

package.json

@@ -3,12 +3,12 @@
   "name": "io.github.xplusplusai/fo-semantic-mcp",
   "title": "FO Semantic MCP",
   "description": "Semantic search over 50,000+ Dynamics 365 F&O artifacts: tables, forms, classes, and more.",
-  "version": "2.0.7",
+  "version": "2.0.8",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "fo-semantic-mcp",
-      "version": "2.0.7",
+      "version": "2.0.8",
       "transport": {
         "type": "stdio"
       }