mdmodels 0.3.0__tar.gz → 0.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (164) hide show
  1. mdmodels-0.4.0/.github/scripts/start_ollama.sh +16 -0
  2. {mdmodels-0.3.0 → mdmodels-0.4.0}/.github/workflows/lint.yml +1 -0
  3. {mdmodels-0.3.0 → mdmodels-0.4.0}/PKG-INFO +6 -4
  4. {mdmodels-0.3.0 → mdmodels-0.4.0}/docs/src/content/docs/integrations/cli.mdx +101 -9
  5. {mdmodels-0.3.0 → mdmodels-0.4.0}/docs/src/content/docs/integrations/fastmcp.mdx +19 -13
  6. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/__init__.py +1 -1
  7. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/cli.py +169 -10
  8. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/config.py +50 -5
  9. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/git_utils.py +15 -4
  10. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/library.py +20 -2
  11. mdmodels-0.4.0/mdmodels/mcp/auth.py +104 -0
  12. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/mcp/config.py +28 -5
  13. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/mcp/create.py +10 -1
  14. mdmodels-0.4.0/mdmodels/mcp/sql/annotation.py +39 -0
  15. mdmodels-0.4.0/mdmodels/mcp/sql/constants.py +90 -0
  16. mdmodels-0.4.0/mdmodels/mcp/sql/create.py +135 -0
  17. mdmodels-0.4.0/mdmodels/mcp/sql/embedding.py +22 -0
  18. mdmodels-0.4.0/mdmodels/mcp/sql/naming.py +27 -0
  19. mdmodels-0.4.0/mdmodels/mcp/sql/ownership.py +261 -0
  20. mdmodels-0.4.0/mdmodels/mcp/sql/relationships_types.py +23 -0
  21. mdmodels-0.4.0/mdmodels/mcp/sql/runtime.py +80 -0
  22. mdmodels-0.4.0/mdmodels/mcp/sql/tools/__init__.py +1 -0
  23. mdmodels-0.4.0/mdmodels/mcp/sql/tools/_assets.py +9 -0
  24. mdmodels-0.4.0/mdmodels/mcp/sql/tools/aggregate.py +140 -0
  25. mdmodels-0.4.0/mdmodels/mcp/sql/tools/annotate.py +197 -0
  26. mdmodels-0.4.0/mdmodels/mcp/sql/tools/assets/data_entry_form.html +947 -0
  27. mdmodels-0.4.0/mdmodels/mcp/sql/tools/assets/downloader.html +208 -0
  28. mdmodels-0.4.0/mdmodels/mcp/sql/tools/assets/plot_viewer.html +989 -0
  29. mdmodels-0.4.0/mdmodels/mcp/sql/tools/download.py +96 -0
  30. mdmodels-0.4.0/mdmodels/mcp/sql/tools/form.py +390 -0
  31. mdmodels-0.4.0/mdmodels/mcp/sql/tools/form_store.py +99 -0
  32. mdmodels-0.4.0/mdmodels/mcp/sql/tools/plot.py +834 -0
  33. mdmodels-0.4.0/mdmodels/mcp/sql/tools/relationships.py +73 -0
  34. mdmodels-0.4.0/mdmodels/mcp/sql/tools/schema.py +36 -0
  35. mdmodels-0.4.0/mdmodels/mcp/sql/tools/select.py +149 -0
  36. mdmodels-0.4.0/mdmodels/mcp/sql/tools/upsert.py +192 -0
  37. mdmodels-0.4.0/mdmodels/mcp/sql/tools/vector_search.py +191 -0
  38. mdmodels-0.4.0/mdmodels/mcp/types.py +4 -0
  39. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/relations.py +26 -2
  40. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/sql/__init__.py +2 -0
  41. mdmodels-0.4.0/mdmodels/sql/childref.py +125 -0
  42. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/sql/config.py +19 -0
  43. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/sql/connector.py +20 -4
  44. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/sql/insert.py +59 -1
  45. mdmodels-0.4.0/mdmodels/sql/migrations.py +159 -0
  46. mdmodels-0.4.0/mdmodels/sql/upsert.py +210 -0
  47. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/sql/vector.py +13 -3
  48. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/units/converter.py +3 -3
  49. {mdmodels-0.3.0 → mdmodels-0.4.0}/pyproject.toml +24 -4
  50. mdmodels-0.4.0/tests/integration/__init__.py +0 -0
  51. mdmodels-0.4.0/tests/integration/conftest.py +51 -0
  52. mdmodels-0.4.0/tests/integration/test_db.py +243 -0
  53. mdmodels-0.4.0/tests/unit/__init__.py +0 -0
  54. mdmodels-0.4.0/tests/unit/test_embedding_config.py +173 -0
  55. {mdmodels-0.3.0 → mdmodels-0.4.0}/tests/unit/test_git_utils.py +2 -2
  56. mdmodels-0.4.0/uv.lock +3919 -0
  57. mdmodels-0.3.0/mdmodels/mcp/sql/create.py +0 -608
  58. mdmodels-0.3.0/tests/integration/test_db.py +0 -71
  59. mdmodels-0.3.0/uv.lock +0 -3419
  60. {mdmodels-0.3.0 → mdmodels-0.4.0}/.github/workflows/publish.yml +0 -0
  61. {mdmodels-0.3.0 → mdmodels-0.4.0}/.github/workflows/test-publish.yml +0 -0
  62. {mdmodels-0.3.0 → mdmodels-0.4.0}/.github/workflows/test.yml +0 -0
  63. {mdmodels-0.3.0 → mdmodels-0.4.0}/.gitignore +0 -0
  64. {mdmodels-0.3.0 → mdmodels-0.4.0}/Dockerfile +0 -0
  65. {mdmodels-0.3.0 → mdmodels-0.4.0}/README.md +0 -0
  66. {mdmodels-0.3.0 → mdmodels-0.4.0}/docs/.gitignore +0 -0
  67. {mdmodels-0.3.0 → mdmodels-0.4.0}/docs/README.md +0 -0
  68. {mdmodels-0.3.0 → mdmodels-0.4.0}/docs/astro.config.mjs +0 -0
  69. {mdmodels-0.3.0 → mdmodels-0.4.0}/docs/package-lock.json +0 -0
  70. {mdmodels-0.3.0 → mdmodels-0.4.0}/docs/package.json +0 -0
  71. {mdmodels-0.3.0 → mdmodels-0.4.0}/docs/public/favicon.svg +0 -0
  72. {mdmodels-0.3.0 → mdmodels-0.4.0}/docs/src/assets/houston.webp +0 -0
  73. {mdmodels-0.3.0 → mdmodels-0.4.0}/docs/src/assets/logo.svg +0 -0
  74. {mdmodels-0.3.0 → mdmodels-0.4.0}/docs/src/content/config.ts +0 -0
  75. {mdmodels-0.3.0 → mdmodels-0.4.0}/docs/src/content/docs/basic/converting-formats.mdx +0 -0
  76. {mdmodels-0.3.0 → mdmodels-0.4.0}/docs/src/content/docs/basic/creating-data.mdx +0 -0
  77. {mdmodels-0.3.0 → mdmodels-0.4.0}/docs/src/content/docs/basic/index.mdx +0 -0
  78. {mdmodels-0.3.0 → mdmodels-0.4.0}/docs/src/content/docs/basic/library.mdx +0 -0
  79. {mdmodels-0.3.0 → mdmodels-0.4.0}/docs/src/content/docs/basic/multiple-models.mdx +0 -0
  80. {mdmodels-0.3.0 → mdmodels-0.4.0}/docs/src/content/docs/basic/parsing.mdx +0 -0
  81. {mdmodels-0.3.0 → mdmodels-0.4.0}/docs/src/content/docs/basic/querying.mdx +0 -0
  82. {mdmodels-0.3.0 → mdmodels-0.4.0}/docs/src/content/docs/basic/serialization.mdx +0 -0
  83. {mdmodels-0.3.0 → mdmodels-0.4.0}/docs/src/content/docs/basic/validation.mdx +0 -0
  84. {mdmodels-0.3.0 → mdmodels-0.4.0}/docs/src/content/docs/databases/graphdb.mdx +0 -0
  85. {mdmodels-0.3.0 → mdmodels-0.4.0}/docs/src/content/docs/databases/sql.mdx +0 -0
  86. {mdmodels-0.3.0 → mdmodels-0.4.0}/docs/src/content/docs/databases/vector.mdx +0 -0
  87. {mdmodels-0.3.0 → mdmodels-0.4.0}/docs/src/content/docs/installation.mdx +0 -0
  88. {mdmodels-0.3.0 → mdmodels-0.4.0}/docs/src/content/docs/integrations/fastapi.mdx +0 -0
  89. {mdmodels-0.3.0 → mdmodels-0.4.0}/docs/src/content/docs/integrations/graphql.mdx +0 -0
  90. {mdmodels-0.3.0 → mdmodels-0.4.0}/docs/src/content.config.ts +0 -0
  91. {mdmodels-0.3.0 → mdmodels-0.4.0}/docs/src/styles/styles.css +0 -0
  92. {mdmodels-0.3.0 → mdmodels-0.4.0}/docs/tsconfig.json +0 -0
  93. {mdmodels-0.3.0 → mdmodels-0.4.0}/examples/basic/BasicExample.ipynb +0 -0
  94. {mdmodels-0.3.0 → mdmodels-0.4.0}/examples/basic/model.jl +0 -0
  95. {mdmodels-0.3.0 → mdmodels-0.4.0}/examples/basic/model.md +0 -0
  96. {mdmodels-0.3.0 → mdmodels-0.4.0}/examples/basic/model.rs +0 -0
  97. {mdmodels-0.3.0 → mdmodels-0.4.0}/examples/basic/model.xsd +0 -0
  98. {mdmodels-0.3.0 → mdmodels-0.4.0}/examples/basic/uml_diagram.md +0 -0
  99. {mdmodels-0.3.0 → mdmodels-0.4.0}/examples/graph/Neo4JExample.ipynb +0 -0
  100. {mdmodels-0.3.0 → mdmodels-0.4.0}/examples/graph/model.md +0 -0
  101. {mdmodels-0.3.0 → mdmodels-0.4.0}/examples/graph/startn4j.sh +0 -0
  102. {mdmodels-0.3.0 → mdmodels-0.4.0}/examples/sql/basic/SQLDatabaseExample.ipynb +0 -0
  103. {mdmodels-0.3.0 → mdmodels-0.4.0}/examples/sql/basic/model.md +0 -0
  104. {mdmodels-0.3.0 → mdmodels-0.4.0}/examples/sql/basic/projects.json +0 -0
  105. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/adder_method.py +0 -0
  106. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/create.py +0 -0
  107. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/datamodel.py +0 -0
  108. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/graph/__init__.py +0 -0
  109. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/graph/basenode.py +0 -0
  110. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/graph/connector.py +0 -0
  111. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/graph/create.py +0 -0
  112. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/graph/relation.py +0 -0
  113. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/graphql/__init__.py +0 -0
  114. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/graphql/create.py +0 -0
  115. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/llm/__init__.py +0 -0
  116. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/llm/handler.py +0 -0
  117. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/mcp/__init__.py +0 -0
  118. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/mcp/sql/__init__.py +0 -0
  119. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/mcp/sql/middleware.py +0 -0
  120. /mdmodels-0.3.0/mdmodels/sql/groupby.py → /mdmodels-0.4.0/mdmodels/mcp/sql/tools/assets/tabular_upload.html +0 -0
  121. /mdmodels-0.3.0/tests/__init__.py → /mdmodels-0.4.0/mdmodels/mcp/sql/tools/tabular.py +0 -0
  122. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/meta.py +0 -0
  123. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/path.py +0 -0
  124. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/reference.py +0 -0
  125. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/rest/__init__.py +0 -0
  126. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/rest/config.py +0 -0
  127. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/rest/create.py +0 -0
  128. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/rest/search.py +0 -0
  129. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/sql/aggregation.py +0 -0
  130. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/sql/base.py +0 -0
  131. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/sql/create.py +0 -0
  132. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/sql/filter.py +0 -0
  133. /mdmodels-0.3.0/tests/integration/__init__.py → /mdmodels-0.4.0/mdmodels/sql/groupby.py +0 -0
  134. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/sql/linked_type.py +0 -0
  135. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/sql/utils.py +0 -0
  136. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/templates.py +0 -0
  137. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/units/__init__.py +0 -0
  138. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/units/annotation.py +0 -0
  139. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/units/mappings.py +0 -0
  140. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/units/unit_definition.py +0 -0
  141. {mdmodels-0.3.0 → mdmodels-0.4.0}/mdmodels/utils.py +0 -0
  142. {mdmodels-0.3.0 → mdmodels-0.4.0}/run-tests.sh +0 -0
  143. {mdmodels-0.3.0/tests/unit → mdmodels-0.4.0/tests}/__init__.py +0 -0
  144. {mdmodels-0.3.0 → mdmodels-0.4.0}/tests/fixtures/expected_json.json +0 -0
  145. {mdmodels-0.3.0 → mdmodels-0.4.0}/tests/fixtures/expected_units.json +0 -0
  146. {mdmodels-0.3.0 → mdmodels-0.4.0}/tests/fixtures/expected_units_complex.json +0 -0
  147. {mdmodels-0.3.0 → mdmodels-0.4.0}/tests/fixtures/expected_wrapped_xml.xml +0 -0
  148. {mdmodels-0.3.0 → mdmodels-0.4.0}/tests/fixtures/expected_xml.xml +0 -0
  149. {mdmodels-0.3.0 → mdmodels-0.4.0}/tests/fixtures/model.md +0 -0
  150. {mdmodels-0.3.0 → mdmodels-0.4.0}/tests/fixtures/model_database.md +0 -0
  151. {mdmodels-0.3.0 → mdmodels-0.4.0}/tests/fixtures/model_graph.md +0 -0
  152. {mdmodels-0.3.0 → mdmodels-0.4.0}/tests/fixtures/model_json_schema.json +0 -0
  153. {mdmodels-0.3.0 → mdmodels-0.4.0}/tests/fixtures/model_multiple_types.md +0 -0
  154. {mdmodels-0.3.0 → mdmodels-0.4.0}/tests/fixtures/model_recursion.md +0 -0
  155. {mdmodels-0.3.0 → mdmodels-0.4.0}/tests/fixtures/model_units.md +0 -0
  156. {mdmodels-0.3.0 → mdmodels-0.4.0}/tests/fixtures/model_wrapped_xml.md +0 -0
  157. {mdmodels-0.3.0 → mdmodels-0.4.0}/tests/integration/test_conversion.py +0 -0
  158. {mdmodels-0.3.0 → mdmodels-0.4.0}/tests/integration/test_from_json_schema.py +0 -0
  159. {mdmodels-0.3.0 → mdmodels-0.4.0}/tests/integration/test_graph.py +0 -0
  160. {mdmodels-0.3.0 → mdmodels-0.4.0}/tests/integration/test_llm.py +0 -0
  161. {mdmodels-0.3.0 → mdmodels-0.4.0}/tests/integration/test_parse.py +0 -0
  162. {mdmodels-0.3.0 → mdmodels-0.4.0}/tests/unit/test_create.py +0 -0
  163. {mdmodels-0.3.0 → mdmodels-0.4.0}/tests/unit/test_datamodel.py +0 -0
  164. {mdmodels-0.3.0 → mdmodels-0.4.0}/tests/unit/test_unit_definition.py +0 -0
