Mojentic MCP Development Assistant

This skill provides expert guidance for working with the Mojentic MCP library, which provides MCP server and client infrastructure for tools and agentic chat creators.

What This Skill Does

Assists developers working with Mojentic MCP by providing guidance on:

Key Project Features

Code Organization Guidelines

Import Structure

1. Group imports in this order with blank lines between groups:

- Standard library imports

- Third-party library imports

- Local application imports

2. Sort alphabetically within each group

Naming Conventions

Type Hints and Documentation

Logging

Code Conventions

Testing Guidelines

General Rules

BDD-Style Testing

Follow the "Describe/should" pattern for readable, behavior-focused tests.

#### Test Structure

1. Organize tests in classes starting with "Describe" + component name

2. Test methods start with `it_should_` + expected behavior in plain English

3. Follow Arrange/Act/Assert pattern separated by blank lines (no comments)

4. No conditional statements in tests

5. Do NOT test private methods (starting with `_`) - test through public API

#### Fixtures and Mocking

1. Use pytest `@fixture` for test prerequisites

2. Break large fixtures into smaller, reusable ones

3. Place fixtures in module scope for sharing

4. Place module-level fixtures at top of file

5. Use pytest's `mocker` for dependencies

6. Use Mock's spec parameter for type safety: `Mock(spec=SmartMemory)`

7. Only mock our own gateway classes

8. Do NOT mock library internals or private functions

9. Do NOT use unittest or MagicMock directly

#### Best Practices

1. Test organization:

- Place instantiation/initialization tests first

- Group related scenarios together

- Keep tests focused on single behaviors

2. Assertions:

- One assertion per line

- Use `in` operator for partial string matches

- Use `==` for exact matches

3. Test data:

- Use fixtures for reusable prerequisites

- Define complex test data within test methods

#### Example Test

```python

class DescribeSmartMemory:

"""

Tests for the SmartMemory component which handles memory operations

"""

def it_should_be_instantiated_with_chroma_gateway(self):

mock_chroma_gateway = Mock(spec=ChromaGateway)

memory = SmartMemory(mock_chroma_gateway)

assert isinstance(memory, SmartMemory)

assert memory.chroma == mock_chroma_gateway

```

Documentation

MkDocs Setup

Markdown Conventions

API Documentation

Use mkdocstrings with these standard options:

```markdown

::: mojentic.llm.MessageBuilder

options:

show_root_heading: true

merge_init_into_class: false

group_by_category: false

```

Release Process

Follow Semantic Versioning (SemVer): MAJOR.MINOR.PATCH

Preparing a Release

1. **Update CHANGELOG.md**:

- Move items from "[Next]" to new version section

- Add version and date: `## [x.y.z] - YYYY-MM-DD`

- Categorize under: Added, Changed, Deprecated, Removed, Fixed, Security

- Keep empty "[Next]" section at top

2. **Update Version Number**:

- Update version in `pyproject.toml`

- Choose version based on changes (major/minor/patch)

3. **Update Documentation**:

- Review and update `README.md`

- Update files referencing changed features/behaviors

- Ensure installation instructions and examples are current

4. **Final Verification**:

- Run all tests

- Verify application works with updated version

- Check documentation accuracy

MCP Protocol Reference

Core JSON-RPC methods every MCP server must implement (JSON-RPC 2.0):

| Method | Returns | Example Result |

|--------|---------|----------------|

| **initialize** | protocolVersion, capabilities, serverInfo, instructions | `{"protocolVersion":"2025-03-26","capabilities":{"prompts":{"listChanged":true},"resources":{"listChanged":true,"subscribe":true},"tools":{"listChanged":true}},"serverInfo":{"name":"MyMCP","version":"1.2.3"},"instructions":"Welcome!"}` |

| **prompts/list** | prompts array, nextCursor | `{"prompts":[{"name":"code_review","description":"Review code","arguments":[{"name":"code","description":"Source","required":true}]}],"nextCursor":null}` |

| **prompts/get** | description, messages array | `{"description":"Code review prompt","messages":[{"role":"user","content":{"type":"text","text":"Review this code:\n…"}}]}` |

| **resources/list** | resources array, nextCursor | `{"resources":[{"uri":"file:///app/main.py","name":"main.py","mimeType":"text/x-python"}],"nextCursor":null}` |

| **resources/read** | contents array | `{"contents":[{"uri":"file:///app/main.py","mimeType":"text/x-python","text":"print(\"Hello\")"}]}` |

| **resources/templates/list** | resourceTemplates array | `{"resourceTemplates":[{"uriTemplate":"file:///{path}","name":"Any File","mimeType":"application/octet-stream"}]}` |

| **tools/list** | tools array, nextCursor | `{"tools":[{"name":"get_time","description":"Current UTC","inputSchema":{"type":"object","properties":{}}}],"nextCursor":null}` |

| **tools/call** | content array, isError | `{"content":[{"type":"text","text":"2025-05-12T11:30:00Z"}],"isError":false}` |

Instructions for AI Assistant

When working with Mojentic MCP code:

1. Always follow the import structure, naming conventions, and code organization guidelines

2. Use structlog for logging with appropriate log levels and context

3. Write BDD-style tests using the Describe/should pattern with pytest

4. Use fixtures and mocking according to best practices

5. Keep tests focused on single behaviors with clear assertions

6. Document code using Google-style docstrings and type hints

7. Update mkdocs.yml navigation when adding/removing documentation

8. Use mkdocstrings for API documentation with standard options

9. Follow semantic versioning when preparing releases

10. Update CHANGELOG.md, version numbers, and documentation for releases

11. Reference the MCP protocol table when implementing server methods