[feat] MCP server to create TILs inside AI tooling

.github/workflows/ci.yml

@@ -24,8 +24,8 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        elixir: [1.17.2]
-        otp: [27.0.1]
+        elixir: [1.18.4]
+        otp: [28.1]
     steps:
     - uses: actions/checkout@v3
     - name: Set up Elixir
@@ -61,8 +61,8 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        elixir: [1.17.2]
-        otp: [27.0.1]
+        elixir: [1.18.4]
+        otp: [28.1]
     services:
       postgres:
         image: postgres:14
@@ -111,8 +111,8 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        elixir: [1.17.2]
-        otp: [27.0.1]
+        elixir: [1.18.4]
+        otp: [28.1]
     steps:
     - uses: actions/checkout@v3
     - name: Set up Elixir

.gitignore

@@ -1,3 +1,4 @@
+.claude/
 .env
 *.ez
 /_build/

.tool-versions

@@ -1,3 +1,3 @@
-elixir 1.17.2-otp-27
-erlang 27.0.1
+elixir 1.18.4-otp-28
+erlang 28.1
 nodejs 19.0.0

AGENTS.md

@@ -0,0 +1,160 @@
+<!-- OPENSPEC:START -->
+# OpenSpec Instructions
+
+These instructions are for AI assistants working in this project.
+
+Always open `@/openspec/AGENTS.md` when the request:
+- Mentions planning or proposals (words like proposal, spec, change, plan)
+- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
+- Sounds ambiguous and you need the authoritative spec before coding
+
+Use `@/openspec/AGENTS.md` to learn:
+- How to create and apply change proposals
+- Spec format and conventions
+- Project structure and guidelines
+
+Keep this managed block so 'openspec update' can refresh the instructions.
+<!-- OPENSPEC:END -->
+<!-- usage-rules-start -->
+<!-- usage-rules-header -->
+# Usage Rules
+
+**IMPORTANT**: Consult these usage rules early and often when working with the packages listed below.
+Before attempting to use any of these packages or to discover if you should use them, review their
+usage rules to understand the correct patterns, conventions, and best practices.
+<!-- usage-rules-header-end -->
+
+<!-- usage_rules-start -->
+## usage_rules usage
+_A dev tool for Elixir projects to gather LLM usage rules from dependencies_
+
+## Using Usage Rules
+
+Many packages have usage rules, which you should *thoroughly* consult before taking any
+action. These usage rules contain guidelines and rules *directly from the package authors*.
+They are your best source of knowledge for making decisions.
+
+## Modules & functions in the current app and dependencies
+
+When looking for docs for modules & functions that are dependencies of the current project,
+or for Elixir itself, use `mix usage_rules.docs`
+
+```
+# Search a whole module
+mix usage_rules.docs Enum
+
+# Search a specific function
+mix usage_rules.docs Enum.zip
+
+# Search a specific function & arity
+mix usage_rules.docs Enum.zip/1
+```
+
+
+## Searching Documentation
+
+You should also consult the documentation of any tools you are using, early and often. The best 
+way to accomplish this is to use the `usage_rules.search_docs` mix task. Once you have
+found what you are looking for, use the links in the search results to get more detail. For example:
+
+```
+# Search docs for all packages in the current application, including Elixir
+mix usage_rules.search_docs Enum.zip
+
+# Search docs for specific packages
+mix usage_rules.search_docs Req.get -p req
+
+# Search docs for multi-word queries
+mix usage_rules.search_docs "making requests" -p req
+
+# Search only in titles (useful for finding specific functions/modules)
+mix usage_rules.search_docs "Enum.zip" --query-by title
+```
+
+
+<!-- usage_rules-end -->
+<!-- usage_rules:elixir-start -->
+## usage_rules:elixir usage
+# Elixir Core Usage Rules
+
+## Pattern Matching
+- Use pattern matching over conditional logic when possible
+- Prefer to match on function heads instead of using `if`/`else` or `case` in function bodies
+- `%{}` matches ANY map, not just empty maps. Use `map_size(map) == 0` guard to check for truly empty maps
+
+## Error Handling
+- Use `{:ok, result}` and `{:error, reason}` tuples for operations that can fail
+- Avoid raising exceptions for control flow
+- Use `with` for chaining operations that return `{:ok, _}` or `{:error, _}`
+
+## Common Mistakes to Avoid
+- Elixir has no `return` statement, nor early returns. The last expression in a block is always returned.
+- Don't use `Enum` functions on large collections when `Stream` is more appropriate
+- Avoid nested `case` statements - refactor to a single `case`, `with` or separate functions
+- Don't use `String.to_atom/1` on user input (memory leak risk)
+- Lists and enumerables cannot be indexed with brackets. Use pattern matching or `Enum` functions
+- Prefer `Enum` functions like `Enum.reduce` over recursion
+- When recursion is necessary, prefer to use pattern matching in function heads for base case detection
+- Using the process dictionary is typically a sign of unidiomatic code
+- Only use macros if explicitly requested
+- There are many useful standard library functions, prefer to use them where possible
+
+## Function Design
+- Use guard clauses: `when is_binary(name) and byte_size(name) > 0`
+- Prefer multiple function clauses over complex conditional logic
+- Name functions descriptively: `calculate_total_price/2` not `calc/2`
+- Predicate function names should not start with `is` and should end in a question mark.
+- Names like `is_thing` should be reserved for guards
+
+## Data Structures
+- Use structs over maps when the shape is known: `defstruct [:name, :age]`
+- Prefer keyword lists for options: `[timeout: 5000, retries: 3]`
+- Use maps for dynamic key-value data
+- Prefer to prepend to lists `[new | list]` not `list ++ [new]`
+
+## Mix Tasks
+
+- Use `mix help` to list available mix tasks
+- Use `mix help task_name` to get docs for an individual task
+- Read the docs and options fully before using tasks
+
+## Testing
+- Run tests in a specific file with `mix test test/my_test.exs` and a specific test with the line number `mix test path/to/test.exs:123`
+- Limit the number of failed tests with `mix test --max-failures n`
+- Use `@tag` to tag specific tests, and `mix test --only tag` to run only those tests
+- Use `assert_raise` for testing expected exceptions: `assert_raise ArgumentError, fn -> invalid_function() end`
+- Use `mix help test` to for full documentation on running tests
+
+## Debugging
+
+- Use `dbg/1` to print values while debugging. This will display the formatted value and other relevant information in the console.
+
+<!-- usage_rules:elixir-end -->
+<!-- usage_rules:otp-start -->
+## usage_rules:otp usage
+# OTP Usage Rules
+
+## GenServer Best Practices
+- Keep state simple and serializable
+- Handle all expected messages explicitly
+- Use `handle_continue/2` for post-init work
+- Implement proper cleanup in `terminate/2` when necessary
+
+## Process Communication
+- Use `GenServer.call/3` for synchronous requests expecting replies
+- Use `GenServer.cast/2` for fire-and-forget messages.
+- When in doubt, use `call` over `cast`, to ensure back-pressure
+- Set appropriate timeouts for `call/3` operations
+
+## Fault Tolerance
+- Set up processes such that they can handle crashing and being restarted by supervisors
+- Use `:max_restarts` and `:max_seconds` to prevent restart loops
+
+## Task and Async
+- Use `Task.Supervisor` for better fault tolerance
+- Handle task failures with `Task.yield/2` or `Task.shutdown/2`
+- Set appropriate task timeouts
+- Use `Task.async_stream/3` for concurrent enumeration with back-pressure
+
+<!-- usage_rules:otp-end -->
+<!-- usage-rules-end -->

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

