Metadata-Version: 2.4
Name: elements-mcp
Version: 0.1.10
Summary: MCP server for shared Elements engineering standards, domain knowledge, skills, prompts, and templates.
Author: Andy Li
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastmcp==3.2.4
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"

# elements-mcp

`elements-mcp` is a read-only MCP server for shared Elements engineering standards, domain knowledge, skills, prompts, and templates. It packages project guidance as MCP tools, resources, and prompts so coding agents can consume the same standards across repositories.

Documentation by audience:

- Users: [Chinese installation and MCP client setup guide](docs/install-elements-mcp-user-guide-zh.md)
- Maintainers: [Chinese project maintenance and release guide](README.zh-CN.md)

## Goals and Boundaries

Goals:

- Consolidate shared engineering standards, domain knowledge, skills, prompts, and templates into reusable MCP content.
- Distribute the server as a PyPI package so users can install the latest version by default, while still allowing pinned versions when needed.
- Expose packaged skills, templates, and reusable prompts through MCP tools, resources, and prompts.
- Keep the server read-only to reduce operational and security risk.

Boundaries:

- Tools may list, search, and read packaged skills/templates.
- Tools must not write files, delete files, execute shell commands, install dependencies, or read arbitrary paths outside the package.
- Any future write-capable or execution-capable tools need a separate security design before being added.

## Install

Users install the published package from PyPI:

```shell
python -m pip install --user --upgrade elements-mcp
```

For an isolated install, use the cross-platform Python helper:

```powershell
python scripts\install_elements_mcp.py
```

On macOS/Linux:

```shell
python scripts/install_elements_mcp.py
```

The helper installs the latest `elements-mcp` package into a dedicated virtual environment under:

- Windows: `C:\Tools\elements-mcp`
- macOS/Linux: `~/Tools/elements-mcp`

It does not accept package, version, or install-directory arguments.

Configure MCP clients to run:

```text
python -m elements_mcp.server
```

If using the isolated install, point the MCP client command at:

```text
C:\Tools\elements-mcp\.venv\Scripts\python.exe
```

or on macOS/Linux:

```text
~/Tools/elements-mcp/.venv/bin/python
```

with args:

```json
["-m", "elements_mcp.server"]
```

## MCP Contract

Tools:

- `get_project_guidance(task: str, max_skills: int = 3)`
- `list_project_skills()`
- `read_project_skill(skill_name: str)`
- `search_project_skills(query: str)`
- `list_skill_templates(skill_name: str)`
- `read_skill_template(skill_name: str, template_name: str)`

Resources:

- `elements-skill://{skill_name}/SKILL.md`
- `elements-template://{skill_name}/{template_name}`

Prompts:

- `apply_project_skill(skill_name: str, task: str)`
- `check-i18n`
- `create-filter-table`

All tools should be read-only, non-destructive, idempotent, and closed-world.

## Recommended Host Flow

The current project, IDE integrations, or other AI hosts should call `get_project_guidance` automatically with the user's original task before asking the AI to code. Users should not need to type MCP tool names.

If `matched` is `true`, inject the returned `guidance` into the AI request. If `matched` is `false`, continue with normal coding behavior and do not invent project-specific rules.

## Repository Layout

```text
elements-mcp/
  README.md
  README.zh-CN.md
  MANIFEST.in
  pyproject.toml
  docs/
    install-elements-mcp-user-guide-zh.md
  scripts/
    install_elements_mcp.py
    publish-pypi.ps1
    pypi-publish.env.example.ps1
    update-package-metadata.ps1
  src/
    elements_mcp/
      __init__.py
      server.py
      tools/
      resources/
        registry.py
        handlers.py
        content/
          skills/
      prompts/
        registry.py
        handlers.py
        content/
  tests/
```

## Key Files

- `pyproject.toml`: Python package metadata, dependencies, entry points, package data, and pytest configuration.
- `MANIFEST.in`: source distribution rules; keeps runtime content and excludes `docs/`.
- `src/elements_mcp/server.py`: FastMCP assembly layer that registers tools, resources, and prompts.
- `src/elements_mcp/tools/`: MCP tool registration and implementations.
- `src/elements_mcp/resources/`: MCP resource handlers, skill/template registry, and packaged resource content.
- `src/elements_mcp/prompts/`: MCP prompt handlers, prompt registry, and packaged prompt content.
- `tests/`: development and pre-release verification; not a user runtime dependency.
- `docs/install-elements-mcp-user-guide-zh.md`: user installation and MCP client setup guide.
- `scripts/install_elements_mcp.py`: cross-platform isolated-install helper; installs the latest `elements-mcp` from PyPI under `Tools/elements-mcp`.
- `scripts/publish-pypi.ps1`: maintainer release script for test, build, Twine check, and upload.
- `scripts/update-package-metadata.ps1`: maintainer helper for synchronizing package name/version text.

