PHPackages                             ashwinmram/mcp-pusher - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. ashwinmram/mcp-pusher

ActiveLibrary[Utility & Helpers](/categories/utility)

ashwinmram/mcp-pusher
=====================

Laravel package to push lessons learned to MCP server

3.0.12(2mo ago)0185↓55%MITPHPPHP ^8.2

Since Jan 11Pushed 2mo agoCompare

[ Source](https://github.com/ashwinmram/mcp-pusher)[ Packagist](https://packagist.org/packages/ashwinmram/mcp-pusher)[ RSS](/packages/ashwinmram-mcp-pusher/feed)WikiDiscussions main Synced yesterday

READMEChangelog (10)Dependencies (9)Versions (20)Used By (0)

Laravel MCP Pusher
==================

[](#laravel-mcp-pusher)

Laravel package to push lessons learned and project implementation details from your projects to a central MCP server via HTTP API. Works with the [Lessons Learned MCP Server](https://github.com/ashwinmram/mcp-server) so AI agents in **Cursor**, **Claude Code**, **Google Antigravity**, and other MCP clients can query your knowledge base.

- [GitHub](https://github.com/ashwinmram/mcp-pusher)
- [Packagist](https://packagist.org/packages/ashwinmram/mcp-pusher)

What's new in 3.0
-----------------

[](#whats-new-in-30)

Version 3.0 is a **capture-and-push workflow** built around session drafts on disk (survives context compaction in any AI client).

Before (1.x / 2.x)After (3.0)Edit `docs/lessons-learned.md` / JSON, then push**`mcp:append`** during session → draft JSONL`mcp:push-lessons` + `mcp:push-project-details`Single **`mcp:push`** (generic + project)Knowledge lost when chat compactsDrafts in `docs/.mcp-session/` persist**Commands:**

- **`mcp:append`** — one structured entry → `lessons-draft.jsonl` or `project-details-draft.jsonl`
- **`mcp:push`** — publish drafts to the MCP server once per session
- **`mcp:extract-session`** — git-only fallback or historical seeding from commit history

**Optional automation:** Cursor `preCompact` hook can show the [knowledge capture prompt](#knowledge-capture-prompt) before compaction. Claude Code and Antigravity have no equivalent hook — paste the prompt manually.

See [CHANGELOG.md](CHANGELOG.md) for full release notes.

```
composer require ashwinmram/mcp-pusher:^3.0

# Migration from 1.x / 2.x
# Before: mcp:push-lessons + mcp:push-project-details
# After:  mcp:push --source=your-project
```

Best practice (read this first)
-------------------------------

[](#best-practice-read-this-first)

**Do not** hand-type `php artisan mcp:append` JSON during normal work.

1. **Paste the [Knowledge capture prompt](#knowledge-capture-prompt)** into your agent before context compaction (or anytime you want to capture learnings).
2. The agent gathers recent **git log + diff**, synthesizes learnings from the session and commits, and runs `mcp:append` for each lesson — entries land in `docs/.mcp-session/*-draft.jsonl`.
3. **End of session:** review drafts, then run `mcp:push` once (see [End of session](#end-of-session)).

**Cursor only (optional):** Install the [preCompact hook](#cursor-precompact-hook) so Cursor surfaces the same prompt automatically.

StepWhat you doWhat runs on disk**Capture**Submit the capture prompt to your agentAgent gathers git context, synthesizes lessons, runs `mcp:append` → draft JSONL**Publish**`php artisan mcp:push --source=your-project`HTTP push to MCP server**Fallback**`mcp:extract-session` after you **commit** (default: latest commit)Git log + diff stat → draft JSONL**Seeding**`mcp:extract-session --since-git=HEAD~N` on a mature repoDeeper history; review drafts before pushKnowledge capture prompt
------------------------

[](#knowledge-capture-prompt)

**Copy the short block below** for agents or macOS Text Replacement (under 2,000 characters). See [Prompt reference](#prompt-reference) for field details and examples.

**Cursor:** With the [preCompact hook](#cursor-precompact-hook) installed, the hook emits the same text as `user_message` automatically (source: `stubs/knowledge-capture-prompt.txt`).

```
Context is about to compact — capture session knowledge NOW.

Step 0 — Run:
git log HEAD~10..HEAD --oneline --no-decorate
git diff HEAD~1..HEAD --stat
Use session + git together. Not a git repo? Session only. Do NOT append raw log, SHAs, or diff stats.

Step 1 — For each learning, execute mcp:append (don't just describe):
php artisan mcp:append '{"knowledge_scope":"generic|project","title":"5-12 words","summary":"problem + when","category":"...","subcategory":"...","type":"ai_output|project_detail","tags":["..."],"content":"paragraph with takeaway","metadata":{"source":"agent"}}'
Drafts: docs/.mcp-session/lessons-draft.jsonl (generic) or project-details-draft.jsonl (project). Never title "Git commit: …". Nothing worth saving? Report 0 generic, 0 project.

Step 2 — Report generic count, project count, every title appended.

```

### Prompt reference

[](#prompt-reference)

For agents that need more detail (not for macOS Text Replacement — 2,000 character limit).

**Scope pairs:**

knowledge\_scopetypeDraft file`generic``ai_output``docs/.mcp-session/lessons-draft.jsonl``project``project_detail``docs/.mcp-session/project-details-draft.jsonl`**Fields:**

- **title** — 5–12 words, specific and searchable (never `Git commit: …`)
- **summary** — 1–2 sentences: problem solved and when to apply
- **content** — short paragraph with context, approach, and takeaway (not a one-liner)
- **metadata.source** — always `"agent"`

**Minimal generic example:**

```
php artisan mcp:append '{"knowledge_scope":"generic","title":"Pest Process fake for git subprocess tests","summary":"Fake Process when testing Artisan commands that shell out to git.","category":"testing-patterns","subcategory":"pest-mocking","type":"ai_output","tags":["pest","git"],"content":"Use Process::fake() with a callback keyed on git argv...","metadata":{"source":"agent"}}'
```

**Bad example (do not do this):** title `Git commit: abc123 Fix tests`, content `abc123 Fix tests`

**Text replacement tip:** macOS Keyboard → Text Replacements → use trigger `/mcpcap` (no spaces) and paste the short block above into **With**.

Connect your AI client to the MCP server
----------------------------------------

[](#connect-your-ai-client-to-the-mcp-server)

Configure your client to reach the Lessons Learned server (and optional Project Details server). Example configs:

ClientExample stub**Cursor**`stubs/mcp-client-config/cursor-mcp.json.example`**Claude Code**`stubs/mcp-client-config/claude-mcp.json.example`**Google Antigravity**`stubs/mcp-client-config/antigravity-mcp_config.json.example`Full setup: [mcp-server README](https://github.com/ashwinmram/mcp-server#configuring-your-ai-client).

Agent startup instructions
--------------------------

[](#agent-startup-instructions)

Install agent instructions for your AI client:

ClientCommand**Cursor**`php artisan mcp:install-cursor-rules`**Claude Code**`php artisan mcp:install-claude-instructions`**Google Antigravity**`php artisan mcp:install-antigravity-skills`**All**`php artisan mcp:install-agent-instructions`See [`stubs/agent-instructions/README.md`](stubs/agent-instructions/README.md) for flags and manual install paths.

### Cursor

[](#cursor)

```
php artisan mcp:install-cursor-rules
```

Optional: `--with-hooks` (preCompact capture), `--with-cursorrules` (short `.cursorrules` index), `--force` (overwrite).

Copies `stubs/cursor-rules/*.mdc` into `.cursor/rules/`:

RuleWhen it applies`mcp-session-startup.mdc`**Always** — query lessons + project details at session start`mcp-session-capture.mdc`**On demand** — `mcp:append` + `mcp:push` workflow### Claude Code

[](#claude-code)

```
php artisan mcp:install-claude-instructions [--with-claude-md]
```

Copies modular rules into `.claude/rules/` (`mcp-session-startup.md`, `mcp-session-capture.md`). Optional `--with-claude-md` adds a short root `CLAUDE.md` index.

### Google Antigravity

[](#google-antigravity)

```
php artisan mcp:install-antigravity-skills [--global]
```

Installs workspace skills under `.agent/skills/mcp-session-startup/` and `mcp-session-capture/` (each with `SKILL.md`). Use `--global` for `~/.gemini/antigravity/global_skills/`. Commit `.agent/skills/` to share with your team.

### Install all clients

[](#install-all-clients)

```
php artisan mcp:install-agent-instructions [--with-hooks] [--with-claude-md] [--with-cursorrules] [--global]
```

Limit scope: `php artisan mcp:install-agent-instructions cursor claude`

End of session
--------------

[](#end-of-session)

When you are ready to publish, review `docs/.mcp-session/lessons-draft.jsonl` and `project-details-draft.jsonl`. Delete any raw git-salvage lines (titles like `Git commit: …` or `metadata.source: git`) before pushing. If drafts are still thin and you have committed session work, run `php artisan mcp:extract-session` as a last resort (produces candidates only — edit or remove before push). Then publish once:

```
php artisan mcp:push --source=
```

Replace `` with your `--source` value (must match Project Details MCP `?project=`).

Requirements
------------

[](#requirements)

- PHP 8.2+
- Laravel 12.x or 13.x
- An MCP server that accepts pushes (e.g. [Lessons Learned MCP Server](https://github.com/ashwinmram/mcp-server))

Installation
------------

[](#installation)

```
composer require ashwinmram/mcp-pusher:^3.0
```

Configuration
-------------

[](#configuration)

Add to `config/services.php`:

```
'mcp' => [
    'server_url' => env('MCP_SERVER_URL'),
    'api_token' => env('MCP_API_TOKEN'),
],
```

`.env`:

```
MCP_SERVER_URL=https://your-mcp-server.com
MCP_API_TOKEN=your-api-token-here

```

Add session drafts to `.gitignore` (see `stubs/gitignore-mcp-session.example`):

```
/docs/.mcp-session/
```

Commands
--------

[](#commands)

### `mcp:install-cursor-rules`

[](#mcpinstall-cursor-rules)

```
php artisan mcp:install-cursor-rules [--force] [--with-hooks] [--with-cursorrules]
```

Installs Cursor rules for MCP session startup and knowledge capture into `.cursor/rules/`.

### `mcp:install-claude-instructions`

[](#mcpinstall-claude-instructions)

```
php artisan mcp:install-claude-instructions [--force] [--with-claude-md]
```

Installs Claude Code rules into `.claude/rules/`. Optional `--with-claude-md` copies a short `CLAUDE.md` index.

### `mcp:install-antigravity-skills`

[](#mcpinstall-antigravity-skills)

```
php artisan mcp:install-antigravity-skills [--force] [--global]
```

Installs Antigravity skills into `.agent/skills/` (workspace) or `~/.gemini/antigravity/global_skills/` with `--global`.

### `mcp:install-agent-instructions`

[](#mcpinstall-agent-instructions)

```
php artisan mcp:install-agent-instructions [cursor|claude|antigravity ...] [--force] [--with-hooks] [--with-claude-md] [--with-cursorrules] [--global]
```

Runs the install commands above for one or more clients (default: all).

### `mcp:append`

[](#mcpappend)

Appends one entry to the correct draft file. The [capture prompt](#knowledge-capture-prompt) tells your agent when and how to run this.

- `knowledge_scope: "generic"` → `docs/.mcp-session/lessons-draft.jsonl`
- `knowledge_scope: "project"` → `docs/.mcp-session/project-details-draft.jsonl`

Advanced (debugging):

```
php artisan mcp:append --file=entry.json
```

### `mcp:push`

[](#mcppush)

```
php artisan mcp:push --source=your-project [--no-truncate]
```

Reads draft JSONL files, pushes to `/api/lessons` and `/api/project-details` when each bucket has content. Clears draft files on success unless `--no-truncate`.

### `mcp:extract-session` (git → drafts)

[](#mcpextract-session-git--drafts)

Git-only salvage into the same draft JSONL files as `mcp:append`. Does **not** read uncommitted files — **commit first** (staging alone is not enough).

```
php artisan mcp:extract-session [--since-git=HEAD~1]
```

#### How `--since-git` controls depth

[](#how---since-git-controls-depth)

The option sets where the commit range **starts**. Everything from that ref up to `HEAD` is summarized into draft lines (`git log` one-liners + `git diff --stat` for the range).

CommandCommits included (approx.)Typical use`mcp:extract-session`Latest commit only (`HEAD~1..HEAD`)End-of-session salvage`mcp:extract-session --since-git=HEAD~7`Last 7 commitsRecent sprint / week of work`mcp:extract-session --since-git=HEAD~30`Last 30 commitsBroader backfill`mcp:extract-session --since-git=main`Commits on `HEAD` not already on `main`Feature branch ahead of `main``mcp:extract-session --since-git=v1.0.0`Since a tag or SHARelease-to-HEAD snapshot- **Default `HEAD~1`** — only the **tip** commit (one commit).
- **`HEAD~N`** — increase `N` to go deeper into history (useful when installing mcp-pusher on a long-running repo).
- **`main`** — same as `git log main..HEAD` (see caveat below).

#### `--since-git=main` (commits only)

[](#--since-gitmain-commits-only)

This does **not** read the staging area or working tree.

SituationResultFeature branch with commits ahead of `main`Extracts those branch commits + diff statOn `main`, only uncommitted/staged changes**Empty range** — command fails; commit first or use `HEAD~N``main` and `HEAD` point at the same commit**Empty range** — use `HEAD~N` or a tag/SHA insteadFor seeding history **on** `main`, use `HEAD~N` (e.g. `HEAD~50`), not `main..HEAD`.

The [knowledge capture prompt](#knowledge-capture-prompt) already instructs agents to gather git context during preCompact capture. Use `mcp:extract-session` only when that capture was skipped.

#### Use case A: session fallback

[](#use-case-a-session-fallback)

When git-informed capture and `mcp:append` were both skipped but you committed session work:

```
php artisan mcp:extract-session
# review docs/.mcp-session/*-draft.jsonl
php artisan mcp:push --source=your-project
```

#### Use case B: seeding an existing project

[](#use-case-b-seeding-an-existing-project)

Installing mcp-pusher on a mature repo — bootstrap drafts from git, then publish:

```
php artisan mcp:extract-session --since-git=HEAD~50   # tune depth to your history
# edit drafts: replace heuristic lines with real lessons (or re-capture via agent + mcp:append)
php artisan mcp:push --source=your-project
```

Use `--since-git=main` only when you have a **feature branch with commits not merged to `main`**. Prefer editing drafts before push; extracted rows are **candidates**, not finished lessons.

#### Limits

[](#limits)

- Output is heuristic (commit subjects + diff stats), not AI-summarized knowledge.
- Large ranges produce many draft lines — review before `mcp:push`.
- First commit in repo: `HEAD~1` may be invalid; use `HEAD~N` or an explicit SHA/tag.

File layout
-----------

[](#file-layout)

```
your-project/
└── docs/
    └── .mcp-session/
        ├── lessons-draft.jsonl         ← generic lessons (mcp:append)
        └── project-details-draft.jsonl ← project details (mcp:append)

```

Optional automation
-------------------

[](#optional-automation)

### Cursor (preCompact hook)

[](#cursor-precompact-hook)

Install once so Cursor shows the [Knowledge capture prompt](#knowledge-capture-prompt) as `user_message` before context compaction.

**Prerequisites:** Cursor with **Agent Hooks**; `jq` or `python3` on PATH.

**Composer install:**

```
mkdir -p .cursor/hooks
cp vendor/ashwinmram/mcp-pusher/stubs/cursor-hooks/hooks.json.example .cursor/hooks.json
cp vendor/ashwinmram/mcp-pusher/stubs/cursor-hooks/pre-compact-checkpoint.sh .cursor/hooks/
cp vendor/ashwinmram/mcp-pusher/stubs/knowledge-capture-prompt.txt .cursor/hooks/
chmod +x .cursor/hooks/pre-compact-checkpoint.sh
```

**Monorepo** (e.g. [mcp-server](https://github.com/ashwinmram/mcp-server)): use `packages/laravel-mcp-pusher/stubs/cursor-hooks/` paths instead of `vendor/…`.

StubPurpose`hooks.json.example`Wires **`preCompact` only**`pre-compact-checkpoint.sh`Reads `knowledge-capture-prompt.txt`, outputs `user_message``knowledge-capture-prompt.txt`Same text as [Knowledge capture prompt](#knowledge-capture-prompt) (hook reads this file)**Optional Cursor rules:** `php artisan mcp:install-cursor-rules --with-hooks --with-cursorrules`

Manual rule copy: `stubs/cursor-rules/mcp-session-capture.mdc` → `.cursor/rules/` (legacy path `stubs/mcp-session-capture.mdc` is identical)

**Troubleshooting:** `chmod +x` the script; paste the capture prompt manually if `preCompact` never fires.

### Claude Code and Google Antigravity

[](#claude-code-and-google-antigravity)

No built-in pre-compaction hook. **Copy the [capture prompt](#knowledge-capture-prompt)** block from this README into your agent.

### Security

[](#security)

Hooks run shell on your machine. Review scripts before enabling. Keep `docs/.mcp-session/` gitignored.

How it works
------------

[](#how-it-works)

- Agent runs `mcp:append` → draft JSONL on disk (survives compaction)
- **`mcp:push`** → `POST /api/lessons` and `/api/project-details`
- Server deduplicates by content hash

License
-------

[](#license)

MIT

###  Health Score

43

—

FairBetter than 89% of packages

Maintenance87

Actively maintained with recent releases

Popularity13

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity56

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~8 days

Recently: every ~0 days

Total

19

Last Release

64d ago

Major Versions

v1.1.0 → v2.0.02026-02-07

v2.0.1 → 3.0.02026-06-04

### Community

Maintainers

![](https://www.gravatar.com/avatar/82e0a336442acfe6109202ef4a3992c163d3ba07097a9fb68f6d24d3d586f1f1?d=identicon)[ashwinmram](/maintainers/ashwinmram)

---

Top Contributors

[![ashwinmram](https://avatars.githubusercontent.com/u/13768053?v=4)](https://github.com/ashwinmram "ashwinmram (22 commits)")

---

Tags

laravelpackagemcplessons-learned

### Embed Badge

![Health badge](/badges/ashwinmram-mcp-pusher/health.svg)

```
[![Health](https://phpackages.com/badges/ashwinmram-mcp-pusher/health.svg)](https://phpackages.com/packages/ashwinmram-mcp-pusher)
```

###  Alternatives

[laravel/mcp

Rapidly build MCP servers for your Laravel applications.

79227.1M209](/packages/laravel-mcp)[forjedio/inertia-table

Backend-driven dynamic tables for Laravel + Inertia.js

272.0k](/packages/forjedio-inertia-table)[mike-bronner/laravel-model-caching

Automatic caching for Eloquent models.

2.4k161.4k1](/packages/mike-bronner-laravel-model-caching)[psalm/plugin-laravel

Psalm plugin for Laravel

3345.4M354](/packages/psalm-plugin-laravel)[spatie/laravel-export

Create a static site bundle from a Laravel app

679153.2k7](/packages/spatie-laravel-export)[zidbih/laravel-deadlock

Make temporary Laravel workarounds expire and fail CI when ignored.

1007.4k](/packages/zidbih-laravel-deadlock)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)