@@ -0,0 +1,16 @@
1
+ #!/bin/bash
2
+
3
+ # Start Ollama in the background.
4
+ /bin/ollama serve &
5
+ # Record Process ID.
6
+ pid=$!
7
+
8
+ # Pause for Ollama to start.
9
+ sleep 5
10
+
11
+ echo "🔴 Retrieve GEMMA2 model..."
12
+ ollama pull gemma2:2b
13
+ echo "🟢 Done!"
14
+
15
+ # Wait for Ollama process to finish.
16
+ wait $pid
@@ -19,6 +19,7 @@ jobs:
19
19
  - uses: actions/checkout@v4
20
20
  - uses: astral-sh/ruff-action@v2
21
21
  with:
22
+ version: "0.17.0"
22
23
  src: >-
23
24
  mdmodels/
24
25
  tests/
@@ -1,6 +1,6 @@
1
- Metadata-Version: 2.4
1
+ Metadata-Version: 2.5
2
2
  Name: mdmodels
3
- Version: 0.3.0
3
+ Version: 0.4.0
4
4
  Summary: Python package for the MDModels Rust crate
5
5
  Author-email: Jan Range <range.jan@web.de>
6
6
  License-Expression: MIT
@@ -9,10 +9,12 @@ Requires-Dist: astropy>=6.1.7
9
9
  Requires-Dist: bigtree<0.22,>=0.21.1
