Desktop Extensions approach

[KaliszS]

Add approach to installation using dxt file format.

[KaliszS]

The extension can be run via nodejs (installed with Claude Desktop), python (detected from the system) and binaries. However, this causes problems – the user would have to install python in the second variant, which goes beyond the ‘one click installation’ model. The last mode raises other issues, as there is currently a bug in dxt that revokes permissions to run scripts. However, there are already plans to add uv along with the installation of Claude Desktop.

modelcontextprotocol/mcpb#17
modelcontextprotocol/mcpb#13

[czajkub]

It is possible to use uv with the .dxt approach, which will force users to have it installed on their machines, but there won't be any issues with the wrong python version installed on the OS (e.g. the fastmcp library requires at least python 3.10).

The issue lies with the .env and .xml files which are normally included in the project directory, but this won't work with .dxt - you could make it so that users will have to build the .dxt after including those files in the directory, but that goes completely against the spirit of this approach.

You can instead use the user_config so that users can specify the path to the .xml file containing their data and other environmental variables, like ES_USER or ES_INDEX. The path to the .xml file will be an absolute path instead of a relative path, but it shouldn't pose any issues due to the way the .xml path is handled

I managed to get it to work, however another issue i ran into is ES_PORT and XML_SAMPLE_SIZE variables being treated as a string while passed to the server despite being specified as a number in the config - although that might be my mistake in the manifest.json file, hence the comment in the issue instead of a pull request.

Here is the manifest.json file i used for reference - without the aforementioned variables:

The only thing that needs to be added except this file is the .dxtignore (which doesn't inherit from .gitignore or .dockerignore, which can be dangerous) and the .dxt itself built by running dxt pack in the root directory where the manifest.json is placed.

{
  "dxt_version": "0.1",
  "name": "apple-health-mcp-server",
  "version": "1.0.0",
  "description": "Apple Health MCP Server implements a Model Context Protocol (MCP) server designed for seamless interaction between LLM-based agents and Apple Health data. It provides a standardized interface for querying, analyzing, and managing Apple Health records—imported from XML exports and indexed in Elasticsearch—through a comprehensive suite of tools. These tools are accessible from MCP-compatible clients (such as Claude Desktop), enabling users to explore, search, and analyze personal health data using natural-language prompts and advanced filtering, all without requiring direct knowledge of the underlying data formats or Elasticsearch queries.",
  "author": {
    "name": "the-momentum",
    "url": "https://www.themomentum.ai/"
  },
  "documentation": "https://github.com/the-momentum/apple-health-mcp-server",
  "support": "https://github.com/the-momentum/apple-health-mcp-server/issues",
  "server": {
    "type": "python",
    "entry_point": "start.py",
    "mcp_config": {
      "command": "uv",
      "args": [
        "run",
        "--frozen",
        "--directory",
        "${__dirname}",
        "${__dirname}/start.py"
      ],
      "env": {
        "RAW_XML_PATH": "${user_config.RAW_XML_PATH}",
        "ES_HOST": "${user_config.ES_HOST}",
        "ES_USER": "${user_config.ES_USER}",
        "ES_PASSWORD": "${user_config.ES_PASSWORD}",
        "ES_INDEX": "${user_config.ES_INDEX}"
      }
    }
  },
  "tools": [
    {
      "name": "get_xml_structure",
      "description": "Analyze the structure and metadata of your Apple Health XML export (file size, tags, types)."
    },
    {
      "name": "search_xml_content",
      "description": "Search for specific content in the XML file (by attribute value, device, type, etc.)."
    },
    {
      "name": "get_xml_by_type",
      "description": "Extract all records of a specific health record type from the XML file."
    },
    {
      "name": "get_health_summary_es",
      "description": "Get a summary of all Apple Health data in Elasticsearch (total count, type breakdown, etc.)."
    },
    {
      "name": "search_health_records_es",
      "description": "Flexible search for health records in Elasticsearch with advanced filtering and query options."
    },
    {
      "name": "get_statistics_by_type_es",
      "description": "Get comprehensive statistics (count, min, max, avg, sum) for a specific health record type."
    },
    {
      "name": "get_trend_data_es",
      "description": "Analyze trends for a health record type over time (daily, weekly, monthly, yearly aggregations)."
    }
  ],
  "user_config": {
    "RAW_XML_PATH": {
      "type": "file",
      "title": "XML path",
      "description": "Path to the Apple Health XML file",
      "required": false,
      "sensitive": false,
      "default": "raw.xml"
    },
    "ES_HOST": {
      "type": "string",
      "title": "Elasticsearch host",
      "description": "Elasticsearch host",
      "required": false,
      "sensitive": false,
      "default": "localhost"
    },
    "ES_USER": {
      "type": "string",
      "title": "Elasticsearch username",
      "description": "Elasticsearch username",
      "required": false,
      "sensitive": false,
      "default": "elastic"
    },
    "ES_PASSWORD": {
      "type": "string",
      "title": "Elasticsearch password",
      "description": "Elasticsearch password",
      "required": false,
      "sensitive": true,
      "default": "elastic"
    },
    "ES_INDEX": {
      "type": "string",
      "title": "Elasticsearch index name",
      "description": "Elasticsearch index name",
      "required": false,
      "sensitive": false,
      "default": "apple_health_data"
    }
  },
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/the-momentum/apple-health-mcp-server"
  }
}

[KaliszS]

Have you managed to include the virtual environment in the installer? Maybe that bug has already been fixed, but a month ago I couldn’t run the uploaded venv. We still need to include it in order to preserve the same environment for every installation. That’s why having Python installed by the user might be problematic.

[czajkub]

I have managed to do that by packing the contents of .venv into the .dxt and adding it to PYTHONPATH in the config, however uv still needs to be installed on the user's machine since the server calls uv during startup:

apple-health-mcp-server/start.py

Lines 10 to 28 in 193b557

	def main():
	project_dir = get_project_dir()
	print("Starting the FastMCP application...", file=sys.stderr)
	cmd = [
	"uv",
	"run",
	"--directory",
	str(project_dir),
	"fastmcp",
	"run",
	"app/main.py",
	]
	print(f"Executing: {' '.join(cmd)}", file=sys.stderr)
	result = subprocess.run(cmd)
	sys.exit(result.returncode)

At first i thought fastmcp uses uv run under the hood, but it only does so with specific flags set. However, the issue with shipping the venv in the installer introduces compatibility issues - i was not able to run the server in Claude on Windows with a .dxt packed on Linux and using the python packed in the venv (which, in hindsight, was pretty obvious), and by using the system python we still run into the issue of the user not necessarily having the right python version installed (and the libraries are still incompatible).

Also, correct me if I'm wrong, but i believe running uv run --frozen will produce a .venv with the same library and python versions, regardless of the user's machine, and without changing the code further to enable running the server without uv, it should pose less issues than just using python and shipping the compiled .venv (excluding the fact that the users still need to install uv)

[KaliszS]

No, fastmcp doesnt use any environmntal tool, like uv or poetry. You can always run the server like that {venv path}/python -m app.main. But incompatibility between different operating systems is a real issue. We should aim for HTTP connectors anyway, that is probably the only way to let users use MCP servers without any technical knowledge.

frozen flag installs virtual environment based only on lock file, completely ignoring pyproject.toml. Maybe we should switch to locked flag, because that one do the comparison first between lock and pyproject to make sure locked versions still meet the requirements from pyproject (and returns error if not, so it still doesnt change the lockfile). But it has nothing to do with python version. That one is set by .python-version file (only if you use uv). And yes, you're right, it might be useles solution if user still needs to install his own python version and maybe uv.