flextools-mcp 2.3.1__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 (88) hide show
  1. flextools_mcp-2.3.1/LICENSE +21 -0
  2. flextools_mcp-2.3.1/MANIFEST.in +11 -0
  3. flextools_mcp-2.3.1/PKG-INFO +270 -0
  4. flextools_mcp-2.3.1/README.md +209 -0
  5. flextools_mcp-2.3.1/VERSION +1 -0
  6. flextools_mcp-2.3.1/pyproject.toml +78 -0
  7. flextools_mcp-2.3.1/setup.cfg +4 -0
  8. flextools_mcp-2.3.1/src/flextools_mcp.egg-info/PKG-INFO +270 -0
  9. flextools_mcp-2.3.1/src/flextools_mcp.egg-info/SOURCES.txt +86 -0
  10. flextools_mcp-2.3.1/src/flextools_mcp.egg-info/dependency_links.txt +1 -0
  11. flextools_mcp-2.3.1/src/flextools_mcp.egg-info/entry_points.txt +3 -0
  12. flextools_mcp-2.3.1/src/flextools_mcp.egg-info/requires.txt +15 -0
  13. flextools_mcp-2.3.1/src/flextools_mcp.egg-info/top_level.txt +1 -0
  14. flextools_mcp-2.3.1/src/flextoolsmcp/__init__.py +9 -0
  15. flextools_mcp-2.3.1/src/flextoolsmcp/__main__.py +9 -0
  16. flextools_mcp-2.3.1/src/flextoolsmcp/archive_old_versions.py +159 -0
  17. flextools_mcp-2.3.1/src/flextoolsmcp/build_casting_index.py +284 -0
  18. flextools_mcp-2.3.1/src/flextoolsmcp/build_embeddings.py +350 -0
  19. flextools_mcp-2.3.1/src/flextoolsmcp/build_navigation_graph.py +427 -0
  20. flextools_mcp-2.3.1/src/flextoolsmcp/build_reverse_mapping.py +442 -0
  21. flextools_mcp-2.3.1/src/flextoolsmcp/casting_helpers.py +236 -0
  22. flextools_mcp-2.3.1/src/flextoolsmcp/config.py +234 -0
  23. flextools_mcp-2.3.1/src/flextoolsmcp/constants.py +129 -0
  24. flextools_mcp-2.3.1/src/flextoolsmcp/extract_patterns.py +305 -0
  25. flextools_mcp-2.3.1/src/flextoolsmcp/file_utils.py +144 -0
  26. flextools_mcp-2.3.1/src/flextoolsmcp/flexicon_analyzer.py +1913 -0
  27. flextools_mcp-2.3.1/src/flextoolsmcp/index/casting_index_liblcm-v11.0.0.json +19116 -0
  28. flextools_mcp-2.3.1/src/flextoolsmcp/index/common_patterns_flexicon-v4.1.0.json +2866 -0
  29. flextools_mcp-2.3.1/src/flextoolsmcp/index/embeddings/embeddings.npy +0 -0
  30. flextools_mcp-2.3.1/src/flextoolsmcp/index/embeddings/faiss.index +0 -0
  31. flextools_mcp-2.3.1/src/flextoolsmcp/index/embeddings/metadata.json +37262 -0
  32. flextools_mcp-2.3.1/src/flextoolsmcp/index/flexlibs/flexicon_api_v4.1.0.json +76882 -0
  33. flextools_mcp-2.3.1/src/flextoolsmcp/index/flexlibs/flexicon_lcm_bridge_v4.1.0.json +83462 -0
  34. flextools_mcp-2.3.1/src/flextoolsmcp/index/flexlibs/flexlibs_api_v1.2.8.json +2687 -0
  35. flextools_mcp-2.3.1/src/flextoolsmcp/index/flexlibs/flexlibs_lcm_bridge_v1.2.8.json +5591 -0
  36. flextools_mcp-2.3.1/src/flextoolsmcp/index/liblcm/liblcm_api_v11.0.0.json +264372 -0
  37. flextools_mcp-2.3.1/src/flextoolsmcp/index/navigation_graph_liblcm-v11.0.0.json +28416 -0
  38. flextools_mcp-2.3.1/src/flextoolsmcp/index/reverse_mapping_liblcm-v11.0.0.json +7156 -0
  39. flextools_mcp-2.3.1/src/flextoolsmcp/json_utils.py +78 -0
  40. flextools_mcp-2.3.1/src/flextoolsmcp/liblcm_extractor.py +1098 -0
  41. flextools_mcp-2.3.1/src/flextoolsmcp/refresh.py +572 -0
  42. flextools_mcp-2.3.1/src/flextoolsmcp/response_utils.py +216 -0
  43. flextools_mcp-2.3.1/src/flextoolsmcp/server/__init__.py +162 -0
  44. flextools_mcp-2.3.1/src/flextoolsmcp/server/constants.py +93 -0
  45. flextools_mcp-2.3.1/src/flextoolsmcp/server/dispatch.py +283 -0
  46. flextools_mcp-2.3.1/src/flextoolsmcp/server/handlers/__init__.py +36 -0
  47. flextools_mcp-2.3.1/src/flextoolsmcp/server/handlers/_import_helper.py +103 -0
  48. flextools_mcp-2.3.1/src/flextoolsmcp/server/handlers/admin.py +728 -0
  49. flextools_mcp-2.3.1/src/flextoolsmcp/server/handlers/api.py +1314 -0
  50. flextools_mcp-2.3.1/src/flextoolsmcp/server/handlers/catalog.py +242 -0
  51. flextools_mcp-2.3.1/src/flextoolsmcp/server/handlers/discovery.py +234 -0
  52. flextools_mcp-2.3.1/src/flextoolsmcp/server/handlers/equivalence.py +388 -0
  53. flextools_mcp-2.3.1/src/flextoolsmcp/server/handlers/execution.py +2778 -0
  54. flextools_mcp-2.3.1/src/flextoolsmcp/server/handlers/utils.py +24 -0
  55. flextools_mcp-2.3.1/src/flextoolsmcp/server/headless_report.py +109 -0
  56. flextools_mcp-2.3.1/src/flextoolsmcp/server/kernel.py +671 -0
  57. flextools_mcp-2.3.1/src/flextoolsmcp/server/models.py +429 -0
  58. flextools_mcp-2.3.1/src/flextoolsmcp/server/project_discovery.py +299 -0
  59. flextools_mcp-2.3.1/src/flextoolsmcp/server/response_keys.py +278 -0
  60. flextools_mcp-2.3.1/src/flextoolsmcp/server/session.py +516 -0
  61. flextools_mcp-2.3.1/src/flextoolsmcp/server/skeleton_storage.py +276 -0
  62. flextools_mcp-2.3.1/src/flextoolsmcp/server/subprocess_helpers.py +80 -0
  63. flextools_mcp-2.3.1/src/flextoolsmcp/server/tool_definitions.py +417 -0
  64. flextools_mcp-2.3.1/src/flextoolsmcp/server/undo_subprocess.py +199 -0
  65. flextools_mcp-2.3.1/src/flextoolsmcp/server/utils.py +79 -0
  66. flextools_mcp-2.3.1/src/flextoolsmcp/server/validators.py +2448 -0
  67. flextools_mcp-2.3.1/src/flextoolsmcp/server/versioning.py +320 -0
  68. flextools_mcp-2.3.1/src/flextoolsmcp/server/worked_examples.py +368 -0
  69. flextools_mcp-2.3.1/src/flextoolsmcp/server.py +906 -0
  70. flextools_mcp-2.3.1/tests/test_async_locking.py +170 -0
  71. flextools_mcp-2.3.1/tests/test_canonical_intents.py +104 -0
  72. flextools_mcp-2.3.1/tests/test_cross_session_logging.py +171 -0
  73. flextools_mcp-2.3.1/tests/test_flexicon_operations.py +536 -0
  74. flextools_mcp-2.3.1/tests/test_flexicon_static_analysis.py +370 -0
  75. flextools_mcp-2.3.1/tests/test_info_message_cap.py +161 -0
  76. flextools_mcp-2.3.1/tests/test_mcp_tools.py +379 -0
  77. flextools_mcp-2.3.1/tests/test_project_discovery.py +229 -0
  78. flextools_mcp-2.3.1/tests/test_rejection_payloads.py +594 -0
  79. flextools_mcp-2.3.1/tests/test_retry_loop_detection.py +225 -0
  80. flextools_mcp-2.3.1/tests/test_script_certification.py +486 -0
  81. flextools_mcp-2.3.1/tests/test_skeleton_storage.py +316 -0
  82. flextools_mcp-2.3.1/tests/test_undo_wiring.py +216 -0
  83. flextools_mcp-2.3.1/tests/test_v1_3_0_upgrade.py +342 -0
  84. flextools_mcp-2.3.1/tests/test_validator_casting_chains.py +294 -0
  85. flextools_mcp-2.3.1/tests/test_validator_cluster_fixes.py +171 -0
  86. flextools_mcp-2.3.1/tests/test_validators.py +284 -0
  87. flextools_mcp-2.3.1/tests/test_version_detection.py +70 -0
  88. flextools_mcp-2.3.1/tests/test_worked_examples.py +83 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,11 @@
