Skip to content

Commit 7174152

Browse files
sametbasbugclaude
andcommitted
Serve the agent guides as plain text
ChatGPT Web's fetcher can read /mcp/ but not /skill.md or /mcp.md. The only difference between them was the content type: text/html versus text/markdown. text/markdown is a registered media type but most non-browser fetchers have no renderer for it and refuse the document, and because we send nosniff there is no fallback for the client either. Markdown is plain text; text/plain loses nothing and is read inline everywhere. GitHub raw serves .md exactly this way, which is why LLM fetchers can read README files at all. The headers were copied across the worker and both Astro routes, so they now come from one place that carries the reason. Three locks keep it from drifting back: the source check in the site tests, and the live contract auditor, which now measures the content type in production and covers mcp.md at all — it did not before. Also rename the connector label on /mcp to Equinox Orbit. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
1 parent 8f4ad33 commit 7174152

8 files changed

Lines changed: 69 additions & 23 deletions

File tree

‎scripts/orbit-live-contract-tests.mjs‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ async function live(pathname) {
2222
const response = await fetch(`${ORIGIN}${pathname}`, {
2323
redirect: 'error',
2424
headers: {
25-
accept: pathname.endsWith('.md') ? 'text/markdown' : 'application/json',
25+
accept: pathname.endsWith('.md') ? 'text/plain' : 'application/json',
2626
'user-agent': 'OrbitLiveContract/1.0 (+https://orbit.sametbasbug.dev/skill.md)',
2727
},
2828
});
@@ -60,6 +60,20 @@ check(skill.includes(`version: ${EXPECTED_GUIDE_VERSION}`), 'Live guide version
6060
check(skill.includes('/clients/orbit-client-v1.mjs'), 'Live guide lacks the JS reference client.');
6161
check(skill.includes('/clients/orbit_client_v1.py'), 'Live guide lacks the Python reference client.');
6262

63+
/* Rehberler düz metin olarak servis edilmezse ajan getiricilerinin bir kısmı
64+
* belgeyi hiç okumaz — bunu bir kez canlıda öğrendik. Deploy bu yüzden
65+
* gövdeye olduğu kadar içerik türüne de bakıyor. */
66+
const mcpResponse = await live('/mcp.md');
67+
for (const [pathname, response] of [['/skill.md', skillResponse], ['/mcp.md', mcpResponse]]) {
68+
check(
69+
(response.headers.get('content-type') ?? '').startsWith('text/plain'),
70+
`${pathname} is not served as plain text; agent fetchers will refuse it.`,
71+
);
72+
}
73+
check(/^no-store\b/u.test(mcpResponse.headers.get('cache-control') ?? ''), 'mcp.md is not no-store.');
74+
const mcpGuide = await mcpResponse.text();
75+
check(mcpGuide.includes(`version: ${EXPECTED_GUIDE_VERSION}`), 'Live MCP guide version does not match this client release.');
76+
6377
for (const pathname of [
6478
'/clients/orbit-client-v1.mjs',
6579
'/clients/orbit_client_v1.py',

‎scripts/orbit-site-tests.mjs‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,29 @@ if (fs.existsSync(mcpPageFile)) {
118118
}
119119
check(!homeHtml.includes('Farklı zihinler.'), 'Kaldırılan ana sayfa sloganı build çıktısında kaldı.');
120120
check(!homeHtml.includes('>Ajan rehberi<'), 'Ajan rehberi navigasyon bağlantısı build çıktısında kaldı.');
121+
/* Rehberleri servis eden üç yol da başlıklarını tek kaynaktan almalı.
122+
* `text/markdown` doğru gibi görünen ama belgeyi okunamaz kılan cevaptır:
123+
* ChatGPT Web'in getiricisi bu türü okumadan geri çeviriyor ve `nosniff`
124+
* gönderdiğimiz için istemcinin tahmin etme yolu da kapalı. Gerekçe
125+
* src/shared/machine-guide.ts'de duruyor; buradaki kilit birinin başlığı
126+
* yerinde "düzeltip" o gerekçeyi görmemesini engelliyor. */
127+
for (const guideRoute of ['src/worker.ts', 'src/pages/skill.md.ts', 'src/pages/mcp.md.ts']) {
128+
const source = fs.readFileSync(path.join(ROOT, guideRoute), 'utf8');
129+
check(
130+
source.includes('MACHINE_GUIDE_HEADERS'),
131+
`${guideRoute} rehber başlıklarını paylaşılan kaynaktan almıyor.`,
132+
);
133+
check(
134+
!source.includes("'content-type': 'text/markdown"),
135+
`${guideRoute} rehberi text/markdown olarak servis ediyor; bu tür ajan getiricilerinde okunmuyor.`,
136+
);
137+
}
138+
check(
139+
fs.readFileSync(path.join(ROOT, 'src', 'shared', 'machine-guide.ts'), 'utf8')
140+
.includes("'content-type': 'text/plain; charset=utf-8'"),
141+
'Ajan rehberleri düz metin olarak servis edilmiyor.',
142+
);
143+
121144
const machineGuideFile = path.join(DIST_DIR, 'skill.md');
122145
check(fs.existsSync(machineGuideFile), 'Makine-okunabilir skill.md rehberi build çıktısında yok.');
123146
if (fs.existsSync(machineGuideFile)) {

‎scripts/orbit-slice1-worker-tests.ts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -282,7 +282,9 @@ describe('Orbit V6 deployment-mode contract', () => {
282282
const env = productionBindings('live');
283283
const response = await worker.fetch(new Request(`${LIVE_ORIGIN}/skill.md`), env);
284284
assert.equal(response.status, 200);
285-
assert.equal(response.headers.get('content-type'), 'text/markdown; charset=utf-8');
285+
// text/markdown olarak servis edersek ajan getiricilerinin bir kısmı
286+
// belgeyi hiç okumaz; gerekçe src/shared/machine-guide.ts'de.
287+
assert.equal(response.headers.get('content-type'), 'text/plain; charset=utf-8');
286288
assert.equal(response.headers.get('cache-control'), 'no-store, no-transform');
287289
// Bu test "worker güncel rehberi mi servis ediyor" sorusunu sorar; doğru
288290
// karşılaştırma sabit bir sayı değil, kaynağın kendisidir.
@@ -298,7 +300,7 @@ describe('Orbit V6 deployment-mode contract', () => {
298300
const env = productionBindings('live');
299301
const response = await worker.fetch(new Request(`${LIVE_ORIGIN}/mcp.md`), env);
300302
assert.equal(response.status, 200);
301-
assert.equal(response.headers.get('content-type'), 'text/markdown; charset=utf-8');
303+
assert.equal(response.headers.get('content-type'), 'text/plain; charset=utf-8');
302304
assert.equal(response.headers.get('cache-control'), 'no-store, no-transform');
303305

304306
// İki belge aynı sözleşmenin iki yüzü; ayrı sürümlerde servis edilirlerse

‎src/pages/mcp.astro‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ import { ORBIT_MCP_ENDPOINT } from '../data/agentOnboarding';
2424
<dl class="mcp-fields">
2525
<div>
2626
<dt>Ad</dt>
27-
<dd><code>Orbit</code></dd>
27+
<dd><code>Equinox Orbit</code></dd>
2828
</div>
2929
<div>
3030
<dt>Sunucu adresi</dt>

‎src/pages/mcp.md.ts‎

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,6 @@
11
import { machineMcpGuide } from '../data/mcpOnboarding';
2+
import { MACHINE_GUIDE_HEADERS } from '../shared/machine-guide';
23

34
export function GET() {
4-
return new Response(machineMcpGuide, {
5-
headers: {
6-
'cache-control': 'no-store, no-transform',
7-
'content-type': 'text/markdown; charset=utf-8',
8-
'x-content-type-options': 'nosniff',
9-
},
10-
});
5+
return new Response(machineMcpGuide, { headers: { ...MACHINE_GUIDE_HEADERS } });
116
}

‎src/pages/skill.md.ts‎

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,6 @@
11
import { machineAgentSkill } from '../data/agentOnboarding';
2+
import { MACHINE_GUIDE_HEADERS } from '../shared/machine-guide';
23

34
export function GET() {
4-
return new Response(machineAgentSkill, {
5-
headers: {
6-
'cache-control': 'no-store, no-transform',
7-
'content-type': 'text/markdown; charset=utf-8',
8-
'x-content-type-options': 'nosniff',
9-
},
10-
});
5+
return new Response(machineAgentSkill, { headers: { ...MACHINE_GUIDE_HEADERS } });
116
}

‎src/shared/machine-guide.ts‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
/**
2+
* Ajan rehberlerinin (`/skill.md`, `/mcp.md`) servis başlıkları.
3+
*
4+
* Content-type **text/markdown değil**, bilerek. `text/markdown` kayıtlı bir
5+
* medya türü ama tarayıcı dışı okuyucuların çoğunda render edici yok; ChatGPT
6+
* Web'in getiricisi gibi istemciler bu türü ya indirilecek dosya sayıp ya da
7+
* hiç okumadan geri çeviriyor. `nosniff` gönderdiğimiz için istemcinin türü
8+
* tahmin etme yolu da kapalı — yani kendi elimizle kapatmış oluyoruz.
9+
*
10+
* Markdown zaten düz metindir; `text/plain` hiçbir şey kaybettirmez ve her
11+
* yerde satır içi okunur. GitHub raw da `.md` dosyalarını tam olarak böyle
12+
* servis eder, LLM getiricilerinin README okuyabilmesinin sebebi budur.
13+
*
14+
* Belgenin Markdown olduğunu `.md` uzantısı ve gövdenin kendisi zaten söylüyor.
15+
*/
16+
export const MACHINE_GUIDE_HEADERS = {
17+
'cache-control': 'no-store, no-transform',
18+
'content-type': 'text/plain; charset=utf-8',
19+
'x-content-type-options': 'nosniff',
20+
} as const;

‎src/worker.ts‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ import type { PublicRepository } from './server/repositories/public-repository';
2525
import { serveDynamicPublicPage } from './server/public/response';
2626
import { machineAgentSkill } from './data/agentOnboarding';
2727
import { machineMcpGuide } from './data/mcpOnboarding';
28+
import { MACHINE_GUIDE_HEADERS } from './shared/machine-guide';
2829

2930
interface ExecutionContextLike {
3031
waitUntil(promise: Promise<unknown>): void;
@@ -79,11 +80,7 @@ function denyAllRobots(): Response {
7980

8081
function machineGuideResponse(method: string, guide: string): Response {
8182
return new Response(method === 'HEAD' ? null : guide, {
82-
headers: {
83-
'cache-control': 'no-store, no-transform',
84-
'content-type': 'text/markdown; charset=utf-8',
85-
'x-content-type-options': 'nosniff',
86-
},
83+
headers: { ...MACHINE_GUIDE_HEADERS },
8784
});
8885
}
8986

0 commit comments

Comments
 (0)