10
10
  Requires-Dist: dotenv>=0.9.9
11
11
  Requires-Dist: dotted-dict<2,>=1.1.3
12
+ Requires-Dist: fastexcel>=0.19.0
12
13
  Requires-Dist: httpx<0.29,>=0.28
13
- Requires-Dist: mdmodels-core<0.3,>=0.2.9
14
+ Requires-Dist: mdmodels-core<0.4,>=0.3.0
14
15
  Requires-Dist: nest-asyncio<2,>=1.6.0
15
16
  Requires-Dist: pandas>=2.2.3
17
+ Requires-Dist: polars>=1.39.3
16
18
  Requires-Dist: pydantic-xml<3,>=2.12.1
17
19
  Requires-Dist: python-forge<19,>=18.6.0
18
20
  Requires-Dist: python-jsonpath<2,>=1.2.0
@@ -29,7 +31,7 @@ Provides-Extra: graphql
29
31
  Requires-Dist: strawberry-graphql>=0.296.0; extra == 'graphql'
30
32
  Requires-Dist: uvicorn>=0.38.0; extra == 'graphql'
31
33
  Provides-Extra: mcp
32
- Requires-Dist: fastmcp>=2.13.3; extra == 'mcp'
34
+ Requires-Dist: fastmcp[apps]>=3.2.0; extra == 'mcp'
33
35
  Requires-Dist: toon-format==0.9.0b1; extra == 'mcp'
