openconstruction-tools 0.1.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 (59) hide show
  1. openconstruction_tools-0.1.0/.env.example +37 -0
  2. openconstruction_tools-0.1.0/.python-version +1 -0
  3. openconstruction_tools-0.1.0/CONTRIBUTING.md +91 -0
  4. openconstruction_tools-0.1.0/LICENSE +201 -0
  5. openconstruction_tools-0.1.0/MANIFEST.in +4 -0
  6. openconstruction_tools-0.1.0/NOTICE +8 -0
  7. openconstruction_tools-0.1.0/PKG-INFO +85 -0
  8. openconstruction_tools-0.1.0/README.md +61 -0
  9. openconstruction_tools-0.1.0/docs/catalog.md +27 -0
  10. openconstruction_tools-0.1.0/docs/development.md +42 -0
  11. openconstruction_tools-0.1.0/docs/hosting.md +76 -0
  12. openconstruction_tools-0.1.0/docs/mcp.md +58 -0
  13. openconstruction_tools-0.1.0/docs/releasing.md +51 -0
  14. openconstruction_tools-0.1.0/docs/usage.md +192 -0
  15. openconstruction_tools-0.1.0/openconstruction_mcp/__init__.py +5 -0
  16. openconstruction_tools-0.1.0/openconstruction_mcp/acquisition.py +221 -0
  17. openconstruction_tools-0.1.0/openconstruction_mcp/catalog.py +327 -0
  18. openconstruction_tools-0.1.0/openconstruction_mcp/cli.py +242 -0
  19. openconstruction_tools-0.1.0/openconstruction_mcp/config.py +82 -0
  20. openconstruction_tools-0.1.0/openconstruction_mcp/downloads.py +1179 -0
  21. openconstruction_tools-0.1.0/openconstruction_mcp/provider_auth.py +206 -0
  22. openconstruction_tools-0.1.0/openconstruction_mcp/provider_downloads.py +89 -0
  23. openconstruction_tools-0.1.0/openconstruction_mcp/providers.py +180 -0
  24. openconstruction_tools-0.1.0/openconstruction_mcp/research.py +156 -0
  25. openconstruction_tools-0.1.0/openconstruction_mcp/security.py +114 -0
  26. openconstruction_tools-0.1.0/openconstruction_mcp/server.py +377 -0
  27. openconstruction_tools-0.1.0/openconstruction_mcp/service.py +344 -0
  28. openconstruction_tools-0.1.0/openconstruction_mcp/skills.py +49 -0
  29. openconstruction_tools-0.1.0/openconstruction_mcp/store.py +345 -0
  30. openconstruction_tools-0.1.0/openconstruction_mcp/web.py +452 -0
  31. openconstruction_tools-0.1.0/openconstruction_mcp/workflows.py +319 -0
  32. openconstruction_tools-0.1.0/openconstruction_tools.egg-info/PKG-INFO +85 -0
  33. openconstruction_tools-0.1.0/openconstruction_tools.egg-info/SOURCES.txt +57 -0
  34. openconstruction_tools-0.1.0/openconstruction_tools.egg-info/dependency_links.txt +1 -0
  35. openconstruction_tools-0.1.0/openconstruction_tools.egg-info/entry_points.txt +4 -0
  36. openconstruction_tools-0.1.0/openconstruction_tools.egg-info/requires.txt +7 -0
  37. openconstruction_tools-0.1.0/openconstruction_tools.egg-info/top_level.txt +1 -0
  38. openconstruction_tools-0.1.0/pyproject.toml +55 -0
  39. openconstruction_tools-0.1.0/scripts/check_remote.py +39 -0
  40. openconstruction_tools-0.1.0/scripts/package_skills.py +48 -0
  41. openconstruction_tools-0.1.0/scripts/smoke_installed.py +31 -0
  42. openconstruction_tools-0.1.0/scripts/smoke_stdio.py +35 -0
  43. openconstruction_tools-0.1.0/scripts/validate_skills.py +132 -0
  44. openconstruction_tools-0.1.0/setup.cfg +4 -0
  45. openconstruction_tools-0.1.0/skills/dataset-discovery/SKILL.md +40 -0
  46. openconstruction_tools-0.1.0/skills/dataset-discovery/examples/hardhat-detection.json +16 -0
  47. openconstruction_tools-0.1.0/skills/dataset-discovery/metadata.json +129 -0
  48. openconstruction_tools-0.1.0/skills/dataset-discovery/tests/dataset-discovery-smoke.json +15 -0
  49. openconstruction_tools-0.1.0/skills/index.json +137 -0
  50. openconstruction_tools-0.1.0/tests/test_acquisition.py +569 -0
  51. openconstruction_tools-0.1.0/tests/test_catalog.py +128 -0
  52. openconstruction_tools-0.1.0/tests/test_cli.py +209 -0
  53. openconstruction_tools-0.1.0/tests/test_hosting.py +38 -0
  54. openconstruction_tools-0.1.0/tests/test_remote_downloads.py +113 -0
  55. openconstruction_tools-0.1.0/tests/test_server.py +164 -0
  56. openconstruction_tools-0.1.0/tests/test_skills.py +49 -0
  57. openconstruction_tools-0.1.0/tests/test_web.py +371 -0
  58. openconstruction_tools-0.1.0/tests/test_workflows.py +97 -0
  59. openconstruction_tools-0.1.0/uv.lock +629 -0
