Skip to content

Commit b055dd7

Browse files
ayoub3bidiayoub3bidi
authored
Merge pull request #201 from fix/make-it-agent-ready
feat(agent-readiness): make Bayan Flow discoverable and usable by AI agents
2 parents 2d8c757 + fe9ad58 commit b055dd7

10 files changed

Lines changed: 247 additions & 25 deletions

File tree

‎docs/AGENTS_REFERENCE.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -615,3 +615,31 @@ Use focused tests first for registry/category changes, then broaden to the full
615615
- If a shared helper is required, add it in the earliest commit that needs it.
616616
- Prefer existing hooks, registries, helpers, and component patterns over one-off branches.
617617
- Keep deterministic generators deterministic in tests by accepting/passing an `rng` where existing utilities do.
618+
619+
## Agent-Readiness Endpoints
620+
621+
### Static files (served from `public/`)
622+
623+
| File | Content-Type | Purpose |
624+
|------|-------------|---------|
625+
| `/.well-known/api-catalog` | `application/linkset+json` | RFC 9727 API catalog with `linkset` array |
626+
| `/.well-known/mcp/server-card.json` | `application/json` | MCP Server Card (SEP-1649) with `serverInfo`, endpoint, capabilities |
627+
| `/.well-known/oauth-authorization-server` | `application/json` | OAuth discovery (Supabase issuer) with `agent_auth` block |
628+
| `/.well-known/oauth-protected-resource` | `application/json` | RFC 9728 Protected Resource Metadata |
629+
| `/.well-known/agent-card.json` | `application/json` | Agent card with capabilities and features |
630+
| `/.well-known/agent-skills/index.json` | `application/json` | Agent skills catalog |
631+
| `/auth.md` | `text/markdown` | Agent registration / authentication guide |
632+
| `/llms.txt` | `text/plain` | Machine-readable site description for AI agents |
633+
634+
### Link headers (in `public/_headers`)
635+
636+
The `/*` section includes `Link` headers pointing to:
637+
- `</.well-known/api-catalog>; rel="api-catalog"`
638+
- `</.well-known/oauth-protected-resource>; rel="oauth-protected-resource"`
639+
- `</.well-known/mcp/server-card.json>; rel="mcp-server-card"`
640+
- `</auth.md>; rel="auth-md"`
641+
- `</llms.txt>; rel="llms-txt"`
642+
643+
### CORS
644+
645+
All `/.well-known/*` paths include `Access-Control-Allow-Origin: *` for cross-origin agent discovery.

‎public/.well-known/api-catalog‎

Lines changed: 43 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,45 @@
11
{
2-
"schemaVersion": 1,
3-
"description": "Bayan Flow is a fully client-side single-page application. No public REST APIs are available. All algorithm execution, visualization rendering, and code interpretation happens in the user's browser via React and Pyodide (WebAssembly Python runtime).",
4-
"endpoints": []
2+
"linkset": [
3+
{
4+
"anchor": "https://bayanflow.com",
5+
"service-desc": [
6+
{
7+
"href": "https://bayanflow.com/.well-known/agent-card.json",
8+
"title": "Bayan Flow Agent Card",
9+
"type": "application/json"
10+
}
11+
],
12+
"service-doc": [
13+
{
14+
"href": "https://bayanflow.com/auth.md",
15+
"title": "Bayan Flow Agent Authentication Guide",
16+
"type": "text/markdown"
17+
}
18+
],
19+
"describedby": [
20+
{
21+
"href": "https://bayanflow.com/llms.txt",
22+
"title": "Bayan Flow — Machine-Readable Description",
23+
"type": "text/plain"
24+
}
25+
]
26+
},
27+
{
28+
"anchor": "https://bayanflow.com/app",
29+
"service-desc": [
30+
{
31+
"href": "https://bayanflow.com/.well-known/mcp/server-card.json",
32+
"title": "Bayan Flow MCP Server Card",
33+
"type": "application/json"
34+
}
35+
],
36+
"service-doc": [
37+
{
38+
"href": "https://bayanflow.com/.well-known/agent-skills/index.json",
39+
"title": "Bayan Flow Agent Skills",
40+
"type": "application/json"
41+
}
42+
]
43+
}
44+
]
545
}

‎public/.well-known/mcp.json‎

Lines changed: 0 additions & 18 deletions
This file was deleted.

