# The Development Roadmap for Open-SEO: From Project Scoping to AI Agents

> Explore the Open-SEO development roadmap, from project scoping to AI agents. Discover key milestones, modular functions, and agent integration plans through Q3 2026.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: architecture
- Published: 2026-08-02

---

**The development roadmap for Open-SEO centers on modular server functions, explicit project scoping, and AI-driven onboarding, with major milestones scheduled through Q3 2026 including an MCP protocol for agent integration and city-level rank tracking.**

Open-SEO is a modular SEO platform built by every-app/open-seo that powers both a hosted SaaS product and self-hosted Cloudflare or Docker deployments. The development roadmap is captured in formal specification documents that define architectural decisions and upcoming features. By examining these specs, developers can track how the platform evolves from foundational request handling to AI-powered SEO coaching.

## Project-Scoped Server Functions (Q2 2026 Foundations)

The first milestone solidifies the platform's backend architecture by mandating explicit `projectId` handling across all TanStack Server Functions. According to [`specs/0001-project-scoping-for-server-functions.md`](https://github.com/every-app/open-seo/blob/main/specs/0001-project-scoping-for-server-functions.md), every server function that requires project context now receives `projectId` directly in its payload, eliminating reliance on session state and fixing multi-tab behavior.

### Explicit projectId Handling and Global Middleware

**Global middleware** resolves the authenticated user and organization once per request, then injects the project context when `projectId` is present. Function-level middleware (`requireAuthenticatedContext`, `requireProjectContext`) performs type-narrowing to ensure type safety. This pattern centralizes authorization while keeping business logic clean.

```typescript
// src/server-functions/createKeywordBrief.ts
import { requireProjectContext } from '~/services/middleware';
import { db } from '~/services/db';

export const createKeywordBrief = async (input: {
  projectId: string;
  keyword: string;
}) => {
  // Project context is injected by global middleware
  const { project } = await requireProjectContext(input);

  // Business logic – fetch data from DataForSEO, generate brief, store in D1
  const metrics = await fetchKeywordMetrics(project.id, input.keyword);
  const brief = await generateBrief(metrics);
  await db.keywordBriefs.insert({
    projectId: project.id,
    keyword: input.keyword,
    brief,
  });

  return { success: true, brief };
};

```