@@ -0,0 +1,37 @@
1
+ OPENCONSTRUCTION_DATA_BASE_URL=https://www.openconstruction.org/data
2
+ OPENCONSTRUCTION_SITE_BASE_URL=https://www.openconstruction.org
3
+ CATALOG_CACHE_TTL_SECONDS=600
4
+
5
+ # Local stdio dataset downloads. destination tool arguments are directory names
6
+ # relative to this root; absolute paths and parent traversal are rejected.
7
+ OC_DOWNLOAD_ROOT=~/.openconstruction/datasets
8
+ OC_MAX_DOWNLOAD_BYTES=536870912000
9
+ # Used only when a Hugging Face dataset requires the user's own access grant.
10
+ HF_TOKEN=
11
+
12
+ # Remote MCP and OAuth broker
13
+ OC_PUBLIC_URL=http://127.0.0.1:8000
14
+ OC_SITE_URL=http://127.0.0.1:8000
15
+ OC_AUTH_DB=.openconstruction/state.db
16
+ OC_ENV=development
17
+ OC_STATIC_DIR=../site
18
+ OC_CORS_ORIGINS=http://127.0.0.1:8000
19
+ OC_CONNECTED_ACCOUNTS_ENABLED=false
20
+ SUPABASE_URL=https://your-project.supabase.co
21
+ SUPABASE_ANON_KEY=your-public-anon-key
22
+ # Generate with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
23
+ OC_TOKEN_ENCRYPTION_KEY=
24
+
25
+ # Connected Accounts OAuth apps. Register each callback under OC_PUBLIC_URL:
26
+ # /api/connections/github/callback
27
+ # /api/connections/huggingface/callback
28
+ # /api/connections/baidu/callback
29
+ OC_GITHUB_CLIENT_ID=
30
+ OC_GITHUB_CLIENT_SECRET=
31
+ OC_GITHUB_SCOPES="read:user"
32
+ OC_HF_CLIENT_ID=
33
+ OC_HF_CLIENT_SECRET=
34
+ OC_HF_SCOPES="openid profile read-repos gated-repos"
35
+ OC_BAIDU_CLIENT_ID=
36
+ OC_BAIDU_CLIENT_SECRET=
37
+ OC_BAIDU_SCOPES="basic netdisk"
@@ -0,0 +1 @@
1
+ 3.12
@@ -0,0 +1,91 @@
1
+ # Contributing OpenConstruction Skills
2
+
3
+ OpenConstruction skills are reusable task workflows over the shared API and MCP tools. A prompt can be an example request, but the skill should define the procedure, inputs, outputs, and review checks behind that request.
4
+
5
+ Submit a public source URL for review before opening a pull request. Good source URLs point to a GitHub skill folder, a ZIP package, or documentation that includes the expected skill files.
6
+
7
+ ## What Makes A Useful Skill
8
+
9
+ A skill should include:
10
+
11
+ - a clear user task
12
+ - structured inputs
13
+ - the API or MCP tools it calls
14
+ - ranking, validation, or decision logic
15
+ - structured outputs users can act on
16
+ - tests or examples that show the workflow works
17
+
18
+ ## Skill Layout
19
+
20
+ ```text
21
+ skills/
22
+ dataset-discovery/
23
+ SKILL.md
24
+ metadata.json
25
+ examples/
26
+ tests/
27
+ ```
28
+
29
+ Every skill must be listed in `skills/index.json`.
30
+
31
+ `metadata.json` is the registry record. `SKILL.md` is the agent instruction file. A complete accepted skill normally includes both, plus examples and tests when runtime behavior is added.
32
+
33
+ ## Required Metadata
34
+
35
+ Each `metadata.json` entry must include:
36
+
37
+ - `id`
38
+ - `name`
39
+ - `author`
40
+ - `version`
41
+ - `tier`
42
+ - `status`
43
+ - `lifecycle_stage`
44
+ - `description`
45
+ - `inputs`
46
+ - `outputs`
47
+ - `tools`
48
+ - `permissions`
49
+ - `risk_level`
50
+ - `license`
51
+ - `review`
52
+
53
+ If the skill has runtime logic, include:
54
+
55
+ - `runtime.tool`
56
+ - `runtime.module`
57
+ - `runtime.function`
58
+
59
+ ## Review Checklist
60
+
61
+ Maintainers review skill submissions for:
62
+
63
+ - concrete user value
64
+ - source URL with reviewable skill files
65
+ - valid metadata
66
+ - clear lifecycle stage
67
+ - correct tool declarations
68
+ - permission declarations
69
+ - working examples
70
+ - tests for runtime logic
71
+ - license, copyright, and permission to share
72
+ - no private data
73
+ - no hidden external access
74
+ - no code execution unless explicitly declared
75
+
76
+ ## Preferred First Step
77
+
78
+ Open a GitHub issue using the skill proposal template before opening a pull request. The maintainers can help refine scope before code is written.
79
+
80
+ ## Pull Request Checklist
81
+
82
+ Before submitting a pull request:
83
+
84
+ - add or update `skills/<skill-id>/metadata.json`
85
+ - add or update `skills/<skill-id>/SKILL.md`
86
+ - add runtime code when the skill needs behavior beyond search
87
+ - update `skills/index.json`
88
+ - add tests
89
+ - run `python scripts/validate_skills.py`
90
+ - run `python -m unittest discover -s tests`
91
+ - run `python scripts/smoke_stdio.py`
@@ -0,0 +1,201 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work
38
+ (an example is provided in the Appendix below).
39
+
40
+ "Derivative Works" shall mean any work, whether in Source or Object
41
+ form, that is based on (or derived from) the Work and for which the
42
+ editorial revisions, annotations, elaborations, or other modifications
43
+ represent, as a whole, an original work of authorship. For the purposes
44
+ of this License, Derivative Works shall not include works that remain
45
+ separable from, or merely link (or bind by name) to the interfaces of,
46
+ the Work and Derivative Works thereof.
47
+
48
+ "Contribution" shall mean any work of authorship, including
49
+ the original version of the Work and any modifications or additions
50
+ to that Work or Derivative Works thereof, that is intentionally
51
+ submitted to Licensor for inclusion in the Work by the copyright owner
52
+ or by an individual or Legal Entity authorized to submit on behalf of
53
+ the copyright owner. For the purposes of this definition, "submitted"
54
+ means any form of electronic, verbal, or written communication sent
55
+ to the Licensor or its representatives, including but not limited to
56
+ communication on electronic mailing lists, source code control systems,
57
+ and issue tracking systems that are managed by, or on behalf of, the
58
+ Licensor for the purpose of discussing and improving the Work, but
59
+ excluding communication that is conspicuously marked or otherwise
60
+ designated in writing by the copyright owner as "Not a Contribution."
61
+
62
+ "Contributor" shall mean Licensor and any individual or Legal Entity
63
+ on behalf of whom a Contribution has been received by Licensor and
64
+ subsequently incorporated within the Work.
65
+
66
+ 2. Grant of Copyright License. Subject to the terms and conditions of
67
+ this License, each Contributor hereby grants to You a perpetual,
68
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69
+ copyright license to reproduce, prepare Derivative Works of,
70
+ publicly display, publicly perform, sublicense, and distribute the
71
+ Work and such Derivative Works in Source or Object form.
72
+
73
+ 3. Grant of Patent License. Subject to the terms and conditions of
74
+ this License, each Contributor hereby grants to You a perpetual,
75
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76
+ (except as stated in this section) patent license to make, have made,
77
+ use, offer to sell, sell, import, and otherwise transfer the Work,
78
+ where such license applies only to those patent claims licensable
79
+ by such Contributor that are necessarily infringed by their
80
+ Contribution(s) alone or by combination of their Contribution(s)
81
+ with the Work to which such Contribution(s) was submitted. If You
82
+ institute patent litigation against any entity (including a
83
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
84
+ or a Contribution incorporated within the Work constitutes direct
85
+ or contributory patent infringement, then any patent licenses
86
+ granted to You under this License for that Work shall terminate
87
+ as of the date such litigation is filed.
88
+
89
+ 4. Redistribution. You may reproduce and distribute copies of the
90
+ Work or Derivative Works thereof in any medium, with or without
91
+ modifications, and in Source or Object form, provided that You
92
+ meet the following conditions:
93
+
94
+ (a) You must give any other recipients of the Work or
95
+ Derivative Works a copy of this License; and
96
+
97
+ (b) You must cause any modified files to carry prominent notices
98
+ stating that You changed the files; and
99
+
100
+ (c) You must retain, in the Source form of any Derivative Works
101
+ that You distribute, all copyright, patent, trademark, and
102
+ attribution notices from the Source form of the Work,
103
+ excluding those notices that do not pertain to any part of
104
+ the Derivative Works; and
105
+
106
+ (d) If the Work includes a "NOTICE" text file as part of its
107
+ distribution, then any Derivative Works that You distribute must
108
+ include a readable copy of the attribution notices contained
109
+ within such NOTICE file, excluding those notices that do not
110
+ pertain to any part of the Derivative Works, in at least one
111
+ of the following places: within a NOTICE text file distributed
112
+ as part of the Derivative Works; within the Source form or
113
+ documentation, if provided along with the Derivative Works; or,
114
+ within a display generated by the Derivative Works, if and
115
+ wherever such third-party notices normally appear. The contents
116
+ of the NOTICE file are for informational purposes only and
117
+ do not modify the License. You may add Your own attribution
118
+ notices within Derivative Works that You distribute, alongside
119
+ or as an addendum to the NOTICE text from the Work, provided
120
+ that such additional attribution notices cannot be construed
121
+ as modifying the License.
122
+
123
+ You may add Your own copyright statement to Your modifications and
124
+ may provide additional or different license terms and conditions
125
+ for use, reproduction, or distribution of Your modifications, or
126
+ for any such Derivative Works as a whole, provided Your use,
127
+ reproduction, and distribution of the Work otherwise complies with
128
+ the conditions stated in this License.
129
+
130
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
131
+ any Contribution intentionally submitted for inclusion in the Work
132
+ by You to the Licensor shall be under the terms and conditions of
133
+ this License, without any additional terms or conditions.
134
+ Notwithstanding the above, nothing herein shall supersede or modify
135
+ the terms of any separate license agreement you may have executed
136
+ with Licensor regarding such Contributions.
137
+
138
+ 6. Trademarks. This License does not grant permission to use the trade
139
+ names, trademarks, service marks, or product names of the Licensor,
140
+ except as required for reasonable and customary use in describing the
141
+ origin of the Work and reproducing the content of the NOTICE file.
142
+
143
+ 7. Disclaimer of Warranty. Unless required by applicable law or
144
+ agreed to in writing, Licensor provides the Work (and each
145
+ Contributor provides its Contributions) on an "AS IS" BASIS,
146
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147
+ implied, including, without limitation, any warranties or conditions
148
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149
+ PARTICULAR PURPOSE. You are solely responsible for determining the
150
+ appropriateness of using or redistributing the Work and assume any
151
+ risks associated with Your exercise of permissions under this License.
152
+
153
+ 8. Limitation of Liability. In no event and under no legal theory,
154
+ whether in tort (including negligence), contract, or otherwise,
155
+ unless required by applicable law (such as deliberate and grossly
156
+ negligent acts) or agreed to in writing, shall any Contributor be
157
+ liable to You for damages, including any direct, indirect, special,
158
+ incidental, or consequential damages of any character arising as a
159
+ result of this License or out of the use or inability to use the
160
+ Work (including but not limited to damages for loss of goodwill,
161
+ work stoppage, computer failure or malfunction, or any and all
162
+ other commercial damages or losses), even if such Contributor
163
+ has been advised of the possibility of such damages.
164
+
165
+ 9. Accepting Warranty or Additional Liability. While redistributing
166
+ the Work or Derivative Works thereof, You may choose to offer,
167
+ and charge a fee for, acceptance of support, warranty, indemnity,
168
+ or other liability obligations and/or rights consistent with this
169
+ License. However, in accepting such obligations, You may act only
170
+ on Your own behalf and on Your sole responsibility, not on behalf
171
+ of any other Contributor, and only if You agree to indemnify,
172
+ defend, and hold each Contributor harmless for any liability
173
+ incurred by, or claims asserted against, such Contributor by reason
174
+ of your accepting any such warranty or additional liability.
175
+
176
+ END OF TERMS AND CONDITIONS
177
+
178
+ APPENDIX: How to apply the Apache License to your work.
179
+
180
+ To apply the Apache License to your work, attach the following
181
+ boilerplate notice, with the fields enclosed by brackets "[]"
182
+ replaced with your own identifying information. (Don't include
183
+ the brackets!) The text should be enclosed in the appropriate
184
+ comment syntax for the file format. We also recommend that a
185
+ file or class name and description of purpose be included on the
186
+ same "printed page" as the copyright notice for easier
187
+ identification within third-party archives.
188
+
189
+ Copyright [yyyy] [name of copyright owner]
190
+
191
+ Licensed under the Apache License, Version 2.0 (the "License");
192
+ you may not use this file except in compliance with the License.
193
+ You may obtain a copy of the License at
194
+
195
+ http://www.apache.org/licenses/LICENSE-2.0
196
+
197
+ Unless required by applicable law or agreed to in writing, software
198
+ distributed under the License is distributed on an "AS IS" BASIS,
199
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200
+ See the License for the specific language governing permissions and
201
+ limitations under the License.
@@ -0,0 +1,4 @@
1
+ include LICENSE NOTICE README.md CONTRIBUTING.md uv.lock .python-version .env.example
2
+ recursive-include docs *.md
3
+ recursive-include scripts *.py
4
+ recursive-include skills *.json *.md
@@ -0,0 +1,8 @@
1
+ OpenConstruction Tools
2
+
3
+ Includes code from OC-mcp (https://github.com/Ben11304/OC-mcp),
4
+ distributed under the Apache License, Version 2.0.
5
+
6
+ This distribution has been modified by OpenConstruction, including its CLI,
7
+ catalog matching, hosted MCP authentication, and dataset download services.
8
+ The software license does not replace dataset licenses or provider terms.
@@ -0,0 +1,85 @@
1
+ Metadata-Version: 2.4
2
+ Name: openconstruction-tools
3
+ Version: 0.1.0
4
+ Summary: OpenConstruction MCP server, command-line interface, and shared catalog services.
5
+ Author: OpenConstruction
6
+ License-Expression: Apache-2.0
7
+ Project-URL: Homepage, https://www.openconstruction.org/mcp-cli.html
8
+ Project-URL: Documentation, https://www.openconstruction.org/mcp-cli.html
9
+ Classifier: Development Status :: 4 - Beta
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: Operating System :: OS Independent
12
+ Requires-Python: >=3.11
13
+ Description-Content-Type: text/markdown
14
+ License-File: LICENSE
15
+ License-File: NOTICE
16
+ Requires-Dist: cryptography<51,>=50.0.2
17
+ Requires-Dist: certifi>=2026.10.18
18
+ Requires-Dist: filelock<5,>=4.2.11
19
+ Requires-Dist: fastapi<1,>=0.115
20
+ Requires-Dist: huggingface-hub<2,>=0.25
21
+ Requires-Dist: httpx<1,>=0.27
22
+ Requires-Dist: uvicorn<1,>=0.30
23
+ Dynamic: license-file
24
+
25
+ # OpenConstruction Tools
26
+
27
+ Find and compare construction datasets, models, and other AEC resources.
28
+ Use the CLI in your terminal or connect an MCP client.
29
+
30
+ ## Install
31
+
32
+ Requires Python 3.11 or newer. Once version 0.1.0 is published on PyPI:
33
+
34
+ ```bash
35
+ pip install openconstruction-tools
36
+ ```
37
+
38
+ ## Use the CLI
39
+
40
+ ```bash
41
+ openconstruction search "hardhat" --type dataset
42
+ openconstruction show dataset CHVG
43
+ openconstruction download CHVG
44
+ ```
45
+
46
+ The download command asks you to review the dataset license and confirm.
47
+ Files are saved under `~/.openconstruction/datasets`. For scripts, review the
48
+ terms first, then pass `--accept-license`. Run `openconstruction --help`
49
+ for more commands.
50
+
51
+ Public Zenodo and Figshare records and declared direct file links support
52
+ downloads. Hugging Face and GitHub require a catalog-declared download route;
53
+ Google Drive and other unsupported or restricted sources require the provider's
54
+ own access workflow. Provider credentials remain local.
55
+
56
+ ## Connect MCP
57
+
58
+ For the hosted service, add this HTTP endpoint to your MCP client and sign in
59
+ to OpenConstruction when prompted. No Python installation is needed:
60
+
61
+ ```text
62
+ https://mcp.openconstruction.org/mcp
63
+ ```
64
+
65
+ For local MCP, install this package and configure your client to launch
66
+ `openconstruction-mcp` over stdio. Then ask:
67
+
68
+ > Download the OpenConstruction dataset "CHVG".
69
+
70
+ Review the license and confirm before downloading. Local MCP saves files on
71
+ your computer; remote MCP returns supported public file links for your client
72
+ to save. A client without file-download support can display those links.
73
+ Hosted features depend on the deployed server version.
74
+
75
+ ## Documentation
76
+
77
+ See the [OpenConstruction guide](https://www.openconstruction.org/mcp-cli.html).
78
+ Detailed CLI, MCP, catalog, and hosting guides are also bundled under
79
+ `share/openconstruction/docs` in your Python environment and in the source archive.
80
+
81
+ Developers with repository access can install a checkout with
82
+ `python -m pip install .`. See `docs/development.md` for checks.
83
+
84
+ The software is licensed under Apache 2.0; `LICENSE` and `NOTICE` are included
85
+ in both release archives. Dataset licenses and provider terms apply separately.
@@ -0,0 +1,61 @@
1
+ # OpenConstruction Tools
2
+
3
+ Find and compare construction datasets, models, and other AEC resources.
4
+ Use the CLI in your terminal or connect an MCP client.
5
+
6
+ ## Install
7
+
8
+ Requires Python 3.11 or newer. Once version 0.1.0 is published on PyPI:
9
+
10
+ ```bash
11
+ pip install openconstruction-tools
12
+ ```
13
+
14
+ ## Use the CLI
15
+
16
+ ```bash
17
+ openconstruction search "hardhat" --type dataset
18
+ openconstruction show dataset CHVG
19
+ openconstruction download CHVG
20
+ ```
21
+
22
+ The download command asks you to review the dataset license and confirm.
23
+ Files are saved under `~/.openconstruction/datasets`. For scripts, review the
24
+ terms first, then pass `--accept-license`. Run `openconstruction --help`
25
+ for more commands.
26
+
27
+ Public Zenodo and Figshare records and declared direct file links support
28
+ downloads. Hugging Face and GitHub require a catalog-declared download route;
29
+ Google Drive and other unsupported or restricted sources require the provider's
30
+ own access workflow. Provider credentials remain local.
31
+
32
+ ## Connect MCP
33
+
34
+ For the hosted service, add this HTTP endpoint to your MCP client and sign in
35
+ to OpenConstruction when prompted. No Python installation is needed:
36
+
37
+ ```text
38
+ https://mcp.openconstruction.org/mcp
39
+ ```
40
+
41
+ For local MCP, install this package and configure your client to launch
42
+ `openconstruction-mcp` over stdio. Then ask:
43
+
44
+ > Download the OpenConstruction dataset "CHVG".
45
+
46
+ Review the license and confirm before downloading. Local MCP saves files on
47
+ your computer; remote MCP returns supported public file links for your client
48
+ to save. A client without file-download support can display those links.
49
+ Hosted features depend on the deployed server version.
50
+
51
+ ## Documentation
52
+
53
+ See the [OpenConstruction guide](https://www.openconstruction.org/mcp-cli.html).
54
+ Detailed CLI, MCP, catalog, and hosting guides are also bundled under
55
+ `share/openconstruction/docs` in your Python environment and in the source archive.
56
+
57
+ Developers with repository access can install a checkout with
58
+ `python -m pip install .`. See `docs/development.md` for checks.
59
+
60
+ The software is licensed under Apache 2.0; `LICENSE` and `NOTICE` are included
61
+ in both release archives. Dataset licenses and provider terms apply separately.
@@ -0,0 +1,27 @@
1
+ # Catalog configuration
2
+
3
+ [Back to README](../README.md)
4
+
5
+ The local MCP server and CLI use the deployed OpenConstruction catalog at
6
+ `https://www.openconstruction.org/data` by default, matching the hosted MCP.
7
+ Override `OPENCONSTRUCTION_DATA_BASE_URL` or pass `--data-base-url` to use another
8
+ compatible catalog endpoint.
9
+
10
+ The CLI and MCP use the same `OpenConstructionService`. Catalog results include
11
+ `catalog_provenance`: the source URL, load time, per-file content hashes, an aggregate
12
+ snapshot hash, and any load errors. These hashes identify the fetched JSON content;
13
+ they do not pin future requests to a Git revision. Export selected records to preserve
14
+ the evidence used in a run. Public Zenodo and Figshare source pages can be resolved to downloadable files
15
+ even when the catalog does not include distribution metadata.
16
+
17
+ ## Metadata sources
18
+
19
+ - `/data/datasets.json`
20
+ - `/data/models.json`
21
+ - `/data/use-cases.json`
22
+ - `/data/oer.json`
23
+ - `/data/tools.json`
24
+ - `/data/guides.json`
25
+ - `/data/contributors.json`
26
+ - `/data/benchmark-results.json`
27
+ - `/data/task-vocabulary.json`
@@ -0,0 +1,42 @@
1
+ # Development and skills
2
+
3
+ [Back to README](../README.md)
4
+
5
+ Run these commands from the repository root after installing the package. When using the uv environment, prefix Python commands with `uv run --frozen`.
6
+
7
+ ## Local checks
8
+
9
+ ```bash
10
+ python scripts/validate_skills.py
11
+ python scripts/package_skills.py
12
+ python -m unittest discover -s tests
13
+ python scripts/smoke_stdio.py
14
+ ```
15
+
16
+ Run the MCP server locally:
17
+
18
+ ```bash
19
+ python -m openconstruction_mcp.server
20
+ ```
21
+
22
+ ## Skills
23
+
24
+ Skills are reusable workflows over the MCP tools. The repo-owned skill registry lives at:
25
+
26
+ - `skills/index.json`
27
+ - `skills/<skill-id>/metadata.json`
28
+
29
+ MCP clients can use `list_skills` or `get_skill`.
30
+
31
+ `dataset-discovery` is the first executable skill. It is available through `run_dataset_discovery` and returns ranked dataset candidates, fit reasons, checks, and suggested next actions.
32
+
33
+ To propose a new skill, open a GitHub issue with the skill proposal template. See [CONTRIBUTING.md](../CONTRIBUTING.md) for metadata requirements, review checks, and pull request expectations.
34
+
35
+ Initial official skills focus on:
36
+
37
+ - dataset discovery
38
+ - dataset comparison
39
+ - model discovery
40
+ - schema explanation
41
+ - catalog gap analysis
42
+ - benchmark preparation
@@ -0,0 +1,76 @@
1
+ # Host a remote MCP server
2
+
3
+ [Back to README](../README.md)
4
+
5
+ Target endpoint: `https://mcp.openconstruction.org/mcp`. Publishing this repository does not create a live endpoint. Deploy the backend, publish the website consent page, and configure DNS before sharing the URL with users.
6
+
7
+ ## Deploy on Render
8
+
9
+ The repository includes a [Render Blueprint](../render.yaml) for one Python web service and a 1 GB persistent disk. Applying it creates **paid resources**; review the displayed charges in Render before creating the service. The disk preserves OAuth registrations and tokens across restarts. Keep one service instance while using SQLite.
10
+
11
+ 1. In Render, create a **Blueprint** connected to `ruoxinx/openconstruction-tools`, branch `main`.
12
+ 2. Review `render.yaml`, then provide `SUPABASE_URL` and `SUPABASE_ANON_KEY` from the existing OpenConstruction project. Use the public anon key, not a service-role key.
13
+ 3. Create the service and wait for `/healthz` to pass. Python 3.12 is selected by `.python-version`.
14
+
15
+ The build command `python -m pip install .` installs the repository that Render checks out. Users connecting to the remote MCP do not run this command. `openconstruction-remote` binds to Render's `PORT` on `0.0.0.0`; HTTPS is terminated by the hosting platform.
16
+
17
+ The Blueprint sets:
18
+
19
+ | Variable | Value |
20
+ | --- | --- |
21
+ | `OC_PUBLIC_URL` | `https://mcp.openconstruction.org` |
22
+ | `OC_SITE_URL` | `https://www.openconstruction.org` |
23
+ | `OC_ENV` | `production` |
24
+ | `OC_AUTH_DB` | `/var/data/state.db` |
25
+ | `OC_CORS_ORIGINS` | `https://www.openconstruction.org` |
26
+ | `OPENCONSTRUCTION_DATA_BASE_URL` | `https://www.openconstruction.org/data` |
27
+ | `OC_CONNECTED_ACCOUNTS_ENABLED` | `false` |
28
+
29
+ The public catalog must be reachable from the service. Verify catalog loading from Render before launch; do not silently substitute a different snapshot if access fails. Provider-account connections are disabled and do not require provider client secrets or a token-encryption key for this deployment.
30
+
31
+ ## Publish the consent page
32
+
33
+ The website repository `ruoxinx/open-construction` supplies `/auth/mcp-authorize.html` and its `mcp-authorize.js` and `mcp-authorize.css` assets. Publish these together.
34
+
35
+ The page uses the website's existing Supabase login, preserves the pending request through sign-in, displays the requesting application and callback origin, and requires an explicit **Allow access** or **Cancel** choice. It sends the user's session token only to the fixed MCP backend origin. Keep the page's CSP and the backend's allowed origins aligned when changing domains. Existing Supabase login redirects still use the website's `/auth/callback.html`.
36
+
37
+ ## Configure DNS
38
+
39
+ The Blueprint registers `mcp.openconstruction.org` as a custom domain. In your DNS provider, add:
40
+
41
+ | Type | Name | Target |
42
+ | --- | --- | --- |
43
+ | `CNAME` | `mcp` | The service's actual `<name>.onrender.com` hostname |
44
+
45
+ Verify the domain in Render and wait for its HTTPS certificate. Only the hostname goes in DNS; `/mcp` is an application route. Preserve the main website's DNS records.
46
+
47
+ See [Render custom domains](https://render.com/docs/custom-domains) and [persistent disks](https://render.com/docs/disks).
48
+
49
+ ## Verify the connection
50
+
51
+ Run the read-only deployment check:
52
+
53
+ ```bash
54
+ python scripts/check_remote.py https://mcp.openconstruction.org
55
+ ```
56
+
57
+ Then connect a compatible remote MCP client to `https://mcp.openconstruction.org/mcp`. Complete login and consent, list the tools, and search the public catalog. Test cancelling a connection as well. Restart the backend and verify that an existing client can reconnect and refresh its token.
58
+
59
+ The remote transport returns JSON over Streamable HTTP, supports MCP `2025-06-18` with `2025-03-26` compatibility, and does not offer an SSE subscription. It rejects untrusted browser origins and unsupported protocol headers. Add another trusted browser-client origin explicitly to `OC_CORS_ORIGINS` if needed; native clients without an Origin header are accepted with valid authorization.
60
+
61
+ Remote tools search, compare, and return downloadable file URLs through `download_dataset` after explicit license confirmation. The client transfers the files; remote MCP never saves dataset payloads to the server. Local CLI and stdio MCP retain background downloads, progress, and resume tools. Public OAuth registration should also have deployment-level rate limits before opening the service to broad traffic; the application does not include a distributed rate limiter. Back up the OAuth database using SQLite's backup mechanism.
62
+
63
+ ## Local development
64
+
65
+ ```bash
66
+ python -m pip install -e .
67
+ openconstruction-remote
68
+ ```
69
+
70
+ Without `PORT`, the process binds to `127.0.0.1:8000`. Configure environment variables from [`.env.example`](../.env.example) in your shell; the server does not automatically load that file. `OC_BIND_HOST` overrides the bind address. `OC_PUBLIC_URL` identifies the external OAuth issuer and is independent of the internal listening port.
71
+
72
+ OAuth discovery is available at `/.well-known/oauth-protected-resource/mcp` and `/.well-known/oauth-authorization-server`. The authorization flow uses `/register`, `/authorize`, `/oauth/request/{id}`, `/oauth/consent`, `/token`, and `/revoke`.
73
+
74
+ ## Optional provider connections
75
+
76
+ Connected accounts are disabled by default. To enable them later, configure provider OAuth applications and an `OC_TOKEN_ENCRYPTION_KEY` generated with Fernet, then set `OC_CONNECTED_ACCOUNTS_ENABLED=true`. Provider callbacks are under `/api/connections/{provider}/callback`. This is separate from the MCP client's OpenConstruction login.