fo-semantic-mcp

FO Semantic MCP Server

🚀 Model Context Protocol server for Microsoft Dynamics 365 Finance & Operations development

Supercharge your AI coding assistant with deep F&O knowledge. This MCP server enables AI agents in Cursor IDE, Claude Desktop, and VS Code to search 50,000+ F&O artifacts, read local source code, and find relevant examples for your development tasks.

🤖 What it provides: When building F&O extensions, your AI assistant can:

• Search F&O artifacts using natural language queries
• Find similar implementations and patterns in standard D365 code
• Read actual XML source files from your local F&O installation
• Access rich metadata about tables, forms, classes, and more

📋 Features

✅ Semantic Search - Find F&O artifacts using natural language ✅ 166,000+ Artifacts - Tables, Forms, Classes, EDTs, Enums, Data Entities, Queries, Security, Menu Items ✅ Detail Lookup - Get full structural data: form control trees, table fields/relations/indexes, entity mappings, security chains ✅ Full Cross-References - Complete uses/usedBy lists for every artifact (untruncated) ✅ AI Descriptions - Understand artifact purpose without reading XML ✅ Local File Access - Read actual F&O XML files for complete analysis ✅ Rich Metadata - Business domains, modules, configuration keys, usage context ✅ Multi-Platform - Works on Windows, macOS, Linux with Node.js ✅ MCP Compatible - Works with Cursor IDE, Claude Desktop, VS Code, Claude Code

🎯 Perfect For

• F&O Developers building extensions and customizations
• Consultants learning existing implementations
• Architects understanding system patterns
• Teams accelerating development cycles

🔧 What's Included

MCP Tool: search_FO_artifacts

Search Microsoft D365 F&O standard artifacts semantically. Returns artifact metadata including:

• Artifact name, type, and module
• AI-generated descriptions and usage context
• Business domain classification
• Local file paths (if configured)

MCP Prompt: fo-development-assistant (Claude Desktop only)

A complete 6-step development workflow for F&O customizations:

• Search standard D365 artifacts
• Read standard implementations
• Search your workspace for custom code
• Read your customizations
• Generate context-aware solutions
• Present comprehensive analysis

Note: The prompt workflow is user-invoked and works in Claude Desktop. In Cursor IDE, you can guide the AI through similar steps manually.

⚡ Quick Start

1. Prerequisites

Ensure you have Node.js installed:

• Download from: https://nodejs.org/
• Minimum version: Node.js 18+

2. Get API Key

Get your API key from: https://www.xplusplus.ai/

Visit our website to view available plans and pricing.

3. Installation

Choose the installation method that works best for you:

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):

{
  "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"
      }
    }
  }
}

Claude Desktop (~/AppData/Roaming/Claude/claude_desktop_config.json on Windows):

