@magek/mcp-server 0.0.8

package/docs/contributing.md

@@ -0,0 +1,349 @@
+---
+title: "Contributing"
+group: "Guides"
+---
+
+# Contributing to Magek
+
+> **DISCLAIMER:** The Magek docs are undergoing an overhaul. Most of what's written here applies, but expect some hiccups in the build process
+> that is described here, as it changed in the last version. New documentation will have this documented properly.
+
+Thanks for taking the time to contribute to Magek. It is an open-source project and it wouldn't be possible without people like you 🙏🎉
+
+This document is a set of guidelines to help you contribute to Magek, which is hosted on the [`theam/magek`](https://github.com/theam/magek) GitHub
+repository. These aren’t absolute laws, use your judgment and common sense 😀.
+Remember that if something here doesn't make sense, you can also propose a change to this document.
+
+## Code of Conduct
+
+This project and everyone participating in it are expected to uphold the [Magek's Code of Conduct](https://github.com/theam/magek/blob/main/CODE_OF_CONDUCT.md), based on the Covenant Code of Conduct.
+If you see unacceptable behavior, please communicate so to `info@theagilemonkeys.com`.
+
+## I don't want to read this whole thing, I just have a question
+
+Go ahead and ask the community in [Discord](https://discord.com/invite/bDY8MKx) or [create a new issue](https://github.com/theam/magek/issues).
+
+## What should I know before I get started?
+
+### Packages
+
+Magek is divided in many different packages. The criteria to split the code in packages is that each package meets at least one of the following conditions:
+
+- They must be run separately, for instance, the CLI is run locally, while the server code runs as a standalone server or serverless function.
+- They contain code that is used by at least two of the other packages.
+- They're an adapter implementation of some abstract part of the framework (for instance, the storage adapter packages).
+
+The packages are managed using [rush](https://rushjs.io/) and [npm](https://npmjs.com), if you run `rush build`, it will build all the packages.
+
+The packages are published to `npmjs` under the prefix `@magek/`, their purpose is as follows:
+
+- `cli` - You guessed it! This package is the `magek` command-line tool, it interacts only with the core package in order to load the project configuration.
+- `core` - This one contains all the framework runtime logic. Stuff like the generation of the config or the commands and events handling happens here.
+- `server` - Local development server with Fastify-based HTTP, WebSocket, SSE support, and all infrastructure components.
+- `common` - This package defines shared types and helpers used across all other packages. It includes the main Magek concepts like:
+  - Entity
+  - Command
+  - etc…
+
+This is a dependency graph that shows the dependencies among all packages, including the application using Magek:
+![Magek packages dependencies](https://raw.githubusercontent.com/theam/magek/main/docs/img/packages-dependencies.png)
+
+## How Can I Contribute?
+
+Contributing to an open source project is never just a matter of code, you can help us significantly by just using Magek and interacting with our community. Here you'll find some tips on how to do it effectively.
+
+### Reporting Bugs
+
+Before creating a bug report, please search for similar issues to make sure that they're not already reported. If you don't find any, go ahead and create an issue including as many details as possible. Fill out the required template, the information requested helps us to resolve issues faster.
+
+> **Note:**
+> If you find a Closed issue that seems related to the issues that you're experiencing, make sure to reference it in the body of your new one by writing its number like this => #42 (Github will autolink it for you).
+
+Bugs are tracked as GitHub issues. Explain the problem and include additional details to help maintainers reproduce the problem:
+
+- Use a clear and descriptive title for the issue to identify the problem.
+- Describe the exact steps which reproduce the problem in as many details as possible.
+- Provide specific examples to demonstrate the steps. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples. If you're providing snippets in the issue, use Markdown code blocks.
+- Describe the behavior you observed after following the steps and point out what exactly is the problem with that behavior.
+- Explain which behavior you expected to see instead and why.
+- If the problem is related to performance or memory, include a CPU profile capture with your report.
+
+### Suggesting Enhancements
+
+Enhancement suggestions are tracked as GitHub issues. Make sure you provide the following information:
+
+- Use a clear and descriptive title for the issue to identify the suggestion.
+- Provide a step-by-step description of the suggested enhancement in as many details as possible.
+- Provide specific examples to demonstrate the steps. Include copy/pasteable snippets which you use in those examples, as Markdown code blocks.
+- Describe the current behavior and explain which behavior you expected to see instead and why.
+- Explain why this enhancement would be useful to most Magek users and isn't something that can or should be implemented as a community package.
+- List some other libraries or frameworks where this enhancement exists.
+
+### Improving documentation
+
+[Magek documentation](https://docs.magek.ai) is treated as a live document that continues improving on a daily basis. If you find something that is missing or can be improved, please contribute, it will be of great help for other developers.
+To contribute you can use the button "Edit on github" at the top of each chapter.
+
+#### Documentation principles and practices
+
+The ultimate goal of a technical document is to translate the knowledge from the technology creators into the reader's mind so that they learn. The challenging
+part here is the one in which they learn. It is challenging because, under the same amount of information, a person can suffer an information overload because
+we (humans) don't have the same information-processing capacity. That idea is going to work as our compass, it should drive our efforts so people with less
+capacity is still able to follow and understand our documentation.
+
+To achieve our goal we propose writing documentation following these principles:
+
+1. Clean and Clear
+2. Simple
+3. Coherent
+4. Explicit
+5. Attractive
+6. Inclusive
+7. Cohesive
+
+##### Principles
+
+**1. Clean and Clear**
+
+Less is more. Apple is, among many others, a good example of creating clean and clear content, where visual elements are carefully chosen to look beautiful
+(e.g. [Apple's swift UI](https://developer.apple.com/tutorials/swiftui)) and making the reader getting the point as soon as possible.
+
+The intention of every section, paragraph, and sentence must be clear, we should avoid writing details of two different things even when they are related.
+It is better to link pages and keep the focus and the intention clear, Wikipedia is the best example on this.
+
+**2. Simple**
+
+Technical writings deal with different backgrounds and expertise from the readers. We should not assume the reader knows everything we are talking about
+but we should not explain everything in the same paragraph or section. Every section has a goal to stick to the goal and link to internal or external resources
+to go deeper.
+
+Diagrams are great tools, you know a picture is worth more than a thousand words unless that picture contains too much information.
+Keep it simple intentionally omitting details.
+
+**3. Coherent**
+
+The documentation tells a story. Every section should integrate naturally without making the reader switch between different contexts. Text, diagrams,
+and code examples should support each other without introducing abrupt changes breaking the reader’s flow. Also, the font, colors, diagrams, code samples,
+animations, and all the visual elements we include, should support the story we are telling.
+
+**4. Explicit**
+
+Go straight to the point without assuming the readers should know about something. Again, link internal or external resources to clarify.
+
+The index of the whole content must be visible all the time so the reader knows exactly where they are and what is left.
+
+**5. Attractive**
+
+Our text must be nice to read, our diagrams delectable to see, and our site… a feast for the eyes!!
+
+**6. Inclusive**
+
+Everybody should understand our writings, especially the topics at the top. We have arranged the documentation structure in a way that anybody can dig
+deeper by just going down so, sections 1 to 4 must be suitable for all ages.
+
+Use gender-neutral language to avoid the use of he, him, his to refer to undetermined gender. It is better to use their or they as a gender-neutral
+approach than s/he or similars.
+
+**7. Cohesive**
+
+Writing short and concise sentences is good, but remember to use proper connectors (“Therefore”, “Besides”, “However”, “thus”, etc) that provide a
+sense of continuation to the whole paragraph. If not, when people read the paragraphs, their internal voice sounds like a robot with unnatural stops.
+
+For example, read this paragraph and try to hear your internal voice:
+
+> Entities are created on the fly, by reducing the whole event stream. You shouldn't assume that they are stored anywhere.  Magek does create
+automatic snapshots to make the reduction process efficient. You are the one in charge of writing the reducer function.
+
+And now read this one:
+
+> Entities are created on the fly by reducing the whole event stream. While you shouldn't assume that they are stored anywhere,  Magek does create automatic
+snapshots to make the reduction process efficient. In any case, this is opaque to you and the only thing you should care is to provide the reducer function.
+
+Did you feel the difference? The latter makes you feel that everything is connected, it is more cohesive.
+
+##### Practices
+
+There are many writing styles depending on the type of document. It is common within technical and scientific writing to use Inductive and/or Deductive styles
+for paragraphs. They have different outcomes and one style may suit better in one case or another, that is why it is important to know them, and decide which
+one to use in every moment. Let’s see the difference with 2 recursive examples.
+
+**Deductive paragraphs ease the reading for advanced users but still allows you to elaborate on ideas and concepts for newcomers**. In deductive paragraphs,
+the conclusions or definitions appear at the beginning, and then, details, facts, or supporting phrases complete the paragraph’s idea. By placing the
+conclusion in the first sentence, the reader immediately identifies the main point so they can decide to skip the whole paragraph or keep reading.
+If you take a look at the structure of this paragraph, it is deductive.
+
+On the other hand, if you want to drive the readers' attention and play with it as if they were in a roller coaster, you can do so by using a different approach.
+In that approach, you first introduce the facts and ideas and then you wrap them with a conclusion. This style is more narrative and forces the reader to
+continue because the main idea is diluted in the whole paragraph. Once all the ideas are placed together, you can finally conclude the paragraph. **This style is
+called Inductive.**
+
+The first paragraph is deductive and the last one is inductive. In general, it is better to use the deductive style, but if we stick to one, our writing will start looking weird and maybe boring.
+So decide one or another being conscious about your intention.
+
+### Create your very first GitHub issue
+
+[Click here](https://github.com/theam/magek/issues/new) to start making contributions to Magek.
+
+## Your First Code Contribution
+
+Unsure where to begin contributing to Magek? You can start by looking through issued tagged as `good-first-issue` and `help-wanted`:
+
+- Beginner issues - issues which should only require a few lines of code, and a test or two.
+- Help wanted issues - issues which should be a bit more involved than beginner issues.
+
+Both issue lists are sorted by the total number of comments. While not perfect, number of comments is a reasonable proxy for impact a given change will have.
+
+Make sure that you assign the chosen issue to yourself to communicate your intention to work on it and reduce the possibilities of other people taking the same assignment.
+
+### Getting the code
+
+To start contributing to the project you would need to set up the project in your system, to do so, you must first follow these steps in your terminal.
+
+- Install Rush: `npm install -g @microsoft/rush`
+
+- Clone the repo and get into the directory of the project: `git clone https://github.com/theam/magek.git && cd magek`
+
+- Install project dependencies: `rush update`
+
+- Compile the project `rush build`
+
+- Add your contribution
+
+- Make sure everything works by [executing the unit tests](#running-unit-tests): `rush rest`
+
+### Understanding the "rush monorepo" approach and how dependencies are structured in the project
+
+The Magek Framework project is organized following the ["rush monorepo"](https://rushjs.io/) structure. There are several "package.json" files and each one has its purpose with regard to the dependencies you include on them:
+
+- The "package.json" files that are on each package root should contain the dependencies used by that specific package. Be sure to correctly differentiate which dependency is only for development and which one is for production.
+
+Finally, **always use exact numbers for dependency versions**. This means that if you want to add the dependency "graphql" in version 1.2.3, you should add `"graphql": "1.2.3"` to the corresponding "package.json" file, and never `"graphql": "^1.2.3"` or `"graphql": "~1.2.3"`. This restriction comes from hard problems we've had in the past.
+
+### Running unit tests
+
+Unit tests are executed when you type `rush test`. If you want to run the unit tests for an especific package, you should move to the corresponding folder and run one of the following commands:
+
+- `rushx test:cli -v`: Run unit tests for the `cli` package.
+- `rushx test:core -v`: Run unit tests for the `core` package.
+- `rushx test:server -v`: Run unit tests for the `server` package.
+- `rushx test:common -v`: Run unit tests for the `common` package.
+
+- `doc/*` - PR that enhances the documentation
+
+In the right side of the branch name you can include the GitHub issue number. An example of doing this could be:
+
+```bash
+git checkout -b feature/XXX_add-an-awesome-new-feature
+```
+
+(where `XXX` is the issue number)
+
+### Commit message guidelines
+
+The merge commit message should be structured following the [conventional commits](https://www.conventionalcommits.org/) standard:
+
+```text
+<commit type>([optional scope]): <description>
+```
+
+As an example:
+
+```text
+fix(cli): Correct minor typos in code
+```
+
+The most important kind of commits are the ones that trigger version bumps and therefore a new release in the CI/CD system:
+
+- `fix` - patch version bump (`0.0.x`)
+- `feat` - minor version bump (`0.x.0`)
+- Any commit type followed by `!`, i.e. `feat!` - major version bump (`x.0.0`)
+
+Apart from those previously mentioned, there are more commit types:
+
+- **build**: Changes that affect the build system or external dependencies (example scopes: rush, tsconfig, npm)
+- **ci**: Changes to our CI configuration files and scripts
+- **docs**: Documentation only changes
+- **feat**: A new feature
+- **fix**: A bug fix
+- **perf**: A code change that improves performance
+- **refactor**: A code change that neither fixes a bug nor adds a feature
+- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
+- **test**: Adding missing tests or correcting existing tests
+
+We're using the following scopes in the project:
+
+- **cli**
+- **core**
+- **common**
+- **server**
+
+Apart of using conventional commits for triggering releases, we use them to build the project changelog.
+
+## Code Style Guidelines
+
+The Magek project comes with a nice set of ESLint config files to help you follow a consistent style, and we really encourage to use it in your editor. You can also run the `rush run lint:fix` commands to try solving any linter problems automatically.
+
+For everything else, the rule of thumb is: Try to be consistent with the code around yours, and if you're not sure, ask :-)
+
+There are some things that the linter doesn't force but are preferred this way:
+
+### Importing other files and libraries
+
+Use ES modules (`import`/`export`) instead of CommonJS (`require`/`module.exports`), and import the objects individually when possible:
+
+```typescript
+```
+
+### Functional style
+
+We give priority to a functional style of programming, but always taking into account how the objects are used to make sure they form a nice DSL. Classes are allowed when there's an actual state to hold, and we usually avoid default exports:
+
+```typescript
+// module-a.ts, a conventional functional module
+export functionA() {
+  ...
+}
+
+export const someConstantA = 42
+```
+
+### Dependency injection
+
+Prefer functions and modules to accept their dependencies as parameters rather than hard-coding imports. This enhances testability and composability.
+
+```typescript
+// module-b.ts, grouping functions with a scope
+export const ModuleB = {
+  functionB1: () => {...},
+  functionB2: () => {...},
+}
+```
+
+```typescript
+// object-c.ts, a class
+export class ObjectC {
+  constructor(readonly value: number) {}
+}
+```
+
+```typescript
+
+functionA()
+ModuleB.functionB1()
+const obj = new ObjectC(someConstantA)
+```
+
+### Use `const` and `let`
+
+Default to `const` and immutable objects when possible, otherwise, use `let`.
+
+```typescript
+// Good
+let a = 0
+const b = 3
+a = a + b
+
+// Less Good
+var c = 0
+let d = 3 // Never updated
+```

package/docs/docs-index.json

@@ -0,0 +1,200 @@
+[
+  {
+    "uri": "magek://docs/advanced/custom-templates",
+    "path": "advanced/custom-templates.md",
+    "title": "Customizing CLI resource templates",
+    "description": "You can change what the newly created Magek resources will contain by customizing the resource template files."
+  },
+  {
+    "uri": "magek://docs/advanced/data-migrations",
+    "path": "advanced/data-migrations.md",
+    "title": "Migrations",
+    "description": "Migrations are a mechanism for updating or transforming the schemas of events and entities as your system evolves. This allows you to make changes to your data model without losing or corrupting ex..."
+  },
+  {
+    "uri": "magek://docs/advanced/environment-configuration",
+    "path": "advanced/environment-configuration.md",
+    "title": "Environments",
+    "description": "You can create multiple environments calling the `Magek.configure` function several times using different environment names as the first argument. You can create one file for each environment, but ..."
+  },
+  {
+    "uri": "magek://docs/advanced/framework-packages",
+    "path": "advanced/framework-packages.md",
+    "title": "Framework packages",
+    "description": "The framework is already splitted into different packages:"
+  },
+  {
+    "uri": "magek://docs/advanced/health/sensor-health",
+    "path": "advanced/health/sensor-health.md",
+    "title": "Sensor Health",
+    "description": null
+  },
+  {
+    "uri": "magek://docs/advanced/instrumentation",
+    "path": "advanced/instrumentation.md",
+    "title": "Magek instrumentation",
+    "description": "The Trace Decorator is a **Magek** functionality that facilitates the reception of notifications whenever significant events occur in Magek's core, such as event dispatching or migration execution."
+  },
+  {
+    "uri": "magek://docs/advanced/register",
+    "path": "advanced/register.md",
+    "title": "Advanced uses of the Register object",
+    "description": "The Register object is a built-in object that is automatically injected by the framework into all command or event handlers to let users interact with the execution context. It can be used for a va..."
+  },
+  {
+    "uri": "magek://docs/advanced/sensor",
+    "path": "advanced/sensor.md",
+    "title": "Sensor",
+    "description": "- [Sensor Health](health/sensor-health.md) - Health monitoring and indicators"
+  },
+  {
+    "uri": "magek://docs/advanced/testing",
+    "path": "advanced/testing.md",
+    "title": "Testing",
+    "description": "Magek applications are fully tested by default. This means that you can be sure that your application will work as expected. However, you can also write your own tests to check that your applicatio..."
+  },
+  {
+    "uri": "magek://docs/advanced/touch-entities",
+    "path": "advanced/touch-entities.md",
+    "title": "TouchEntities",
+    "description": "Magek provides a way to refresh the value of an entity and update the corresponding ReadModels that depend on it."
+  },
+  {
+    "uri": "magek://docs/architecture/command",
+    "path": "architecture/command.md",
+    "title": "Command",
+    "description": "Commands are any action a user performs on your application. For example, `RemoveItemFromCart`, `RatePhoto` or `AddCommentToPost`. They express the intention of an user, and they are the main inter..."
+  },
+  {
+    "uri": "magek://docs/architecture/entity",
+    "path": "architecture/entity.md",
+    "title": "Entity",
+    "description": "If events are the _source of truth_ of your application, entities are the _current state_ of your application. For example, if you have an application that allows users to create bank accounts, the..."
+  },
+  {
+    "uri": "magek://docs/architecture/event-driven",
+    "path": "architecture/event-driven.md",
+    "title": "Magek architecture",
+    "description": "Magek is a highly opinionated framework that provides a complete toolset to build production-ready event-driven serverless applications."
+  },
+  {
+    "uri": "magek://docs/architecture/event-handler",
+    "path": "architecture/event-handler.md",
+    "title": "Event handler",
+    "description": "An event handler is a class that reacts to events. They are commonly used to trigger side effects in case of a new event. For instance, if a new event is registered in the system, an event handler ..."
+  },
+  {
+    "uri": "magek://docs/architecture/event",
+    "path": "architecture/event.md",
+    "title": "Event",
+    "description": "An event is a fact of something that has happened in your application. Every action that takes place on your application should be stored as an event. They are stored in a single collection, formin..."
+  },
+  {
+    "uri": "magek://docs/architecture/notifications",
+    "path": "architecture/notifications.md",
+    "title": "Notifications",
+    "description": "Notifications are an important concept in event-driven architecture, and they play a crucial role in informing interested parties about certain events that take place within an application."
+  },
+  {
+    "uri": "magek://docs/architecture/queries",
+    "path": "architecture/queries.md",
+    "title": "Queries",
+    "description": "ReadModels offer read operations over reduced events. On the other hand, Queries provide a way to do custom read operations."
+  },
+  {
+    "uri": "magek://docs/architecture/read-model",
+    "path": "architecture/read-model.md",
+    "title": "Read model",
+    "description": "A read model contains the data of your application that is exposed to the client through the GraphQL API. It's a _projection_ of one or more entities, so you dont have to directly expose them to th..."
+  },
+  {
+    "uri": "magek://docs/contributing",
+    "path": "contributing.md",
+    "title": "Contributing to Magek",
+    "description": "> **DISCLAIMER:** The Magek docs are undergoing an overhaul. Most of what's written here applies, but expect some hiccups in the build process"
+  },
+  {
+    "uri": "magek://docs/features/error-handling",
+    "path": "features/error-handling.md",
+    "title": "Error handling",
+    "description": "Magek provides a default error handling mechanism that will try to catch all the errors that are thrown in the application and will log them. This is useful for debugging purposes, but you may want..."
+  },
+  {
+    "uri": "magek://docs/features/event-stream",
+    "path": "features/event-stream.md",
+    "title": "The event stream",
+    "description": "The event stream API is a read-only API that allows you to fetch the events that have been generated by your application. It's useful for debugging purposes, but also for building your own analytic..."
+  },
+  {
+    "uri": "magek://docs/features/logging",
+    "path": "features/logging.md",
+    "title": "Logging in Magek",
+    "description": "If no configuration is provided, Magek uses the default JavaScript logging capabilities. Depending on the log level, it will call different logging methods:"
+  },
+  {
+    "uri": "magek://docs/features/schedule-actions",
+    "path": "features/schedule-actions.md",
+    "title": "Schedule actions",
+    "description": "There are many cases in which you want to trigger some action periodically. For example, you may want to send a reminder email to a user every day at 10:00 AM. For this, you can use scheduled comma..."
+  },
+  {
+    "uri": "magek://docs/getting-started/ai-coding-assistants",
+    "path": "getting-started/ai-coding-assistants.md",
+    "title": "AI Coding Assistants",
+    "description": "Magek provides an MCP (Model Context Protocol) server that enables AI coding assistants like **Claude Code** and **Codex CLI** to understand and work with Magek projects. This gives your AI assista..."
+  },
+  {
+    "uri": "magek://docs/getting-started/coding",
+    "path": "getting-started/coding.md",
+    "title": "Build a Magek app in minutes",
+    "description": "In this section, we will go through all the necessary steps to have the backend up and"
+  },
+  {
+    "uri": "magek://docs/getting-started/installation",
+    "path": "getting-started/installation.md",
+    "title": "Installation",
+    "description": "You can develop with Magek using any of the following operating systems:"
+  },
+  {
+    "uri": "magek://docs/graphql",
+    "path": "graphql.md",
+    "title": "GraphQL API",
+    "description": "This is the main API of your application, as it allows you to:"
+  },
+  {
+    "uri": "magek://docs/index",
+    "path": "index.md",
+    "title": "Magek Framework Documentation",
+    "description": "Welcome to the Magek documentation! Use the navigation on the left to browse guides and API reference."
+  },
+  {
+    "uri": "magek://docs/introduction",
+    "path": "introduction.md",
+    "title": "Introduction",
+    "description": "> _Progress isn't made by early risers. It's made by lazy men trying to find easier ways to do something._ — [Robert A. Heinlein](https://en.wikipedia.org/wiki/Robert_A._Heinlein)"
+  },
+  {
+    "uri": "magek://docs/magek-cli",
+    "path": "magek-cli.md",
+    "title": "Magek CLI",
+    "description": "The Magek CLI is a command line interface that helps you develop your Magek applications. It is built with Node.js and published to NPM through the package `@magek/cli`. It's automatically included..."
+  },
+  {
+    "uri": "magek://docs/security/authentication",
+    "path": "security/authentication.md",
+    "title": "Authentication",
+    "description": "Magek uses the OAuth 2.0 protocol to authenticate users. That means that it uses tokens to identify users and authorize them. These tokens are called _access tokens_ and are issued by an _authentic..."
+  },
+  {
+    "uri": "magek://docs/security/authorization",
+    "path": "security/authorization.md",
+    "title": "Authorization",
+    "description": "Magek uses a whitelisting approach to authorize users to perform commands and read models. This means that you must explicitly specify which users are allowed to perform each action. In order to do..."
+  },
+  {
+    "uri": "magek://docs/security/security",
+    "path": "security/security.md",
+    "title": "Security",
+    "description": "Magek accepts standard [JWT tokens](https://jwt.io/) to authenticate incoming requests."
+  }
+]