1
+ # Ship the indexed API documentation and the version file inside the package.
2
+ graft src/flextoolsmcp/index
3
+ include VERSION
4
+ include LICENSE
5
+ include README.md
6
+
7
+ # Do not ship archived old index versions or caches.
8
+ prune src/flextoolsmcp/index/archive
9
+ prune src/flextoolsmcp/index/liblcm/archive
10
+ prune src/flextoolsmcp/index/flexlibs/archive
11
+ global-exclude __pycache__ *.py[cod]
@@ -0,0 +1,270 @@
1
+ Metadata-Version: 2.4
2
+ Name: flextools-mcp
3
+ Version: 2.3.1
4
+ Summary: MCP server that gives AI assistants searchable LibLCM / FlexLibs / Flexicon API docs for writing FLExTools scripts.
5
+ Author-email: Matthew Lee <matthew_lee@sil.org>
6
+ License: MIT License
7
+
8
+ Copyright (c) 2025
9
+
10
+ Permission is hereby granted, free of charge, to any person obtaining a copy
11
+ of this software and associated documentation files (the "Software"), to deal
12
+ in the Software without restriction, including without limitation the rights
13
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14
+ copies of the Software, and to permit persons to whom the Software is
15
+ furnished to do so, subject to the following conditions:
16
+
17
+ The above copyright notice and this permission notice shall be included in all
18
+ copies or substantial portions of the Software.
19
+
20
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26
+ SOFTWARE.
27
+
28
+ Project-URL: Homepage, https://github.com/MattGyverLee/FlexToolsMCP
29
+ Project-URL: Repository, https://github.com/MattGyverLee/FlexToolsMCP
30
+ Project-URL: Issues, https://github.com/MattGyverLee/FlexToolsMCP/issues
31
+ Keywords: mcp,fieldworks,flextools,flexlibs,flexicon,liblcm,linguistics,lexicon
32
+ Classifier: Development Status :: 4 - Beta
33
+ Classifier: Environment :: Console
34
+ Classifier: Intended Audience :: Developers
35
+ Classifier: Intended Audience :: Science/Research
36
+ Classifier: License :: OSI Approved :: MIT License
37
+ Classifier: Operating System :: Microsoft :: Windows
38
+ Classifier: Programming Language :: Python :: 3
39
+ Classifier: Programming Language :: Python :: 3.10
40
+ Classifier: Programming Language :: Python :: 3.11
41
+ Classifier: Programming Language :: Python :: 3.12
42
+ Classifier: Topic :: Text Processing :: Linguistic
43
+ Requires-Python: >=3.10
44
+ Description-Content-Type: text/markdown
45
+ License-File: LICENSE
46
+ Requires-Dist: mcp>=1.27.0
47
+ Requires-Dist: anyio>=4.5
48
+ Requires-Dist: httpx>=0.27.1
49
+ Requires-Dist: typing-inspection>=0.4.1
50
+ Requires-Dist: sentence-transformers>=2.2.0
51
+ Requires-Dist: faiss-cpu>=1.7.4
52
+ Requires-Dist: pythonnet>=3.0.0
53
+ Requires-Dist: pydantic>=2.0.0
54
+ Requires-Dist: python-dotenv>=1.0.0
55
+ Requires-Dist: pyflexicon>=4.1.0
56
+ Provides-Extra: dev
57
+ Requires-Dist: pytest>=7.0.0; extra == "dev"
58
+ Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
59
+ Requires-Dist: pre-commit>=4.0.0; extra == "dev"
60
+ Dynamic: license-file
61
+
62
+ # FLExTools MCP
63
+
64
+ An MCP server that enables AI assistants to write FLExTools scripts and directly manipulate FieldWorks lexicon data using natural language.
65
+
66
+ Developed for SIL Global by Matthew Lee in connection with the SIL's AI Integration Advisory Board and the FLExTrans team.
67
+
68
+ ## Quick Overview
69
+
70
+ **What it does:** FLExTools MCP gives AI assistants (Claude, Copilot, Gemini) the knowledge to write FLExTools modules by providing indexed, searchable documentation of LibLCM and FlexLibs APIs.
71
+
72
+ ** Videos **
73
+
74
+ ## Videos
75
+
76
+ **[The MCP Connection: Talking to your Dictinary](https://vimeo.com/showcase/12149678?video=1171396540)**
77
+
78
+ This podcast, for a linguistic audience, gives an overview of using the FLExTools MCP.
79
+
80
+ [![MCP Video Thumbnail](./docs/MCPodcast.png)](https://vimeo.com/showcase/12149678?video=1171396540)
81
+
82
+ **[MCPs for FLEx and FLExTools: LangTech AI Software Engineering CoP](https://www.youtube.com/watch?v=JyNwUbAWYIM)**
83
+
84
+ This presentation, given to an audience of programmers, discusses the background, architecture, and advantages of an MCP, and introduces the FLExTools MCP.
85
+
86
+ [![COP Video Thumbnail](./docs/COP-Thumbnail.png)](https://www.youtube.com/watch?v=JyNwUbAWYIM)
87
+
88
+ **Three ways to use it:**
89
+ 1. Generate legacy modules (FlexLibs stable)
90
+ 2. Generate modern modules (Flexicon with ~1,400 functions)
91
+ 3. Run operations directly on FieldWorks databases using natural language queries
92
+
93
+ **Example:** "Delete any sense with 'q' in the gloss" → AI generates, tests, and runs the operation automatically.
94
+
95
+ ⚠️ **Warning:** Backup your project first - there are no guard-rails.
96
+
97
+ ## Why MCP? Why AI?
98
+
99
+ - **What is an MCP Server?** See [WHY-MCP.md](docs/WHY-MCP.md) - explains the LibLCM complexity problem and why generic AI assistants fail
100
+ - **When is AI useful?** See [WHY-AI.md](docs/WHY-AI.md) - learning curve problems and when manual approaches are better
101
+
102
+ ## Getting Started
103
+
104
+ ### 1. Installation
105
+
106
+ FLExToolsMCP is published on PyPI. The indexed API documentation ships inside
107
+ the package, so there is nothing to clone or build. The one prerequisite is
108
+ FieldWorks/FLExTools, which means **Windows + .NET**.
109
+
110
+ **One-line install (recommended)** — no repo, no manual dependency install:
111
+
112
+ ```bash
113
+ # Claude Code
114
+ claude mcp add flextoolsmcp -- uvx flextoolsmcp
115
+ ```
116
+
117
+ `uvx` (from [uv](https://docs.astral.sh/uv/)) fetches the package and all of its
118
+ dependencies — including [Flexicon](https://pypi.org/project/pyflexicon/), the
119
+ deep FieldWorks wrapper — into an isolated cache and runs the server. Nothing
120
+ else to install. Upgrading FLExToolsMCP re-resolves to the latest compatible
121
+ Flexicon. Prefer a persistent install? `uv tool install flextoolsmcp` or
122
+ `pip install flextoolsmcp`.
123
+
124
+ **Manual MCP config** (Claude Desktop, Cursor, and other tools):
125
+
126
+ ```json
127
+ {
128
+ "mcpServers": {
129
+ "flextoolsmcp": {
130
+ "command": "uvx",
131
+ "args": ["flextoolsmcp"]
132
+ }
133
+ }
134
+ }
135
+ ```
136
+
137
+ ### 2. Connect to Your AI Assistant
138
+ See [SETUP.md](SETUP.md#connecting-to-ai-assistants) for Claude Code, Antigravity, and other tools.
139
+
140
+ **Note:** Each AI tool has different MCP configuration syntax. See SETUP.md for your specific tool.
141
+
142
+ **User data** lives under `~/.flextoolsmcp/` (logs, saved skeletons, cached
143
+ models, and any runtime-refreshed indexes) — it persists across upgrades.
144
+
145
+ ### Developing from source
146
+ ```bash
147
+ git clone https://github.com/MattGyverLee/FlexToolsMCP.git
148
+ cd FlexToolsMCP
149
+ pip install -e ".[dev]" # editable install with dev tools (pulls in Flexicon)
150
+
151
+ # Test it works
152
+ python -c "from flextoolsmcp.server import APIIndex, get_index_dir; i=APIIndex.load(get_index_dir()); print('Loaded', len(i.flexicon.get('entities', {})), 'Flexicon entities')"
153
+ ```
154
+
155
+ ### 3. Updating to New Versions
156
+ See [SETUP.md](SETUP.md#updating-flextoolsmcp) for how to pull new releases.
157
+
158
+ ### 4. Start Using
159
+ See [USAGE.md](USAGE.md) for workflows, tool reference, and examples.
160
+
161
+ ## What's Included
162
+
163
+ ### MCP Tools (16)
164
+
165
+ **Admin & Config:**
166
+ - `flextools_start` - Initialize session, set project and API mode
167
+ - `flextools_manage_config` - Get/set/delete persistent configuration
168
+ - `flextools_get_session_history` - View operation history and undo stack
169
+ - `flextools_undo_last_operation` - Undo the most recent write
170
+ - `flextools_get_module_template` - Get FLExTools module boilerplate
171
+
172
+ **Discovery:**
173
+ - `flextools_search_by_capability` - Find APIs by natural language intent
174
+ - `flextools_get_object_api` - Get full API for an object/operations class
175
+ - `flextools_get_navigation_path` - Find traversal between object types
176
+ - `flextools_find_examples` - Get code examples by operation type
177
+ - `flextools_resolve_property` - Check casting requirements for properties
178
+
179
+ **Catalog:**
180
+ - `flextools_list_categories` - List semantic domains (lexicon, grammar, etc.)
181
+ - `flextools_list_entities_in_category` - List entities in a domain
182
+
183
+ **Module & Execution:**
184
+ - `flextools_start_module` - Interactive wizard for new module
185
+ - `flextools_get_operation_logs` - View logs and pattern recommendations
186
+ - `flextools_run_module` - Execute code with dry-run and write modes
187
+
188
+ ### API Coverage
189
+ - **LibLCM**: 2,295 C# entities
190
+ - **FlexLibs Stable**: ~71 methods
191
+ - **Flexicon**: ~1,400 methods (99% documented, 82% with examples)
192
+
193
+ ### Test-Proven Examples
194
+ ```
195
+ "Remove 'el ' from the beginning of any Spanish gloss"
196
+ "Add an environment named 'pre-y' with the context '/_y'"
197
+ "Delete the entry with lexeme ɛʃːɛr"
198
+ "List entries with "ː" in the headword"
199
+ "Are there any duplicates by gloss (fuzzy match) and POS?"
200
+ ```
201
+
202
+ ## Key Features
203
+
204
+ - **Discovery-first workflow** - the AI assembles modules from indexed building blocks (signatures, navigation skeletons, examples, casting fixes) rather than inventing API calls from training memory. See [USAGE.md](USAGE.md#recommended-workflow).
205
+ - **Automatic index refresh** when you update FieldWorks or libraries
206
+ - **Dry-run mode** to test before writing data
207
+ - **Semantic search** with synonym expansion
208
+ - **Pythonnet casting detection** - warns when you need type conversions
209
+ - **Code examples** extracted from real-world usage
210
+ - **Multiple library versions** supported simultaneously
211
+
212
+ ## Documentation
213
+
214
+ | Document | Purpose |
215
+ |----------|---------|
216
+ | [HISTORY.md](HISTORY.md) | Release notes and version history |
217
+ | [SETUP.md](SETUP.md) | Installation and AI tool configuration |
218
+ | [USAGE.md](USAGE.md) | How to use the MCP, workflows, examples |
219
+ | [DEVELOPMENT.md](DEVELOPMENT.md) | Project structure, architecture, contributing |
220
+ | [docs/WHY-MCP.md](docs/WHY-MCP.md) | Why FieldWorks needs MCP servers |
221
+ | [docs/WHY-AI.md](docs/WHY-AI.md) | When AI is useful for FieldWorks work |
222
+ | [docs/INNOVATIONS.md](docs/INNOVATIONS.md) | Technical innovations in this MCP |
223
+ | [docs/BACKGROUND.md](docs/BACKGROUND.md) | Project history |
224
+
225
+ ## Safety & Limitations
226
+
227
+ ### Safety
228
+ - **Always backup before write operations** - the MCP defaults to dry-run mode
229
+ - Dry run shows what would happen before writing
230
+ - Requires explicit user permission for write operations
231
+
232
+ ### Limitations
233
+ - Cannot control the FLEx GUI (filters, display, etc.)
234
+ - Only manipulates data, not UI state
235
+ - Flexicon still undergoing extensive testing
236
+ - Some Scripture module edge cases recently fixed
237
+
238
+ ## Architecture
239
+
240
+ ```
241
+ User Request -> AI Assistant -> MCP Server -> Indexed APIs
242
+ |
243
+ Generated FLExTools Script or Direct Execution
244
+ |
245
+ FLExTools (IronPython) or Flexicon
246
+ |
247
+ LibLCM (C# data model)
248
+ |
249
+ FieldWorks Database
250
+ ```
251
+
252
+ For technical details, see [DEVELOPMENT.md](DEVELOPMENT.md#architecture).
253
+
254
+ ## License
255
+
256
+ MIT License - See LICENSE file for details
257
+
258
+ ## Contributing
259
+
260
+ Contributions are welcome! Please submit issues and pull requests on GitHub.
261
+
262
+ For development info, see [DEVELOPMENT.md](DEVELOPMENT.md).
263
+
264
+ ## Acknowledgments
265
+
266
+ - The FieldWorks developers (Jason, Ken, Hasso, and team)
267
+ - Craig, the developer of FLExTools and FlexLibs
268
+ - The SIL AI Implementation Advisory Board
269
+ - Ron, Beth and the FLExTrans team
270
+ - My mentors Doug, Jeff, and Jenni at SIL LangTech
@@ -0,0 +1,209 @@
1
+ # FLExTools MCP
2
+
3
+ An MCP server that enables AI assistants to write FLExTools scripts and directly manipulate FieldWorks lexicon data using natural language.
4
+
5
+ Developed for SIL Global by Matthew Lee in connection with the SIL's AI Integration Advisory Board and the FLExTrans team.
6
+
7
+ ## Quick Overview
8
+
9
+ **What it does:** FLExTools MCP gives AI assistants (Claude, Copilot, Gemini) the knowledge to write FLExTools modules by providing indexed, searchable documentation of LibLCM and FlexLibs APIs.
10
+
11
+ ** Videos **
12
+
13
+ ## Videos
14
+
15
+ **[The MCP Connection: Talking to your Dictinary](https://vimeo.com/showcase/12149678?video=1171396540)**
16
+
17
+ This podcast, for a linguistic audience, gives an overview of using the FLExTools MCP.
18
+
19
+ [![MCP Video Thumbnail](./docs/MCPodcast.png)](https://vimeo.com/showcase/12149678?video=1171396540)
20
+
21
+ **[MCPs for FLEx and FLExTools: LangTech AI Software Engineering CoP](https://www.youtube.com/watch?v=JyNwUbAWYIM)**
22
+
23
+ This presentation, given to an audience of programmers, discusses the background, architecture, and advantages of an MCP, and introduces the FLExTools MCP.
24
+
25
+ [![COP Video Thumbnail](./docs/COP-Thumbnail.png)](https://www.youtube.com/watch?v=JyNwUbAWYIM)
26
+
27
+ **Three ways to use it:**
28
+ 1. Generate legacy modules (FlexLibs stable)
29
+ 2. Generate modern modules (Flexicon with ~1,400 functions)
30
+ 3. Run operations directly on FieldWorks databases using natural language queries
31
+
32
+ **Example:** "Delete any sense with 'q' in the gloss" → AI generates, tests, and runs the operation automatically.
33
+
34
+ ⚠️ **Warning:** Backup your project first - there are no guard-rails.
35
+
36
+ ## Why MCP? Why AI?
37
+
38
+ - **What is an MCP Server?** See [WHY-MCP.md](docs/WHY-MCP.md) - explains the LibLCM complexity problem and why generic AI assistants fail
39
+ - **When is AI useful?** See [WHY-AI.md](docs/WHY-AI.md) - learning curve problems and when manual approaches are better
40
+
41
+ ## Getting Started
42
+
43
+ ### 1. Installation
44
+
45
+ FLExToolsMCP is published on PyPI. The indexed API documentation ships inside
46
+ the package, so there is nothing to clone or build. The one prerequisite is
47
+ FieldWorks/FLExTools, which means **Windows + .NET**.
48
+
49
+ **One-line install (recommended)** — no repo, no manual dependency install:
50
+
51
+ ```bash
52
+ # Claude Code
53
+ claude mcp add flextoolsmcp -- uvx flextoolsmcp
54
+ ```
55
+
56
+ `uvx` (from [uv](https://docs.astral.sh/uv/)) fetches the package and all of its
57
+ dependencies — including [Flexicon](https://pypi.org/project/pyflexicon/), the
58
+ deep FieldWorks wrapper — into an isolated cache and runs the server. Nothing
59
+ else to install. Upgrading FLExToolsMCP re-resolves to the latest compatible
60
+ Flexicon. Prefer a persistent install? `uv tool install flextoolsmcp` or
61
+ `pip install flextoolsmcp`.
62
+
63
+ **Manual MCP config** (Claude Desktop, Cursor, and other tools):
64
+
65
+ ```json
66
+ {
67
+ "mcpServers": {
68
+ "flextoolsmcp": {
69
+ "command": "uvx",
70
+ "args": ["flextoolsmcp"]
71
+ }
72
+ }
73
+ }
74
+ ```
75
+
76
+ ### 2. Connect to Your AI Assistant
77
+ See [SETUP.md](SETUP.md#connecting-to-ai-assistants) for Claude Code, Antigravity, and other tools.
78
+
79
+ **Note:** Each AI tool has different MCP configuration syntax. See SETUP.md for your specific tool.
80
+
81
+ **User data** lives under `~/.flextoolsmcp/` (logs, saved skeletons, cached
82
+ models, and any runtime-refreshed indexes) — it persists across upgrades.
83
+
84
+ ### Developing from source
85
+ ```bash
86
+ git clone https://github.com/MattGyverLee/FlexToolsMCP.git
87
+ cd FlexToolsMCP
88
+ pip install -e ".[dev]" # editable install with dev tools (pulls in Flexicon)
89
+
90
+ # Test it works
91
+ python -c "from flextoolsmcp.server import APIIndex, get_index_dir; i=APIIndex.load(get_index_dir()); print('Loaded', len(i.flexicon.get('entities', {})), 'Flexicon entities')"
92
+ ```
93
+
94
+ ### 3. Updating to New Versions
95
+ See [SETUP.md](SETUP.md#updating-flextoolsmcp) for how to pull new releases.
96
+
97
+ ### 4. Start Using
98
+ See [USAGE.md](USAGE.md) for workflows, tool reference, and examples.
99
+
100
+ ## What's Included
101
+
102
+ ### MCP Tools (16)
103
+
104
+ **Admin & Config:**
105
+ - `flextools_start` - Initialize session, set project and API mode
106
+ - `flextools_manage_config` - Get/set/delete persistent configuration
107
+ - `flextools_get_session_history` - View operation history and undo stack
108
+ - `flextools_undo_last_operation` - Undo the most recent write
109
+ - `flextools_get_module_template` - Get FLExTools module boilerplate
110
+
111
+ **Discovery:**
112
+ - `flextools_search_by_capability` - Find APIs by natural language intent
113
+ - `flextools_get_object_api` - Get full API for an object/operations class
114
+ - `flextools_get_navigation_path` - Find traversal between object types
115
+ - `flextools_find_examples` - Get code examples by operation type
116
+ - `flextools_resolve_property` - Check casting requirements for properties
117
+
118
+ **Catalog:**
119
+ - `flextools_list_categories` - List semantic domains (lexicon, grammar, etc.)
120
+ - `flextools_list_entities_in_category` - List entities in a domain
121
+
122
+ **Module & Execution:**
123
+ - `flextools_start_module` - Interactive wizard for new module
124
+ - `flextools_get_operation_logs` - View logs and pattern recommendations
125
+ - `flextools_run_module` - Execute code with dry-run and write modes
126
+
127
+ ### API Coverage
128
+ - **LibLCM**: 2,295 C# entities
129
+ - **FlexLibs Stable**: ~71 methods
130
+ - **Flexicon**: ~1,400 methods (99% documented, 82% with examples)
131
+
132
+ ### Test-Proven Examples
133
+ ```
134
+ "Remove 'el ' from the beginning of any Spanish gloss"
135
+ "Add an environment named 'pre-y' with the context '/_y'"
136
+ "Delete the entry with lexeme ɛʃːɛr"
137
+ "List entries with "ː" in the headword"
138
+ "Are there any duplicates by gloss (fuzzy match) and POS?"
139
+ ```
140
+
141
+ ## Key Features
142
+
143
+ - **Discovery-first workflow** - the AI assembles modules from indexed building blocks (signatures, navigation skeletons, examples, casting fixes) rather than inventing API calls from training memory. See [USAGE.md](USAGE.md#recommended-workflow).
144
+ - **Automatic index refresh** when you update FieldWorks or libraries
145
+ - **Dry-run mode** to test before writing data
146
+ - **Semantic search** with synonym expansion
147
+ - **Pythonnet casting detection** - warns when you need type conversions
148
+ - **Code examples** extracted from real-world usage
149
+ - **Multiple library versions** supported simultaneously
150
+
151
+ ## Documentation
152
+
153
+ | Document | Purpose |
154
+ |----------|---------|
155
+ | [HISTORY.md](HISTORY.md) | Release notes and version history |
156
+ | [SETUP.md](SETUP.md) | Installation and AI tool configuration |
157
+ | [USAGE.md](USAGE.md) | How to use the MCP, workflows, examples |
158
+ | [DEVELOPMENT.md](DEVELOPMENT.md) | Project structure, architecture, contributing |
159
+ | [docs/WHY-MCP.md](docs/WHY-MCP.md) | Why FieldWorks needs MCP servers |
160
+ | [docs/WHY-AI.md](docs/WHY-AI.md) | When AI is useful for FieldWorks work |
161
+ | [docs/INNOVATIONS.md](docs/INNOVATIONS.md) | Technical innovations in this MCP |
162
+ | [docs/BACKGROUND.md](docs/BACKGROUND.md) | Project history |
163
+
164
+ ## Safety & Limitations
165
+
166
+ ### Safety
167
+ - **Always backup before write operations** - the MCP defaults to dry-run mode
168
+ - Dry run shows what would happen before writing
169
+ - Requires explicit user permission for write operations
170
+
171
+ ### Limitations
172
+ - Cannot control the FLEx GUI (filters, display, etc.)
173
+ - Only manipulates data, not UI state
174
+ - Flexicon still undergoing extensive testing
175
+ - Some Scripture module edge cases recently fixed
176
+
177
+ ## Architecture
178
+
179
+ ```
180
+ User Request -> AI Assistant -> MCP Server -> Indexed APIs
181
+ |
182
+ Generated FLExTools Script or Direct Execution
183
+ |
184
+ FLExTools (IronPython) or Flexicon
185
+ |
186
+ LibLCM (C# data model)
187
+ |
188
+ FieldWorks Database
189
+ ```
190
+
191
+ For technical details, see [DEVELOPMENT.md](DEVELOPMENT.md#architecture).
192
+
193
+ ## License
194
+
195
+ MIT License - See LICENSE file for details
196
+
197
+ ## Contributing
198
+
199
+ Contributions are welcome! Please submit issues and pull requests on GitHub.
200
+
201
+ For development info, see [DEVELOPMENT.md](DEVELOPMENT.md).
202
+
203
+ ## Acknowledgments
204
+
205
+ - The FieldWorks developers (Jason, Ken, Hasso, and team)
206
+ - Craig, the developer of FLExTools and FlexLibs
207
+ - The SIL AI Implementation Advisory Board
208
+ - Ron, Beth and the FLExTrans team
209
+ - My mentors Doug, Jeff, and Jenni at SIL LangTech
@@ -0,0 +1 @@
1
+ 2.3.1
@@ -0,0 +1,78 @@
1
+ [build-system]
2
+ requires = ["setuptools>=64", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "flextools-mcp"
7
+ dynamic = ["version"]
8
+ description = "MCP server that gives AI assistants searchable LibLCM / FlexLibs / Flexicon API docs for writing FLExTools scripts."
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = { file = "LICENSE" }
12
+ authors = [{ name = "Matthew Lee", email = "matthew_lee@sil.org" }]
13
+ keywords = ["mcp", "fieldworks", "flextools", "flexlibs", "flexicon", "liblcm", "linguistics", "lexicon"]
14
+ classifiers = [
15
+ "Development Status :: 4 - Beta",
16
+ "Environment :: Console",
17
+ "Intended Audience :: Developers",
18
+ "Intended Audience :: Science/Research",
19
+ "License :: OSI Approved :: MIT License",
20
+ "Operating System :: Microsoft :: Windows",
21
+ "Programming Language :: Python :: 3",
22
+ "Programming Language :: Python :: 3.10",
23
+ "Programming Language :: Python :: 3.11",
24
+ "Programming Language :: Python :: 3.12",
25
+ "Topic :: Text Processing :: Linguistic",
26
+ ]
27
+
28
+ # Runtime dependencies. FLExTools/FieldWorks require Windows + .NET, so the
29
+ # .NET interop (pythonnet) and semantic-search stack ship as core deps rather
30
+ # than optional extras -- there is no lightweight cross-platform install to
31
+ # protect. Mirrors requirements.txt.
32
+ dependencies = [
33
+ "mcp>=1.27.0",
34
+ "anyio>=4.5",
35
+ "httpx>=0.27.1",
36
+ "typing-inspection>=0.4.1",
37
+ "sentence-transformers>=2.2.0",
38
+ "faiss-cpu>=1.7.4",
39
+ "pythonnet>=3.0.0",
40
+ "pydantic>=2.0.0",
41
+ "python-dotenv>=1.0.0",
42
+ # The deep FieldWorks wrapper the server generates scripts against. A floor
43
+ # (not a pin) so upgrading FLExToolsMCP re-resolves to the latest Flexicon.
44
+ "pyflexicon>=4.1.0",
45
+ ]
46
+
47
+ [project.optional-dependencies]
48
+ dev = [
49
+ "pytest>=7.0.0",
50
+ "pytest-asyncio>=0.21.0",
51
+ "pre-commit>=4.0.0",
52
+ ]
53
+
54
+ [project.urls]
55
+ Homepage = "https://github.com/MattGyverLee/FlexToolsMCP"
56
+ Repository = "https://github.com/MattGyverLee/FlexToolsMCP"
57
+ Issues = "https://github.com/MattGyverLee/FlexToolsMCP/issues"
58
+
59
+ # Two console-script names: `flextoolsmcp` matches the distribution so
60
+ # `uvx flextoolsmcp` works with no --from, and `flextools-mcp` is the readable
61
+ # hyphenated alias. Both launch the stdio MCP server.
62
+ [project.scripts]
63
+ flextoolsmcp = "flextoolsmcp.server:run"
64
+ flextools-mcp = "flextoolsmcp.server:run"
65
+
66
+ [tool.setuptools]
67
+ include-package-data = true
68
+
69
+ [tool.setuptools.dynamic]
70
+ version = { file = "VERSION" }
71
+
72
+ [tool.setuptools.packages.find]
73
+ where = ["src"]
74
+
75
+ # The indexed API documentation is bundled as package data so it is available
76
+ # after `pip install` / `uvx` with no separate download.
77
+ [tool.setuptools.package-data]
78
+ flextoolsmcp = ["index/**/*", "VERSION"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+