*Source:* [`src/server-functions/createKeywordBrief.ts`](https://github.com/every-app/open-seo/blob/main/src/server-functions/createKeywordBrief.ts) (pattern reference).

## AI-Powered User Activation (Q2 2026)

The **onboarding agent**, detailed in [`specs/0005-onboarding-agent.md`](https://github.com/every-app/open-seo/blob/main/specs/0005-onboarding-agent.md), converts fresh signups into activated users by generating a free, AI-crafted SEO strategy. The system limits total per-onboarding spend to **under $0.30** with hard caps and email verification to prevent abuse.

### The Onboarding Agent Pipeline

The agent executes a five-stage pipeline:

1. **Profile** – Collects domain, country, and language preferences.
2. **Discover** – Crawls sitemap and robots.txt files.
3. **Read** – Performs live Cloudflare Browser Rendering of key pages.
4. **Signal** – Makes minimal DataForSEO calls (`domain_rank_overview`, `keyword_ideas`, optional `ranked_keywords`).
5. **Synthesize** – Streams a single LLM call that produces positioning statements, content clusters, a starter keyword table, and actionable next steps.

The resulting strategy persists as a markdown document in the `project_context` table (D1, with planned migration to R2), exposing project intelligence to downstream services.

## Local Rank Tracking Expansion (Q2 2026)

Open-SEO extends rank tracking to support **city and region-level SERP monitoring**, as specified in [`specs/0008-local-rank-tracking-locations.md`](https://github.com/every-app/open-seo/blob/main/specs/0008-local-rank-tracking-locations.md). This enables location-aware SEO strategies beyond national aggregates.

### City-Level SERP Monitoring with KV Caching

The implementation introduces a `location_name` field (e.g., `Enid,Oklahoma,United States`) to rank-tracking configurations. When provided, the backend forwards this value directly to DataForSEO for geo-specific SERP checks.

To maintain performance, the platform caches full country location lists in **Cloudflare Workers KV** (`serp-locations:{iso}`) with a 30-day TTL. The data is slimmed to the five most useful location types before caching, keeping the payload lightweight while supporting combobox search in the UI.

```tsx
// web/src/components/RankTrackingForm.tsx
import { useMutation } from '@tanstack/react-query';
import { createRankTrackingConfig } from '~/api';

export const RankTrackingForm = ({ projectId }: { projectId: string }) => {
  const mutation = useMutation((data) =>
    createRankTrackingConfig({ projectId, ...data })
  );

  return (
    <form onSubmit={handleSubmit}>
      {/* domain, country selectors omitted for brevity */}
      <label>
        City / Region
        <input
          type="text"
          placeholder="Enid,Oklahoma,United States"
          {...register('location_name')}
        />
      </label>
      <button type="submit" disabled={mutation.isLoading}>
        Save Tracker
      </button>
    </form>
  );
};

```

When `location_name` is non-null, the keyword table displays a "Local volume" column alongside national metrics.

## Agent Skills and MCP Protocol (Q3 2026)

Q3 2026 introduces **MCP (Meta-Control-Protocol)** support, transforming Open-SEO into an agent-accessible platform. According to [`specs/0006-onboarding-agent-implementation.md`](https://github.com/every-app/open-seo/blob/main/specs/0006-onboarding-agent-implementation.md), the system exposes project data to external AI agents such as Claude Code or Hermes.

### Exposing Project Context to External Agents

The unified **"seo-coach" skill** reads the persisted Project Context via MCP and continues the activation flow into paid actions like rank tracking and content briefs. Agents interact through standardized tools:

```json
{
  "tool": "get_project_context",
  "arguments": {
    "projectId": "proj_01G9ZK4M5H2..."
  }
}

```

Additional MCP tools include `read_website` and `get_seo_metrics`, allowing agents to perform deep research while respecting the project's scoped boundaries established in the Q2 foundations.

## Future Directions (Late 2026–2027)

The specification documents outline several planned enhancements not yet under active development:

- **ZIP-code fast-path** – A separate cached blob for numeric location queries to accelerate common US postal code searches.
- **Multi-city fan-out** – Bulk creation of rank-tracking configurations for agencies managing clients across multiple municipalities.
- **Server-side validation** – Rejection of arbitrary location strings before expensive DataForSEO API calls.
- **Picker quality upgrades** – Prominence-ranked results, recent location history, and enhanced type filtering in the UI combobox.

## Summary

- **Project scoping** via explicit `projectId` in server functions eliminates session dependency and enables correct multi-tab behavior, implemented through global middleware in `specs/0001`.
- **Onboarding agent** delivers AI-generated SEO strategies for under $0.30 per user by combining Cloudflare Browser Rendering with selective DataForSEO calls, defined in `specs/0005`.
- **Local rank tracking** adds granular city/region support using KV-cached location registries, specified in `specs/0008`.
- **MCP integration** exposes project context to external agents via the `get_project_context` tool, creating a bridge between the Open-SEO platform and third-party AI systems in `specs/0006`.

## Frequently Asked Questions

### What architecture changes are planned for Q2 2026 in Open-SEO?

Q2 2026 focuses on foundational stability through project-scoped server functions and user activation. The platform moves to explicit `projectId` passing in TanStack Server Functions and launches an AI onboarding agent that generates free SEO strategies using Cloudflare Browser Rendering and DataForSEO signals.

### How does Open-SEO handle authentication in its server functions?

Authentication is centralized through **global middleware** that resolves the user and organization once per request, then injects project context when `projectId` is present. Function-level middleware like `requireProjectContext` performs type-narrowing, ensuring type-safe access to project data throughout the request lifecycle.

### What is MCP in the Open-SEO roadmap?

**MCP (Meta-Control-Protocol)** is a Q3 2026 milestone that exposes Open-SEO project data to external AI agents via standardized tools like `get_project_context`. This protocol allows agents such as Claude Code to read the markdown strategy generated during onboarding and suggest or execute subsequent SEO actions.

### How does the local rank tracking feature minimize API costs?

Local rank tracking uses **Cloudflare Workers KV** to cache slimmed location registries (top five location types per country) with a 30-day TTL. This eliminates repeated lookups to the full DataForSEO location database while still allowing city-level SERP queries, reducing latency and external API dependency.