{
  "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:

{
  "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:

npm install -g fo-semantic-mcp

Then configure your MCP client:

Cursor IDE / Claude Desktop / VS Code:

{
  "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:

npm update -g fo-semantic-mcp

Option C: Manual Installation from GitHub Release

Download and run from a local directory:

• Download the latest release from GitHub
• Extract to your preferred location (e.g., C:\tools\fo-semantic-mcp)
• Run npm install in the extracted folder

Then configure using the full path:

{
  "mcpServers": {
    "fo-semantic-mcp": {
      "command": "node",
      "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"
      }
    }
  }
}

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

4. Restart Your AI Client

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)	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

PowerShell command to find it:

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

"Find customer tables in D365"
"Show me sales order forms"
"Search for pricing calculation classes"
"Find inventory transaction data entities"

Artifact Type Filters

You can filter by artifact type for more focused results:

• Tables
• Forms
• Classes
• EDT (Extended Data Types)
• Enums
• DataEntity
• 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. Simply type /fo-development-assistant to activate the structured workflow.

In Cursor IDE & VS Code

Ask your AI assistant to search F&O artifacts, then guide it through a workflow:

• Search standard D365 implementations
• Read source files to understand patterns
• Search your workspace for existing customizations
• Combine insights for context-aware solutions

🎬 Live Demo

See it in action! Check out our Real-Life Demo showing how an AI agent uses the MCP server to complete a full D365 F&O customization task - from natural language request to working code.

Task: "Create a new field 'External name' on vendor group table and add it to form general tab"

What you'll see:

• AI using semantic search to find D365 artifacts
• Reading standard implementations via file paths
• Checking workspace for existing customizations
• Generating complete table and form extensions
• All in a single session with proper D365 patterns

👉 View the Complete Demo

🔧 Troubleshooting

Tools Not Loading

Symptom: MCP server appears in your client but tools don't show up

Solutions:

• Verify FOINDEX_API_KEY is set correctly (no quotes in JSON, no extra spaces)
• Completely restart your AI client (not just reload window)
• Check MCP server logs in your client's developer console
• Test with npx fo-semantic-mcp directly in terminal to verify installation

Timeout Errors

Symptom: "Request timeout" or "Connection refused" errors

Solutions:

• Verify internet connectivity to https://search.xplusplus.ai
• Increase timeout: "FO_SEARCH_TIMEOUT_MS": "30000" (30 seconds)
• Check if firewall/proxy is blocking the connection
• 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:

• Verify FO_LOCAL_ASSETS_PATH points to correct directory
• Ensure the path exists and is accessible
• On Windows, use double backslashes: "C:\\Users\\..."
• Check file permissions for the PackagesLocalDirectory
• Restart your AI client after updating the path

npx Command Fails

Symptom: "npx: command not found" or npm errors

Solutions:

• Ensure Node.js 18+ is installed: node --version
• Ensure npm is installed: npm --version
• Update npm: npm install -g npm@latest
• Try global installation method instead (Option B above)

Version-Specific Issues

To check your installed version:

# 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:

{
  "command": "npx",
  "args": ["-y", "fo-semantic-mcp@2.0.7"]
}

📖 What's New in v2.2.0

Detail Lookup — Full Structural Data for Any Artifact

Search by exact name + artifact type to get complete structural metadata beyond what semantic search returns.

search_fo_artifacts("SalesTable", filters: { foName: "SalesTable" }, artifact_types: ["Table"])
search_fo_artifacts("SalesTable", filters: { foName: "SalesTable" }, artifact_types: ["Form"])

What you get per artifact type:

Type	Structural Data
Table	All fields (with EDT, type, mandatory), FK relations with field-level constraints, indexes with fields, table group, primary index
Form	Complete control tree (see below), data sources with table bindings, form pattern
Data Entity	Field-to-source mappings, data sources, staging table
Query	Hierarchical data source joins, ranges, order by
EDT	Base type, extends chain, reference table, string size
Enum	All values with integer values and labels
Security	Privilege entry points, duty-to-privilege chains, role-to-duty chains
Class	Extends/extensionOf, event handlers, method signatures
Menu Item	Target object, label, config key
All types	Full cross-references — complete uses and usedBy lists (no longer truncated)

Form Control Trees

Detail lookup on a Form returns the complete UI control hierarchy in a compact, readable text format:

0 Design [Design]
1   ActionPaneHeader [ActionPane]
2     SalesOrder [ActionPaneTab]
3       NewGroup [ButtonGroup]
3       SalesOrderProcess [ButtonGroup]
1   NavigationList [Group]
2     QuickFilterControl [Control]
1   MainTab [Tab]
2     TabPageDetails [TabPage]
3       HeaderView [Group]
4         TabHeaderGeneral [TabPage]
5           GroupCustomer [Group]

• Level number = nesting depth (0 = root)
• Type = abbreviated control type (ActionPane, Group, Tab, TabPage, Grid, String, CheckBox, ComboBox, MenuButton, etc.)
• Complete tree — all controls at all levels
• SalesTable form: 1,138 controls in ~15KB (vs 86KB raw XML)

Use this to understand form layout, find the right control group for extensions, and identify where to add new controls.

Full Cross-References

Every detail lookup now includes complete uses and usedBy arrays — the full list of artifacts that reference or are referenced by the target. Previously these were truncated for large artifacts like SalesTable (19,000+ references).

Previous Versions

v2.0.7 and earlier

• MCP STDIO protocol compliance — fixed initialization timeouts in Claude Desktop
• MCP registry publication — discoverable in official MCP catalog
• npm installation support — npm install -g or npx
• Character encoding fixes, logging improvements
• Simplified architecture, single prompt, standard TypeScript build

🆘 Support

• Issues: Report bugs and feature requests on GitHub Issues
• Documentation: See Getting Started Guide
• Enterprise: Contact [e-mail] for custom solutions and enterprise support
• Community: Join discussions on GitHub

📄 License

This software is licensed for commercial use. See LICENSE file for details.

🚀 About FO-Index

Built by the team behind FO-Index - 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 and start today! 🎯