Skip to content

Commit 8c83891

Browse files
matsjfunkematsjfunke
authored
Merge pull request #4 from matsjfunke/docs
2 parents 605b42f + c0ccb36 commit 8c83891

File tree

12 files changed

+375
-59
lines changed

12 files changed

+375
-59
lines changed

‎.github/ISSUE_TEMPLATE/bug_report.yml

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
name: Bug Report
2+
description: Report a bug or unexpected behavior
3+
title: "[Bug]: "
4+
labels: ["bug"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Thanks for taking the time to report a bug 🫶 ! Please fill out the information below to help us investigate.
10+
11+
- type: textarea
12+
id: description
13+
attributes:
14+
label: Bug Description
15+
description: A clear and concise description of what the bug is.
16+
placeholder: Describe what happened and what you expected to happen instead.
17+
validations:
18+
required: true
19+
20+
- type: textarea
21+
id: reproduction
22+
attributes:
23+
label: Steps to Reproduce
24+
description: Steps to reproduce the behavior
25+
validations:
26+
required: true
27+
28+
- type: textarea
29+
id: expected
30+
attributes:
31+
label: Expected Behavior
32+
description: What you expected to happen
33+
validations:
34+
required: true
35+
36+
- type: textarea
37+
id: actual
38+
attributes:
39+
label: Actual Behavior
40+
description: What actually happened (include full error message if applicable)
41+
validations:
42+
required: true
43+
44+
- type: textarea
45+
id: additional-context
46+
attributes:
47+
label: Additional Context
48+
description: Any other context about the problem here.

‎.github/ISSUE_TEMPLATE/config.yml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
blank_issues_enabled: true
2+
contact_links:
3+
- name: 📖 Documentation
4+
url: https://github.com/matsjfunke/paperclip/blob/main/README.md
5+
about: Check the README for documentation

‎.github/ISSUE_TEMPLATE/feature_request.yml

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
name: Feature Request
2+
description: Suggest a new feature or improvement
3+
title: "[Feature]: "
4+
labels: ["enhancement"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Thanks for suggesting a new feature! Please fill out the information below to help us understand your request.
10+
11+
- type: textarea
12+
id: summary
13+
attributes:
14+
label: Feature Summary
15+
description: A clear and concise description of the feature you'd like to see added.
16+
placeholder: Briefly describe the feature you're requesting.
17+
validations:
18+
required: true
19+
20+
- type: textarea
21+
id: problem
22+
attributes:
23+
label: Problem or Use Case
24+
description: What problem does this feature solve? What use case does it address?
25+
placeholder: |
26+
e.g., "I often need to... but currently paperclip doesn't support..."
27+
or "It would be helpful if paperclip could..."
28+
validations:
29+
required: true
30+
31+
- type: textarea
32+
id: solution
33+
attributes:
34+
label: Proposed Solution
35+
description: How would you like this feature to work?
36+
placeholder: |
37+
Describe your ideal solution. Consider:
38+
- What command/option would trigger this feature?
39+
- What would the output look like?
40+
- How should it interact with existing features?
41+
validations:
42+
required: true
43+
44+
- type: textarea
45+
id: alternatives
46+
attributes:
47+
label: Alternatives Considered
48+
description: Have you considered any alternative solutions or workarounds?
49+
placeholder: |
50+
e.g., "I currently work around this by..."
51+
or "Other tools like X handle this by..."
52+
53+
- type: textarea
54+
id: additional-context
55+
attributes:
56+
label: Additional Context
57+
description: |
58+
Any other context, screenshots, or examples that would help us understand your request.

‎.github/ISSUE_TEMPLATE/question.yml

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
name: Question
2+
description: Ask a question about paperclip
3+
title: "[Question]: "
4+
labels: ["question"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Have a question about paperclip? We're here to help! Please provide as much detail as possible.
10+
11+
- type: textarea
12+
id: question
13+
attributes:
14+
label: Your Question
15+
description: What would you like to know about paperclip?
16+
placeholder: Ask your question here...
17+
validations:
18+
required: true
19+
20+
- type: textarea
21+
id: context
22+
attributes:
23+
label: Context
24+
description: |
25+
What are you trying to achieve? Providing context helps us give better answers.
26+
placeholder: |
27+
e.g., "I'm trying to understand how paperclip handles..."
28+
or "I want to use paperclip to..."
29+
30+
- type: checkboxes
31+
id: checklist
32+
attributes:
33+
label: Checklist
34+
description: Please confirm you've done the following
35+
options:
36+
- label: I've checked the README and documentation
37+
required: true
38+
- label: I've searched existing issues for similar questions
39+
required: true
40+
41+
- type: textarea
42+
id: additional-info
43+
attributes:
44+
label: Additional Information
45+
description: Any other details that might be helpful

‎.github/pull_request_template.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
## Description
2+
3+
Brief description of what this PR does.
4+
5+
## Changes Made
6+
7+
- [ ] List specific changes
8+
- [ ] Include any new features
9+
- [ ] Mention any bug fixes
10+
11+
## Testing
12+
13+
- [ ] All existing tests pass
14+
- [ ] Added tests for new functionality (if applicable)
15+
- [ ] Tested base functonality manually with MCP Inspector
16+
17+
## Related Issues
18+
19+
Closes #[issue-number] (if applicable)
20+
21+
## Additional Notes
22+
23+
Any additional context or considerations for reviewers.

‎.github/workflows/ping-server.yml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
name: Ping MCP Server
1+
name: Ping / Health Check Paperclip Server
22

33
on:
44
schedule:
@@ -87,4 +87,4 @@ jobs:
8787
if: success()
8888
run: |
8989
echo "✅ Server ping successful!"
90-
echo "🟢 MCP server is healthy and responsive"
90+
echo "🟢 Paperclip server is healthy and responsive"

‎.github/workflows/tests.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
name: Run Tests
22

33
on:
4+
push:
5+
branches: [main]
46
workflow_dispatch:
57

68
jobs:

‎CONTRIBUTING.md

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# Contributing to Paperclip
2+
3+
Thank you for your interest in contributing to Paperclip! This guide will help you get started with development.
4+
5+
## Development Setup
6+
7+
### Prerequisites
8+
9+
- Python 3.12+
10+
- pip
11+
12+
### Installation
13+
14+
1. **Fork and clone the repository**
15+
16+
- Fork this repository on GitHub
17+
- Clone your fork:
18+
19+
```bash
20+
git clone https://github.com/YOUR_USERNAME/paperclip.git
21+
cd paperclip
22+
```
23+
24+
2. **Create and activate virtual environment**
25+
26+
```bash
27+
python -m venv .venv
28+
source .venv/bin/activate # On Windows: .venv\Scripts\activate
29+
```
30+
31+
3. **Install dependencies**
32+
33+
```bash
34+
pip install -r requirements.txt
35+
```
36+
37+
4. **Add dependencies**
38+
```bash
39+
pip install <new-lib>
40+
pip freeze > requirements.txt
41+
```
42+
43+
### Running the Server with Hot Reload
44+
45+
```bash
46+
# Run with hot reload
47+
watchmedo auto-restart --patterns="*.py" --recursive -- python src/server.py
48+
# Run Server using fastmcp
49+
fastmcp run src/server.py --transport http --host 0.0.0.0 --port 8000
50+
# use docker compose
51+
docker-compose up --build
52+
```
53+
54+
The server will automatically restart when you make changes to any `.py` files.
55+
56+
## Testing
57+
58+
Use the [MCP Inspector](https://inspector.modelcontextprotocol.io/) to interact with the server.
59+
60+
```bash
61+
pnpx @modelcontextprotocol/inspector
62+
```
63+
64+
### Unit Tests
65+
66+
Run the unit tests to verify the functionality of individual components:
67+
68+
```bash
69+
# Run all tests
70+
python -m unittest discover tests -v
71+
```
72+
73+
## Contributing Changes
74+
75+
### Creating a Pull Request
76+
77+
1. **Create a feature branch**
78+
79+
```bash
80+
git checkout -b feat/your-feature-name
81+
# or for bug fixes:
82+
git checkout -b fix/issue-description
83+
```
84+
85+
2. **Make your changes**
86+
87+
- Write your code following the existing style
88+
- Add tests for new functionality
89+
- Update documentation as needed
90+
91+
3. **Commit your changes and push to your fork**
92+
93+
```bash
94+
git push origin feat/your-feature-name
95+
```
96+
97+
4. **Open a Pull Request**
98+
99+
- Go to the original repository on GitHub
100+
- Click "New Pull Request"
101+
- Select your branch from your fork
102+
- Fill out the PR template with:
103+
- Clear description of changes
104+
- Link to related issues (if applicable)
105+
- Testing steps you've performed
106+
107+
### Pull Request Guidelines
108+
109+
- **Keep PRs focused**: One feature or fix per PR
110+
- **Write clear descriptions**: Explain what changes you made and why
111+
- **Test your changes**: Ensure all tests pass before submitting
112+
- **Update documentation**: Add or update docs for new features
113+
- **Be responsive**: Address feedback and questions promptly

0 commit comments

Comments
 (0)