34
36
  Provides-Extra: mysql
35
37
  Requires-Dist: pymysql>=1.1.2; extra == 'mysql'
@@ -13,8 +13,10 @@ Use the CLI when you want to:
13
13
 
14
14
  - start a REST API quickly from an existing markdown model,
15
15
  - expose the same data model as MCP tools for AI clients,
16
+ - manage SQL schema migrations from the same config file,
16
17
  - keep model path, database settings, and integration settings in one shared config,
17
18
  - run the same setup consistently across local machines, CI, and servers.
19
+ - point `model.repo` at a GitHub repository so the markdown schema is loaded from `raw.githubusercontent.com` while SQL and integration settings stay in your TOML.
18
20
 
19
21
  In short: if your workflow is "configure once, run anywhere", the CLI is the most direct path.
20
22
 
@@ -32,7 +34,23 @@ Another advantage is alignment across teams: data engineers, backend developers,
32
34
 
33
35
  By default this creates SQL tables from your model. Use `--create-tables false` if you only want to validate config and connection setup.
34
36
 
35
- 2. **Run REST API**
37
+ 2. **Create a migration revision (Alembic)**
38
+
39
+ ```bash
40
+ mdmodels migrate revision --config config.toml --message "describe schema change"
41
+ ```
42
+
43
+ This autogenerates a migration by comparing the current database schema with metadata rebuilt from your markdown model + `config.toml`.
44
+
45
+ 3. **Apply migrations**
46
+
47
+ ```bash
48
+ mdmodels migrate upgrade --config config.toml head
49
+ ```
50
+
51
+ Use `mdmodels migrate check --config config.toml` in CI to fail when model/config schema changes are missing migrations.
52
+
53
+ 4. **Run REST API**
36
54
 
37
55
  ```bash
38
56
  mdmodels rest --config config.toml
@@ -40,7 +58,7 @@ Another advantage is alignment across teams: data engineers, backend developers,
40
58
 
41
59
  Optional flags include `--host`, `--port`, `--name`, `--graphql`, and `--env`.
42
60
 
43
- 3. **Run MCP Server**
61
+ 5. **Run MCP Server**
44
62
 
45
63
  ```bash
46
64
  mdmodels mcp --config config.toml --transport stdio
@@ -48,7 +66,7 @@ Another advantage is alignment across teams: data engineers, backend developers,
48
66
 
49
67
  Supported transports are `stdio`, `sse`, and `streamable-http`. For non-stdio transports, you can also set `--host` and `--port`.
50
68
 
51
- 4. **Install MCP in Claude Desktop**
69
+ 6. **Install MCP in Claude Desktop**
52
70
 
53
71
  ```bash
54
72
  mdmodels install claude-desktop --config config.toml --name mdmodels --project .
@@ -84,6 +102,8 @@ Then validate:
84
102
 
85
103
  During iteration, update your markdown model and rerun the command to verify endpoint shape and validation behavior.
86
104
 
105
+ For production workflows, prefer migrations (`mdmodels migrate ...`) over repeatedly calling `init` on existing databases.
106
+
87
107
  If you also need GraphQL in the same app for frontend teams or analytical clients:
88
108
 
89
109
  ```bash
@@ -134,6 +154,36 @@ Recommended rollout pattern:
134
154
 
135
155
  For most modern deployments, `streamable-http` is a good default because it integrates cleanly with standard HTTP infrastructure.
136
156
 
157
+ ### 4) Govern schema changes with Alembic
158
+
159
+ Use this when your markdown model or SQL table config changes over time and you need reproducible schema history.
160
+
161
+ Create a migration:
162
+
163
+ ```bash
164
+ mdmodels migrate revision --config config.toml --message "add experiment status"
165
+ ```
166
+
167
+ Apply migrations:
168
+
169
+ ```bash
170
+ mdmodels migrate upgrade --config config.toml head
171
+ ```
172
+
173
+ Validate migration drift (recommended in CI):
174
+
175
+ ```bash
176
+ mdmodels migrate check --config config.toml
177
+ ```
178
+
179
+ Downgrade if needed:
180
+
181
+ ```bash
182
+ mdmodels migrate downgrade --config config.toml <revision>
183
+ ```
184
+
185
+ Migration metadata is generated from your existing `model` and `sql` sections. No separate migration config section is required.
186
+
137
187
  ## Choosing the Right Command
138
188
 
139
189
  Use `mdmodels rest` when your consumers are web/mobile/backend clients and you want HTTP endpoints with OpenAPI docs. Add `--graphql` when your consumers need flexible field selection and nested queries in one request.
@@ -154,6 +204,8 @@ The root config object contains these sections:
154
204
  - `rest`: endpoint exposure per model.
155
205
  - `mcp`: MCP tool exposure per model.
156
206
 
207
+ The migration commands also use this same `model` + `sql` configuration to generate Alembic metadata.
208
+
157
209
  This separation keeps concerns clear: the `sql` section defines storage and table behavior, while `rest` and `mcp` define how that data is exposed to external consumers.
158
210
 
159
211
  Minimal example:
@@ -174,8 +226,42 @@ password = "postgres"
174
226
  ## `model` Section
175
227
 
176
228
  - `model.path` (`Path`, required): path to your markdown model file.