‎public/.well-known/mcp/server-card.json‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
{
2+
"serverInfo": {
3+
"name": "Bayan Flow",
4+
"version": "0.5.0"
5+
},
6+
"description": "Interactive algorithm visualizer — 45 algorithms across sorting, pathfinding, searching, tree traversal, and graph categories with step-by-step animation, Python code editing, and complexity analysis.",
7+
"endpoint": "/mcp",
8+
"homepageUrl": "https://bayanflow.com",
9+
"capabilities": {
10+
"tools": [
11+
{
12+
"name": "bayan_flow_info",
13+
"description": "Get information about Bayan Flow, an interactive algorithm visualizer with 45 algorithms across sorting, pathfinding, searching, tree traversal, and graph categories. Optionally filter by category name.",
14+
"inputSchema": {
15+
"type": "object",
16+
"properties": {
17+
"category": {
18+
"type": "string",
19+
"description": "Optional algorithm category name (sorting, pathfinding, searching, tree, graph)"
20+
}
21+
}
22+
}
23+
},
24+
{
25+
"name": "list_algorithms",
26+
"description": "List all available algorithms with their names, categories, and time/space complexity.",
27+
"inputSchema": {
28+
"type": "object",
29+
"properties": {
30+
"category": {
31+
"type": "string",
32+
"description": "Filter by category: sorting, pathfinding, searching, tree, graph"
33+
}
34+
}
35+
}
36+
}
37+
],
38+
"resources": [
39+
{
40+
"name": "algorithm_catalog",
41+
"description": "Full catalog of 45 algorithms with descriptions and complexity."
42+
}
43+
]
44+
}
45+
}

‎public/.well-known/oauth-authorization-server‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
{
2+
"issuer": "https://qketsapzqpzmccljfjcm.supabase.co",
3+
"authorization_endpoint": "https://qketsapzqpzmccljfjcm.supabase.co/auth/v1/authorize",
4+
"token_endpoint": "https://qketsapzqpzmccljfjcm.supabase.co/auth/v1/token",
5+
"jwks_uri": "https://qketsapzqpzmccljfjcm.supabase.co/auth/v1/.well-known/jwks.json",
6+
"registration_endpoint": "https://qketsapzqpzmccljfjcm.supabase.co/auth/v1/signup",
7+
"scopes_supported": [
8+
"openid",
9+
"profile",
10+
"email"
11+
],
12+
"response_types_supported": [
13+
"code",
14+
"token",
15+
"id_token"
16+
],
17+
"grant_types_supported": [
18+
"authorization_code",
19+
"implicit",
20+
"password",
21+
"refresh_token"
22+
],
23+
"token_endpoint_auth_methods_supported": [
24+
"client_secret_basic",
25+
"client_secret_post",
26+
"none"
27+
],
28+
"service_documentation": "https://bayanflow.com/auth.md",
29+
"agent_auth": {
30+
"skill": "https://bayanflow.com/auth.md",
31+
"register_uri": "https://bayanflow.com/auth.md",
32+
"identity_types_supported": ["anonymous"],
33+
"anonymous": {
34+
"credential_types_supported": ["session"],
35+
"claim_uri": "https://bayanflow.com/auth.md"
36+
}
37+
}
38+
}

‎public/.well-known/oauth-protected-resource‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{
2+
"resource": "https://bayanflow.com",
3+
"authorization_servers": [
4+
"https://qketsapzqpzmccljfjcm.supabase.co"
5+
],
6+
"scopes_supported": [
7+
"openid",
8+
"profile",
9+
"email"
10+
],
11+
"bearer_methods_supported": [
12+
"header"
13+
],
14+
"resource_documentation": "https://bayanflow.com/auth.md"
15+
}

‎public/_headers‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,11 @@
77
# Pyodide CDN origins: jsDelivr below; custom VITE_PYODIDE_CDN_BASE origins appended at build (vite.config.js)
88
Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline' 'wasm-unsafe-eval' blob: https://cloud.umami.is https://static.cloudflareinsights.com https://cdn.jsdelivr.net https://accounts.google.com; connect-src 'self' blob: https://cloud.umami.is https://gateway.umami.is https://cloudflareinsights.com https://api.github.com https://cdn.jsdelivr.net https://www.remotion.pro https://qketsapzqpzmccljfjcm.supabase.co https://accounts.google.com https://oauth2.googleapis.com; img-src 'self' data: blob: https://api.producthunt.com https://lh3.googleusercontent.com; style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; font-src 'self' data:; worker-src 'self' blob:; media-src 'self' blob:; frame-src https://www.youtube-nocookie.com https://accounts.google.com; object-src 'none'; base-uri 'self'; form-action 'self'
99
Link: <https://bayanflow.com/sitemap.xml>; rel="sitemap"
10+
Link: </.well-known/api-catalog>; rel="api-catalog"
11+
Link: </.well-known/oauth-protected-resource>; rel="oauth-protected-resource"
12+
Link: </.well-known/mcp/server-card.json>; rel="mcp-server-card"
13+
Link: </auth.md>; rel="auth-md"
14+
Link: </llms.txt>; rel="llms-txt"
1015

