agent-plugins MCP server
Commit Sep 20, 2026Packages Python distributions with instructions, skills, and MCP configurations to create portable agent plugins.
Also known as peter-gy/agent-plugins
- Stars
- 5
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Sep 20, 2026
- License
- Apache-2.0
What is agent-plugins MCP?
agent-plugins packages Python distributions with instructions, skills, and MCP configurations to create portable agent plugins.
Summary generated from the project's README
About agent-plugins MCP server
Packaging Python distributions with instructions, skills, and MCP configurations is what agent-plugins enables for developers building portable agent plugins. This library allows you to bundle library code, tool configurations, and resources into a single release. By using this tool, an agent with Python execution capabilities can read packaged instructions and use the library within the same environment.
Developers use the library to create a directory containing a manifest, Agent Skills for instructions, and Model Context Protocol server configurations for tools. You can manage this process through the CLI or the Python API. The system supports integration with the uv build backend by configuring pyproject.toml, or you can use the Hatchling adapter. For existing distributions, the attach-wheel command allows you to update a wheel in place to include plugin metadata.
This approach ensures that skills and MCP configurations remain version-matched with the underlying code. You can inspect installed plugins using the read command via uvx or by calling the read function within a Python script to retrieve specific skills.
What you can do with it
- 1Inspect installed plugin instructionsRetrieve version-matched guidance and skills from a package that has already been installed in your environment.
- 2Access skills via Python APIUse the Python library to programmatically read specific skills or briefings from an installed package.
Written from the project's README. Every use case is checked against a quote from it.
README
View on GitHubagent-plugins ships a Python library and its agent integrations in one package. An agent with Python execution can read its packaged instructions, then use the library in the same environment. Library code, skills, tool configuration, and resources share one release.
The Agent Plugins format defines the directory: a manifest, Agent Skills for instructions and resources, Model Context Protocol (MCP) server configuration for tools, and client extensions. This library packages that directory and makes it discoverable through Python metadata. Agent clients choose which components to activate.
Read the bundled guidance
Run agent-plugins without arguments to read its own installed plugin:
uvx agent-plugins
The output contains two version-matched skills. agent-plugins explains how to
read instructions from Python packages that already ship an Agent Plugin.
package-agent-plugin explains how to add Agent Plugin packaging to a Python
project.
Package your plugin
Keep plugin.json and skills/ beside your code. For a project using the uv build backend, configure pyproject.toml:
[build-system]
requires = ["agent-plugins", "uv_build"]
build-backend = "agent_plugins.build.uv_build"
[tool.agent-plugins]
root = "."
Build with the uv package manager:
uv build
The quickstart creates a complete project, builds it, and locates the installed plugin. Use the Hatchling adapter for Hatchling projects, or attach a prebuilt wheel when another tool owns the build:
agent-plugins attach-wheel dist/my_project-0.1.0-py3-none-any.whl --project .
Attachment updates the wheel in place. Pass --output-dir to preserve the input.
Inspect an installed plugin
Load the complete version-matched guidance shipped by a package:
uvx --with my-package agent-plugins read my-package
The first my-package tells uv which distribution to install. The second
identifies the installed Agent Plugin to read.
Use the Python API when the package is already installed in the current environment:
import agent_plugins as ap
print(ap.read("agent-plugins"))
print(ap.read("agent-plugins", skill="package-agent-plugin"))
read() returns a briefing for the same-name skill by default. Pass skill=
for another workflow. The CLI reads all packaged skills unless --skill is
provided. uvx uses an isolated tool environment, so read through the target
interpreter when working with an existing installation.
Pass your library's distribution name to locate() to inspect its plugin. Use Plugin.from_project() to inspect the selected source files before building.
Documentation
- Get started: package, install, and locate a plugin.
- How packaging works: wheels, source distributions, and editable installs.
- Integrate: read skills, inspect files, and resolve MCP configuration.
- Python API · CLI · Configuration
Development
See development_docs/ for setup, architecture, checks, and releases. Serve the documentation locally with pnpm --dir docs dev.
License
agent-plugins MCP questions
How do I package my own plugin?
Keep your plugin.json and skills/ directory beside your code and configure your pyproject.toml with the agent-plugins build backend.
What does the Agent Plugins format include?
The format defines a directory containing a manifest, Agent Skills for instructions and resources, MCP server configuration for tools, and client extensions.