229
+ - `model.repo` (`string`, optional): GitHub repository as `owner/repo`. When set, the model is fetched from GitHub’s raw content URLs (`raw.githubusercontent.com`) instead of the local filesystem.
230
+ - `model.branch` (`string`, optional): branch to read from. Do not set `model.tag` in the same file when using a branch.
231
+ - `model.tag` (`string`, optional): tag to read from. Mutually exclusive with `model.branch`. If neither `branch` nor `tag` is set but `repo` is set, the default ref is `main`.
232
+
233
+ When **only** `model.path` is used (no `model.repo`), relative `model.path` values are resolved relative to the config file location, which keeps projects portable across environments.
234
+
235
+ When **`model.repo` is set**, `model.path` must be the path to the markdown file **inside the repository** (for example `specifications/model.md`). It is **not** resolved against the config file directory on disk; it is passed through as the file path in the repo when building the raw GitHub URL. Use forward-slash style paths as in the repo tree.
236
+
237
+ ### Example: model from GitHub
238
+
239
+ Pin a published schema in CI or on a server without copying the markdown into your deploy artifact:
240
+
241
+ ```toml
242
+ [model]
243
+ repo = "my-org/my-specs"
244
+ branch = "main"
245
+ path = "models/experiment.md"
246
+
247
+ [sql]
248
+ type = "sqlite"
249
+ database = "app.db"
250
+ # ... rest of config (same as local usage)
251
+ ```
252
+
253
+ To pin an immutable release, use `tag` instead of `branch`:
177
254
 
178
- When using the CLI, relative `model.path` values are resolved relative to the config file location, which keeps projects portable across environments.
255
+ ```toml
256
+ [model]
257
+ repo = "my-org/my-specs"
258
+ tag = "v1.0.0"
259
+ path = "models/experiment.md"
260
+ ```
261
+
262
+ All CLI commands that load config (`init`, `rest`, `mcp`, and `install` via the same config) will use the remote model when `repo` is present. You still keep `sql`, `rest`, and `mcp` sections locally—only what the markdown schema defines is pulled from GitHub.
263
+
264
+ **Requirements:** The repository (or the chosen branch/tag) must be **public**, or GitHub must allow unauthenticated raw access for your use case. Private repos typically need a token or a vendored copy of the schema; the CLI fetches via HTTPS without git clone. The model file must be valid MD-Models markdown, as with a local file.
179
265
 
180
266
  ## `sql` Section
181
267
 
@@ -204,7 +290,7 @@ Embedding settings can be added under `[sql.tables.<TableName>.embedding]`:
204
290
 
205
291
  - `column` (`string`, required when embedding is used)
206
292
  - `model` (`string`, required)
207
- - `provider` (`openai | huggingface`, required)
293
+ - `provider` (`openai | huggingface | fastembed`, required)
208
294
  - `dimension` (`int`, optional)
209
295
 
210
296
  Provider-specific subsections:
@@ -217,6 +303,11 @@ Provider-specific subsections:
217
303
  - `device` (`string`, optional)
218
304
  - `batch_size` (`int`, default `32`)
219
305
  - `normalize_embeddings` (`bool`, default `true`)
306
+ - `trust_remote_code` (`bool`, default `false`)
307
+
308
+ - `[sql.tables.<TableName>.embedding.fastembed]`
309
+ - `cache_dir` (`string`, optional)
310
+ - `batch_size` (`int`, optional)
220
311
 
221
312
  ## `rest` Section
222
313
 
@@ -247,14 +338,14 @@ Configure MCP tool behavior per model in `[mcp.tools.<ModelName>]`:
247
338
 
248
339
  ```toml
249
340
  [mcp.tools.Experiment]
250
- description = "Create a new experiment entry."
341
+ description = "Upsert an experiment entry."
251
342
  allow_create = true
252
343
  ```
253
344
 
254
345
  Fields:
255
346
 
256
347
  - `description` (`string`, optional)
257
- - `allow_create` (`bool`, default `false`)
348
+ - `allow_create` (`bool`, default `false`) - enables `Upsert_<ModelName>` for that model.
258
349
 
259
350
  This lets you expose only the MCP tools you want. A common pattern is enabling `allow_create` only for selected models and keeping others query-only.
260
351
 
@@ -275,7 +366,7 @@ This is especially useful for credentials and provider keys. Keeping sensitive v
275
366
  ## Operational Notes
276
367
 
277
368
  - `mdmodels init` creates tables by default (`--create-tables true`).
278
- - For stricter production workflows, run schema setup as a controlled deployment step and use `mdmodels init --create-tables false` when you only want startup checks.
369
+ - For stricter production workflows, prefer `mdmodels migrate revision/upgrade/check` and use `mdmodels init --create-tables false` when you only want startup checks.
279
370
  - Use explicit `--host` and `--port` values in infrastructure environments to avoid accidental defaults for `rest` and non-`stdio` MCP transports.
280
371
 
281
372
  ## Troubleshooting Tips
@@ -284,6 +375,7 @@ This is especially useful for credentials and provider keys. Keeping sensitive v
284
375
  - If database connection fails, verify `sql.type` and connection values (`host`, `port`, `database`, credentials).
285
376
  - If MCP tools are missing, confirm the model names under `[mcp.tools.<ModelName>]` match your generated model names.
286
377
  - If vector search is not available, check table embedding settings under `[sql.tables.<TableName>.embedding]`.
378
+ - If migration commands fail, verify `alembic.ini` and `migrations/env.py` exist in the project root and that your `--config` path points to the expected TOML file.
287
379
 
288
380
  ## Complete Example
289
381
 
@@ -306,6 +398,6 @@ embedding.model = "text-embedding-3-small"
306
398
  StrendaBiocatalysis = ["create", "list", "retrieve", "search", "vectorsearch"]
307
399
 
308
400
  [mcp.tools.StrendaBiocatalysis]
309
- description = "Create a new Strenda-biocatalysis project"
401
+ description = "Upsert a Strenda-biocatalysis project"
310
402
  allow_create = true
