elements-mcp 0.1.0__tar.gz

elements_mcp-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.zh-CN.md
+recursive-include src/elements_mcp/content *
+recursive-include docs *.md

elements_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,334 @@
+Metadata-Version: 2.4
+Name: elements-mcp
+Version: 0.1.0
+Summary: MCP server for shared Elements project skills and templates.
+Author: Elements Team
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastmcp==3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+
+# elements-mcp
+
+`elements-mcp` is a local MCP server for shared Elements engineering skills and templates. It exposes repository guidance as read-only MCP resources, tools, and prompts so multiple projects can consume the same standards without copying `.github/skills` into every repository.
+
+This project is intended to be published as an internal Python package. Users install the package, configure Codex to start the MCP server, then ask Codex to read project skills and templates through MCP.
+
+中文工程说明见 [README.zh-CN.md](README.zh-CN.md)。
+
+中文安装与使用说明见 [docs/mcp-user-guide-zh.md](docs/mcp-user-guide-zh.md)。
+
+## Current Scopes
+
+Current scope IDs:
+
+```text
+ui
+partner
+```
+
+The `ui` scope currently contains:
+
+```text
+ui/
+  accessibility-standards/
+  api-integration/
+  code-quality/
+  component-catalog/
+  i18n-usage/
+  license-knowledge/
+  naming-conventions/
+  page-structure/
+  performance-optimization/
+  security-standards/
+  ui-component-guidelines/
+  ui-standard-layout/
+  ui-table-column/
+  ui-table-column-filter/
+```
+
+The `partner` scope is reserved for Partner-specific engineering skills and templates.
+
+## What The MCP Server Provides
+
+Tools:
+
+- `list_skill_scopes()`
+- `list_project_skills(scope: str | None = None)`
+- `read_project_skill(scope: str, skill_name: str)`
+- `search_project_skills(query: str, scope: str | None = None)`
+- `list_skill_templates(scope: str, skill_name: str)`
+- `read_skill_template(scope: str, skill_name: str, template_name: str)`
+
+Resources:
+
+- `elements-skill://{scope}/{skill_name}/SKILL.md`
+- `elements-template://{scope}/{skill_name}/{template_name}`
+
+Prompts:
+
+- `apply_project_skill(scope: str, skill_name: str, task: str)`
+
+## Maintainer Setup
+
+Use this when developing or publishing `elements-mcp`.
+
+```powershell
+cd C:\Code\elements-mcp
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
+```
+
+Run tests:
+
+```powershell
+.\.venv\Scripts\python.exe -m pytest
+```
+
+Run the MCP server directly:
+
+```powershell
+.\.venv\Scripts\python.exe -m elements_mcp.server
+```
+
+The direct server command is a long-running stdio MCP process. In normal usage, Codex starts and manages it.
+
+## Publishing A Package
+
+Install packaging tools:
+
+```powershell
+.\.venv\Scripts\python.exe -m pip install build twine
+```
+
+Build source distribution and wheel:
+
+```powershell
+.\.venv\Scripts\python.exe -m build
+```
+
+Expected output:
+
+```text
+dist/elements_mcp-0.1.0.tar.gz
+dist/elements_mcp-0.1.0-py3-none-any.whl
+```
+
+Publish to the company Python package feed:
+
+```powershell
+.\.venv\Scripts\python.exe -m twine upload --repository-url https://your-private-pypi.example/repository/pypi-internal/ dist/*
+```
+
+Replace the URL with the actual internal PyPI-compatible repository.
+
+## User Installation
+
+Recommended user setup is a dedicated virtual environment. This keeps the MCP server dependency tree separate from system Python and project-specific frontend tooling.
+
+```powershell
+mkdir C:\Tools\elements-mcp
+cd C:\Tools\elements-mcp
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install --index-url https://your-private-pypi.example/repository/pypi-internal/simple elements-mcp==0.1.0
+```
+
+If the package is shared as a wheel file before the internal package feed is ready:
+
+```powershell
+mkdir C:\Tools\elements-mcp
+cd C:\Tools\elements-mcp
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install C:\Path\To\elements_mcp-0.1.0-py3-none-any.whl
+```
+
+Verify the package can be imported:
+
+```powershell
+.\.venv\Scripts\python.exe -c "from elements_mcp.registry import SkillRegistry; print(SkillRegistry().list_scopes())"
+```
+
+Expected output includes:
+
+```text
+['partner', 'ui']
+```
+
+Verify the server can be created:
+
+```powershell
+.\.venv\Scripts\python.exe -c "from elements_mcp.server import create_server; print(create_server().name)"
+```
+
+Expected output:
+
+```text
+Elements MCP
+```
+
+## Codex Configuration For Users
+
+Add the MCP server to the user's Codex config file.
+
+Typical Windows path:
+
+```text
+C:\Users\<user>\.codex\config.toml
+```
+
+Recommended configuration when installed into `C:\Tools\elements-mcp\.venv`:
+
+```toml
+[mcp_servers.elements]
+command = "C:\\Tools\\elements-mcp\\.venv\\Scripts\\python.exe"
+args = ["-m", "elements_mcp.server"]
+cwd = "C:\\Tools\\elements-mcp"
+startup_timeout_sec = 20
+tool_timeout_sec = 60
+```
+
+Restart Codex after editing the config.
+
+Check connection in Codex:
+
+```text
+/mcp
+```
+
+Or from a terminal:
+
+```powershell
+codex mcp list
+```
+
+Expected result: an MCP server named `elements` is listed and available.
+
+## Business Repository Guidance
+
+Each business repository should tell agents to use this MCP server. Add a short note to that repository's `AGENTS.md`.
+
+Example:
+
+```markdown
+## Project Skills
+
+This repository uses the `elements` MCP server for shared project skills and templates.
+
+- For UI work, use scope `ui`.
+- For Partner work, use scope `partner`.
+- Before editing UIStandardLayout pages, read `ui-standard-layout`.
+- Before adding API services, read `api-integration`.
+- Before adding table cell renderers, read `ui-table-column`.
+- Before adding table filters, read `ui-table-column-filter`.
+- Do not hardcode user-visible strings; read `i18n-usage`.
+```
+
+## Example Codex Usage
+
+After the MCP server is connected, users can ask Codex:
+
+```text
+Use the elements MCP server. Read the ui-standard-layout skill from scope ui and the page-shell template before changing this page.
+```
+
+Useful MCP calls for agents:
+
+```text
+list_skill_scopes()
+list_project_skills(scope="ui")
+read_project_skill(scope="ui", skill_name="ui-standard-layout")
+list_skill_templates(scope="ui", skill_name="ui-standard-layout")
+read_skill_template(scope="ui", skill_name="ui-standard-layout", template_name="page-shell.template.mdx")
+```
+
+## Updating Users To A New Version
+
+Publish a new package version, then users upgrade their dedicated environment:
+
+```powershell
+C:\Tools\elements-mcp\.venv\Scripts\python.exe -m pip install --upgrade --index-url https://your-private-pypi.example/repository/pypi-internal/simple elements-mcp==0.2.0
+```
+
+Restart Codex after upgrading.
+
+If a user needs to roll back:
+
+```powershell
+C:\Tools\elements-mcp\.venv\Scripts\python.exe -m pip install --force-reinstall --index-url https://your-private-pypi.example/repository/pypi-internal/simple elements-mcp==0.1.0
+```
+
+## Adding New Skills
+
+Add shared content under:
+
+```text
+src/elements_mcp/content/skills/<scope>/<skill-name>/
+```
+
+Required:
+
+```text
+SKILL.md
+```
+
+Optional:
+
+```text
+templates/*.template.mdx
+```
+
+Example:
+
+```text
+src/elements_mcp/content/skills/ui/new-skill/
+  SKILL.md
+  templates/
+    example.template.mdx
+```
+
+Then run:
+
+```powershell
+.\.venv\Scripts\python.exe -m pytest
+.\.venv\Scripts\python.exe -m build
+```
+
+## Content Rules
+
+- Keep this server read-only.
+- Do not add tools that write files or execute shell commands.
+- Add new shared project guidance under `src/elements_mcp/content/skills/<scope>/<skill-name>`.
+- Each skill directory must contain `SKILL.md`.
+- Optional templates belong under `templates/` inside the skill directory.
+- Use safe names with letters, numbers, dots, underscores, and hyphens only.
+- Pin released package versions for users, such as `elements-mcp==0.1.0`.
+
+## Troubleshooting
+
+`No module named elements_mcp`:
+
+The Codex config is pointing at a Python environment where `elements-mcp` is not installed. Use the Python path from the dedicated virtual environment.
+
+`No module named fastmcp`:
+
+The package was not installed with dependencies. Reinstall with `pip install elements-mcp==<version>` instead of copying source files manually.
+
+`/mcp` does not show `elements`:
+
+Restart Codex after editing `config.toml`, then check that the configured `command` path exists.
+
+Server starts then exits:
+
+Run the configured command manually:
+
+```powershell
+C:\Tools\elements-mcp\.venv\Scripts\python.exe -m elements_mcp.server
+```
+
+If it reports import errors, reinstall the package in that virtual environment.
+
+## References
+
+- Codex MCP configuration: `~/.codex/config.toml`, `[mcp_servers.<name>]`, `/mcp`, and `codex mcp list`
+- FastMCP packaging dependency: `fastmcp==3.0.0`

