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.
- flextools_mcp-2.3.1/LICENSE +21 -0
- flextools_mcp-2.3.1/MANIFEST.in +11 -0
- flextools_mcp-2.3.1/PKG-INFO +270 -0
- flextools_mcp-2.3.1/README.md +209 -0
- flextools_mcp-2.3.1/VERSION +1 -0
- flextools_mcp-2.3.1/pyproject.toml +78 -0
- flextools_mcp-2.3.1/setup.cfg +4 -0
- flextools_mcp-2.3.1/src/flextools_mcp.egg-info/PKG-INFO +270 -0
- flextools_mcp-2.3.1/src/flextools_mcp.egg-info/SOURCES.txt +86 -0
- flextools_mcp-2.3.1/src/flextools_mcp.egg-info/dependency_links.txt +1 -0
- flextools_mcp-2.3.1/src/flextools_mcp.egg-info/entry_points.txt +3 -0
- flextools_mcp-2.3.1/src/flextools_mcp.egg-info/requires.txt +15 -0
- flextools_mcp-2.3.1/src/flextools_mcp.egg-info/top_level.txt +1 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/__init__.py +9 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/__main__.py +9 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/archive_old_versions.py +159 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/build_casting_index.py +284 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/build_embeddings.py +350 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/build_navigation_graph.py +427 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/build_reverse_mapping.py +442 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/casting_helpers.py +236 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/config.py +234 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/constants.py +129 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/extract_patterns.py +305 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/file_utils.py +144 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/flexicon_analyzer.py +1913 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/index/casting_index_liblcm-v11.0.0.json +19116 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/index/common_patterns_flexicon-v4.1.0.json +2866 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/index/embeddings/embeddings.npy +0 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/index/embeddings/faiss.index +0 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/index/embeddings/metadata.json +37262 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/index/flexlibs/flexicon_api_v4.1.0.json +76882 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/index/flexlibs/flexicon_lcm_bridge_v4.1.0.json +83462 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/index/flexlibs/flexlibs_api_v1.2.8.json +2687 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/index/flexlibs/flexlibs_lcm_bridge_v1.2.8.json +5591 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/index/liblcm/liblcm_api_v11.0.0.json +264372 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/index/navigation_graph_liblcm-v11.0.0.json +28416 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/index/reverse_mapping_liblcm-v11.0.0.json +7156 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/json_utils.py +78 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/liblcm_extractor.py +1098 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/refresh.py +572 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/response_utils.py +216 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/server/__init__.py +162 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/server/constants.py +93 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/server/dispatch.py +283 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/server/handlers/__init__.py +36 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/server/handlers/_import_helper.py +103 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/server/handlers/admin.py +728 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/server/handlers/api.py +1314 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/server/handlers/catalog.py +242 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/server/handlers/discovery.py +234 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/server/handlers/equivalence.py +388 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/server/handlers/execution.py +2778 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/server/handlers/utils.py +24 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/server/headless_report.py +109 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/server/kernel.py +671 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/server/models.py +429 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/server/project_discovery.py +299 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/server/response_keys.py +278 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/server/session.py +516 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/server/skeleton_storage.py +276 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/server/subprocess_helpers.py +80 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/server/tool_definitions.py +417 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/server/undo_subprocess.py +199 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/server/utils.py +79 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/server/validators.py +2448 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/server/versioning.py +320 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/server/worked_examples.py +368 -0
- flextools_mcp-2.3.1/src/flextoolsmcp/server.py +906 -0
- flextools_mcp-2.3.1/tests/test_async_locking.py +170 -0
- flextools_mcp-2.3.1/tests/test_canonical_intents.py +104 -0
- flextools_mcp-2.3.1/tests/test_cross_session_logging.py +171 -0
- flextools_mcp-2.3.1/tests/test_flexicon_operations.py +536 -0
- flextools_mcp-2.3.1/tests/test_flexicon_static_analysis.py +370 -0
- flextools_mcp-2.3.1/tests/test_info_message_cap.py +161 -0
- flextools_mcp-2.3.1/tests/test_mcp_tools.py +379 -0
- flextools_mcp-2.3.1/tests/test_project_discovery.py +229 -0
- flextools_mcp-2.3.1/tests/test_rejection_payloads.py +594 -0
- flextools_mcp-2.3.1/tests/test_retry_loop_detection.py +225 -0
- flextools_mcp-2.3.1/tests/test_script_certification.py +486 -0
- flextools_mcp-2.3.1/tests/test_skeleton_storage.py +316 -0
- flextools_mcp-2.3.1/tests/test_undo_wiring.py +216 -0
- flextools_mcp-2.3.1/tests/test_v1_3_0_upgrade.py +342 -0
- flextools_mcp-2.3.1/tests/test_validator_casting_chains.py +294 -0
- flextools_mcp-2.3.1/tests/test_validator_cluster_fixes.py +171 -0
- flextools_mcp-2.3.1/tests/test_validators.py +284 -0
- flextools_mcp-2.3.1/tests/test_version_detection.py +70 -0
- 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
|
+
[](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
|
+
[](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
|
+
[](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
|
+
[](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"]
|