311
403
  ```
@@ -5,9 +5,9 @@ description: Learn how to turn your data model into MCP tools with FastMCP.
5
5
 
6
6
  import { Steps } from '@astrojs/starlight/components';
7
7
 
8
- MD-Models provides MCP (Model Context Protocol) integration that automatically generates MCP tools from your markdown-defined data models. Using FastMCP, MD-Models creates a fully functional MCP server with tools for querying, creating, and aggregating data from your database.
8
+ MD-Models provides MCP (Model Context Protocol) integration that automatically generates MCP tools from your markdown-defined data models. Using FastMCP, MD-Models creates a fully functional MCP server with tools for querying, upserting, and aggregating data from your database.
9
9
 
10
- The MCP integration transforms your markdown data models into LLM-accessible tools, allowing language models to interact with your database through a standardized protocol. Each model in your markdown becomes a set of MCP tools for database operations. This enables language models to understand your data schema, create new records, query existing data, and perform aggregations—all through a consistent, well-defined interface.
10
+ The MCP integration transforms your markdown data models into LLM-accessible tools, allowing language models to interact with your database through a standardized protocol. Each model in your markdown becomes a set of MCP tools for database operations. This enables language models to understand your data schema, upsert records, query existing data, and perform aggregations—all through a consistent, well-defined interface.
11
11
 
12
12
  MCP (Model Context Protocol) is a protocol that allows AI assistants and language models to interact with external systems through tools. By exposing your database as MCP tools, you enable language models to perform database operations autonomously, making your data accessible to AI-powered applications. The tools are self-describing, meaning the language model can discover available operations and their parameters through introspection, reducing the need for manual configuration.
13
13
 
@@ -72,17 +72,19 @@ The `DBSessionMiddleware` is automatically added when calling `create_mcp_tools(
72
72
 
73
73
  `create_mcp_tools()` automatically generates a comprehensive set of tools for interacting with your database. These tools are designed to be self-describing, meaning language models can discover their capabilities through introspection and use them appropriately.
74
74
 
75
- The generated tools fall into three categories:
75
+ The generated tools fall into four categories:
76
76
 
77
77
  - **Schema tools**: These tools help language models understand your data structure. `get_schema` returns JSON schemas for all models, allowing the model to understand field types, required fields, and validation rules. `get_relationships` provides information about how models relate to each other, enabling the model to understand foreign key relationships and navigate your data model structure.
78
78
 
79
- - **Create tools**: For each model in your markdown, a `create_<model_name>` tool is generated (e.g., `create_molecule`, `create_reaction`). These tools accept JSON data matching your model structure and handle the creation of database records. They automatically process nested data, creating related records and establishing foreign key relationships as needed.
79
+ - **Upsert tools**: For each model in your markdown, an `Upsert_<ModelName>` tool is generated (for example, `Upsert_Molecule`, `Upsert_Reaction`). Each payload item accepts an optional top-level `row_pk`. If `row_pk` matches an existing row, the row is updated; otherwise, a new row is created.
80
+
81
+ - **Relationship reference rules**: Upsert payloads are intentionally flat. For related objects, use `ChildRef` payloads (`{"row_pk": <id>}`) instead of nested inline objects. For array-valued relationships, upsert behavior is append+dedupe when the target row already exists.
80
82
 
81
83
  - **Query tools**: The `select_from_table` tool allows querying data with flexible filtering capabilities, while `aggregate_from_table` supports aggregations like counts, sums, averages, and more. These tools use the `FilterTask` system for complex query construction, allowing language models to build sophisticated database queries.
82
84
 
83
85
  - **Vector search tools**: The `vector_search` tool enables semantic search across your data using vector embeddings. This tool allows you to find records based on semantic similarity rather than exact matches, making it powerful for discovering related content, finding similar entities, or performing content-based searches. The tool supports cross-table similarity search, where you can search one table using embeddings from a related table (e.g., finding experiments by protein sequence similarity).
84
86
 
85
- All tools handle nested data insertion automatically and maintain referential integrity. When creating records with relationships, the tools check for existing related records and reuse them when appropriate, preventing duplicate data and ensuring referential integrity is maintained.
87
+ All tools maintain referential integrity. Upsert tools resolve `ChildRef` entries against existing rows and reuse those rows by primary key.
86
88
 
87
89
  ## Filtering and Aggregation
88
90
 
@@ -142,7 +144,7 @@ create_mcp_tools(
142
144
  allow_create=True,
143
145
  ),
144
146
  "Experiment": MCPConfig(
145
- allow_create=False, # Disable create tool for this model
147
+ allow_create=False, # Disable upsert tool for this model
146
148
  ),
147
149
  },
148
150
  )