1116
/assets/*
1217
Cache-Control: public, max-age=31536000, immutable
@@ -20,9 +25,30 @@
2025
/logo.svg
2126
Cache-Control: public, max-age=86400
2227

28+
/.well-known/*
29+
Access-Control-Allow-Origin: *
30+
Content-Type: application/json
31+
2332
/.well-known/api-catalog
33+
Content-Type: application/linkset+json
34+
35+
/.well-known/mcp/server-card.json
36+
Content-Type: application/json
37+
38+
/.well-known/oauth-authorization-server
2439
Content-Type: application/json
2540

41+
/.well-known/oauth-protected-resource
42+
Content-Type: application/json
43+
44+
/llms.txt
45+
Content-Type: text/plain; charset=utf-8
46+
Access-Control-Allow-Origin: *
47+
48+
/auth.md
49+
Content-Type: text/markdown; charset=utf-8
50+
Access-Control-Allow-Origin: *
51+
2652
https://dev.bayanflow.com/*
2753
X-Robots-Tag: noindex
2854

‎public/auth.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Authentication
1+
# auth.md
22

33
Bayan Flow offers optional sign-in with Google. All algorithm visualizations are **free to use** without an account. The following additional free features require signing in:
44

‎public/llms.txt‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# Bayan Flow
2+
3+
> Interactive algorithm visualizer for learning computer science through step-by-step animations with clarity. Bayan (بيان) means clarity in Arabic.
4+
5+
Bayan Flow is a free, client-side single-page application that visualizes 45 algorithms across five categories. All computation runs in the browser — there are no server-side APIs.
6+
7+
## Categories
8+
9+
- **Sorting** (14): Bubble, Selection, Insertion, Merge, Quick, Heap, Counting, Radix, Shell, Cocktail Shaker, Gnome, Comb, Tim, Bitonic
10+
- **Pathfinding** (8): Dijkstra, A*, BFS, DFS, Greedy Best-First, Bidirectional BFS, Jump Point Search, Bellman-Ford
11+
- **Searching** (6): Linear, Binary, Jump, Exponential, Ternary, Fibonacci
12+
- **Tree Traversal** (7): Pre-order, In-order, Post-order, Level-order, BFS, DFS, Morris In-order
13+
- **Graph** (10): BFS, DFS, Topological Sort, Bellman-Ford, Floyd-Warshall, Kruskal, Prim, Tarjan, Kosaraju, Ford-Fulkerson
14+
15+
## Key URLs
16+
17+
- Homepage: https://bayanflow.com
18+
- App: https://bayanflow.com/app
19+
- Roadmap: https://bayanflow.com/roadmap
20+
- API Catalog: https://bayanflow.com/.well-known/api-catalog
21+
- Agent Card: https://bayanflow.com/.well-known/agent-card.json
22+
- MCP Server Card: https://bayanflow.com/.well-known/mcp/server-card.json
23+
- Agent Skills: https://bayanflow.com/.well-known/agent-skills/index.json
24+
- Auth Guide: https://bayanflow.com/auth.md
25+
- OAuth Discovery: https://bayanflow.com/.well-known/oauth-authorization-server
26+
- OAuth Protected Resource: https://bayanflow.com/.well-known/oauth-protected-resource
27+
28+
## Capabilities
29+
30+
- Step-by-step algorithm visualization with configurable speed
31+
- Real-time time and space complexity analysis
32+
- Python code execution in the browser via Pyodide (WebAssembly)
33+
- HD video export with optional sound
34+
- Multi-language support (English, French, Arabic with RTL)
35+
- Google sign-in for saved preferences and favorites
36+
- 45 algorithms, each with detailed descriptions and complexity info
37+
38+
## How It Works
39+
40+
1. User selects a category and algorithm from the sidebar
41+
2. The app generates random input and runs the algorithm, recording each step
42+
3. Steps are animated in the visualization panel with color-coded state changes
43+
4. The complexity panel shows interactive time/space complexity charts
44+
5. Optional Python code panel shows editable, runnable pseudocode
45+
46+
## Agent Integration
47+
48+
Bayan Flow exposes an MCP server card and WebMCP tools for AI agent discovery. Agents can query algorithm information, list available algorithms, and navigate to specific visualizations. The app is fully client-side — no API keys or authentication required for browsing algorithms.

‎src/pages/LandingPage.jsx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,15 +28,15 @@ function LandingPage() {
2828
<Header />
2929

3030
{/* Landing Sections */}
31-
<div className="relative z-10">
31+
<main className="relative z-10">
3232
<Hero />
3333
<LearnYourWay />
3434
<AlgorithmTypes />
3535
<Features />
3636
<ClaritySection />
3737
<RoadmapCTA />
38-
<Footer />
39-
</div>
38+
</main>
39+
<Footer />
4040
</div>
4141
);
4242
}

0 commit comments

Comments
 (0)