Skip to content

Commit 7e1f4b4

Browse files
jmhbhjmhbh
authored
Contribution and Development guidelines (#42)
Add contribution and development guidelines --------- Signed-off-by: JM Huibonhoa <jm.huibonhoa@solo.io>
1 parent 7e883a3 commit 7e1f4b4

4 files changed

Lines changed: 314 additions & 0 deletions

File tree

‎CODE_OF_CONDUCT.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# KMCP Community Code of Conduct
2+
3+
All members of the kmcp community must abide by the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md).
4+
Only by respecting one another can we build a strong and collaborative community.

‎CONTRIBUTION.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# Contribution Guidelines
2+
3+
## Development
4+
5+
### Code of Conduct
6+
7+
We are committed to providing a friendly, safe, and welcoming environment for all contributors. Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md).
8+
9+
### Getting Started
10+
11+
1. **Fork the repository** on GitHub.
12+
2. **Clone your fork** locally:
13+
```bash
14+
git clone https://github.com/YOUR-USERNAME/kmcp.git
15+
cd kmcp
16+
```
17+
3. **Add the upstream repository** as a remote:
18+
```bash
19+
git remote add upstream https://github.com/kagent-dev/kmcp.git
20+
```
21+
4. **Create a new branch** for your changes:
22+
```bash
23+
git checkout -b feature/your-feature-name
24+
```
25+
26+
### Development Environment Setup
27+
28+
See the [DEVELOPMENT.md](DEVELOPMENT.md) file for more information.
29+
30+
### Making Changes
31+
32+
If you are making significant improvements to the kmcp project, please create a design document using the [design template](design/template.md) and submit it as a pull request on GitHub.
33+
34+
#### Coding Standards
35+
36+
- **Go Code**:
37+
- Follow the [Go Code Review Comments](https://go.dev/wiki/CodeReviewComments)
38+
- Run `make lint` before submitting your changes
39+
- Ensure all tests pass with `make test`
40+
- Add tests for new functionality
41+
42+
- **Python Code**:
43+
- check formatting with `uv run ruff check`
44+
- check linting with `uv run ruff format`
45+
- Use type hints where appropriate
46+
- Run tests with `uv run pytest`
47+
48+
#### Commit Guidelines
49+
50+
We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
51+
52+
- **feat**: A new feature
53+
- **fix**: A bug fix
54+
- **docs**: Documentation only changes
55+
- **style**: Changes that do not affect the meaning of the code
56+
- **refactor**: A code change that neither fixes a bug nor adds a feature
57+
- **perf**: A code change that improves performance
58+
- **test**: Adding missing tests or correcting existing tests
59+
- **chore**: Changes to the build process or auxiliary tools
60+
61+
Example commit message:
62+
```
63+
feat(controller): add support for custom resource validation
64+
65+
This adds validation for the MCPServer custom resource to ensure
66+
that the configuration is valid before applying it to the cluster.
67+
68+
Closes #123
69+
```
70+
71+
### Pull Request Process
72+
73+
1. **Update your fork** with the latest changes from upstream:
74+
```bash
75+
git fetch upstream
76+
git rebase upstream/main
77+
```
78+
79+
2. **Push your changes** to your fork:
80+
```bash
81+
git push origin feature/your-feature-name
82+
```
83+
84+
3. **Create a Pull Request** from your fork to the main repository.
85+
86+
4. **Fill out the PR template** with all required information.
87+
88+
5. **Address review comments** if requested by maintainers.
89+
90+
6. **Update your PR** if needed:
91+
```bash
92+
git add .
93+
git commit -m "address review comments"
94+
git push origin feature/your-feature-name
95+
```
96+
97+
7. Once approved, a maintainer will merge your PR.
98+
99+
100+
### Documentation
101+
102+
- Update documentation for any changes to APIs, CLIs, or user-facing features
103+
- Add examples for new features
104+
- Update the README if necessary
105+
- Add comments to your code explaining complex logic
106+
107+
### Releasing
108+
109+
Only project maintainers can create releases. The process is:
110+
111+
1. Update version numbers in relevant files
112+
2. Create a release branch
113+
3. Create a tag for the release
114+
4. Build and publish artifacts
115+
5. Create a GitHub release with release notes
116+
117+
### Community
118+
119+
- Join our [Discord server](https://discord.gg/Fu3k65f2k3) for discussions
120+
- Participate in community calls (scheduled on our website)
121+
- Help answer questions in GitHub issues
122+
- Review pull requests from other contributors
123+
124+
## License
125+
126+
By contributing to this project, you agree that your contributions will be licensed under the project's license.
127+
128+
## Questions?
129+
130+
If you have any questions about contributing, please open an issue or reach out to the maintainers.

‎DEVELOPMENT.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Development
2+
3+
- [cmd](cmd): Contains the code for KMCP CLI.
4+
- [pkg/agentgateway](pkg/agentgateway/): Contains the code for the kubernetes controller.
5+
- [pkg/frameworks](pkg/frameworks/): Contains the generator code for the supported MCP frameworks (fastmcp-python, mcp-go).
6+
7+
8+
## How to run everything locally
9+
10+
Running locally.
11+
12+
1. Build the KMCP CLI.
13+
14+
```shell
15+
make build-cli
16+
```
17+
18+
2. Create your mcp project.
19+
20+
```shell
21+
dist/kmcp init python my-mcp-python
22+
```
23+
24+
3. Run project locally via the [mcp inspector](https://github.com/modelcontextprotocol/inspector)
25+
26+
```shell
27+
dist/kmcp run --project-dir ./my-mcp-python/
28+
```
29+
----------------------------------------------------------------
30+
31+
Running in a kubernetes environment.
32+
33+
1. Create a cluster.
34+
35+
```shell
36+
kind create cluster --name kind
37+
```
38+
39+
2. Package the helm chart.
40+
41+
```shell
42+
make helm-package VERSION=<version_number>
43+
```
44+
45+
3. Install the KMCP helm chart.
46+
47+
```shell
48+
helm install kmcp dist/kmcp-<version_number>.tgz --namespace kmcp-system --create-namespace
49+
```
50+
51+
4. Build and load your mcp docker image into the kind cluster.
52+
53+
```bash
54+
dist/kmcp build --project-dir my-mcp-python --kind-load
55+
```
56+
57+
5. Deploy your mcp server.
58+
59+
```bash
60+
kmcp deploy --file my-mcp-python/kmcp.yaml
61+
```
62+
63+
Your MCP server will be automatically port-forwarded on port 3000 and the MCP inspector will be spun up so you can access it on `http://localhost:6274`.

‎design/template.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
<!--
2+
**Note:** When your Enhancement Proposal (EP) is complete, all of these comment blocks should be removed.
3+
4+
This template is inspired by the Kubernetes Enhancement Proposal (KEP) template: https://github.com/kubernetes/enhancements/blob/master/keps/sig-architecture/0000-kep-process/README.md
5+
6+
To get started with this template:
7+
8+
- [ ] **Create an issue in kagent-dev/kmcp**
9+
- [ ] **Make a copy of this template.**
10+
`EP-[ID]: [Feature/Enhancement Name]`, where `ID` is the issue number (with no
11+
leading-zero padding) assigned to your enhancement above.
12+
- [ ] **Fill out this file as best you can.**
13+
At minimum, you should fill in the "Summary" and "Motivation" sections.
14+
- [ ] **Create a PR for this EP.**
15+
Assign it to maintainers with relevant context.
16+
- [ ] **Merge early and iterate.**
17+
Avoid getting hung up on specific details and instead aim to get the goals of
18+
the EP clarified and merged quickly. The best way to do this is to just
19+
start with the high-level sections and fill out details incrementally in
20+
subsequent PRs.
21+
22+
Just because a EP is merged does not mean it is complete or approved. Any EP
23+
marked as `provisional` is a working document and subject to change. You can
24+
denote sections that are under active debate as follows:
25+
26+
```
27+
<<[UNRESOLVED optional short context or usernames ]>>
28+
Stuff that is being argued.
29+
<<[/UNRESOLVED]>>
30+
```
31+
32+
When editing EPS, aim for tightly-scoped, single-topic PRs to keep discussions
33+
focused. If you disagree with what is already in a document, open a new PR
34+
with suggested changes.
35+
36+
One EP corresponds to one "feature" or "enhancement" for its whole lifecycle. Once a feature has become
37+
"implemented", major changes should get new EPs.
38+
-->
39+
# EP-[ID]: [Feature/Enhancement Name]
40+
41+
<!--
42+
This is the title of your EP. Keep it short, simple, and descriptive. A good
43+
title can help communicate what the EP is and should be considered as part of
44+
any review.
45+
-->
46+
47+
* Issue: [#ID](URL to GitHub issue)
48+
49+
## Background
50+
51+
<!--
52+
Provide a brief overview of the feature/enhancement, including relevant background information, origin, and sponsors.
53+
Highlight the primary purpose and how it fits within the broader ecosystem.
54+
55+
Include Motivation, concise overview of goals, challenges, and trade-offs.
56+
57+
-->
58+
59+
## Motivation
60+
61+
<!--
62+
This section is for explicitly listing the motivation, goals, and non-goals of
63+
this EP. Describe why the change is important and the benefits to users. The
64+
motivation section can optionally provide links to [experience reports] to
65+
demonstrate the interest in a EP within the wider Kubernetes community.
66+
67+
[experience reports]: https://github.com/golang/go/wiki/ExperienceReports
68+
-->
69+
70+
### Goals
71+
72+
<!--
73+
74+
List the specific goals of the EP. What is it trying to achieve? How will we
75+
know that this has succeeded?
76+
77+
Include specific, actionable outcomes. Ensure that the goals focus on the scope of
78+
the proposed feature.
79+
-->
80+
81+
82+
### Non-Goals
83+
84+
<!--
85+
What is out of scope for this EP? Listing non-goals helps to focus discussion
86+
and make progress.
87+
-->
88+
89+
## Implementation Details
90+
91+
<!--
92+
This section should contain enough information that the specifics of your
93+
change are understandable. This may include API specs (though not always
94+
required) or even code snippets. If there's any ambiguity about HOW your
95+
proposal will be implemented, this is the place to discuss them.
96+
97+
-->
98+
99+
### Test Plan
100+
101+
<!--
102+
Define the testing strategy for the feature.
103+
Include unit, integration, and end-to-end (e2e) tests.
104+
Specify any additional frameworks or tools required for testing.
105+
-->
106+
107+
## Alternatives
108+
109+
<!--
110+
Highlight potential challenges or trade-offs.
111+
-->
112+
113+
## Open Questions
114+
115+
<!--
116+
Include any unresolved questions or areas requiring feedback.
117+
-->

0 commit comments

Comments
 (0)