## Content Maintenance

Add skills under:

```text
src/elements_mcp/resources/content/skills/<skill-name>/
  SKILL.md
  templates/
    example.template.mdx
```

Add prompts under:

```text
src/elements_mcp/prompts/content/<prompt-name>.prompt.md
```

Rules:

- Every skill must include `SKILL.md`.
- `templates/` is optional.
- Skill and template file names should use letters, digits, dots, underscores, and hyphens.
- Do not use spaces, non-ASCII file names, path separators, or special characters in skill/template names.
- Put long reusable examples in `templates/*.template.mdx` instead of making a single `SKILL.md` too large.

## Local Development

Maintainers should use the project-root `.venv` for development, testing, and publishing. Do not install development tools into the global Python environment or user site-packages.

```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
```

Verify the skill registry:

```powershell
.\.venv\Scripts\python.exe -c "from elements_mcp.resources.registry import SkillRegistry; print([skill.name for skill in SkillRegistry().list_skills()])"
```

Verify server creation:

```powershell
.\.venv\Scripts\python.exe -c "from elements_mcp.server import create_server; print(create_server().name)"
```

## Build and Publish

After changing code or packaged content, update the version before publishing a new package and rebuild clean distribution artifacts.

Publishing also uses only the project-root `.venv`. `scripts\publish-pypi.ps1` calls `.\.venv\Scripts\python.exe`, so initialize the local development environment first and install the build tools into that `.venv`:

```powershell
.\.venv\Scripts\python.exe -m pip install -U build twine
```

For normal publishing, run the one-step script. It cleans `dist/`, runs tests, builds distributions, runs `twine check`, and uploads:

```powershell
.\scripts\publish-pypi.ps1
```

Publish to a non-default repository:

```powershell
.\scripts\publish-pypi.ps1 -Repository <repository-name>
```

Expected artifacts:

```text
dist/elements_mcp-<version>.tar.gz
dist/elements_mcp-<version>-py3-none-any.whl
```

If you need to troubleshoot build or publish failures, run the script's main steps manually:

```powershell
Remove-Item -LiteralPath dist -Recurse -Force -ErrorAction SilentlyContinue
.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe -m build
.\.venv\Scripts\python.exe -m twine check dist/*
```

When publishing a new version:

1. Update `version` in `pyproject.toml`.
2. If needed, run `.\scripts\update-package-metadata.ps1 -Version <version> -WhatIf` to preview version text updates, then rerun without `-WhatIf`.
3. Confirm `scripts/pypi-publish.env.ps1` is configured with a PyPI token and keeps `TWINE_USERNAME` as `__token__`.
4. Run `.\scripts\publish-pypi.ps1`.
5. If the script fails, fix the failure and rerun the same command.
6. Confirm the new version appears at https://pypi.org/project/elements-mcp/.
7. Verify installation in a clean virtual environment:

```powershell
python -m venv C:\Temp\elements-mcp-publish-check
C:\Temp\elements-mcp-publish-check\Scripts\python.exe -m pip install elements-mcp==<version>
C:\Temp\elements-mcp-publish-check\Scripts\python.exe -c "from elements_mcp.server import create_server; print(create_server().name)"
```

8. Tell users to rerun the PyPI update command from the user guide. By default they upgrade to the latest version; use `elements-mcp==<version>` only for rollback or staged verification.

`src/elements_mcp/__init__.py` reads `__version__` from the installed package metadata, so it does not need separate manual version maintenance.

## Scripts

- `scripts/install_elements_mcp.py`: cross-platform isolated-install helper for users; installs latest `elements-mcp` under `Tools/elements-mcp`.
- `scripts/publish-pypi.ps1`: maintainer release script for test, build, Twine check, and upload.
- `scripts/update-package-metadata.ps1`: maintainer helper for synchronizing package name/version text.
- `scripts/pypi-publish.env.example.ps1`: local PyPI token template. The real `pypi-publish.env.ps1` file stays untracked.

## Documentation Map

- `README.md`: English entry point for project purpose, installation, MCP contract, and maintainer workflow.
- `README.zh-CN.md`: Chinese maintainer guide for project maintenance, build, release, and content rules.
- `docs/install-elements-mcp-user-guide-zh.md`: Chinese user guide for installing `elements-mcp`, configuring MCP clients, and troubleshooting connection issues.