@@ -150,17 +152,21 @@ create_mcp_tools(
150
152
 
151
153
  The `config` parameter accepts a dictionary mapping model names (as strings) to `MCPConfig` instances. Each `MCPConfig` supports the following properties:
152
154
 
153
- - **`description`** (Optional[str]): Custom tool description for the model's create tool. Tool descriptions are crucial for language models—they help the model understand what each tool does and when to use it. If not provided, MD-Models generates a generic description. Custom descriptions should be clear and concise, explaining what the tool does and what kind of data it expects. They should mention the model's purpose, key fields, and any important relationships or constraints.
155
+ - **`description`** (Optional[str]): Custom tool description for the model's upsert tool. Tool descriptions are crucial for language models—they help the model understand what each tool does and when to use it. If not provided, MD-Models generates a generic description. Custom descriptions should be clear and concise, explaining what the tool does and what kind of data it expects. They should mention the model's purpose, key fields, and any important relationships or constraints.
154
156
 
155
- - **`allow_create`** (bool): Controls whether a `create_<model_name>` tool is generated for this model. Defaults to `False`, meaning create tools are disabled by default. Set to `True` to enable creation tools for specific models. This allows you to selectively expose creation capabilities, useful for read-only models or when you want to restrict which models can be created through the MCP interface.
157
+ - **`allow_create`** (bool): Controls whether an `Upsert_<ModelName>` tool is generated for this model. Defaults to `False`. Set to `True` to enable upsert/write capability for specific models.
156
158
 
157
- ## Nested Data Insertion
159
+ ## Upsert Input Semantics
158
160
 
159
- MD-Models automatically handles nested data structures. When calling `create_<model>` tools with nested objects, it automatically creates database rows, handles foreign keys, prevents duplicates, and maintains referential integrity. This means you can pass complex, hierarchical data structures to the create tools, and MD-Models will handle all the complexity of breaking them down into database operations.
161
+ When calling `Upsert_<ModelName>` tools, payload items follow these rules:
160
162
 
161
- The nested insertion process works by recursively processing the data structure: when it encounters a nested object that represents a related model, it first checks if a matching record already exists in the database. If a match is found (based on identifying fields), it reuses that record. If not, it creates a new record. This prevents duplicate data and ensures that relationships are properly established.
163
+ - Use top-level `row_pk` to target an existing row for update.
164
+ - If `row_pk` is omitted, the tool follows create behavior.
165
+ - If both model primary key and `row_pk` are provided and disagree, the operation fails.
166
+ - For related fields, provide `ChildRef` values: `{"row_pk": <id>}`.
167
+ - For array relationships on existing rows, input refs are merged with existing refs (append+dedupe).
162
168
 
163
- This automatic handling makes it easy for language models to create complex data structures—they can simply provide the full nested JSON structure, and MD-Models takes care of the rest. The tools maintain referential integrity throughout the process, ensuring that foreign key relationships are valid and that related records exist before references are created.
169
+ This keeps write behavior explicit and reduces accidental link corruption from guessed or stale IDs.
164
170
 
165
171
  ## Complete Example
166
172
 
@@ -195,7 +201,7 @@ if __name__ == "__main__":
195
201
  app.run("stdio")
196
202
  ```
197
203
 
198
- This creates a fully functional MCP server with tools for every model. Language models can connect and use the tools for schema introspection, data creation, querying, and aggregation. The server runs in stdio mode, which is the standard for MCP servers, allowing it to communicate with MCP clients through standard input/output streams.
204
+ This creates a fully functional MCP server with tools for every model. Language models can connect and use the tools for schema introspection, upsert operations, querying, and aggregation. The server runs in stdio mode, which is the standard for MCP servers, allowing it to communicate with MCP clients through standard input/output streams.
199
205
 
200
206
  Once running, the MCP server exposes all generated tools to connected language models. The models can discover available tools through introspection, understand their parameters through the JSON schemas, and use them to interact with your database. This enables AI-powered applications to autonomously work with your data, performing complex operations like creating related records, querying with filters, and computing aggregations—all without requiring manual SQL queries or custom API endpoints.
201
207
 
@@ -24,7 +24,7 @@ import nest_asyncio
24
24
  from .datamodel import DataModel
25
25
  from .templates import Templates
26
26
 
27
- __version__ = "0.3.0"
27
+ __version__ = "0.3.1"
28
28
 
29
29
 
30
30
  def patch_nest_asyncio():
@@ -5,6 +5,7 @@ This module provides CLI commands for running MDModels applications in different
5
5
  """
6
6
 
7
7
  import os
8
+ import subprocess
8
9
  import sys
9
10
  from pathlib import Path
10
11
  from typing import Literal, Optional, cast
@@ -15,11 +16,14 @@ from fastmcp.mcp_config import StdioMCPServer, update_config_file
15
16
  from rich import print
16
17
 
17
18
  from mdmodels.config import AppConfig
19
+ from mdmodels.mcp.auth import OIDCConfig
18
20
 
19
21
  app = typer.Typer(
20
22
  help="MDModels CLI - Manage and run MDModels applications",
21
23
  add_completion=False,
22
24
  )
25
+ migrate_app = typer.Typer(help="Manage Alembic migrations for MDModels SQL schemas")
26
+ app.add_typer(migrate_app, name="migrate")
23
27
 
24
28
 
25
29
  @app.command()
@@ -106,12 +110,12 @@ def rest(
106
110
  def mcp(
107
111
  config: Path = typer.Option(..., help="Path to the configuration TOML file"),
108
112
  host: str = typer.Option(
109
- "127.0.0.1", help="Host to bind the server to (for non-stdio transports)"
113
+ "localhost", help="Host to bind the server to (for non-stdio transports)"
110
114
  ),
111
115
  port: int = typer.Option(
112
116
  7000, help="Port to bind the server to (for non-stdio transports)"
113
117
  ),
114
- env: Path = typer.Option(
118
+ env: Optional[Path] = typer.Option(
115
119
  default=None, help="Path to .env file for environment variables"
116
120
  ),
117
121
  transport: Literal["stdio", "sse", "streamable-http"] = typer.Option(
@@ -134,15 +138,32 @@ def mcp(
134
138
  from mdmodels.mcp.config import MCPConfig
135
139
  from mdmodels.sql.connector import DatabaseConnector
136
140
 
137
- if env is not None:
138
- dotenv.load_dotenv(dotenv_path=env)
141
+ # Load .env so OIDC_BASE_URL matches the MCP URL in the client (e.g. 127.0.0.1 vs localhost).
142
+ # override=True: project .env wins over stale shell exports during local dev.
143
+ if env:
144
+ dotenv.load_dotenv(dotenv_path=env, override=True)
145
+ else:
146
+ dotenv.load_dotenv(override=True)
139
147
 
140
148
  app_config = _load_app_config(config)
141
149
 
142
150
  app = FastMCP(name="mdmodels")
143
151
  db = DatabaseConnector.from_config(app_config)
144
- mcp_config = MCPConfig.map_from_config(app_config)
145
- create_mcp_tools(app=app, db=db, config=mcp_config)
152
+ mcp_config, all_create, auth = MCPConfig.map_from_config(app_config)
153
+
154
+ if transport == "stdio":
155
+ auth = None
156
+
157
+ create_mcp_tools(
158
+ app=app,
159
+ db=db,
160
+ config=mcp_config,
161
+ all_create=all_create,
162
+ auth=app_config.mcp.auth,
163
+ )
164
+
165
+ if auth:
166
+ OIDCConfig.from_env().add_to_mcp_app(app)
146
167
 
147
168
  match transport:
148
169
  case "stdio":
@@ -151,8 +172,6 @@ def mcp(
151
172
  app.run("sse", host=host, port=port)
152
173
  case "streamable-http":
153
174
  app.run("streamable-http", host=host, port=port)
154
- case _:
155
- raise ValueError(f"Invalid transport: {transport}")
156
175
 
157
176
 
158
177
  @app.command()
@@ -216,6 +235,91 @@ def install(
216
235
  print(f"[green]Successfully installed '{name}' in Claude Desktop[/green]")
217
236
 
218
237
 
238
+ @migrate_app.command("revision")
239
+ def migrate_revision(
240
+ config: Path = typer.Option(..., help="Path to the configuration TOML file"),
241
+ message: str = typer.Option(..., "--message", "-m", help="Revision message"),
242
+ autogenerate: bool = typer.Option(
243
+ True, "--autogenerate/--no-autogenerate", help="Enable autogeneration"
244
+ ),
245
+ alembic_ini: Path = typer.Option(
246
+ Path("alembic.ini"), help="Path to alembic.ini"
247
+ ),
248
+ env: Optional[Path] = typer.Option(
249
+ default=None, help="Path to .env file for environment variables"
250
+ ),
251
+ ):
252
+ """Create a new Alembic migration revision."""
253
+ args = ["revision", "-m", message]
254
+ if autogenerate:
255
+ args.append("--autogenerate")
256
+ _run_alembic(
257
+ alembic_ini=alembic_ini,
258
+ config=config,
259
+ env=env,
260
+ args=args,
261
+ )
262
+
263
+
264
+ @migrate_app.command("upgrade")
265
+ def migrate_upgrade(
266
+ config: Path = typer.Option(..., help="Path to the configuration TOML file"),
267
+ revision: str = typer.Argument("head", help="Target revision (default: head)"),
268
+ alembic_ini: Path = typer.Option(
269
+ Path("alembic.ini"), help="Path to alembic.ini"
270
+ ),
271
+ env: Optional[Path] = typer.Option(
272
+ default=None, help="Path to .env file for environment variables"
273
+ ),
274
+ ):
275
+ """Apply Alembic migrations up to target revision."""
276
+ _run_alembic(
277
+ alembic_ini=alembic_ini,
278
+ config=config,
279
+ env=env,
280
+ args=["upgrade", revision],
281
+ )
282
+
283
+
284
+ @migrate_app.command("downgrade")
285
+ def migrate_downgrade(
286
+ config: Path = typer.Option(..., help="Path to the configuration TOML file"),
287
+ revision: str = typer.Argument(..., help="Target revision"),
288
+ alembic_ini: Path = typer.Option(
289
+ Path("alembic.ini"), help="Path to alembic.ini"
290
+ ),
291
+ env: Optional[Path] = typer.Option(
292
+ default=None, help="Path to .env file for environment variables"
293
+ ),
294
+ ):
295
+ """Downgrade Alembic migrations down to target revision."""
296
+ _run_alembic(
297
+ alembic_ini=alembic_ini,
298
+ config=config,
299
+ env=env,
300
+ args=["downgrade", revision],
301
+ )
302
+
303
+
304
+ @migrate_app.command("check")
305
+ def migrate_check(
306
+ config: Path = typer.Option(..., help="Path to the configuration TOML file"),
307
+ alembic_ini: Path = typer.Option(
308
+ Path("alembic.ini"), help="Path to alembic.ini"
309
+ ),
310
+ env: Optional[Path] = typer.Option(
311
+ default=None, help="Path to .env file for environment variables"
312
+ ),
313
+ ):
314
+ """Fail if model/config schema changes are not reflected in Alembic migrations."""
315
+ _run_alembic(
316
+ alembic_ini=alembic_ini,
317
+ config=config,
318
+ env=env,
319
+ args=["check"],
320
+ )
321
+
322
+
219
323
  def _load_app_config(config: Path) -> AppConfig:
220
324
  """Load config and normalize contained paths to absolute.
221
325
 
@@ -229,12 +333,67 @@ def _load_app_config(config: Path) -> AppConfig:
229
333
  config_path = config_path.resolve()
230
334
 
231
335
  app_config = AppConfig.from_toml(config_path)
232
- if not app_config.model.path.is_absolute():
233
- app_config.model.path = (config_path.parent / app_config.model.path).resolve()
336
+ if app_config.model.repo is None:
337
+ if not app_config.model.path.is_absolute():
338
+ app_config.model.path = (
339
+ config_path.parent / app_config.model.path
340
+ ).resolve()
234
341
 
235
342
  return app_config
236
343
 
237
344
 
345
+ def _run_alembic(
346
+ *,
347
+ alembic_ini: Path,
348
+ config: Path,
349
+ env: Optional[Path],
350
+ args: list[str],
351
+ ) -> None:
352
+ from mdmodels.sql.migrations import build_database_url
353
+
354
+ if env:
355
+ dotenv.load_dotenv(dotenv_path=env, override=True)
356
+ else:
357
+ dotenv.load_dotenv(override=True)
358
+
359
+ config_path = config if config.is_absolute() else (Path.cwd() / config)
360
+ config_path = config_path.resolve()
361
+
362
+ if not config_path.exists():
363
+ raise typer.BadParameter(f"Config file not found: {config_path}")
364
+
365
+ alembic_ini_path = (
366
+ alembic_ini if alembic_ini.is_absolute() else (Path.cwd() / alembic_ini)
367
+ ).resolve()
368
+
369
+ if not alembic_ini_path.exists():
370
+ raise typer.BadParameter(
371
+ f"Alembic config not found: {alembic_ini_path}. "
372
+ "Create alembic.ini and migrations/env.py first."
373
+ )
374
+
375
+ db_url = build_database_url(config_path)
376
+ env_vars = os.environ.copy()
377
+ env_vars["MDMODELS_CONFIG"] = str(config_path)
378
+ env_vars["DATABASE_URL"] = db_url
379
+
380
+ cmd = [
381
+ sys.executable,
382
+ "-m",
383
+ "alembic",
384
+ "-c",
385
+ str(alembic_ini_path),
386
+ "-x",
387
+ f"config={config_path}",
388
+ *args,
389
+ ]
390
+
391
+ try:
392
+ subprocess.run(cmd, check=True, env=env_vars)
393
+ except subprocess.CalledProcessError as exc:
394
+ raise typer.Exit(code=exc.returncode) from exc
395
+
396
+
238
397
  def get_claude_config_path() -> Path | None:
239
398
  """Get Claude Desktop config directory based on platform.
240
399