Makefile

@@ -19,6 +19,7 @@ setup: ## Setup the App.
 	mix local.hex --force
 	mix setup
 	mix gettext.extract --merge --no-fuzzy
+	mix usage_rules.sync AGENTS.md --all --inline usage_rules:all --link-to-folder deps
 
 server: ## Start the App server.
 	npm install --prefix assets/

README.md

@@ -2,11 +2,7 @@
 
 [![CI](https://github.com/hashrocket/tilex/actions/workflows/ci.yml/badge.svg)](https://github.com/hashrocket/tilex/actions/workflows/ci.yml)
 
-> Today I Learned is an open-source project by the team at
-> [Hashrocket][hashrocket] that catalogues the sharing & accumulation of
-> knowledge as it happens day-to-day. Posts have a 200-word limit, and posting
-> is open to any Rocketeer as well as select friends of the team. We hope you
-> enjoy learning along with us.
+> Today I Learned is an open-source project by the team at [Hashrocket][hashrocket] that catalogues the sharing & accumulation of knowledge as it happens day-to-day. Posts have a 200-word limit, and posting is open to any Rocketeer as well as select friends of the team. We hope you enjoy learning along with us.
 
 Today I Learned was open-sourced to:
 - provide a window into our development process
@@ -28,60 +24,86 @@ $ git clone https://github.com/<your_github>/tilex
 $ cd tilex
 ```
 
-Then, install [Erlang][erlang], [Elixir][elixir], Node, and PostgreSQL.
-[asdf][asdf] can do this in a single command:
+Then, install [Erlang][erlang], [Elixir][elixir], Node, and PostgreSQL. [mise][mise] can do this in a single command:
 
 ```shell
-$ asdf install
+$ mise install
 ```
 
-From here, we recommend using `make`:
+The first step in the setup is to clone the `.env` file:
+
+```shell
+$ cp .env.example .env
+```
+
+#### Option 1 - Makefile
+
+From here, we recommend using `make` which will print out the help message with all dev tools we have:
 
 ```shell
 $ make
+
+Makefile  console    ## Opens the App console.
+Makefile  help       ## Shows this help.
+Makefile  outdated   ## Shows outdated packages.
+Makefile  server     ## Start the App server.
+Makefile  setup      ## Setup the App.
+Makefile  test       ## Run the test suite.
+Makefile  update     ## Update dependencies.
+```
+
+To **setup** the project and start the **server** you can:
+
+```shell
 $ make setup server
 ```
 
-#### Option 1 (seeded db)
+Now you can visit http://localhost:4000 from your browser.
+
+#### Option 2 - Manual
+
+All Makefile tasks will **automatically** load the `.env` file, so if you want to run any command manually you may have to load that file first:
+
+```shell
+source .env
+```
 
 Source your environment variables, install
 dependencies, seed the db, and start the server:
 
 ```shell
-$ cp .env{.example,}
-$ source .env
 $ mix deps.get
 $ mix ecto.setup
 $ npm install --prefix assets
 $ mix phx.server
 ```
 
-### Option 2 (empty db)
+Now you can visit http://localhost:4000 from your browser.
+
+#### Seeds the local Database
 
-For those who prefer to start with a blank slate:
+**Optionally**, And if you want to run a seeds task to populate your local database with some fake data you can run:
 
 ```shell
-$ cp .env{.example,}
-$ source .env
-$ mix deps.get
-$ mix ecto.create && mix ecto.migrate
-$ npm install --prefix assets
-$ mix phx.server
+$ DATE_DISPLAY_TZ=America/Chicago mix ecto.seeds
 ```
 
-### Running the application
+### AI Tooling
 
-```shell
-$ mix phx.server
-```
+#### Creating TILs: from AI via MCP
 
-Now you can visit http://localhost:4000 from your browser.
+If you are an user of TIL and wants to write TIL posts with some help of your AI tooling you can use our MCP servers. Log in into your TIL service, then go to the **profile** page. There's a box there to generate an MCP API Key that's needed to authenticate. We added a few helper code snippets to help you to setup the TIL MCP into your tooling.
 
-To serve the application at a different port, include the `PORT` environment
-variable when starting the server:
+<img width="551" height="1065" alt="image" src="https://github.com/user-attachments/assets/3f99129e-0f91-4621-83d1-bae1d250f5f7" />
 
-```shell
-$ PORT=4444 mix phx.server
+After the MCP is setup correctly you can start asking your AI to write TILs. The response on each new TIL should be a link where you'd have to review the title, content and channel and publish it.
+
+#### Developing TIL code: Improving AI Context
+
+So in case you want to use your AI tools to improve the TIL code we've added the [usage_rules](https://hexdocs.pm/usage_rules) into the project and we also added [tidewave](https://hexdocs.pm/tidewave) served as a MCP.
+
+```
+http://localhost:4000/tidewave/mcp
 ```
 
 ### Authentication
@@ -158,14 +180,16 @@ see [LICENSE](LICENSE.md) for more information.
 
 ---
 
-<p align="center">
-  <img src="https://hashrocket.com/hashrocket_logo.svg" />
-</p>
+<a href="https://hashrocket.com/">
+  <p align="center">
+    <img src="https://hashrocket.com/hashrocket_logo.svg" />
+  </p>
+</a>
 
 Tilex is supported by the team at [Hashrocket][hashrocket], a multidisciplinary design and
 development consultancy. If you'd like to work with us, don't hesitate to [contact us][hire-us] today!
 
-[asdf]: https://github.com/asdf-vm/asdf
+[mise]: https://github.com/jdx/mise
 [cc]: http://contributor-covenant.org
 [chromedriver]: https://sites.google.com/a/chromium.org/chromedriver/
 [contrib]: https://github.com/hashrocket/tilex/graphs/contributors

app.json

@@ -1,7 +1,7 @@
 {
   "name": "tilex",
   "scripts": {
-    "postdeploy": "mix ecto.migrate && POOL_SIZE=1 mix run priv/repo/seeds.exs"
+    "postdeploy": "POOL_SIZE=1 mix ecto.migrate"
   },
   "env": {
     "BASIC_AUTH_PASSWORD": {