Skip to content

Commit 927f99f

Browse files
danilocdaniloc
committed
Merge branch 'main' into update-completion-prompt
2 parents b3c44e1 + d13e4b6 commit 927f99f

File tree

10 files changed

+868
-83
lines changed

10 files changed

+868
-83
lines changed

‎.github/workflows/build-release.yml‎

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -37,12 +37,6 @@ jobs:
3737
- name: Install dependencies
3838
run: npm install
3939

40-
- name: Build markdown documentation
41-
run: npm run build:docs
42-
43-
- name: List build artifacts
44-
run: ls -lh dist/
45-
4640
- name: Determine version
4741
id: version
4842
run: |
@@ -107,6 +101,14 @@ jobs:
107101
echo "tag=v${VERSION}" >> $GITHUB_OUTPUT
108102
echo "Building version: ${VERSION}"
109103
104+
- name: Build markdown documentation
105+
run: npm run build:docs
106+
env:
107+
BUILD_VERSION: ${{ steps.version.outputs.version }}
108+
109+
- name: List build artifacts
110+
run: ls -lh dist/
111+
110112
- name: Create Release
111113
id: create_release
112114
uses: actions/create-release@v1
@@ -157,5 +159,10 @@ jobs:
157159
echo "- **Tag:** ${{ steps.version.outputs.tag }}" >> $GITHUB_STEP_SUMMARY
158160
echo "- **Artifact:** examples-mcp-resources.zip" >> $GITHUB_STEP_SUMMARY
159161
echo "" >> $GITHUB_STEP_SUMMARY
162+
echo "### Manifest Metadata" >> $GITHUB_STEP_SUMMARY
163+
echo '```json' >> $GITHUB_STEP_SUMMARY
164+
cat dist/manifest.json | jq '{version, buildVersion, buildTimestamp}' >> $GITHUB_STEP_SUMMARY
165+
echo '```' >> $GITHUB_STEP_SUMMARY
166+
echo "" >> $GITHUB_STEP_SUMMARY
160167
echo "### Files Generated" >> $GITHUB_STEP_SUMMARY
161168
ls -lh dist/ >> $GITHUB_STEP_SUMMARY

‎README.md‎

Lines changed: 46 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -112,7 +112,7 @@ Coming soon.
112112

113113
Coming soon.
114114

115-
## Getting Started
115+
## Getting started
116116

117117
Each example includes its own README with setup instructions. Generally:
118118

@@ -123,3 +123,48 @@ Each example includes its own README with setup instructions. Generally:
123123

124124
See individual example READMEs for detailed instructions.
125125