elements_mcp-0.1.0/README.md

@@ -0,0 +1,323 @@
+# elements-mcp
+
+`elements-mcp` is a local MCP server for shared Elements engineering skills and templates. It exposes repository guidance as read-only MCP resources, tools, and prompts so multiple projects can consume the same standards without copying `.github/skills` into every repository.
+
+This project is intended to be published as an internal Python package. Users install the package, configure Codex to start the MCP server, then ask Codex to read project skills and templates through MCP.
+
+中文工程说明见 [README.zh-CN.md](README.zh-CN.md)。
+
+中文安装与使用说明见 [docs/mcp-user-guide-zh.md](docs/mcp-user-guide-zh.md)。
+
+## Current Scopes
+
+Current scope IDs:
+
+```text
+ui
+partner
+```
+
+The `ui` scope currently contains:
+
+```text
+ui/
+  accessibility-standards/
+  api-integration/
+  code-quality/
+  component-catalog/
+  i18n-usage/
+  license-knowledge/
+  naming-conventions/
+  page-structure/
+  performance-optimization/
+  security-standards/
+  ui-component-guidelines/
+  ui-standard-layout/
+  ui-table-column/
+  ui-table-column-filter/
+```
+
+The `partner` scope is reserved for Partner-specific engineering skills and templates.
+
+## What The MCP Server Provides
+
+Tools:
+
+- `list_skill_scopes()`
+- `list_project_skills(scope: str | None = None)`
+- `read_project_skill(scope: str, skill_name: str)`
+- `search_project_skills(query: str, scope: str | None = None)`
+- `list_skill_templates(scope: str, skill_name: str)`
+- `read_skill_template(scope: str, skill_name: str, template_name: str)`
+
+Resources:
+
+- `elements-skill://{scope}/{skill_name}/SKILL.md`
+- `elements-template://{scope}/{skill_name}/{template_name}`
+
+Prompts:
+
+- `apply_project_skill(scope: str, skill_name: str, task: str)`
+
+## Maintainer Setup
+
+Use this when developing or publishing `elements-mcp`.
+
+```powershell
+cd C:\Code\elements-mcp
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
+```
+
+Run tests:
+
+```powershell
+.\.venv\Scripts\python.exe -m pytest
+```
+
+Run the MCP server directly:
+
+```powershell
+.\.venv\Scripts\python.exe -m elements_mcp.server
+```
+
+The direct server command is a long-running stdio MCP process. In normal usage, Codex starts and manages it.
+
+## Publishing A Package
+
+Install packaging tools:
+
+```powershell
+.\.venv\Scripts\python.exe -m pip install build twine
+```
+
+Build source distribution and wheel:
+
+```powershell
+.\.venv\Scripts\python.exe -m build
+```
+
+Expected output:
+
+```text
+dist/elements_mcp-0.1.0.tar.gz
+dist/elements_mcp-0.1.0-py3-none-any.whl
+```
+
+Publish to the company Python package feed:
+
+```powershell
+.\.venv\Scripts\python.exe -m twine upload --repository-url https://your-private-pypi.example/repository/pypi-internal/ dist/*
+```
+
+Replace the URL with the actual internal PyPI-compatible repository.
+
+## User Installation
+
+Recommended user setup is a dedicated virtual environment. This keeps the MCP server dependency tree separate from system Python and project-specific frontend tooling.
+
+```powershell
+mkdir C:\Tools\elements-mcp
+cd C:\Tools\elements-mcp
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install --index-url https://your-private-pypi.example/repository/pypi-internal/simple elements-mcp==0.1.0
+```
+
+If the package is shared as a wheel file before the internal package feed is ready:
+
+```powershell
+mkdir C:\Tools\elements-mcp
+cd C:\Tools\elements-mcp
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install C:\Path\To\elements_mcp-0.1.0-py3-none-any.whl
+```
+
+Verify the package can be imported:
+
+```powershell
+.\.venv\Scripts\python.exe -c "from elements_mcp.registry import SkillRegistry; print(SkillRegistry().list_scopes())"
+```
+
+Expected output includes:
+
+```text
+['partner', 'ui']
+```
+
+Verify the server can be created:
+
+```powershell
+.\.venv\Scripts\python.exe -c "from elements_mcp.server import create_server; print(create_server().name)"
+```
+
+Expected output:
+
+```text
+Elements MCP
+```
+
+## Codex Configuration For Users
+
+Add the MCP server to the user's Codex config file.
+
+Typical Windows path:
+
+```text
+C:\Users\<user>\.codex\config.toml
+```
+
+Recommended configuration when installed into `C:\Tools\elements-mcp\.venv`:
+
+```toml
+[mcp_servers.elements]
+command = "C:\\Tools\\elements-mcp\\.venv\\Scripts\\python.exe"
+args = ["-m", "elements_mcp.server"]
+cwd = "C:\\Tools\\elements-mcp"
+startup_timeout_sec = 20
+tool_timeout_sec = 60
+```
+
+Restart Codex after editing the config.
+
+Check connection in Codex:
+
+```text
+/mcp
+```
+
+Or from a terminal:
+
+```powershell
+codex mcp list
+```
+
+Expected result: an MCP server named `elements` is listed and available.
+
+## Business Repository Guidance
+
+Each business repository should tell agents to use this MCP server. Add a short note to that repository's `AGENTS.md`.
+
+Example:
+
+```markdown
+## Project Skills
+
+This repository uses the `elements` MCP server for shared project skills and templates.
+
+- For UI work, use scope `ui`.
+- For Partner work, use scope `partner`.
+- Before editing UIStandardLayout pages, read `ui-standard-layout`.
+- Before adding API services, read `api-integration`.
+- Before adding table cell renderers, read `ui-table-column`.
+- Before adding table filters, read `ui-table-column-filter`.
+- Do not hardcode user-visible strings; read `i18n-usage`.
+```
+
+## Example Codex Usage
+
+After the MCP server is connected, users can ask Codex:
+
+```text
+Use the elements MCP server. Read the ui-standard-layout skill from scope ui and the page-shell template before changing this page.
+```
+
+Useful MCP calls for agents:
+
+```text
+list_skill_scopes()
+list_project_skills(scope="ui")
+read_project_skill(scope="ui", skill_name="ui-standard-layout")
+list_skill_templates(scope="ui", skill_name="ui-standard-layout")
+read_skill_template(scope="ui", skill_name="ui-standard-layout", template_name="page-shell.template.mdx")
+```
+
+## Updating Users To A New Version
+
+Publish a new package version, then users upgrade their dedicated environment:
+
+```powershell
+C:\Tools\elements-mcp\.venv\Scripts\python.exe -m pip install --upgrade --index-url https://your-private-pypi.example/repository/pypi-internal/simple elements-mcp==0.2.0
+```
+
+Restart Codex after upgrading.
+
+If a user needs to roll back:
+
+```powershell
+C:\Tools\elements-mcp\.venv\Scripts\python.exe -m pip install --force-reinstall --index-url https://your-private-pypi.example/repository/pypi-internal/simple elements-mcp==0.1.0
+```
+
+## Adding New Skills
+
+Add shared content under:
+
+```text
+src/elements_mcp/content/skills/<scope>/<skill-name>/
+```
+
+Required:
+
+```text
+SKILL.md
+```
+
+Optional:
+
+```text
+templates/*.template.mdx
+```
+
+Example:
+
+```text
+src/elements_mcp/content/skills/ui/new-skill/
+  SKILL.md
+  templates/
+    example.template.mdx
+```
+
+Then run:
+
+```powershell
+.\.venv\Scripts\python.exe -m pytest
+.\.venv\Scripts\python.exe -m build
+```
+
+## Content Rules
+
+- Keep this server read-only.
+- Do not add tools that write files or execute shell commands.
+- Add new shared project guidance under `src/elements_mcp/content/skills/<scope>/<skill-name>`.
+- Each skill directory must contain `SKILL.md`.
+- Optional templates belong under `templates/` inside the skill directory.
+- Use safe names with letters, numbers, dots, underscores, and hyphens only.
+- Pin released package versions for users, such as `elements-mcp==0.1.0`.
+
+## Troubleshooting
+
+`No module named elements_mcp`:
+
+The Codex config is pointing at a Python environment where `elements-mcp` is not installed. Use the Python path from the dedicated virtual environment.
+
+`No module named fastmcp`:
+
+The package was not installed with dependencies. Reinstall with `pip install elements-mcp==<version>` instead of copying source files manually.
+
+`/mcp` does not show `elements`:
+
+Restart Codex after editing `config.toml`, then check that the configured `command` path exists.
+
+Server starts then exits:
+
+Run the configured command manually:
+
+```powershell
+C:\Tools\elements-mcp\.venv\Scripts\python.exe -m elements_mcp.server
+```
+
+If it reports import errors, reinstall the package in that virtual environment.
+
+## References
+
+- Codex MCP configuration: `~/.codex/config.toml`, `[mcp_servers.<name>]`, `/mcp`, and `codex mcp list`
+- FastMCP packaging dependency: `fastmcp==3.0.0`