126+
## MCP manifest architecture
127+
128+
This repository serves as the **single source of truth** for PostHog integration resources accessed via the [PostHog MCP server](https://github.com/PostHog/posthog/tree/main/products/mcp).
129+
130+
### How it works
131+
132+
1. **Build process** (`npm run build:docs`):
133+
- Converts example projects to markdown
134+
- Discovers workflow guides from `llm-prompts/`
135+
- Discovers MCP prompts from `mcp-commands/`
136+
- Generates `manifest.json` with all URIs and metadata
137+
- Packages everything into `examples-mcp-resources.zip`
138+
139+
2. **MCP server** (runtime):
140+
- Fetches the ZIP from GitHub releases
141+
- Loads `manifest.json`
142+
- **Purely reflects** the manifest - no hardcoded URIs or logic
143+
144+
### Manifest structure
145+
146+
The manifest defines:
147+
- **Workflows**: Step-by-step guides with automatic next-step linking
148+
- **Docs**: PostHog documentation URLs
149+
- **Prompts**: MCP command prompts with template variable substitution
150+
- **Templates**: Resource templates for parameterized access (e.g., `posthog://examples/{framework}`)
151+
152+
### Adding new resources
153+
154+
**Workflows**: Add markdown files to `llm-prompts/[category]/` following the naming convention `[order].[step]-[name].md`
155+
156+
**Examples**: Add new example projects to `basics/` and configure in `scripts/build-examples-mcp-resources.js`
157+
158+
**Prompts**: Add JSON files to `mcp-commands/`
159+
160+
The build script automatically discovers, orders, and generates URIs for all resources.
161+
162+
### Why this architecture?
163+
164+
- **Single source of truth**: All URIs defined in examples repo
165+
- **Zero hardcoding**: MCP server has no URIs or business logic
166+
- **Easy to extend**: Add resources by creating properly named files
167+
- **Version controlled**: Resources evolve with the examples
168+
169+
See `llm-prompts/README.md` for detailed workflow conventions.
170+

‎llm-prompts/README.md‎

Lines changed: 80 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,93 @@
1-
# LLM Prompts
1+
# LLM prompts
22

3-
This directory contains LLM workflow prompts that guide AI agents through various PostHog integration tasks.
3+
This directory contains LLM workflow prompts that guide AI agents through PostHog integration tasks.
44

55
Feel free to try these out directly, or summon them from the PostHog MCP server. You can also use them as a starting point for your own deep integrations. We've tested these extensively.
66

77
## Structure
88

99
- **basic-integration/**: Step-by-step workflow guides for adding PostHog event tracking to a project
10-
- `1.0-event-setup-begin.md`: Initial project analysis and event planning
11-
- `1.1-event-setup-edit.md`: Implementation guidance for adding PostHog tracking
12-
- `1.2-event-setup-revise.md`: Error checking and correction
10+
- `1.0-begin.md`: Initial project analysis and event planning
11+
- `1.1-edit.md`: Implementation guidance for adding PostHog tracking
12+
- `1.2-revise.md`: Error checking and correction
1313

14-
## Build Process
14+
## Manifest-driven architecture
15+
16+
These prompts and their URIs are defined in `manifest.json`, which is generated during the build process. The manifest is the **source of truth** for all resource URIs and metadata.
17+
18+
### How it works
19+
20+
1. **Build time**: `scripts/build-examples-mcp-resources.js` generates:
21+
- `manifest.json` with all resource definitions and URIs
22+
- Packaged into `examples-mcp-resources.zip`
23+
24+
2. **Runtime**: The MCP server:
25+
- Fetches the ZIP from GitHub releases
26+
- Loads `manifest.json`
27+
- **Purely reflects** the manifest - no URI generation, just registration
28+
29+
### Manifest structure
30+
31+
The manifest includes:
32+
- **Workflows**: Ordered sequence with `nextStepUri` for automatic linking
33+
- **Templates**: Resource templates for parameterized access (e.g., `posthog://examples/{framework}`)
34+
- **URIs**: Fully generated at build time (e.g., `posthog://workflows/basic-integration/begin`)
35+
36+
### File conventions
37+
38+
**Naming:** `[order].[step]-[name].md`
39+
40+
Examples:
41+
- `1.0-begin.md` → Order 1.0, step 0, ID: `basic-integration-begin`
42+
- `1.1-edit.md` → Order 1.1, step 1, ID: `basic-integration-edit`
43+
- `2.0-analytics-setup.md` → Order 2.0, step 0, ID: `category-analytics-setup`
44+
45+
**Required frontmatter:**
46+
47+
Every workflow file MUST include YAML frontmatter with `title` and `description`:
48+
49+
```markdown
50+
---
51+
title: PostHog setup - Begin
52+
description: Start the event tracking setup process by analyzing the project
53+
---
54+
55+
Your workflow content here...
56+
```
57+
58+
The build will fail if frontmatter is missing or incomplete.
59+
60+
**Automatic features:**
61+
- **Next step**: Automatically linked to the next file in numerical order
62+
- **URI generation**: `posthog://workflows/[category]/[name]`
63+
64+
### Adding new workflows
65+
66+
1. Create a new category directory: `llm-prompts/[category]/`
67+
2. Add markdown files following the naming convention
68+
3. Files are automatically:
69+
- Discovered and ordered
70+
- Linked to next steps
71+
- Given URIs (e.g., `posthog://workflows/[category]/[name]`)
72+
- Added to the manifest
73+
74+
**No configuration needed!** Just add properly named files.
75+
76+
## Build process
1577

1678
These prompts are packaged into the release artifact `examples-mcp-resources.zip`.
1779

80+
```bash
81+
npm run build:docs
82+
```
83+
1884
## Usage
1985

20-
The MCP server fetches these prompts from the latest GitHub release and serves them as resources to AI agents and the PostHog wizard during integration tasks.
86+
The MCP server fetches these prompts from the latest GitHub release and serves them as resources to AI agents and the PostHog wizard during integration tasks.
87+
88+
## Architecture benefits
89+
90+
- **Single source of truth**: Examples repo controls all URIs
91+
- **No hardcoded URIs in MCP**: MCP purely reflects manifest
92+
- **Easy to extend**: Add resources by creating properly named files
93+
- **Version controlled**: URIs and metadata evolve with the examples

‎llm-prompts/basic-integration/1.0-event-setup-begin.md‎ renamed to ‎llm-prompts/basic-integration/1.0-begin.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
title: PostHog Setup - Begin
3+
description: Start the event tracking setup process by analyzing the project and creating an event tracking plan
4+
---
5+
16
We're making an event tracking plan for this project.
27

38
From the project's file list, select between 10 and 15 files that might have interesting business value for event tracking, especially conversion and churn events. Also look for additional files related login that could be used for identifying users, along with error handling. Read the files.

‎llm-prompts/basic-integration/1.1-event-setup-edit.md‎ renamed to ‎llm-prompts/basic-integration/1.1-edit.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
title: PostHog Setup - Edit
3+
description: Implement PostHog event tracking in the identified files, following best practices and the example project
4+
---
5+
16
For each of the files and events noted in .posthog-events.json, make edits to capture events using PostHog. Make sure to set up any helper files needed. Carefully examine the included example project code: your implementation should match it as closely as possible.
27

38
Use environment variables for PostHog keys. Do not hardcode PostHog keys.

‎llm-prompts/basic-integration/1.2-event-setup-revise.md‎ renamed to ‎llm-prompts/basic-integration/1.2-revise.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
title: PostHog Setup - Revise
3+
description: Review and fix any errors in the PostHog integration implementation
4+
---
5+
16
Check the project for errors. Read the package.json file for any type checking or build scripts that may provide input about what to fix. Remember that you can find the source code for any dependency in the node_modules directory.
27

38
Once all other tasks are complete, run any linter or prettier-like scripts found in the package.json.

‎mcp-commands/posthog-setup.json‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{
2+
"name": "posthog-setup",
3+
"title": "Setup a deep PostHog integration",
4+
"description": "Automatically instrument your project with PostHog event tracking, user identification, and error tracking",
5+
"messages": [
6+
{
7+
"role": "user",
8+
"content": {
9+
"type": "text",
10+
"text": "Setup automatic PostHog event tracking in this project.\n\nUse these MCP resources:\n- {{workflows.basic-integration.begin}} - The event setup workflow guide (start here)\n- {{docs.frameworks}} - Integration documentation per framework\n- {{examples}} - Example projects with known-good PostHog integrations\n\nFollow the workflow guide to implement a deep PostHog integration."
11+
}
12+
},
13+
{
14+
"role": "assistant",
15+
"content": {
16+
"type": "text",
17+
"text": "I'll set up PostHog event tracking in your project using the provided workflow guide and documentation."
18+
}
19+
}
20+
]
21+
}

0 commit comments

Comments
 (0)